From c29a98ef8405368b86086dd41da0aa273abfbc36 Mon Sep 17 00:00:00 2001
From: Hilton Bristow <hilton.bristow@gmail.com>
Date: Fri, 15 Mar 2013 00:02:51 +1000
Subject: [PATCH] Added README

---
 modules/matlab/README | 67 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 modules/matlab/README

diff --git a/modules/matlab/README b/modules/matlab/README
new file mode 100644
index 0000000000..1e0114a39e
--- /dev/null
+++ b/modules/matlab/README
@@ -0,0 +1,67 @@
+-------------------------------------------------------------------------------
+                          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