mexopencv  0.1
mex interface for opencv library
mexopencv Documentation

Collection of MATLAB MEX functions for OpenCV library

Kota Yamaguchi
March 2012

Developing a new MEX function

All you need to do is to add your C++ source file in src/+cv/. If you want to add a MEX function called myfunc, create src/+cv/myfunc.cpp. The minimum contents of the myfunc.cpp would look like this:

#include "mexopencv.hpp"
void mexFunction(int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[])
// Check arguments
nargchk(nlhs<=1 && nrhs==1);
// Convert MxArray to cv::Mat
cv::Mat mat = MxArray(prhs[0]).toMat();
// Do whatever you want
// Convert cv::Mat back to mxArray*
plhs[0] = MxArray(mat);

This example simply copies an input to cv::Mat object and then copies again to the output. Notice how the MxArray class provided by mexopencv converts mxArray to cv::Mat object. Of course you would want to do something more with the object. Once you create a file, type mexopencv.make() to build your new function. The compiled MEX function will be located inside +cv/ and accessible through cv.myfunc within MATLAB.

The mexopencv.hpp header includes a class MxArray to manipulate mxArray objects. Mostly this class is used to convert between OpenCV data types and mxArray .

int i = MxArray(prhs[0]).toInt();
double d = MxArray(prhs[0]).toDouble();
bool b = MxArray(prhs[0]).toBool();
std::string s = MxArray(prhs[0]).toString();
cv::Mat mat = MxArray(prhs[0]).toMat(); // For pixels
cv::Mat ndmat = MxArray(prhs[0]).toMatND(); // For N-D array
cv::Point pt = MxArray(prhs[0]).toPoint();
cv::Size siz = MxArray(prhs[0]).toSize();
cv::Rect rct = MxArray(prhs[0]).toRect();
cv::Scalar sc = MxArray(prhs[0]).toScalar();
cv::SparseMat sp = MxArray(prhs[0]).toSparseMat(); // Only double to float
plhs[0] = MxArray(i);
plhs[0] = MxArray(d);
plhs[0] = MxArray(b);
plhs[0] = MxArray(s);
plhs[0] = MxArray(mat);
plhs[0] = MxArray(ndmat);
plhs[0] = MxArray(pt);
plhs[0] = MxArray(siz);
plhs[0] = MxArray(rct);
plhs[0] = MxArray(sc);
plhs[0] = MxArray(sp); // Only 2D float to double

Check MxArray.hpp for the complete list of the conversion API.

If you rather want to develop a MATLAB class that internally calls a MEX function, make use of the +cv/private/ directory. Any function placed under private directory is only accessible from +cv/ directory. So, for example, when you want to design a MATLAB class that wraps the various behavior of the MEX function, define your class at +cv/MyClass.m and develop a MEX function dedicated for that class in src/+cv/private/MyClass_.cpp. Inside of +cv/MyClass.m, you can call MyClass_() without the cv namespace. In mexopencv, this is usually used to exposed C++ classes as MATLAB classes.


You can optionally add a testing script for your new function. The testing convention in mexopencv is that testing scripts are all written as a static function in a MATLAB class. For example, test/unit_tests/TestFilter2D.m is a class that describes test cases for cv::filter2D function. Inside of the class, a couple of test cases are written as static functions whose name start with 'test'.

If there is such a class inside test/unit_tests/, typing make test would invoke all test cases and show your result. Use test/ directory to place any resource files necessary for testing. An example of testing class is shown below:

classdef TestMyFunc
methods (Static)
function test_1
src = imread(fullfile(mexopencv.root(),'test','img001.jpg'));
ref = [1,2,3]; % reference output
dst = cv.myfunc(src); % execute your function
assert(isequal(dst, ref)); % check the output
function test_error_1
cv.myfunc('foo'); % myfunc should throw an error
error('UnitTest:Fail','myfunc incorrectly returned');
catch e

In Windows, add the test directory to the MATLAB path and invoke UnitTest to run all the test routines.


You can create a MATLAB help documentation for a MEX function by having the same file with '.m' extension. For example, a help file for filter2D.mex* would be filter2D.m. The help file should only contain MATLAB comments. An example is shown below:

%MYFUNC brief description about myfunc
% out = cv.myfunc(in)
% ## Input
% * __in__ input image.
% ## Output
% * __out__ output image.
% Detailed description of function continues...