/** \mainpage
\brief Collection of mex functions for OpenCV library
\author Kota Yamaguchi
\date   March 2012

http://www.cs.stonybrook.edu/~kyamagu/mexopencv/

\section development Developing a new mex function

All you need to do is to add your mex source file in \c src/+cv/. If you
want to add a mex function called myfunc, create \c src/+cv/myfunc.cpp.
The minimum contents of the myfunc.cpp would look like this:

\code
    #include "mexopencv.hpp"
    void mexFunction( int nlhs, mxArray *plhs[],
                      int nrhs, const mxArray *prhs[] )
    {
    	// Check arguments
        if (nlhs!=1 || nrhs!=1)
            mexErrMsgIdAndTxt("myfunc:invalidArgs","Wrong number of arguments");
        
        // Convert MxArray to cv::Mat
        cv::Mat mat = MxArray(prhs[0]).toMat();
        
        // Do whatever you want
        
        // Convert cv::Mat back to mxArray*
        plhs[0] = MxArray(mat);
    }
\endcode

This example simply copies an input to cv::Mat object and then copies again to
the output. Notice how the \c MxArray class provided by mexopencv converts
mxArray to cv::Mat object. Of course you would want to do something more with
the object. Once you create a file, type \c cv.make to build your new function. The
compiled mex function will be located inside \c +cv/ and accessible through
\c cv.myfunc within matlab.

The \c mexopencv.hpp header includes a class \c MxArray to manipulate \c mxArray
object. Mostly this class is used to convert between opencv data types and
\c mxArray.

\code
    int i            = MxArray(prhs[0]).toInt();
    double d         = MxArray(prhs[0]).toDouble();
    bool b           = MxArray(prhs[0]).toBool();
    std::string s    = MxArray(prhs[0]).toString();
    cv::Mat mat      = MxArray(prhs[0]).toMat();   // For pixels
    cv::Mat ndmat    = MxArray(prhs[0]).toMatND(); // For N-D array
    cv::Point pt     = MxArray(prhs[0]).toPoint();
    cv::Size siz     = MxArray(prhs[0]).toSize();
    cv::Rect rct     = MxArray(prhs[0]).toRect();
    cv::Scalar sc    = MxArray(prhs[0]).toScalar();
    cv::SparseMat sp = MxArray(prhs[0]).toSparseMat(); // Only double to float
\endcode
\code
    mxArray* plhs[0] = MxArray(i);
    mxArray* plhs[0] = MxArray(d);
    mxArray* plhs[0] = MxArray(b);
    mxArray* plhs[0] = MxArray(s);
    mxArray* plhs[0] = MxArray(mat);
    mxArray* plhs[0] = MxArray(ndmat);
    mxArray* plhs[0] = MxArray(pt);
    mxArray* plhs[0] = MxArray(siz);
    mxArray* plhs[0] = MxArray(rct);
    mxArray* plhs[0] = MxArray(sc);
    mxArray* plhs[0] = MxArray(sp); // Only 2D float to double
\endcode

Check \c MxArraay.hpp for the complete list of conversion API.

If you rather want to develop a matlab function that internally calls a mex
function, make use of the \c +cv/private directory. Any function placed under
private directory is only accessible from \c +cv/ directory. So, for example,
when you want to design a matlab class that wraps the various behavior of the
mex function, define your class at \c +cv/MyClass.m and develop a mex function
dedicated for that class in \c src/+cv/private/MyClass_.cpp . Inside of
\c +cv/MyClass.m, you can call \c MyClass_() without cv namescope.


\section testing Testing

Optionally, you can add a testing script for your new function. The testing
convention in mexopencv is that testing scripts are all written as a static
function in a matlab class. For example, \c test/unit_tests/TestFilter2D.m is
a class that describes test cases for filter2d function. Inside of the class,
a couple of test cases are written as a static function whose name starts with
'test'.

If there is such a class inside \c test/unit_tests/ , typing `make test` would
invoke all test cases and show your result. Use \c test/ directory to place any
resource file necessary for testing. An example of testing class is shown below:

\code
    classdef TestMyFunc
        methods (Static)
            function test_1
                src = imread('/path/to/myimg');
                ref = [1,2,3];                  % reference output
                dst = cv.myfunc(src);           % execute your function
                assert(all(dst(:) == ref(:)));  % check the output
            end
            
            function test_error_1
                try
                    cv.myfunc('foo');           % myfunc should throw an error
                    error('UnitTest:Fail','myfunc incorrectly returned');
                catch e
                    assert(strcmp(e.identifier,'mexopencv:error'));
                end
            end
        end
    end
\endcode

In Windows, add path to the \c test directory and invoke \c UnitTest to run all
the test routines.

\section documenting Documenting

You can create a Matlab help documentation for mex function by having the same
file with '.m' extension. For example, on linux 64-bit architecture, the help
file for \c filter2D.mexa64 would be \c filter2D.m. Inside the help file should be
only matlab comments. An example is shown below:

\code
    %MYFUNC  brief description about myfunc
    %
    % Detailed description of function continues
    % ...
\endcode
*/