From 2ac31a87c9447de1aca1548e30584f3c4a7166d4 Mon Sep 17 00:00:00 2001
From: hbristow <hilton.bristow@gmail.com>
Date: Wed, 28 Aug 2013 17:40:20 +1000
Subject: [PATCH] Added tutorial for writing your own mex files

---
 modules/matlab/README.md | 54 +++++++++++++++++++++++++++++++++++++++-
 1 file changed, 53 insertions(+), 1 deletion(-)

diff --git a/modules/matlab/README.md b/modules/matlab/README.md
index 7871b31b8..1167a5e0e 100644
--- a/modules/matlab/README.md
+++ b/modules/matlab/README.md
@@ -46,6 +46,58 @@ to get general help regarding the OpenCV bindings. If you ever run into issues w
 	
 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
+--------------------------
+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:
+
+    // include useful constructs 
+    // this automatically includes opencv core.hpp and mex.h)
+    #include <opencv2/matlab/bridge.hpp>
+    using namespace cv;
+    using namespace std;
+
+    // define the mex gateway
+    void mexFunction(int nlhs, mxArray* plhs[],
+                     int nrhs, const mxArray* prhs[]) {
+
+      // claim the inputs into scoped management
+      MxArrayVector raw_inputs(prhs, prhs+nrhs);
+
+      // add an argument parser to automatically handle basic options
+      ArgumentParser parser("my function");
+      parser.addVariant(1, 1, "opt");
+      MxArrayVector parsed_inputs = parser.parse(inputs);
+
+      // if we get here, we know the inputs are valid. Unpack...
+      BridgeVector inputs(parsed_inputs);
+      Mat required    = inputs[0].toMat();
+      string optional = inputs[1].empty() ? "Default string" : inputs[1].toString();
+
+      try {
+        // Do stuff...
+      } catch(Exception& e) {
+        error(e.what());
+      } catch(...) {
+        error("Uncaught exception occurred");
+      }
+
+      // allocate an output
+      Bridge out = required;
+      plhs[0] = out.toMxArray().releaseOwnership();
+    }
+
+There are a couple of important things going on in this example. Firstly, you need to include `<opencv2/matlab/bridge.hpp>` to enable the bridging capabilities. Once you've done this, you get some nice utilities for free. `MxArray` is a class that wraps Matlab's `mxArray*` class in an OOP-style interface. `ArgumentParser` is a class that handles default, optional and named arguments for you, along with multiple possible calling syntaxes. Finally, `Bridge` is a class that allows bidirectional conversions between OpenCV/std and Matlab types.
+
+Once you have written your file, it can be compiled with the provided mex utility:
+    
+    cv.mex('my_function.cpp');
+
+This utility automatically links in all of the necessary OpenCV libraries to make your function work.
+
+NOTE: OpenCV uses exceptions throughout the codebase. It is a **very** good idea to wrap your code in exception handlers to avoid crashing Matlab in the event of an exception being thrown.
+
 ------------------------------------------------------------------
 
 
@@ -271,4 +323,4 @@ The bridge interface defines a `Bridge` class which provides type conversion bet
 	MyObject toMyObject();
 	operator MyObject();
 	
-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.
\ No newline at end of file
+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.