mexopencv

facedetect

Collection and a development kit of matlab mex functions for OpenCV library

This software package provides matlab mex functions that interface a hundred of OpenCV APIs. Also the package contains a C++ class that converts between Matlab's native data types and OpenCV data types. The package is suitable for fast prototyping of OpenCV application in Matlab, use of OpenCV as an external toolbox in Matlab, and the development of a custom mex function.

Note: The OpenCV developers are planning to implement Matlab wrappers as of February 2013. While the mexopencv will be kept as a private project, let's see how the official wrappers come out.

Download

Github

Please refer the above link for how to compile the source code. Usually it is as easy as typing mexopencv.make in matlab.

If you're using git,

git clone git://github.com/kyamagu/mexopencv.git

Documentation

Getting started

Here is an example of how simple it is to use an OpenCV function from matlab:

% Load a face detector and an image
detector = cv.CascadeClassifier('haarcascade_frontalface_alt.xml');
im = imread('myface.jpg');
% Preprocess
gr = cv.cvtColor(im, 'RGB2GRAY');
gr = cv.equalizeHist(gr);
% Detect
boxes = detector.detect(gr, 'ScaleFactor',  1.3, ...
                            'MinNeighbors', 2, ...
                            'MinSize',      [30, 30]);
% Draw results
imshow(im);
for i = 1:numel(boxes)
    rectangle('Position',  boxes{i}, ...
              'EdgeColor', 'g');
end

Would you like to use a camera input? No problem.

% Connect to a camera
camera = cv.VideoCapture();
pause(2);
for i = 1:50
    % Capture and show frame
    frame = camera.read;
    imshow(frame);
    pause(0.3);
end

The package already contains more than 150 OpenCV functions/classes. You can check a list of supported functions in the online documentation. If there isn't your favorite one, you can easily add a new mex function through MxArray class. MxArray is a data conversion utility for Matlab's native array and OpenCV data types. With this class, your mex function is as simple as the following:

#include "mexopencv.hpp"
void mexFunction( int nlhs, mxArray *plhs[],
                  int nrhs, const mxArray *prhs[] )
{
    // Check arguments
    if (nrhs!=2 || nlhs>1)
        mexErrMsgIdAndTxt("myfunc:invalidArgs", "Wrong number of arguments");

    // Convert MxArray to cv::Mat and cv::Size
    cv::Mat src = MxArray(prhs[0]).toMat(), dst;
    cv::Size ksize = MxArray(prhs[1]).toSize();

    // Use your favorite OpenCV function
    cv::blur(src, dst, ksize);

    // Convert cv::Mat back to mxArray*
    plhs[0] = MxArray(dst);
}

Check the README file and the developer documentation for detail.

License

The code may be redistributed under The BSD 3-Clause License.

FAQ

Windows

Compile error / Invalid MEX file

There could be a various possible reasons.

