Collection and development kit of MATLAB MEX functions for OpenCV library.
The package provides MATLAB MEX functions that interface with hundreds of OpenCV APIs. Also the package contains a C++ class that converts between MATLAB's native data type and OpenCV data types. The package is suitable for fast prototyping of OpenCV application in MATLAB, use of OpenCV as an external toolbox in MATLAB, and development of custom MEX functions.
The current version of mexopencv is compatible with OpenCV 3.4.1.
For previous OpenCV 3.x versions, checkout the corresponding tags:
For OpenCV 2.x, checkout these older branches:
Consult the wiki for help.
The project tree is organized as follows:
+cv/ OpenCV or custom API directory
+mexopencv/ mexopencv utility API directory
doc/ directory for documentation
include/ header files
lib/ directory for compiled C++ library files
samples/ directory for sample application codes
src/ directory for C++ source files
src/+cv/ directory for MEX source files
src/+cv/private/ directory for private MEX source files
test/ directory for test scripts and resources
opencv_contrib/ directory for sources/samples/tests of additional modules
utils/ directory for utilities
Doxyfile config file for doxygen
Makefile make script
README.markdown this file
Prerequisite
Depending on your platform, you also need the required build tools:
- Linux: g++, make, pkg-config
- OS X: Xcode Command Line Tools, pkg-config
- Windows: Visual Studio
Refer to the Makefile and make.m scripts for a complete list of
options accepted for building mexopencv across supported platforms.
Refer to the wiki for detailed build instructions.
Currently, mexopencv targets the final 3.4.1 stable version of OpenCV. You
must build it against this exact version, rather than using the bleeding-edge
dev-version of opencv and opencv_contrib. UNIX users should consider using
a package manager to install OpenCV if available.
DO NOT use the "master" branch of opencv and opencv_contrib!
Only the 3.4.1 release is supported by mexopencv.
First make sure you have OpenCV 3.4.1 installed in the system:
-
if applicable, install OpenCV 3 package available in your package manager (e.g.,
libopencv-devin Debian/Ubuntu,opencv-develin Fedora). Note that these packages are not always up-to-date, so you might need to use older mexopencv versions to match their opencv package version. -
otherwise, you can always build and install OpenCV from source:
$ cd <opencv_build_dir> $ cmake <options> <opencv_src_dir> $ make $ sudo make install
At this point, you should make sure that the pkg-config command can
identify and locate OpenCV libraries (if needed, set the PKG_CONFIG_PATH
environment variable to help it find the opencv.pc file):
$ pkg-config --cflags --libs opencv
If you have all the prerequisites, go to the mexopencv directory and type:
$ make
This will build and place all MEX functions inside +cv/. Specify your MATLAB
directory if you installed MATLAB to a non-default location:
$ make MATLABDIR=/opt/local/MATLAB/R2017a
You can also work with Octave instead of MATLAB by specifying:
$ make WITH_OCTAVE=true
To enable support for contributed modules, you must build OpenCV from both
opencv and opencv_contrib sources. You can then compile
mexopencv as:
$ make all contrib
Finally you can test mexopencv functionality:
$ make test
Developer documentation can be generated with Doxygen if installed:
$ make doc
This will create HTML files under doc/.
Refer to the wiki for detailed instructions on how to compile OpenCV for both MATLAB and Octave.
Currently, the recommended approach to install OpenCV in OS X is Homebrew. Install Homebrew first, and do the following to install OpenCV 3:
$ brew install pkg-config homebrew/science/opencv3
$ brew link opencv3
Otherwise, you can build OpenCV from source, similar to the Linux case.
If you have all the prerequisites, go to the mexopencv directory and run (modifying the options as needed):
$ make MATLABDIR=/Applications/MATLAB_R2016a.app PKG_CONFIG_MATLAB=opencv3 LDFLAGS=-L/usr/local/share/OpenCV/3rdparty/lib -j2
Replace the path to MATLAB with your version. This will build and place all
MEX functions inside +cv/.
Refer to the wiki for detailed instructions on how to compile OpenCV on Windows, and build mexopencv against it.
In a nutshell, execute the following in MATLAB to compile mexopencv:
>> addpath('C:\path\to\mexopencv')
>> mexopencv.make('opencv_path','C:\OpenCV\build')
Replace the path above with the location where OpenCV binaries are installed
(i.e location specified in CMAKE_INSTALL_PREFIX while building OpenCV).
Contrib modules are enabled as:
>> addpath('C:\path\to\mexopencv')
>> addpath('C:\path\to\mexopencv\opencv_contrib')
>> mexopencv.make('opencv_path','C:\OpenCV\build', 'opencv_contrib',true)
If you have previously compiled mexopencv with a different configuration, don't forget to clean old artifacts before building:
>> mexopencv.make('clean',true, 'opencv_contrib',true)
Once MEX functions are compiled, you can add path to the project directory and
call MEX functions within MATLAB using package name cv.
addpath('/path/to/mexopencv');
addpath('/path/to/mexopencv/opencv_contrib');
% recommended
out = cv.filter2D(img, kern); % with package name 'cv'
% not recommended
import cv.*;
out = filter2D(img, kern); % no need to specify 'cv' after importedNote that some functions such as cv.imread will overload MATLAB's built-in
imread function when imported. Use the scoped name when you need to avoid
name collision. It is also possible to import individual functions. Check
help import in MATLAB.
Check a list of functions available by help command in MATLAB.
>> help cv; % shows list of functions in package 'cv'
>> help cv.VideoCapture; % shows documentation of VideoCaptureLook at the samples/ directory for examples.
mexopencv includes a simple documentation utility that generates HTML help
files for MATLAB. The following command creates HTML user documentation
under doc/matlab/ directory.
addpath('/path/to/mexopencv/utils');
MDoc;On-line documentation is available.
You can test the functionality of compiled files by UnitTest class located
inside test directory.
addpath('/path/to/mexopencv/test');
UnitTest;Look at the test/unit_tests/ directory for all unit-tests.
The code may be redistributed under the BSD 3-Clause license.
