Merged in code changes from MITIE project

dlib/cmake

 
+cmake_minimum_required(VERSION 2.6.4)
+
 # Don't add dlib if it's already been added to the cmake project
 if (NOT TARGET dlib)
 

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)
+

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 ..
+

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__
+

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()
+
+

dlib/matlab/example.m

+% This example calls the two mex functions defined in this folder.  As you
+% can see, you call them just like you would normal MATLAB functions.
+
+x = magic(3)
+y = 2*magic(3)
+
+[out1, out2] = example_mex_function(x,y, 12345)
+
+z = example_mex_callback(x, @(a)a+a)
+

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"
+

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"
+