Matlab API for OpenCV

edit

Detail 1: Conversion types

The excellent mexopencv utility uses a conversion type called MxArray as a means of converting to and from native Matlab (mxArray) and OpenCV and related types (cv::Mat, std::string, etc). Do you like this type of encapsulation, and if so do you prefer explicit conversion (assuming here prhs is of type mxArray**):

std::string name = MxArray(prhs[0]).toString();

or implicit conversion:

std::string name = MxArray(prhs[0]);

Or would you rather a set of utility functions that make memcopys and ownership more explicit:

std::string name = mxArrayToString(prhs[0]);

Detail 2: OpenCV classes in Matlab

There is no ideal solution to referencing C++ classes from Matlab. A set of best practices have been devised by the Matlab community that results in the least amount of undefined behaviour, memory leaks, dangling pointers, etc.

Even so, this requires that the memory address of the C++ object be passed back to Matlab (as a uint64_t) and trusted in the hands of the user (though it is private and invisible).

A better way to do this is to store all of the object instances in a map:

static std::unordered_map<KeyType, OpenCVClass> instances_;

and then give the user a key to accessing their object. That way, if they attempt to modify their key, they'll get a std:out_of_range exception, rather than a segfault. Memory addresses of the objects make good keys since they're not contiguous, so it'll be harder for the user to "guess" another valid instance.

Detail 4: Finding Matlab

The FindMatlab.cmake distributed with cmake by KitWare is woefully inadequate at finding any recent releases of Matlab. So it's time to write a new one. With a bit of crowd-sourcing I've been able to come up with the default install paths of Matlab on different architectures (in order of likelihood)

Linux: /usr/local /opt/local /usr /opt

Apple: /Applications /usr/local /opt/local /usr /opt

Windows: C:\Program Files C:\Program Files (x86)

In the case of Windows machines, assuming everything is in C: is a baaaad idea, so there are (gulp) recommended methods of hunting through the registry for paths:

execute_process(COMMAND reg query HKLM\\SOFTWARE\\MathWorks\\MATLAB /f * /k)

In the case of Unix derivatives, grep and regex are your friends.

OpenCV eschews the regular package finding convention of find_package(<package>) which locates a Find<package>.cmake file on the CMAKE_MODULE_PATH, in favour of having all the packages called OpenCV[Find/Detect]<package>.cmake and then simply including them in the root CMakeLists.txt as include(cmake/OpenCV[Find/Deteect]<package>.cmake). This is for one very simple and deliberate reason:

They want to make sure their own cmake files are loaded and not other ones on the system

Detail 3: Other useful utilities

As part of writing the code generator, it would be useful to expose some utilities that make it easier to use OpenCV constructs in mex files, and Matlab features in OpenCV. I was thinking of implementing:

• Matlab (.mat) I/O for cv::FileStorage. I have an implementation which needs refactoring.

• A mex script which automatically finds OpenCV and adds the relevant build flags, so compiling your own C++ function containing OpenCV declarations within matlab should be as simple as:

  cvmex my_awesome_function.cpp

• Conversion class/operations for easily getting between mxArray and cv:: std:: types

What would you like to see?