mirror of
https://github.com/opencv/opencv.git
synced 2024-12-11 22:59:16 +08:00
68 lines
2.9 KiB
Plaintext
68 lines
2.9 KiB
Plaintext
|
-------------------------------------------------------------------------------
|
||
|
|
MATLAB WRAPPER GENERATOR
|
||
|
|
-------------------------------------------------------------------------------
|
||
|
|
|
||
|
|
Author: Hilton Bristow
|
||
|
|
Module: matlab
|
||
|
|
Depends: Matlab, python
|
||
|
|
Inputs: Module headers (<name>/include/opencv2/<name>/<name>.hpp)
|
||
|
|
Outputs: mex libraries wrapping OpenCV functionality
|
||
|
|
Date: 2013 Google Summer of Code (GSOC)
|
||
|
|
|
||
|
|
This module is designed to automatically generate Matlab mex wrappers for
|
||
|
|
other modules within the OpenCV library. Once compiled and added to the Matlab
|
||
|
|
path, this gives uses the ability to call OpenCV functions natively from within
|
||
|
|
Matlab. Further, it acts as a gateway to writing much more expressive mex
|
||
|
|
files, since all the core matrix expressions and arithmetic of OpenCV can
|
||
|
|
be used.
|
||
|
|
|
||
|
|
The generation of Matlab mex wrappers consists of 5 phases. Each phase is
|
||
|
|
explained below, along with information about when the phase is called, the
|
||
|
|
relevant files acting in the phase, and the outputs:
|
||
|
|
|
||
|
|
1. PARSING EXISTING HEADERS
|
||
|
|
------------------
|
||
|
|
The main parsing entry point is modules/matlab/generator/gen_matlab_caller.py
|
||
|
|
The header parser (modules/python/src2/hdr_parser.py) is invoked on the main
|
||
|
|
header on each module to get a list of symbols that are exported into the
|
||
|
|
public API. This is invoked when cmake is parsing the matlab CMakeLists.txt.
|
||
|
|
|
||
|
|
|
||
|
|
2. REFACTORING PARSE OUTPUT
|
||
|
|
------------------
|
||
|
|
The output from the parser is refactored by modules/matlab/generator/parse_tree.py
|
||
|
|
into a more functional form. This reconstructs the semantic information of
|
||
|
|
the original headers. This is invoked when cmake is parsing the matlab
|
||
|
|
CMakeLists.txt.
|
||
|
|
|
||
|
|
|
||
|
|
3. POPULATING SOURCE TEMPLATES
|
||
|
|
------------------
|
||
|
|
Now that we have the exported definitions (namespaces, classes, structs,
|
||
|
|
functions, constants) we synthesise matlab callable wrappers for each using
|
||
|
|
a templating system. Jinja does most of the heavy lifting, and we populate
|
||
|
|
templates derived from three base templates: template_function_base.cpp,
|
||
|
|
template_class_base.cpp and template_doc_base.m found in
|
||
|
|
modules/matlab/generator/templates. During template population we also
|
||
|
|
map from OpenCV types to Matlab types and visa versa. This is invoked when
|
||
|
|
cmake is parsing the matlab CMakeLists.txt.
|
||
|
|
|
||
|
|
|
||
|
|
4. COMPILE SOURCES
|
||
|
|
------------------
|
||
|
|
We have now done all of the pre-processing work. When make is invoked, we
|
||
|
|
compile each of the mex sources (.cpp) down to executables that can be
|
||
|
|
called from matlab (.mexmaci64, .mexa64, .mexsol, etc) using the mex
|
||
|
|
compile script that was found when searching for Matlab cmake/OpenCVFindMatlab.cmake.
|
||
|
|
|
||
|
|
|
||
|
|
5. INSTALL
|
||
|
|
------------------
|
||
|
|
When make install is invoked, we install the following:
|
||
|
|
mex: ${INSTALL_DIR}/lib/matlab/+cv
|
||
|
|
docs: ${INSTALL_DIR}/doc/matlab/cv
|
||
|
|
|
||
|
|
The preceding '+' on the lib install path acts as pseudo namespacing within
|
||
|
|
Matlab. This makes functions/classes callable with the 'cv.' prefix
|
||
|
|
e.g. E = cv.sobel(I); and prevents the global namespace from being trashed
|