mexopencv  0.1
mex interface for opencv library
 All Classes Files Functions Variables
mexopencv Documentation

Collection of mex functions for OpenCV library

Author
Kota Yamaguchi
Date
March 2012

http://www.cs.stonybrook.edu/~kyamagu/mexopencv/

Developing a new mex function

All you need to do is to add your mex 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
if (nlhs!=1 || nrhs!=1)
mexErrMsgIdAndTxt("myfunc:invalidArgs","Wrong number of arguments");
// 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 cv.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 object. 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
mxArray* plhs[0] = MxArray(i);
mxArray* plhs[0] = MxArray(d);
mxArray* plhs[0] = MxArray(b);
mxArray* plhs[0] = MxArray(s);
mxArray* plhs[0] = MxArray(mat);
mxArray* plhs[0] = MxArray(ndmat);
mxArray* plhs[0] = MxArray(pt);
mxArray* plhs[0] = MxArray(siz);
mxArray* plhs[0] = MxArray(rct);
mxArray* plhs[0] = MxArray(sc);
mxArray* plhs[0] = MxArray(sp); // Only 2D float to double

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

If you rather want to develop a matlab function 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 cv namescope.

Testing

Optionally, you can 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 filter2d function. Inside of the class, a couple of test cases are written as a static function whose name starts 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 file necessary for testing. An example of testing class is shown below:

classdef TestMyFunc
methods (Static)
function test_1
src = imread('/path/to/myimg');
ref = [1,2,3]; % reference output
dst = cv.myfunc(src); % execute your function
assert(all(dst(:) == ref(:))); % check the output
end
function test_error_1
try
cv.myfunc('foo'); % myfunc should throw an error
error('UnitTest:Fail','myfunc incorrectly returned');
catch e
assert(strcmp(e.identifier,'mexopencv:error'));
end
end
end
end

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

Documenting

You can create a Matlab help documentation for mex function by having the same file with '.m' extension. For example, on linux 64-bit architecture, the help file for filter2D.mexa64 would be filter2D.m. Inside the help file should be only matlab comments. An example is shown below:

%MYFUNC brief description about myfunc
%
% Detailed description of function continues
% ...