mexopencv

facedetect

OpenCVのためのMatlab MEX関数開発パッケージ

このパッケージでは150以上のOpenCV APIをカバーするMatlab MEX関数を提供します. また,このパッケージにはOpenCVデータ型とMatlabのデータ型を変換するC++クラスが含まれています. このパッケージはOpenCVアプリケーションのプロトタイプ作成,MatlabからOpenCV関数のツールボックスとしての利用,そしてOpenCVを使ったMEX関数の開発といった用途に最適です.

注:OpenCVではMatlab APIの公式サポートが計画されています.OpenCVソースツリーのMatlabモジュールを確認してください.(Oct 3, 2013)
https://github.com/Itseez/opencv

ダウンロード

Github

上記Githubページからzipファイルをダウンロードしてください.ビルドは通常ならMatlab内でmexopencv.makeを実行するだけで済みます.

Gitを利用しているなら次のコマンドでもmexopencvを入手できます.

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

ドキュメント

使い方

以下に簡単な使い方の一例を示します.

% 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

カメラにアクセスしたい場合は次のように使います.

% 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

このパッケージには150以上のOpenCV関数及びクラスが含まれています. サポートされている関数はオンラインドキュメントで確認することができます. もし使いたいOpenCV関数がサポートされていなくてもMxArrayクラスを使って簡単に実装することができます. MxArrayクラスはMatlabとOpenCVのデータ型を変換するAPIを提供します. このクラスを使う事で,OpenCVを呼び出すMEX関数を以下のように簡単に記述することができます.

#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);
}

詳細はREADMEファイル,または開発者向けドキュメントを参照してください.

ライセンス

このコードは 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 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.