First make sure you have correctly configured the system path to use OpenCV (see Changing the system path). Your Path variable should contain an appropriate path to the dll files (e.g., c:\opencv\build\x86\vc10\bin). Be careful that the architecture (x86 or x64) should match your matlab architecture but not your OS. Also VC version (vc9 or vc10) should match the mex setup (and probably matlab's internal runtime). For example, if you're running Matlab 32-bit in Windows 7 64-bit with Visual Studio 2010 Express, you would use x86 and vc10. If you're running Matlab 64-bit in Windows 7 64-bit with Visual Studio 2010 Express and Windows SDK compiler, you would use x64 and vc10.

Next, make sure you are using the supported version of VC compiler (Supported compilers). Note that Windows 64-bit users need to use Windows SDK compiler. Using VC2010 compiler in Windows 64-bit leads to Matlab crash. Use mex -setup command in matlab to change the compiler.

Whenever you change the compiler setting, first clear all the previously built binaries with mexopencv.make('clean') command. After that, use mexopencv.make again to compile the source.

Missing stdint.h in Visual Studio 2008

Please note that Visual Studio 2008 is known to have a compatibility issue with mexopencv. Try to use newer version of supported compiler whenever possible. Nevertheless, if VS2008 is the only available compiler, please note there is a missing header file.

Visual Studio 2008 or earlier does not comply with the C99 standard and lacks stdint.h header file. Luckily, the header file is available on the Web. For example, here.

Place this file under include directory in the mexopencv package.

The _SECURE_SCL flag

The OpenCV binary package contains library files compiled with default _SECURE_SCL flag in Visual Studio, but mex command in Matlab might disable this flag depending on the environment and that results in segmentation fault on execution. The mexopencv build script adjusts this flag in a usual case, but this might not work for a self-compiled opencv binary. To fix the issue, adjust _SECURE_SCL flag in the default mex configuration. The default mex configuration is created with mex -setup command in matlab, and located in the following path. 

C:\Users\(Username)\AppData\Roaming\MathWorks\MATLAB\(version)\mexopts.bat

Open this file and set to the default _SECURE_SCL flag used in the specific version of Visual Studio. After this, clean all the generated binaries and compile all the mex files again.

If fixing _SECURE_SCL flag does not work, it indicates that the OpenCV binary files are still incompatible with Matlab runtime. If you're sure you set up all the path configurations are correct, please check your OS, compiler, Matlab, and OpenCV version, and file a bug report in Github.

Can I compile mexopencv with OpenCV built from source?

Yes, but be careful about the path setup. In Windows, the build script mexopencv.make assumes that the installed opencv is organized in the same way the binary distribution does. The easiest way to reuse this script is to replace the dll files in the binary distribution with the newly built lib/dll files in the correct location. Alternatively, if you're familier with matlab, you can modify +cv/make.m so that linker can point to your newly built library files.

Linux

Invalid MEX file

In most of cases, mexopencv gives an error due to conflicting internal dynamic libraries. You will need to find out which library is causing the conflict. Following is the steps to locate such libraries using ldd tool.

  1. Use ldd in unix shell.
    $ ldd /path/to/mexopencv/+cv/private/imread.mexa64
  2. Use ldd in matlab shell.
    >> !ldd /path/to/mexopencv/+cv/private/imread.mexa64
  3. Find any difference in the loaded libraries. (Hint: use diff tool.) Usually such libraries are causing error. If you find any, such as libstdc++ or libgcc_s, put the one found in unix shell in the LD_PRELOAD variable before launching matlab. For example,
    LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libstdc++.so.6:/lib/x86_64-linux-gnu/libgcc_s.so.1 matlab
    It is probably handy to use bash alias to specify the above long command after you find the erroneous library. Put the following in your .bashrc, for example.
    alias matlab='LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libstdc++.so.6:/lib/x86_64-linux-gnu/libgcc_s.so.1 matlab'

Note that if you have the computer vision toolbox from Mathworks, you almost always see this error, because that toolbox internally loads its own version of opencv. In that case, use LD_PRELOAD to force loading your opencv installation.

Mac OS X

Compile error

In Mac OS X, Matlab may require additional setup to use mex depending on the OS version. See http://www.mathworks.com/support/solutions/en/data/1-FR6LXJ/ for more information.

Invalid MEX file

In OS X environment, runtime error can happen when the version of your system library conflicts with matlab's internal library. Try setting the DYLD_INSERT_LIBRARIES variable to force matlab to use the system's library. For example,

DYLD_INSERT_LIBRARIES=/opt/local/lib/libtiff.3.dylib /Applications/MATLAB_R2012a.app/bin/matlab

To find which library is causing an error, use otool -L command. See the Invalid MEX file instruction in the Linux section above.

General usage

0-based index vs 1-based index

OpenCV uses 0-based index while matlab uses 1-based index. That is, the top left pixel is (0,0) in OpenCV whereas matlab treats it as (1,1). mexopencv does NOT convert image coordinates. Be careful when accessing a function that deals with image coordinates.

Channeled array

OpenCV often uses channels as dimensions of coordinate representation, as seen in perspectiveTransform. In matlab, you can make these channeled array by creating 1-by-N-by-d array for an N element array of d-dimensional vectors. Hint: use shiftdim function to convert from/to N-by-d numeric array in matlab.