The Matlab code generator is fully integrated into the OpenCV build system. If cmake finds a Matlab installation available on the host system while configuring OpenCV, it will attempt to generate Matlab wrappers for all OpenCV modules. If cmake is having trouble finding your Matlab installation, you can explicitly point it to the root by defining the `MATLAB_ROOT_DIR` variable. For example, on a Mac you could type:
The Matlab code generator is fully integrated into the OpenCV build system. If cmake finds a Matlab installation available on the host system while configuring OpenCV, it will attempt to generate Matlab wrappers for all OpenCV modules. If cmake is having trouble finding your Matlab installation, you can explicitly point it to the root by defining the `MATLAB_ROOT_DIR` variable. For example, on a Mac you could type:
@@ -44,18 +44,18 @@ to get help on the purpose and call signature of a particular method, or
...
@@ -44,18 +44,18 @@ to get help on the purpose and call signature of a particular method, or
to get general help regarding the OpenCV bindings. If you ever run into issues with the bindings
to get general help regarding the OpenCV bindings. If you ever run into issues with the bindings
cv.buildInformation();
cv.buildInformation();
will produce a printout of diagnostic information pertaining to your particular build of OS, OpenCV and Matlab. It is useful to submit this information alongside a bug report to the OpenCV team.
will produce a printout of diagnostic information pertaining to your particular build of OS, OpenCV and Matlab. It is useful to submit this information alongside a bug report to the OpenCV team.
Writing your own mex files
Writing your own mex files
--------------------------
--------------------------
The Matlab bindings come with a set of utilities to help you quickly write your own mex files using OpenCV definitions. By doing so, you have all the speed and freedom of C++, with the power of OpenCV's math expressions and optimizations.
The Matlab bindings come with a set of utilities to help you quickly write your own mex files using OpenCV definitions. By doing so, you have all the speed and freedom of C++, with the power of OpenCV's math expressions and optimizations.
The first thing you need to learn how to do is write a mex-file with Matlab constructs. Following is a brief example:
The first thing you need to learn how to do is write a mex-file with Matlab constructs. Following is a brief example:
```cpp
```cpp
// include useful constructs
// include useful constructs
// this automatically includes opencv core.hpp and mex.h)
// this automatically includes opencv core.hpp and mex.h)
#include <opencv2/matlab/bridge.hpp>
#include <opencv2/matlab/bridge.hpp>
usingnamespacecv;
usingnamespacecv;
...
@@ -120,7 +120,7 @@ Once a source file has been generated for each OpenCV definition, and type conve
...
@@ -120,7 +120,7 @@ Once a source file has been generated for each OpenCV definition, and type conve
*`map.hpp` (hash map interface for instance storage and method lookup)
*`map.hpp` (hash map interface for instance storage and method lookup)
*`io` (FileStorage interface for .mat files)
*`io` (FileStorage interface for .mat files)
*`test` (generator, compiler and binding test scripts)
*`test` (generator, compiler and binding test scripts)
Call Tree
Call Tree
---------
---------
The cmake call tree can be broken into 3 main components:
The cmake call tree can be broken into 3 main components:
...
@@ -147,22 +147,22 @@ The cmake call tree can be broken into 3 main components:
...
@@ -147,22 +147,22 @@ The cmake call tree can be broken into 3 main components:
2. build time
2. build time
3. install time
3. install time
**Find Matlab (configure)**
**Find Matlab (configure)**
The first thing to do is discover a Matlab installation on the host system. This is handled by the `OpenCVFindMatlab.cmake` in `opencv/cmake`. On Windows machines it searches the registry and path, while on *NIX machines it searches a set of canonical install paths. Once Matlab has been found, a number of variables are defined, such as the path to the mex compiler, the mex libraries, the mex include paths, the architectural extension, etc.
The first thing to do is discover a Matlab installation on the host system. This is handled by the `OpenCVFindMatlab.cmake` in `opencv/cmake`. On Windows machines it searches the registry and path, while on *NIX machines it searches a set of canonical install paths. Once Matlab has been found, a number of variables are defined, such as the path to the mex compiler, the mex libraries, the mex include paths, the architectural extension, etc.
**Test the generator (configure)**
**Test the generator (configure)**
Attempt to produce a source file for a simple definition. This tests whether python and pythonlibs are correctly invoked on the host.
Attempt to produce a source file for a simple definition. This tests whether python and pythonlibs are correctly invoked on the host.
**Test the mex compiler (configure)**
**Test the mex compiler (configure)**
Attempt to compile a simple definition using the mex compiler. A mex file is actually just a shared object with a special exported symbol `_mexFunction` which serves as the entry-point to the function. As such, the mex compiler is just a set of scripts configuring the system compiler. In most cases this is the same as the OpenCV compiler, but *could* be different. The test checks whether the mex and generator includes can be found, the system libraries can be linked and the passed compiler flags are compatible.
Attempt to compile a simple definition using the mex compiler. A mex file is actually just a shared object with a special exported symbol `_mexFunction` which serves as the entry-point to the function. As such, the mex compiler is just a set of scripts configuring the system compiler. In most cases this is the same as the OpenCV compiler, but *could* be different. The test checks whether the mex and generator includes can be found, the system libraries can be linked and the passed compiler flags are compatible.
If any of the configure time tests fail, the bindings will be disabled, but the main OpenCV configure will continue without error. The configuration summary will contain the block:
If any of the configure time tests fail, the bindings will be disabled, but the main OpenCV configure will continue without error. The configuration summary will contain the block:
Matlab
Matlab
mex: /Applications/MATLAB_R2013a.app/bin/mex
mex: /Applications/MATLAB_R2013a.app/bin/mex
compiler/generator: Not working (bindings will not be generated)
compiler/generator: Not working (bindings will not be generated)
**Generate the sources (build)**
**Generate the sources (build)**
Given a set of modules (the intersection of the OpenCV modules being built and the matlab module optional dependencies), the `CppHeaderParser()` from `opencv/modules/python/src2/hdr_parser.py` will parse the module headers and produce a set of definitions.
Given a set of modules (the intersection of the OpenCV modules being built and the matlab module optional dependencies), the `CppHeaderParser()` from `opencv/modules/python/src2/hdr_parser.py` will parse the module headers and produce a set of definitions.
The `ParseTree()` from `opencv/modules/matlab/generator/parse_tree.py` takes this set of definitions and refactors them into a semantic tree better suited to templatization. For example, a trivial definition from the header parser may look something like:
The `ParseTree()` from `opencv/modules/matlab/generator/parse_tree.py` takes this set of definitions and refactors them into a semantic tree better suited to templatization. For example, a trivial definition from the header parser may look something like:
...
@@ -170,22 +170,22 @@ The `ParseTree()` from `opencv/modules/matlab/generator/parse_tree.py` takes thi
...
@@ -170,22 +170,22 @@ The `ParseTree()` from `opencv/modules/matlab/generator/parse_tree.py` takes thi
```python
```python
[fill,void,['/S'],[cv::Mat&,mat,'',['/I','/O']]]
[fill,void,['/S'],[cv::Mat&,mat,'',['/I','/O']]]
```
```
The equivalent refactored output will look like:
The equivalent refactored output will look like:
```python
```python
Function
Function
name='fill'
name='fill'
rtype='void'
rtype='void'
static=True
static=True
req=
req=
Argument
Argument
name='mat'
name='mat'
type='cv::Mat'
type='cv::Mat'
ref='&'
ref='&'
I=True
I=True
O=True
O=True
default=''
default=''
```
```
The added semantics (Namespace, Class, Function, Argument, name, etc) make it easier for the templating engine to parse, slice and populate definitions.
The added semantics (Namespace, Class, Function, Argument, name, etc) make it easier for the templating engine to parse, slice and populate definitions.
...
@@ -194,16 +194,16 @@ Once the definitions have been parsed, `gen_matlab.py` passes each definition to
...
@@ -194,16 +194,16 @@ Once the definitions have been parsed, `gen_matlab.py` passes each definition to
The generator relies upon a proxy object called `generate.proxy` to determine when the sources are out of date and need to be re-generated.
The generator relies upon a proxy object called `generate.proxy` to determine when the sources are out of date and need to be re-generated.
**Compile the sources (build)**
**Compile the sources (build)**
Once the sources have been generated, they are compiled by the mex compiler. The `compile.cmake` script in `opencv/modules/matlab/` takes responsibility for iterating over each source file in `${CMAKE_CURRENT_BUILD_DIR}/src` and compiling it with the passed includes and OpenCV libraries.
Once the sources have been generated, they are compiled by the mex compiler. The `compile.cmake` script in `opencv/modules/matlab/` takes responsibility for iterating over each source file in `${CMAKE_CURRENT_BUILD_DIR}/src` and compiling it with the passed includes and OpenCV libraries.
The flags used to compile the main OpenCV libraries are also forwarded to the mex compiler. So if, for example, you compiled OpenCV with SSE support, the mex bindings will also use SSE. Likewise, if you compile OpenCV in debug mode, the bindings will link to the debug version of the libraries.
The flags used to compile the main OpenCV libraries are also forwarded to the mex compiler. So if, for example, you compiled OpenCV with SSE support, the mex bindings will also use SSE. Likewise, if you compile OpenCV in debug mode, the bindings will link to the debug version of the libraries.
Importantly, the mex compiler includes the `mxarray.hpp`, `bridge.hpp` and `map.hpp` files from the `opencv/modules/matlab/include` directory. `mxarray.hpp` defines a `MxArray` class which wraps Matlab's `mxArray*` type in a more friendly OOP-syle interface. `bridge.hpp` defines a `Bridge` class which is able to perform type conversions between Matlab types and std/OpenCV types. It can be extended with new definitions using the plugin interface described in that file.
Importantly, the mex compiler includes the `mxarray.hpp`, `bridge.hpp` and `map.hpp` files from the `opencv/modules/matlab/include` directory. `mxarray.hpp` defines a `MxArray` class which wraps Matlab's `mxArray*` type in a more friendly OOP-syle interface. `bridge.hpp` defines a `Bridge` class which is able to perform type conversions between Matlab types and std/OpenCV types. It can be extended with new definitions using the plugin interface described in that file.
The compiler relies upon a proxy object called `compile.proxy` to determine when the generated sources are out of date and need to be re-compiled.
The compiler relies upon a proxy object called `compile.proxy` to determine when the generated sources are out of date and need to be re-compiled.
**Install the files (install)**
**Install the files (install)**
At install time, the mex files are put into place at `${CMAKE_INSTALL_PREFIX}/matlab` and their linkages updated.
At install time, the mex files are put into place at `${CMAKE_INSTALL_PREFIX}/matlab` and their linkages updated.
...
@@ -259,32 +259,32 @@ Thus the style and layout of the view is kept separate from the content (model).
...
@@ -259,32 +259,32 @@ Thus the style and layout of the view is kept separate from the content (model).
File Reference
File Reference
--------------
--------------
**gen_matlab.py**
**gen_matlab.py**
gen_matlab has the following call signature:
gen_matlab has the following call signature:
gen_matlab.py --hdrparser path/to/hdr_parser/dir
gen_matlab.py --hdrparser path/to/hdr_parser/dir
--rstparser path/to/rst_parser/dir
--rstparser path/to/rst_parser/dir
--moduleroot path/to/opencv/modules
--moduleroot path/to/opencv/modules
--modules core imgproc highgui etc
--modules core imgproc highgui etc
--extra namespace=/additional/header/to/parse
--extra namespace=/additional/header/to/parse
--outdir /path/to/place/generated/src
--outdir /path/to/place/generated/src
**build_info.py**
**build_info.py**
build_info has the following call signature:
build_info has the following call signature:
build_info.py --os operating_system_string
build_info.py --os operating_system_string
--arch bitness processor
--arch bitness processor
--compiler id version
--compiler id version
--mex_arch arch_string
--mex_arch arch_string
--mex_script /path/to/mex/script
--mex_script /path/to/mex/script
--cxx_flags -list -of -flags -to -passthrough
--cxx_flags -list -of -flags -to -passthrough
--opencv_version version_string
--opencv_version version_string
--commit commit_hash_if_using_git
--commit commit_hash_if_using_git
--modules core imgproc highgui etc
--modules core imgproc highgui etc
--configuration Debug/Release
--configuration Debug/Release
--outdir path/to/place/build/info
--outdir path/to/place/build/info
**parse_tree.py**
**parse_tree.py**
To build a parse tree, first parse a set of headers, then invoke the parse tree to refactor the output:
To build a parse tree, first parse a set of headers, then invoke the parse tree to refactor the output:
```python
```python
...
@@ -304,20 +304,20 @@ for namespace in parse_tree.namespaces:
...
@@ -304,20 +304,20 @@ for namespace in parse_tree.namespaces:
# do stuff
# do stuff
```
```
**mxarray.hpp**
**mxarray.hpp**
mxarray.hpp defines a class called `MxArray` which provides an OOP-style interface for Matlab's homogeneous `mxArray*` type. To create an `MxArray`, you can either inherit an existing array
mxarray.hpp defines a class called `MxArray` which provides an OOP-style interface for Matlab's homogeneous `mxArray*` type. To create an `MxArray`, you can either inherit an existing array
The bridge interface defines a `Bridge` class which provides type conversion between std/OpenCV and Matlab types. A type conversion must provide the following:
The bridge interface defines a `Bridge` class which provides type conversion between std/OpenCV and Matlab types. A type conversion must provide the following:
The binding generator will then automatically call the conversion operators (either explicitly or implicitly) if your `MyObject` class is encountered as an input or return from a parsed definition.
The binding generator will then automatically call the conversion operators (either explicitly or implicitly) if your `MyObject` class is encountered as an input or return from a parsed definition.
