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.
Table of Contents
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
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
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
opencv_contrib. UNIX users should consider using
a package manager to install OpenCV if available.
DO NOT use the "master" branch of
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.,
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
environment variable to help it find the
$ pkg-config --cflags --libs opencv
If you have all the prerequisites, go to the mexopencv directory and type:
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
$ 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
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
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
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 imported
Note 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 VideoCapture
Look 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
On-line documentation is available.
You can test the functionality of compiled files by
UnitTest class located
Look at the
test/unit_tests/ directory for all unit-tests.
The code may be redistributed under the BSD 3-Clause license.