Merge github.com:davisking/dlib

.hgtags

@@ -21,3 +21,4 @@ a6c2b16111b8023dbded7299dcc7e6acd26671b8 v18.8
 4de62892e10850e8f0205b4857cf48b31fd730c8 v18.9
 5a14394843c04628990857e5db94ff6bc43c2da0 v18.10
 dd8e950033d5026373acce9ed4b2ffb85908d3b5 v18.11
+4e3941b13ca859f788853cfcef9973ac4b161e65 v18.12

dlib/CMakeLists.txt

@@ -12,6 +12,9 @@ set(CMAKE_LEGACY_CYGWIN_WIN32 0) # Remove when CMake >= 2.8.4 is required
 # Suppress cmake warnings about changes in new versions.
 if(COMMAND cmake_policy) 
    cmake_policy(SET CMP0003 NEW) 
+   if (POLICY CMP0054)
+      cmake_policy(SET CMP0054 NEW)
+   endif()
 endif()
 
 

dlib/add_python_module

@@ -20,10 +20,13 @@
 # A list of various paths you need to search on windows since people install
 # boost in a bunch of different places.
 set(CMAKE_PREFIX_PATH ${CMAKE_PREFIX_PATH} 
-        "C:/local/boost_1_*"
-        "C:/Program Files (x86)/boost/boost_1_*"  
-        "C:/Program Files/boost/boost_1_*")
-set(BOOST_LIBRARYDIR "C:/local/boost_1_*/lib32-msvc-*")
+         C:/local/boost_* 
+         C:/Program\ Files\ \(x86\)/boost/boost_*   
+         C:/Program\ Files/boost/boost_* 
+         )
+set(BOOST_LIBRARYDIR ${BOOST_LIBRARYDIR} $ENV{BOOST_LIBRARYDIR} 
+         C:/local/boost_*/lib32-msvc-* 
+         )
 
 
 
@@ -32,8 +35,10 @@ set(BOOST_LIBRARYDIR "C:/local/boost_1_*/lib32-msvc-*")
 #SET(Boost_USE_STATIC_RUNTIME OFF)
 set(Boost_NO_BOOST_CMAKE ON)
 
-
-set(BOOST_LIBRARYDIR  /usr/lib/x86_64-linux-gnu/)
+if (NOT WIN32)
+    set(BOOST_LIBRARYDIR ${BOOST_LIBRARYDIR} $ENV{BOOST_LIBRARYDIR}  
+            /usr/lib/x86_64-linux-gnu/)
+endif()
 if (PYTHON3)
     FIND_PACKAGE(Boost 1.41.0 COMPONENTS python-py34 REQUIRED)
     FIND_PACKAGE(PythonLibs 3.4 REQUIRED)

dlib/cmake

@@ -3,6 +3,9 @@ cmake_minimum_required(VERSION 2.6.4)
 
 
 set(CMAKE_LEGACY_CYGWIN_WIN32 0) # Remove when CMake >= 2.8.4 is required
+if (POLICY CMP0054)
+    cmake_policy(SET CMP0054 NEW)
+endif()
 
 # Don't add dlib if it's already been added to the cmake project
 if (NOT TARGET dlib)

dlib/image_processing/shape_predictor.h

@@ -315,10 +315,6 @@ namespace dlib
 
         unsigned long num_parts (
         ) const
-        /*!
-            ensures
-                - returns the number of points in the shape
-        !*/
         {
             return initial_shape.size()/2;
         }
@@ -328,13 +324,6 @@ namespace dlib
             const image_type& img,
             const rectangle& rect
         ) const
-        /*!
-            ensures
-                - runs the tree regressor on the detection rect inside img and returns a 
-                  full_object_detection DET such that:
-                    - DET.get_rect() == rect
-                    - DET.num_parts() == num_parts()
-        !*/
         {
             using namespace impl;
             matrix<float,0,1> current_shape = initial_shape;

dlib/image_processing/shape_predictor_abstract.h

@@ -270,7 +270,7 @@ namespace dlib
                   of the box.  So a padding of 0.5 would cause the algorithm to sample
                   pixels from a box that was 2x2, effectively multiplying the area pixels
                   are sampled from by 4.  Similarly, setting the padding to -0.2 would
-                  cause it to sample from a box 0.8x0.8 in size.
+                  cause it to sample from a box 0.6x0.6 in size.
         !*/
 
         void set_feature_pool_region_padding (

dlib/image_transforms/interpolation.h

@@ -1621,7 +1621,7 @@ namespace dlib
         }
 
         // now make an image pyramid
-        dlib::array<image_type1> levels(max_depth);
+        dlib::array<image_type2> levels(max_depth);
         if (levels.size() != 0)
             pyr(img,levels[0]);
         for (unsigned long i = 1; i < levels.size(); ++i)

dlib/image_transforms/morphological_operations.h

@@ -6,6 +6,7 @@
 #include "../pixel.h"
 #include "thresholding.h"
 #include "morphological_operations_abstract.h"
+#include "assign_image.h"
 
 namespace dlib
 {
@@ -662,6 +663,182 @@ namespace dlib
     }
 
 // ----------------------------------------------------------------------------------------
+// ----------------------------------------------------------------------------------------
+
+    namespace impl
+    {
+        template <typename image_type>
+        inline bool should_remove_pixel (
+            const image_type& img,
+            long r,
+            long c,
+            int iter
+        )
+        {
+            unsigned int p2 = img[r-1][c];
+            unsigned int p3 = img[r-1][c+1];
+            unsigned int p4 = img[r][c+1];
+            unsigned int p5 = img[r+1][c+1];
+            unsigned int p6 = img[r+1][c];
+            unsigned int p7 = img[r+1][c-1];
+            unsigned int p8 = img[r][c-1];
+            unsigned int p9 = img[r-1][c-1];
+
+            int A  = (p2 == 0 && p3 == 255) + (p3 == 0 && p4 == 255) + 
+                (p4 == 0 && p5 == 255) + (p5 == 0 && p6 == 255) + 
+                (p6 == 0 && p7 == 255) + (p7 == 0 && p8 == 255) +
+                (p8 == 0 && p9 == 255) + (p9 == 0 && p2 == 255);
+            int B  = p2 + p3 + p4 + p5 + p6 + p7 + p8 + p9;
+            int m1 = iter == 0 ? (p2 * p4 * p6) : (p2 * p4 * p8);
+            int m2 = iter == 0 ? (p4 * p6 * p8) : (p2 * p6 * p8);
+            // Decide if we should remove the pixel img[r][c].  
+            return (A == 1 && (B >= 2*255 && B <= 6*255) && m1 == 0 && m2 == 0);
+        }
+
+        template <typename image_type>
+        inline void add_to_remove (
+            std::vector<point>& to_remove,
+            array2d<unsigned char>& marker, 
+            const image_type& img,
+            long r,
+            long c,
+            int iter
+        )
+        {
+            if (marker[r][c]&&should_remove_pixel(img,r,c,iter)) 
+            {
+                to_remove.push_back(point(c,r));
+                marker[r][c] = 0;
+            }
+        }
+
+        template <typename image_type>
+        inline bool is_bw_border_pixel(
+            const image_type& img,
+            long r,
+            long c
+        )
+        {
+            unsigned int p2 = img[r-1][c];
+            unsigned int p3 = img[r-1][c+1];
+            unsigned int p4 = img[r][c+1];
+            unsigned int p5 = img[r+1][c+1];
+            unsigned int p6 = img[r+1][c];
+            unsigned int p7 = img[r+1][c-1];
+            unsigned int p8 = img[r][c-1];
+            unsigned int p9 = img[r-1][c-1];
+
+            int B  = p2 + p3 + p4 + p5 + p6 + p7 + p8 + p9;
+            // If you are on but at least one of your neighbors isn't.
+            return B<8*255 && img[r][c];
+
+        }
+
+        inline void add_if(
+            std::vector<point>& to_check2, 
+            const array2d<unsigned char>& marker,
+            long c,
+            long r
+        )
+        {
+            if (marker[r][c])
+                to_check2.push_back(point(c,r));
+        }
+
+    } // end namespace impl
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename image_type
+        >
+    void skeleton(
+        image_type& img_
+    )
+    {
+        /*
+            The implementation of this function is based on the paper
+            "A fast parallel algorithm for thinning digital patterns” by T.Y. Zhang and C.Y. Suen.
+            and also the excellent discussion of it at:
+            http://opencv-code.com/quick-tips/implementation-of-thinning-algorithm-in-opencv/
+        */
+
+        typedef typename image_traits<image_type>::pixel_type pixel_type;
+
+        // This function only works on grayscale images
+        COMPILE_TIME_ASSERT(pixel_traits<pixel_type>::grayscale);
+
+        using namespace impl;
+        // Note that it's important to zero the border for 2 reasons. First, it allows
+        // thinning to being at the border of the image.  But more importantly, it causes
+        // the mask to have a border of 0 pixels as well which we use later to avoid
+        // indexing outside the image inside add_to_remove().
+        zero_border_pixels(img_,1,1);
+        image_view<image_type> img(img_);
+
+        // We use the marker to keep track of pixels we have committed to removing but
+        // haven't yet removed from img.
+        array2d<unsigned char> marker(img.nr(), img.nc());
+        assign_image(marker, img);
+
+
+        // Begin by making a list of the pixels on the borders of binary blobs.
+        std::vector<point> to_remove, to_check, to_check2;
+        for (int r = 1; r < img.nr()-1; r++)
+        {
+            for (int c = 1; c < img.nc()-1; c++)
+            {
+                if (is_bw_border_pixel(img, r, c))
+                {
+                    to_check.push_back(point(c,r));
+                }
+            }
+        }
+
+        // Now start iteratively looking at the border pixels and removing them.
+        while(to_check.size() != 0)
+        {
+            for (int iter = 0; iter <= 1; ++iter)
+            {
+                // Check which pixels we should remove
+                to_remove.clear();
+                for (unsigned long i = 0; i < to_check.size(); ++i)
+                {
+                    long r = to_check[i].y();
+                    long c = to_check[i].x();
+                    add_to_remove(to_remove, marker, img, r, c, iter);
+                }
+                for (unsigned long i = 0; i < to_check2.size(); ++i)
+                {
+                    long r = to_check2[i].y();
+                    long c = to_check2[i].x();
+                    add_to_remove(to_remove, marker, img, r, c, iter);
+                }
+                // Now remove those pixels.  Also add their neighbors into the "to check"
+                // pixel list for the next iteration.
+                for (unsigned long i = 0; i < to_remove.size(); ++i)
+                {
+                    long r = to_remove[i].y();
+                    long c = to_remove[i].x();
+                    // remove the pixel
+                    img[r][c] = 0;
+                    add_if(to_check2, marker, c-1, r-1);
+                    add_if(to_check2, marker, c,   r-1);
+                    add_if(to_check2, marker, c+1, r-1);
+                    add_if(to_check2, marker, c-1, r);
+                    add_if(to_check2, marker, c+1, r);
+                    add_if(to_check2, marker, c-1, r+1);
+                    add_if(to_check2, marker, c,   r+1);
+                    add_if(to_check2, marker, c+1, r+1);
+                }
+            }
+            to_check.clear();
+            to_check.swap(to_check2);
+        }
+    }
+
+// ----------------------------------------------------------------------------------------
+// ----------------------------------------------------------------------------------------
 
 }
 

