opencv/modules/matlab/README

-------------------------------------------------------------------------------
                          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