mexopencv Documentation

Collection of MATLAB MEX functions for OpenCV library

Author

Kota Yamaguchi

Date

March 2012

http://kyamagu.github.io/mexopencv/

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.

Testing

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
        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 the test directory to the MATLAB path and invoke UnitTest to run all the test routines.

Documenting

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