dlib/image_transforms/morphological_operations_abstract.h

@@ -283,6 +283,30 @@ namespace dlib
             - calls binary_complement(img,img);
     !*/
 
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename image_type
+        >
+    void skeleton(
+        image_type& img
+    );
+    /*!
+        requires
+            - image_type is an object that implement the interface defined in
+              dlib/image_processing/generic_image.h 
+            - img must contain a grayscale pixel type.
+            - all pixels in img are set to either on_pixel or off_pixel.
+              (i.e. it must be a binary image)
+        ensures
+            - This function computes the skeletonization of img and stores the result in
+              #img.  That is, given a binary image, we progressively thin the binary blobs
+              (composed of on_pixel values) until only a single pixel wide skeleton of the
+              original blobs remains.
+            - #img.nc() == img.nc()
+            - #img.nr() == img.nr()
+    !*/
+
 // ----------------------------------------------------------------------------------------
 
 }

dlib/image_transforms/spatial_filtering.h

@@ -1217,7 +1217,7 @@ namespace dlib
         typename in_image_type,
         typename out_image_type
         >
-    void gaussian_blur (
+    rectangle gaussian_blur (
         const in_image_type& in_img,
         out_image_type& out_img,
         double sigma = 1,
@@ -1241,7 +1241,7 @@ namespace dlib
         ptype scale = sum(filt);
         scale = scale*scale;
 
-        spatially_filter_image_separable(in_img, out_img, filt, filt, scale);
+        return spatially_filter_image_separable(in_img, out_img, filt, filt, scale);
 
     }
 

dlib/image_transforms/spatial_filtering_abstract.h

@@ -353,7 +353,7 @@ namespace dlib
         typename in_image_type,
         typename out_image_type
         >
-    void gaussian_blur (
+    rectangle gaussian_blur (
         const in_image_type& in_img,
         out_image_type& out_img,
         double sigma = 1,
@@ -384,6 +384,8 @@ namespace dlib
               inside the image are set to zero.
             - #out_img.nc() == in_img.nc()
             - #out_img.nr() == in_img.nr()
+            - returns a rectangle which indicates what pixels in #out_img are considered 
+              non-border pixels and therefore contain output from the filter.
     !*/
 
 // ----------------------------------------------------------------------------------------

dlib/matlab/CMakeLists.txt

-
-cmake_minimum_required(VERSION 2.8.4)
-
-PROJECT(mex_functions)
-
-include(cmake_mex_wrapper)
-
-include(../cmake)
-
-# Compile the example_mex_function.cpp file and link it to dlib.  Note
-# that you can give a list of things to link to here.  E.g. 
-#    add_mex_function(some_other_mex_function pthread dlib fftw) 
-add_mex_function(example_mex_function dlib)
-add_mex_function(example_mex_callback dlib)
-
+
+cmake_minimum_required(VERSION 2.8.4)
+
+PROJECT(mex_functions)
+
+include(cmake_mex_wrapper)
+
+include(../cmake)
+
+# Compile the example_mex_function.cpp file and link it to dlib.  Note
+# that you can give a list of things to link to here.  E.g. 
+#    add_mex_function(some_other_mex_function pthread dlib fftw) 
+add_mex_function(example_mex_function dlib)
+add_mex_function(example_mex_callback dlib)
+

dlib/matlab/README.txt

-This folder contains a set of tools which make it easy to create MATLAB mex
-functions.  To understand how they work, you should read the
-example_mex_function.cpp and example_mex_callback.cpp examples.
-
-To compile them, you can use CMake.  In particular, from this folder execute
-these commands:
-
-   mkdir build
-   cd build
-   cmake ..
-   cmake --build . --config release --target install
-
-That should build the mex files on any platform.
-
-Note that on windows you will probably need to tell CMake to use a 64bit
-version of visual studio.  You can do this by using a command like:
-   cmake -G "Visual Studio 10 Win64" ..
-instead of
-   cmake ..
-
+This folder contains a set of tools which make it easy to create MATLAB mex
+functions.  To understand how they work, you should read the
+example_mex_function.cpp and example_mex_callback.cpp examples.
+
+To compile them, you can use CMake.  In particular, from this folder execute
+these commands:
+
+   mkdir build
+   cd build
+   cmake ..
+   cmake --build . --config release --target install
+
+That should build the mex files on any platform.
+
+Note that on windows you will probably need to tell CMake to use a 64bit
+version of visual studio.  You can do this by using a command like:
+   cmake -G "Visual Studio 10 Win64" ..
+instead of
+   cmake ..
+

dlib/matlab/call_matlab.h

-// Copyright (C) 2012 Massachusetts Institute of Technology, Lincoln Laboratory
-// License: Boost Software License   See LICENSE.txt for the full license.
-// Authors: Davis E. King (davis@dlib.net)
-#ifndef MIT_LL_CALL_MATLAB_H__
-#define MIT_LL_CALL_MATLAB_H__
-
-#include <string>
-
-// ----------------------------------------------------------------------------------------
-// ----------------------------------------------------------------------------------------
-
-template <typename T> 
-struct output_decorator
-{
-    output_decorator(T& item_):item(item_){}
-    T& item;
-};
-
-template <typename T>
-output_decorator<T> returns(T& item) { return output_decorator<T>(item); }
-/*!
-    ensures
-        - decorates item as an output type.  This stuff is used by the call_matlab()
-          functions to tell if an argument is an input to the function or is supposed
-          to be bound to one of the return arguments.
-!*/
-
-// ----------------------------------------------------------------------------------------
-// ----------------------------------------------------------------------------------------
-
-struct function_handle
-{
-    /*!
-        WHAT THIS OBJECT REPRESENTS
-            This type is used to represent function handles passed from MATLAB into a
-            mex function.  You can call the function referenced by the handle by
-            saying:
-                call_matlab(my_handle);
-    !*/
-
-    // These two lines are just implementation details, ignore them.
-    function_handle():h(0){}
-    void* const h;
-};
-
-// ----------------------------------------------------------------------------------------
-// ----------------------------------------------------------------------------------------
-
-void call_matlab (
-    const std::string& function_name
-);
-/*!
-    ensures
-        - Calls MATLAB's function of the given name
-!*/
-
-// ----------------------------------------------------------------------------------------
-
-void call_matlab (
-    const function_handle& funct 
-);
-/*!
-    ensures
-        - Calls MATLAB's function represented by the handle funct
-!*/
-
-// ----------------------------------------------------------------------------------------
-
-template <
-    typename T1
-    >
-void call_matlab (
-    const std::string& function_name,
-    const T1& A1
-);
-/*!
-    ensures
-        - calls MATLAB's function of the given name.  
-        - if (A1 is not decorated as an output by returns()) then
-            - A1 is passed as an argument into the MATLAB function
-        - else
-            - A1 is treated as the first return value from the MATLAB function.
-!*/
-
-template <
-    typename T1
-    >
-void call_matlab (
-    const function_handle& funct,
-    const T1& A1
-) { call_matlab("feval", funct, A1); }
-/*!
-    ensures
-        - Calls MATLAB's function represented by the handle funct
-        - if (A1 is not decorated as an output by returns()) then
-            - A1 is passed as an argument into the MATLAB function
-        - else
-            - A1 is treated as the first return value from the MATLAB function.
-!*/
-
-// ----------------------------------------------------------------------------------------
-// ----------------------------------------------------------------------------------------
-/*
-    The rest of this file is just overloads of call_matlab() for up to 10 arguments (or
-    just 9 arguments if function_handle is used).  They all do the same thing as the above 
-    version of call_matlab().  Generally, any argument not decorated by returns() is an 
-    input to the MATLAB function.  On the other hand, all arguments decorated by returns() 
-    are treated as outputs.  
-*/
-// ----------------------------------------------------------------------------------------
-
-template <
-    typename T1, 
-    typename T2
-    >
-void call_matlab (
-    const std::string& function_name,
-    const T1& A1,
-    const T2& A2
-);
-
-// ----------------------------------------------------------------------------------------
-
-template <
-    typename T1, 
-    typename T2,
-    typename T3
-    >
-void call_matlab (
-    const std::string& function_name,
-    const T1& A1,
-    const T2& A2,
-    const T3& A3
-);
-
-// ----------------------------------------------------------------------------------------
-
-template <
-    typename T1, 
-    typename T2,
-    typename T3,
-    typename T4
-    >
-void call_matlab (
-    const std::string& function_name,
-    const T1& A1,
-    const T2& A2,
-    const T3& A3,
-    const T4& A4
-);
-
-// ----------------------------------------------------------------------------------------
-
-template <
-    typename T1, 
-    typename T2,
-    typename T3,
-    typename T4,
-    typename T5
-    >
-void call_matlab (
-    const std::string& function_name,
-    const T1& A1,
-    const T2& A2,
-    const T3& A3,
-    const T4& A4,
-    const T5& A5
-);
-
-// ----------------------------------------------------------------------------------------
-
-template <
-    typename T1, 
-    typename T2,
-    typename T3,
-    typename T4,
-    typename T5,
-    typename T6
-    >
-void call_matlab (
-    const std::string& function_name,
-    const T1& A1,
-    const T2& A2,
-    const T3& A3,
-    const T4& A4,
-    const T5& A5,
-    const T6& A6
-);
-
-// ----------------------------------------------------------------------------------------
-
-template <
-    typename T1, 
-    typename T2,
-    typename T3,
-    typename T4,
-    typename T5,
-    typename T6,
-    typename T7
-    >
-void call_matlab (
-    const std::string& function_name,
-    const T1& A1,
-    const T2& A2,
-    const T3& A3,
-    const T4& A4,
-    const T5& A5,
-    const T6& A6,
-    const T7& A7
-);
-
-// ----------------------------------------------------------------------------------------
-
-template <
-    typename T1, 
-    typename T2,
-    typename T3,
-    typename T4,
-    typename T5,
-    typename T6,
-    typename T7,
-    typename T8
-    >
-void call_matlab (
-    const std::string& function_name,
-    const T1& A1,
-    const T2& A2,
-    const T3& A3,
-    const T4& A4,
-    const T5& A5,
-    const T6& A6,
-    const T7& A7,
-    const T8& A8
-);
-
-// ----------------------------------------------------------------------------------------
-
-template <
-    typename T1, 
-    typename T2,
-    typename T3,
-    typename T4,
-    typename T5,
-    typename T6,
-    typename T7,
-    typename T8,
-    typename T9
-    >
-void call_matlab (
-    const std::string& function_name,
-    const T1& A1,
-    const T2& A2,
-    const T3& A3,
-    const T4& A4,
-    const T5& A5,
-    const T6& A6,
-    const T7& A7,
-    const T8& A8,
-    const T9& A9
-);
-
-// ----------------------------------------------------------------------------------------
-
-template <
-    typename T1, 
-    typename T2,
-    typename T3,
-    typename T4,
-    typename T5,
-    typename T6,
-    typename T7,
-    typename T8,
-    typename T9,
-    typename T10
-    >
-void call_matlab (
-    const std::string& function_name,
-    const T1& A1,
-    const T2& A2,
-    const T3& A3,
-    const T4& A4,
-    const T5& A5,
-    const T6& A6,
-    const T7& A7,
-    const T8& A8,
-    const T9& A9,
-    const T10& A10
-);
-
-// ----------------------------------------------------------------------------------------
-// ----------------------------------------------------------------------------------------
-// ----------------------------------------------------------------------------------------
-// ----------------------------------------------------------------------------------------
-
-template <
-    typename T1,
-    typename T2
-    >
-void call_matlab (
-    const function_handle& funct,
-    const T1& A1,
-    const T2& A2
-)
-{
-    call_matlab("feval", funct, A1, A2);
-}
-
-template <
-    typename T1,
-    typename T2,
-    typename T3
-    >
-void call_matlab (
-    const function_handle& funct,
-    const T1& A1,
-    const T2& A2,
-    const T3& A3
-)
-{
-    call_matlab("feval", funct, A1, A2, A3);
-}
-
-template <
-    typename T1,
-    typename T2,
-    typename T3,
-    typename T4
-    >
-void call_matlab (
-    const function_handle& funct,
-    const T1& A1,
-    const T2& A2,
-    const T3& A3,
-    const T4& A4
-)
-{
-    call_matlab("feval", funct, A1, A2, A3, A4);
-}
-
-template <
-    typename T1,
-    typename T2,
-    typename T3,
-    typename T4,
-    typename T5
-    >
-void call_matlab (
-    const function_handle& funct,
-    const T1& A1,
-    const T2& A2,
-    const T3& A3,
-    const T4& A4,
-    const T5& A5
-)
-{
-    call_matlab("feval", funct, A1, A2, A3, A4, A5);
-}
-
-template <
-    typename T1,
-    typename T2,
-    typename T3,
-    typename T4,
-    typename T5,
-    typename T6
-    >
-void call_matlab (
-    const function_handle& funct,
-    const T1& A1,
-    const T2& A2,
-    const T3& A3,
-    const T4& A4,
-    const T5& A5,
-    const T6& A6
-)
-{
-    call_matlab("feval", funct, A1, A2, A3, A4, A5, A6);
-}
-
-template <
-    typename T1,
-    typename T2,
-    typename T3,
-    typename T4,
-    typename T5,
-    typename T6,
-    typename T7
-    >
-void call_matlab (
-    const function_handle& funct,
-    const T1& A1,
-    const T2& A2,
-    const T3& A3,
-    const T4& A4,
-    const T5& A5,
-    const T6& A6,
-    const T7& A7
-)
-{
-    call_matlab("feval", funct, A1, A2, A3, A4, A5, A6, A7);
-}
-
-template <
-    typename T1,
-    typename T2,
-    typename T3,
-    typename T4,
-    typename T5,
-    typename T6,
-    typename T7,
-    typename T8
-    >
-void call_matlab (
-    const function_handle& funct,
-    const T1& A1,
-    const T2& A2,
-    const T3& A3,
-    const T4& A4,
-    const T5& A5,
-    const T6& A6,
-    const T7& A7,
-    const T8& A8
-)
-{
-    call_matlab("feval", funct, A1, A2, A3, A4, A5, A6, A7, A8);
-}
-
-template <
-    typename T1,
-    typename T2,
-    typename T3,
-    typename T4,
-    typename T5,
-    typename T6,
-    typename T7,
-    typename T8,
-    typename T9
-    >
-void call_matlab (
-    const function_handle& funct,
-    const T1& A1,
-    const T2& A2,
-    const T3& A3,
-    const T4& A4,
-    const T5& A5,
-    const T6& A6,
-    const T7& A7,
-    const T8& A8,
-    const T9& A9
-)
-{
-    call_matlab("feval", funct, A1, A2, A3, A4, A5, A6, A7, A8, A9);
-}
-
-// ----------------------------------------------------------------------------------------
-
-#endif // MIT_LL_CALL_MATLAB_H__
-
+// Copyright (C) 2012 Massachusetts Institute of Technology, Lincoln Laboratory
+// License: Boost Software License   See LICENSE.txt for the full license.
+// Authors: Davis E. King (davis@dlib.net)
+#ifndef MIT_LL_CALL_MATLAB_H__
+#define MIT_LL_CALL_MATLAB_H__
+
+#include <string>
+
+// ----------------------------------------------------------------------------------------
+// ----------------------------------------------------------------------------------------
+
+template <typename T> 
+struct output_decorator
+{
+    output_decorator(T& item_):item(item_){}
+    T& item;
+};
+
+template <typename T>
+output_decorator<T> returns(T& item) { return output_decorator<T>(item); }
+/*!
+    ensures
+        - decorates item as an output type.  This stuff is used by the call_matlab()
+          functions to tell if an argument is an input to the function or is supposed
+          to be bound to one of the return arguments.
+!*/
+
+// ----------------------------------------------------------------------------------------
+// ----------------------------------------------------------------------------------------
+
+struct function_handle
+{
+    /*!
+        WHAT THIS OBJECT REPRESENTS
+            This type is used to represent function handles passed from MATLAB into a
+            mex function.  You can call the function referenced by the handle by
+            saying:
+                call_matlab(my_handle);
+    !*/
+
+    // These two lines are just implementation details, ignore them.
+    function_handle():h(0){}
+    void* const h;
+};
+
+// ----------------------------------------------------------------------------------------
+// ----------------------------------------------------------------------------------------
+
+void call_matlab (
+    const std::string& function_name
+);
+/*!
+    ensures
+        - Calls MATLAB's function of the given name
+!*/
+
+// ----------------------------------------------------------------------------------------
+
+void call_matlab (
+    const function_handle& funct 
+);
+/*!
+    ensures
+        - Calls MATLAB's function represented by the handle funct
+!*/
+
+// ----------------------------------------------------------------------------------------
+
+template <
+    typename T1
+    >
+void call_matlab (
+    const std::string& function_name,
+    const T1& A1
+);
+/*!
+    ensures
+        - calls MATLAB's function of the given name.  
+        - if (A1 is not decorated as an output by returns()) then
+            - A1 is passed as an argument into the MATLAB function
+        - else
+            - A1 is treated as the first return value from the MATLAB function.
+!*/
+
+template <
+    typename T1
+    >
+void call_matlab (
+    const function_handle& funct,
+    const T1& A1
+) { call_matlab("feval", funct, A1); }
+/*!
+    ensures
+        - Calls MATLAB's function represented by the handle funct
+        - if (A1 is not decorated as an output by returns()) then
+            - A1 is passed as an argument into the MATLAB function
+        - else
+            - A1 is treated as the first return value from the MATLAB function.
+!*/
+
+// ----------------------------------------------------------------------------------------
+// ----------------------------------------------------------------------------------------
+/*
+    The rest of this file is just overloads of call_matlab() for up to 10 arguments (or
+    just 9 arguments if function_handle is used).  They all do the same thing as the above 
+    version of call_matlab().  Generally, any argument not decorated by returns() is an 
+    input to the MATLAB function.  On the other hand, all arguments decorated by returns() 
+    are treated as outputs.  
+*/
+// ----------------------------------------------------------------------------------------
+
+template <
+    typename T1, 
+    typename T2
+    >
+void call_matlab (
+    const std::string& function_name,
+    const T1& A1,
+    const T2& A2
+);
+
+// ----------------------------------------------------------------------------------------
+
+template <
+    typename T1, 
+    typename T2,
+    typename T3
+    >
+void call_matlab (
+    const std::string& function_name,
+    const T1& A1,
+    const T2& A2,
+    const T3& A3
+);
+
+// ----------------------------------------------------------------------------------------
+
+template <
+    typename T1, 
+    typename T2,
+    typename T3,
+    typename T4
+    >
+void call_matlab (
+    const std::string& function_name,
+    const T1& A1,
+    const T2& A2,
+    const T3& A3,
+    const T4& A4
+);
+
+// ----------------------------------------------------------------------------------------
+
+template <
+    typename T1, 
+    typename T2,
+    typename T3,
+    typename T4,
+    typename T5
+    >
+void call_matlab (
+    const std::string& function_name,
+    const T1& A1,
+    const T2& A2,
+    const T3& A3,
+    const T4& A4,
+    const T5& A5
+);
+
+// ----------------------------------------------------------------------------------------
+
+template <
+    typename T1, 
+    typename T2,
+    typename T3,
+    typename T4,
+    typename T5,
+    typename T6
+    >
+void call_matlab (
+    const std::string& function_name,
+    const T1& A1,
+    const T2& A2,
+    const T3& A3,
+    const T4& A4,
+    const T5& A5,
+    const T6& A6
+);
+
+// ----------------------------------------------------------------------------------------
+
+template <
+    typename T1, 
+    typename T2,
+    typename T3,
+    typename T4,
+    typename T5,
+    typename T6,
+    typename T7
+    >
+void call_matlab (
+    const std::string& function_name,
+    const T1& A1,
+    const T2& A2,
+    const T3& A3,
+    const T4& A4,
+    const T5& A5,
+    const T6& A6,
+    const T7& A7
+);
+
+// ----------------------------------------------------------------------------------------
+
+template <
+    typename T1, 
+    typename T2,
+    typename T3,
+    typename T4,
+    typename T5,
+    typename T6,
+    typename T7,
+    typename T8
+    >
+void call_matlab (
+    const std::string& function_name,
+    const T1& A1,
+    const T2& A2,
+    const T3& A3,
+    const T4& A4,
+    const T5& A5,
+    const T6& A6,
+    const T7& A7,
+    const T8& A8
+);
+
+// ----------------------------------------------------------------------------------------
+
+template <
+    typename T1, 
+    typename T2,
+    typename T3,
+    typename T4,
+    typename T5,
+    typename T6,
+    typename T7,
+    typename T8,
+    typename T9
+    >
+void call_matlab (
+    const std::string& function_name,
+    const T1& A1,
+    const T2& A2,
+    const T3& A3,
+    const T4& A4,
+    const T5& A5,
+    const T6& A6,
+    const T7& A7,
+    const T8& A8,
+    const T9& A9
+);
+
+// ----------------------------------------------------------------------------------------
+
+template <
+    typename T1, 
+    typename T2,
+    typename T3,
+    typename T4,
+    typename T5,
+    typename T6,
+    typename T7,
+    typename T8,
+    typename T9,
+    typename T10
+    >
+void call_matlab (
+    const std::string& function_name,
+    const T1& A1,
+    const T2& A2,
+    const T3& A3,
+    const T4& A4,
+    const T5& A5,
+    const T6& A6,
+    const T7& A7,
+    const T8& A8,
+    const T9& A9,
+    const T10& A10
+);
+
+// ----------------------------------------------------------------------------------------
+// ----------------------------------------------------------------------------------------
+// ----------------------------------------------------------------------------------------
+// ----------------------------------------------------------------------------------------
+
+template <
+    typename T1,
+    typename T2
+    >
+void call_matlab (
+    const function_handle& funct,
+    const T1& A1,
+    const T2& A2
+)
+{
+    call_matlab("feval", funct, A1, A2);
+}
+
+template <
+    typename T1,
+    typename T2,
+    typename T3
+    >
+void call_matlab (
+    const function_handle& funct,
+    const T1& A1,
+    const T2& A2,
+    const T3& A3
+)
+{
+    call_matlab("feval", funct, A1, A2, A3);
+}
+
+template <
+    typename T1,
+    typename T2,
+    typename T3,
+    typename T4
+    >
+void call_matlab (
+    const function_handle& funct,
+    const T1& A1,
+    const T2& A2,
+    const T3& A3,
+    const T4& A4
+)
+{
+    call_matlab("feval", funct, A1, A2, A3, A4);
+}
+
+template <
+    typename T1,
+    typename T2,
+    typename T3,
+    typename T4,
+    typename T5
+    >
+void call_matlab (
+    const function_handle& funct,
+    const T1& A1,
+    const T2& A2,
+    const T3& A3,
+    const T4& A4,
+    const T5& A5
+)
+{
+    call_matlab("feval", funct, A1, A2, A3, A4, A5);
+}
+
+template <
+    typename T1,
+    typename T2,
+    typename T3,
+    typename T4,
+    typename T5,
+    typename T6
+    >
+void call_matlab (
+    const function_handle& funct,
+    const T1& A1,
+    const T2& A2,
+    const T3& A3,
+    const T4& A4,
+    const T5& A5,
+    const T6& A6
+)
+{
+    call_matlab("feval", funct, A1, A2, A3, A4, A5, A6);
+}
+
+template <
+    typename T1,
+    typename T2,
+    typename T3,
+    typename T4,
+    typename T5,
+    typename T6,
+    typename T7
+    >
+void call_matlab (
+    const function_handle& funct,
+    const T1& A1,
+    const T2& A2,
+    const T3& A3,
+    const T4& A4,
+    const T5& A5,
+    const T6& A6,
+    const T7& A7
+)
+{
+    call_matlab("feval", funct, A1, A2, A3, A4, A5, A6, A7);
+}
+
+template <
+    typename T1,
+    typename T2,
+    typename T3,
+    typename T4,
+    typename T5,
+    typename T6,
+    typename T7,
+    typename T8
+    >
+void call_matlab (
+    const function_handle& funct,
+    const T1& A1,
+    const T2& A2,
+    const T3& A3,
+    const T4& A4,
+    const T5& A5,
+    const T6& A6,
+    const T7& A7,
+    const T8& A8
+)
+{
+    call_matlab("feval", funct, A1, A2, A3, A4, A5, A6, A7, A8);
+}
+
+template <
+    typename T1,
+    typename T2,
+    typename T3,
+    typename T4,
+    typename T5,
+    typename T6,
+    typename T7,
+    typename T8,
+    typename T9
+    >
+void call_matlab (
+    const function_handle& funct,
+    const T1& A1,
+    const T2& A2,
+    const T3& A3,
+    const T4& A4,
+    const T5& A5,
+    const T6& A6,
+    const T7& A7,
+    const T8& A8,
+    const T9& A9
+)
+{
+    call_matlab("feval", funct, A1, A2, A3, A4, A5, A6, A7, A8, A9);
+}
+
+// ----------------------------------------------------------------------------------------
+
+#endif // MIT_LL_CALL_MATLAB_H__
+

dlib/matlab/cmake_mex_wrapper

-# This file figured out where MATLAB is and then defines a macro, add_mex_function(name)
-# which when called instructs CMake to build a mex file from a file called name.cpp.  Note
-# that additional library dependencies can be added like this: add_mex_function(name lib1 dlib libetc).
-# That is, just add more libraries after the name and they will be build into the mex file.
-
-cmake_minimum_required(VERSION 2.8.4)
-
-
-# Find MATLAB's include directory and needed libraries 
-find_program(MATLAB_EXECUTABLE matlab PATHS
-        "C:/Program Files/MATLAB/*/bin"
-        "C:/Program Files (x86)/MATLAB/*/bin"
-        )
-# Resolve symbolic links to try and get the real path to the MATLAB executable
-get_filename_component(MATLAB_EXECUTABLE ${MATLAB_EXECUTABLE} REALPATH)
-# Now get MATLAB root directory
-get_filename_component(MATLAB_HOME ${MATLAB_EXECUTABLE} PATH)
-get_filename_component(MATLAB_HOME ${MATLAB_HOME} PATH)
-set(MATLAB_LIB_FOLDERS
-   "${MATLAB_HOME}/extern/lib/win64/microsoft"
-   "${MATLAB_HOME}/bin/glnxa64"
-   )
-# Find the MATLAB libraries that need to get linked into the mex file
-if (WIN32)
-   find_library(MATLAB_MEX_LIBRARY libmex PATHS ${MATLAB_LIB_FOLDERS} )
-   find_library(MATLAB_MX_LIBRARY  libmx  PATHS ${MATLAB_LIB_FOLDERS} )
-   find_library(MATLAB_ENG_LIBRARY libeng PATHS ${MATLAB_LIB_FOLDERS} )
-else()
-   find_library(MATLAB_MEX_LIBRARY mex    PATHS ${MATLAB_LIB_FOLDERS} )
-   find_library(MATLAB_MX_LIBRARY  mx     PATHS ${MATLAB_LIB_FOLDERS} )
-   find_library(MATLAB_ENG_LIBRARY eng    PATHS ${MATLAB_LIB_FOLDERS} )
-endif()
-set(MATLAB_LIBRARIES ${MATLAB_MEX_LIBRARY} ${MATLAB_MX_LIBRARY} ${MATLAB_ENG_LIBRARY})
-INCLUDE_DIRECTORIES("${MATLAB_HOME}/extern/include")
-# Determine the path to cmake_mex_wrapper file so we can add it to the include search path..
-string(REGEX REPLACE "cmake_mex_wrapper$" "" dlib_matlab_binding_path ${CMAKE_CURRENT_LIST_FILE})
-INCLUDE_DIRECTORIES("${dlib_matlab_binding_path}")
-
-# Determine the path to dlib so we can add it to the include search path.
-string(REGEX REPLACE "cmake_mex_wrapper$" "" dlib_path ${CMAKE_CURRENT_LIST_FILE})
-INCLUDE_DIRECTORIES(${dlib_path}/../..)
-
-ADD_DEFINITIONS(-DMATLAB_MEX_FILE)
-
-# Determine the path to our CMakeLists.txt file.  This is the file that
-# includeded the one you are reading right now.  So here we make it so that
-# when you run the install target it will copy the compiled mex files into the
-# same folder as the parent CMakeLists.txt file.
-string(REGEX REPLACE "CMakeLists.txt$" "" install_dir ${CMAKE_PARENT_LIST_FILE})
-set(CMAKE_INSTALL_PREFIX "${install_dir}")
-set(CMAKE_INSTALL_SYSTEM_RUNTIME_DESTINATION "${install_dir}")
-INCLUDE(InstallRequiredSystemLibraries)
-
-
-MACRO(add_mex_function name )
-   ADD_LIBRARY(${name} MODULE ${name}.cpp )
-    # Change the output file extension to a mex extension.
-   if (WIN32)
-      set_target_properties(${name} PROPERTIES SUFFIX ".mexw64")
-   elseif(APPLE)
-      set_target_properties(${name} PROPERTIES SUFFIX ".mexmaci64")
-   else()
-      set_target_properties(${name} PROPERTIES SUFFIX ".mexa64")
-   endif()
-   set_target_properties(${name} PROPERTIES PREFIX "")
-   TARGET_LINK_LIBRARIES(${name} ${MATLAB_LIBRARIES} ${ARGN})
-   install(TARGETS ${name} DESTINATION "${install_dir}")
-ENDMACRO()
-
-
+# This file figures out where MATLAB is and then defines a macro, add_mex_function(name)
+# which when called instructs CMake to build a mex file from a file called name.cpp.  Note
+# that additional library dependencies can be added like this: add_mex_function(name lib1 dlib libetc).
+# That is, just add more libraries after the name and they will be build into the mex file.
+
+cmake_minimum_required(VERSION 2.8.4)
+
+
+# Find MATLAB's include directory and needed libraries 
+find_program(MATLAB_EXECUTABLE matlab PATHS
+        "C:/Program Files/MATLAB/*/bin"
+        "C:/Program Files (x86)/MATLAB/*/bin"
+        )
+# Resolve symbolic links to try and get the real path to the MATLAB executable
+get_filename_component(MATLAB_EXECUTABLE ${MATLAB_EXECUTABLE} REALPATH)
+# Now get MATLAB root directory
+get_filename_component(MATLAB_HOME ${MATLAB_EXECUTABLE} PATH)
+get_filename_component(MATLAB_HOME ${MATLAB_HOME} PATH)
+set(MATLAB_LIB_FOLDERS
+   "${MATLAB_HOME}/extern/lib/win64/microsoft"
+   "${MATLAB_HOME}/bin/glnxa64"
+   )
+# Find the MATLAB libraries that need to get linked into the mex file
+if (WIN32)
+   find_library(MATLAB_MEX_LIBRARY libmex PATHS ${MATLAB_LIB_FOLDERS} )
+   find_library(MATLAB_MX_LIBRARY  libmx  PATHS ${MATLAB_LIB_FOLDERS} )
+   find_library(MATLAB_ENG_LIBRARY libeng PATHS ${MATLAB_LIB_FOLDERS} )
+else()
+   find_library(MATLAB_MEX_LIBRARY mex    PATHS ${MATLAB_LIB_FOLDERS} )
+   find_library(MATLAB_MX_LIBRARY  mx     PATHS ${MATLAB_LIB_FOLDERS} )
+   find_library(MATLAB_ENG_LIBRARY eng    PATHS ${MATLAB_LIB_FOLDERS} )
+endif()
+set(MATLAB_LIBRARIES ${MATLAB_MEX_LIBRARY} ${MATLAB_MX_LIBRARY} ${MATLAB_ENG_LIBRARY})
+INCLUDE_DIRECTORIES("${MATLAB_HOME}/extern/include")
+# Determine the path to cmake_mex_wrapper file so we can add it to the include search path..
+string(REGEX REPLACE "cmake_mex_wrapper$" "" dlib_matlab_binding_path ${CMAKE_CURRENT_LIST_FILE})
+INCLUDE_DIRECTORIES("${dlib_matlab_binding_path}")
+
+# Determine the path to dlib so we can add it to the include search path.
+string(REGEX REPLACE "cmake_mex_wrapper$" "" dlib_path ${CMAKE_CURRENT_LIST_FILE})
+INCLUDE_DIRECTORIES(${dlib_path}/../..)
+
+ADD_DEFINITIONS(-DMATLAB_MEX_FILE)
+
+# Determine the path to our CMakeLists.txt file.  This is the file that
+# includeded the one you are reading right now.  So here we make it so that
+# when you run the install target it will copy the compiled mex files into the
+# same folder as the parent CMakeLists.txt file.
+string(REGEX REPLACE "CMakeLists.txt$" "" install_dir ${CMAKE_PARENT_LIST_FILE})
+set(CMAKE_INSTALL_PREFIX "${install_dir}")
+set(CMAKE_INSTALL_SYSTEM_RUNTIME_DESTINATION "${install_dir}")
+INCLUDE(InstallRequiredSystemLibraries)
+
+
+MACRO(add_mex_function name )
+   ADD_LIBRARY(${name} MODULE ${name}.cpp )
+    # Change the output file extension to a mex extension.
+   if (WIN32)
+      set_target_properties(${name} PROPERTIES SUFFIX ".mexw64")
+   elseif(APPLE)
+      set_target_properties(${name} PROPERTIES SUFFIX ".mexmaci64")
+   else()
+      set_target_properties(${name} PROPERTIES SUFFIX ".mexa64")
+   endif()
+   set_target_properties(${name} PROPERTIES PREFIX "")
+   TARGET_LINK_LIBRARIES(${name} ${MATLAB_LIBRARIES} ${ARGN})
+   install(TARGETS ${name} DESTINATION "${install_dir}")
+ENDMACRO()
+
+

dlib/matlab/example_mex_callback.cpp

-
-#include "call_matlab.h"
-#include "dlib/matrix.h"
-
-using namespace dlib;
-using namespace std;
-
-/*
-    This mex function takes a MATLAB function handle, calls it, and
-    returns the results.
-
-    For example, you can call this function in MATLAB like so:
-        A = magic(3)
-        y = example_mex_callback(A, @(x)x+x)
-
-    This will result in y containing the value 2*A.
-*/
-
-void mex_function (
-    const matrix<double>& A,
-    const function_handle& f,
-    matrix<double>& result
-) 
-{
-    // The f argument to this function is a function handle passed from MATLAB.  To
-    // call it we use the following syntax:
-    call_matlab(f, A, returns(result));
-    // This is equivalent to result = f(A). Therefore, the returns(variable) syntax 
-    // is used to indicate which variables are outputs of the function.
-
-
-
-
-    // Another thing we can do is call MATLAB functions based on their string name
-    // rather than a function_handle.  Here is an example of calling eigs().   
-    matrix<double> m(2,2);
-    m = 1,2,
-        3,4;
-    matrix<double> v,d;
-
-    // This is equivalent to [v,d] = eigs(m);
-    call_matlab("eigs", m, returns(v), returns(d));
-    cout << "eigenvectors: \n" << v << endl;
-    cout << "eigenvalues:  \n" << d << endl;
-}
-
-
-
-// #including this brings in all the mex boiler plate needed by MATLAB.
-#include "mex_wrapper.cpp"
-
+// The contents of this file are in the public domain. See LICENSE_FOR_EXAMPLE_PROGRAMS.txt
+
+#include "call_matlab.h"
+#include "dlib/matrix.h"
+
+using namespace dlib;
+using namespace std;
+
+/*
+    This mex function takes a MATLAB function handle, calls it, and
+    returns the results.
+
+    For example, you can call this function in MATLAB like so:
+        A = magic(3)
+        y = example_mex_callback(A, @(x)x+x)
+
+    This will result in y containing the value 2*A.
+*/
+
+void mex_function (
+    const matrix<double>& A,
+    const function_handle& f,
+    matrix<double>& result
+) 
+{
+    // The f argument to this function is a function handle passed from MATLAB.  To
+    // call it we use the following syntax:
+    call_matlab(f, A, returns(result));
+    // This is equivalent to result = f(A). Therefore, the returns(variable) syntax 
+    // is used to indicate which variables are outputs of the function.
+
+
+
+
+    // Another thing we can do is call MATLAB functions based on their string name
+    // rather than a function_handle.  Here is an example of calling eigs().   
+    matrix<double> m(2,2);
+    m = 1,2,
+        3,4;
+    matrix<double> v,d;
+
+    // This is equivalent to [v,d] = eigs(m);
+    call_matlab("eigs", m, returns(v), returns(d));
+    cout << "eigenvectors: \n" << v << endl;
+    cout << "eigenvalues:  \n" << d << endl;
+}
+
+
+
+// #including this brings in all the mex boiler plate needed by MATLAB.
+#include "mex_wrapper.cpp"
+

dlib/matlab/example_mex_function.cpp

-
-#include "dlib/matrix.h"
-using namespace dlib;
-using namespace std;
-
-
-/*!
-    This file defines a function callable from MATLAB once you mex it. 
-
-    It computes the same thing as the following MATLAB function:
-
-        function [A, B] = example_mex_function(x, y, some_number)
-            A = x+y;
-            B = sum(sum(x+y));
-            disp(['some_number: ' num2str(some_number)])
-        end
-
-
-    VALID INPUT AND OUTPUT ARGUMENTS
-        The mex wrapper can handle the following kinds of input and output arguments:
-            - Types corresponding to a MATLAB matrix
-                - a dlib::matrix containing any kind of scalar value.
-                - a dlib::array2d containing any kind of scalar value.
-                - a dlib::vector containing any kind of scalar value.
-                - a dlib::point
-
-            - RGB color images
-                - dlib::array2d<dlib::rgb_pixel> can be used to represent 
-                  MATLAB uint8 MxNx3 images.
-
-            - Types corresponding to a MATLAB scalar
-                - any kind of scalar value, e.g. double, int, etc.
-
-            - Types corresponding to a MATLAB string 
-                - std::string 
-        
-            - Types corresponding to a MATLAB cell array
-                - a std::vector or dlib::array containing any of the above 
-                  types of objects or std::vector or dlib::array objects.
-!*/
-
-
-// You can also define default values for your input arguments.  So
-// here we say that if the user in MATLAB doesn't provide the "some_number" 
-// then it will get a value of 3.141.  
-#define ARG_5_DEFAULT 3.141
-
-// Make a function named mex_function() and put your code inside it.
-// Note that the return type should be void.  Use non-const reference
-// arguments to return outputs.  Finally, mex_function() must have no
-// more than 10 arguments.
-void mex_function (
-    const matrix<double>& x,
-    const matrix<double>& y,
-    matrix<double>& out1,
-    double& out2,
-    double some_number 
-) 
-{
-    out1 = x + y;
-    out2 = sum(x+y);
-
-    // we can also use cout to print things as usual:
-    cout << "some_number: "<< some_number << endl;
-}
-
-
-
-// #including this brings in all the mex boiler plate needed by MATLAB.
-#include "mex_wrapper.cpp"
-
+// The contents of this file are in the public domain. See LICENSE_FOR_EXAMPLE_PROGRAMS.txt
+
+#include "dlib/matrix.h"
+using namespace dlib;
+using namespace std;
+
+
+/*!
+    This file defines a function callable from MATLAB once you mex it. 
+
+    It computes the same thing as the following MATLAB function:
+
+        function [A, B] = example_mex_function(x, y, some_number)
+            A = x+y;
+            B = sum(sum(x+y));
+            disp(['some_number: ' num2str(some_number)])
+        end
+
+
+    VALID INPUT AND OUTPUT ARGUMENTS
+        The mex wrapper can handle the following kinds of input and output arguments:
+            - Types corresponding to a MATLAB matrix
+                - a dlib::matrix containing any kind of scalar value.
+                - a dlib::array2d containing any kind of scalar value.
+                - a dlib::vector containing any kind of scalar value.
+                - a dlib::point
+
+            - RGB color images
+                - dlib::array2d<dlib::rgb_pixel> can be used to represent 
+                  MATLAB uint8 MxNx3 images.
+
+            - Types corresponding to a MATLAB scalar
+                - any kind of scalar value, e.g. double, int, etc.
+
+            - Types corresponding to a MATLAB string 
+                - std::string 
+        
+            - Types corresponding to a MATLAB cell array
+                - a std::vector or dlib::array containing any of the above 
+                  types of objects or std::vector or dlib::array objects.
+!*/
+
+
+// You can also define default values for your input arguments.  So
+// here we say that if the user in MATLAB doesn't provide the "some_number" 
+// then it will get a value of 3.141.  
+#define ARG_5_DEFAULT 3.141
+
+// Make a function named mex_function() and put your code inside it.
+// Note that the return type should be void.  Use non-const reference
+// arguments to return outputs.  Finally, mex_function() must have no
+// more than 10 arguments.
+void mex_function (
+    const matrix<double>& x,
+    const matrix<double>& y,
+    matrix<double>& out1,
+    double& out2,
+    double some_number 
+) 
+{
+    out1 = x + y;
+    out2 = sum(x+y);
+
+    // we can also use cout to print things as usual:
+    cout << "some_number: "<< some_number << endl;
+}
+
+
+
+// #including this brings in all the mex boiler plate needed by MATLAB.
+#include "mex_wrapper.cpp"
+

dlib/test/image.cpp

@@ -1800,6 +1800,16 @@ namespace
             for (int i = 0; i < 100; ++i)
                 test_separable_filtering_center<float>(rnd);
 
+            {
+                print_spinner();
+                matrix<unsigned char> img(40,80);
+                assign_all_pixels(img, 255);
+                skeleton(img);
+
+                DLIB_TEST(sum(matrix_cast<int>(mat(img)))/255 == 40);
+                draw_line(img, point(20,19), point(59,19), 00);
+                DLIB_TEST(sum(matrix_cast<int>(mat(img))) == 0);
+            }
         }
     } a;
 

docs/.current_minor_release_number

-11
+12

docs/.logger_revnum

-dd8e950033d5
+4e3941b13ca8

docs/docs/imaging.xml

@@ -161,6 +161,7 @@
          <item>suppress_non_maximum_edges</item> 
          <item>threshold_image</item>
          <item>auto_threshold_image</item>
+         <item>hough_transform</item>
       </section>
 
       <section>
@@ -175,6 +176,7 @@
          <item>binary_union</item>
          <item>binary_difference</item>
          <item>binary_complement</item>
+         <item>skeleton</item>
       </section>
 
       <section>
@@ -240,7 +242,6 @@
          <item>zero_border_pixels</item> 
          <item>integral_image</item>
          <item>integral_image_generic</item>
-         <item>hough_transform</item>
 
       </section>
 
@@ -274,6 +275,20 @@
                                  
       </component>
 
+   <!-- ************************************************************************* -->
+      
+      <component>
+         <name>skeleton</name>
+         <file>dlib/image_transforms.h</file>
+         <spec_file link="true">dlib/image_transforms/morphological_operations_abstract.h</spec_file>
+         <description>
+              This function computes the skeletonization of an image.  That is,
+              given a binary image, we progressively thin the binary blobs
+              until only a single pixel wide skeleton of the original blobs
+              remains.
+         </description>
+      </component>
+
    <!-- ************************************************************************* -->
       
       <component>

docs/docs/index.xml

@@ -216,6 +216,7 @@
                   <li><a href="other.html#serialize">Serialization support</a></li>
                   <li>Many <a href="other.html#memory_manager">memory manager</a> objects that implement 
                   different memory pooling strategies</li>
+                  <li>A tool that lets you easily <a href="other.html#MATLAB">call C++ from MATLAB</a></li>
                </ul>
             </li>
          </ul>

docs/docs/other.xml

@@ -103,8 +103,9 @@
       </section>
 
       <section>
-         <name>Testing</name>
+         <name>Other</name>
          <item>dlib_testing_suite</item>
+         <item>MATLAB</item>
       </section>
 
     </top>  
@@ -1008,6 +1009,21 @@
                                  
       </component>
             
+   <!-- ************************************************************************* -->
+
+      <component>
+         <name>MATLAB</name>
+         <description>
+            dlib contains a tool that makes it easy to call C++ code from MATLAB.  It's
+            documented in the examples in the dlib/matlab folder.  In particular, the
+            <a href="dlib/matlab/example_mex_function.cpp.html">dlib/matlab/example_mex_function.cpp</a> and
+            <a href="dlib/matlab/example_mex_callback.cpp.html">dlib/matlab/example_mex_callback.cpp</a> examples.
+            You can also easily compile these files using CMake.  See the instructions in the README file
+            in the dlib/matlab folder for further details.
+         </description>
+                                 
+      </component>
+            
    <!-- ************************************************************************* -->
 
       <component>

docs/docs/release_notes.xml

@@ -12,12 +12,25 @@
 
 <current>
 New Features:
+   - Upgraded fft() and ifft() to support 2D matrices.
+   - Added hough_transform
+   - Added skeleton() for finding the skeletonization of a binary image.
+   - Added distance_to_line(), clip_line_to_rectangle(), min_point(), and max_point().
+   - Added a simple API for calling C++ from MATLAB.
 
 Non-Backwards Compatible Changes:
 
 Bug fixes:
+   - Fixed a compile time error that could happen when calling fft() for
+     certain input types.
+   - Fixed a compile time error that prevented auto_threshold_image() from
+     being used.
+   - Fixed name clashes with new version of Boost. 
+   - Changed Python pickling code so it works with Python 3.
+   - Fixed CMake compile time error related to finding fftw.
 
 Other:
+   - Made extract_image_chips() much faster when extracting unscaled image chips.
 </current>
 
 <!-- **************************************************************************************  -->

docs/docs/term_index.xml

@@ -676,6 +676,7 @@
          <term file="metaprogramming.html" name="DLIB_CASSERT"                      include="dlib/assert.h"/>
          <term file="metaprogramming.html" name="COMPILE_TIME_ASSERT"               include="dlib/assert.h"/>
          <term file="metaprogramming.html" name="DLIB_ASSERT_HAS_STANDARD_LAYOUT"   include="dlib/assert.h"/>
+         <term file="other.html" name="MATLAB"                       />
          <term file="other.html" name="TIME_THIS"                       include="dlib/time_this.h"/>
          <term link="other.html#timing code blocks" name="print"        include="dlib/timing.h"/>
          <term file="other.html" name="timing code blocks"              include="dlib/timing.h"/>
@@ -1151,6 +1152,7 @@
          <term file="containers.html" name="tuple"                      include="dlib/tuple.h"/>
          <term file="dlib/type_safe_union/type_safe_union_kernel_abstract.h.html" 
                name="bad_type_safe_union_cast"            include="dlib/type_safe_union.h"/>
+         <term file="containers.html" name="type_safe_union"            include="dlib/type_safe_union.h"/>
 
          <term file="containers.html" name="array2d"                    include="dlib/array2d.h"/>
 
@@ -1287,6 +1289,7 @@
          <term file="imaging.html" name="integral_image"          include="dlib/image_transforms.h"/>
          <term file="imaging.html" name="integral_image_generic"  include="dlib/image_transforms.h"/>
          <term file="imaging.html" name="hough_transform"         include="dlib/image_transforms.h"/>
+         <term file="imaging.html" name="skeleton"                include="dlib/image_transforms.h"/>
          <term file="imaging.html" name="hessian_pyramid"         include="dlib/image_keypoint.h"/>
          <term file="imaging.html" name="compute_dominant_angle"  include="dlib/image_keypoint.h"/>
          <term file="imaging.html" name="draw_surf_points"        include="dlib/image_keypoint/draw_surf_points.h"/>