View on GitHub

mexopencv

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

Download this project as a .zip file Download this project as a tar.gz file

mexopencv

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: Starting OpenCV 3.0, the official Matlab module is available in the OpenCV contrib repository. mexopencv is a private project independent of the official Matlab module. (May 2015)

Note: Mathworks also provide an OpenCV development kit for Matlab in Computer Vision System Toolbox. They have mexOpenCV function to compile a MEX file. (Oct 2015)

There is a user-contributed video tutorial for mexopencv (Thanks, Surya).

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

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.

Use ldd in unix shell.

$ ldd /path/to/mexopencv/+cv/private/imread.mexa64

Use ldd in matlab shell.

>> !ldd /path/to/mexopencv/+cv/private/imread.mexa64

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 Mathworks support for more information.

OS X 10.9 and XCode 5

Due to the change in the default C++ runtime in OS X 10.9, you probably need to tweak a few configurations in mexopts.sh to avoid compile issues. If you haven't run mex -setup in Matlab, please do so first and edit mexopts.sh and change a few variables. Following shows an example.

CC='clang'
CXX='clang++'
SDKROOT='/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.9.sdk/'
MACOSX_DEPLOYMENT_TARGET='10.9'
CLIBS="$CLIBS -lc++"
CXXFLAGS="-fno-common -no-cpp-precomp -fexceptions -arch $ARCHS -isysroot $SDKROOT -mmacosx-version-min=$MACOSX_DEPLOYMENT_TARGET -std=c++11 -stdlib=libc++ -DCHAR16_T"
CXXLIBS="$MLIBS -lc++"

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.