/*************************************************************************
 * cimgmatlab.h
 * -------------
 *
 * cimgmatlab.h  is a "plugin" for the CImg library that allows to convert
 * CImg<T> images from/to MATLAB arrays, so that CImg can be used to write
 * MATLAB mex files.  It also swaps the "x" and "y" coordinates when going
 * from / to MATLAB array, i.e. the usual image-processing annoying MATLAB
 * behaviour of considering images as matrices.
 *
 * Added to the CImg<T> class are:
 *
 *  - a constructor : CImg(const mxArray *matlabArray, bool vdata = false)
 *    the vdata  serves  to  decide  whether a 3D matlab array should give
 *    rise to a 3D CImg object or a "2D vectorial" one.
 *
 *  - a assignment operator : CImg & operator=(const mxArray *matlabArray)
 *    (I use myself extremely seldom and might remove it in the future).
 *
 *  - a routine converting a CImg image to a matlab array:
 *    mxArray *toMatlab(mxClassID classID = mxDOUBLE_CLASS,
 *                      bool squeeze = false) const
 *    the squeeze argument serves the opposite purpose than the vdata from
 *    the constructor.
 *
 * For a  bit  more documentation, the manual is this header, see the more
 * detailed comments in the source code (i.e. RTFM)
 *
 *
 * Its usage should be straightforward:
 *
 * - file cimgmatlab.h must be in a directory that the compiler can locate.
 * - prior to include CImg.h, mex.h  must  be  included first, else it will
 *   result in a compiler error.
 * - after the inclusion of mex.h, one must define the macro cimg_plugin as
 *   "cimgmatlab.h"  or  <cimgmatlab.h> or  <CImg/plugins/cimgmatlab.h>  or
 *   a variation that  matches your  local installation of CImg package and
 *   plugins probably via the appropriate specification of the include path
 *   "-Ipath/to/cimg/and/plugins" at mex cmdline.
 *
 * You would probably have this kind of declaration:
 *
 * // The begining of my fantastic mex file code...
 * #include <mex.h>
 * ...
 * #define cimg_plugin  <cimgmatlab.h>
 * #include <CImg.h>
 * ...
 * // and now I can implement my new killer MATLAB function!
 * ....
 *
 *
 * Copyright (c) 2004-2008 Francois Lauze
 * Licence: the Gnu Lesser General Public License
 * http://www.gnu.org/licenses/lgpl.html
 *
 * MATLAB is copyright of The MathWorks, Inc, http://www.mathworks.com
 *
 * Any comments, improvements and potential bug corrections are welcome, so
 * write to  me at francois@diku.dk, or use CImg forums, I promise I'll try
 * to read them once in a while. BTW who modified the cpMatlabData with the
 * cimg::type<t>::is_float() test (good idea!)
 *
 ***************************************************************************/

#define CIMGMATLAB_VER 0102
#ifndef mex_h
#error the file mex.h must be included prior to inclusion of cimgmatlab.h
#endif
#ifndef cimg_version
#error cimgmatlab.h requires that CImg.h is included!
#endif

/**********************************************************
 * introduction of mwSize and mwIndex types in relatively *
 * recent versions of matlab, 7.3.0 from what I gathered. *
 * here is hopefully a needed fix for older versions      *
 **********************************************************/
#if !defined(MX_API_VER) ||  MX_API_VER < 0x7030000
typedef int mwSize;
#endif

/*********************************************************
 * begin of included methods                             *
 * They are just added as member functions / constructor *
 * for the CImg<T> class.                                *
 *********************************************************/

private:
    /**********************************************************************
     * internally used to transfer MATLAB array values to CImg<> objects,
     * check wether the array type is a "numerical" one (including logical)
     */
    static int isNumericalClassID(mxClassID id)
    {
        // all these constants are defined in matrix.h included by mex.h
        switch (id) {
        case mxLOGICAL_CLASS:
        case mxDOUBLE_CLASS:
        case mxSINGLE_CLASS:
        case mxINT8_CLASS:
        case mxUINT8_CLASS:
        case mxINT16_CLASS:
        case mxUINT16_CLASS:
        case mxINT32_CLASS:
        case mxUINT32_CLASS:
        case mxINT64_CLASS:
        case mxUINT64_CLASS:
            return 1;
        default:
            return 0;
        }
    }

    /***************************************************
     * driving routine that will copy the content of
     * a MATLAB array to this->data
     * The type names used are defined in matlab c/c++
     * header file tmwtypes.h
     */
    void makeImageFromMatlabData(const mxArray *matlabArray, mxClassID classID)
    {
        if (classID == mxLOGICAL_CLASS)
        {
            // logical type works a bit differently than the numerical types
            mxLogical *mdata = mxGetLogicals(matlabArray);
            cpMatlabData((const mxLogical *)mdata);
        }
        else
        {
            void *mdata = (void *)mxGetPr(matlabArray);

            switch (classID) {
            case mxDOUBLE_CLASS:
                cpMatlabData((const real64_T *)mdata);
                break;
            case mxSINGLE_CLASS:
                cpMatlabData((const real32_T *)mdata);
                break;
            case mxINT8_CLASS:
                cpMatlabData((const int8_T *)mdata);
                break;
            case mxUINT8_CLASS:
                cpMatlabData((const uint8_T *)mdata);
                break;
            case mxINT16_CLASS:
                cpMatlabData((const int16_T *)mdata);
                break;
            case mxUINT16_CLASS:
                cpMatlabData((const uint16_T *)mdata);
                break;
            case mxINT32_CLASS:
                cpMatlabData((const int32_T *)mdata);
                break;
            case mxUINT32_CLASS:
                cpMatlabData((const uint32_T *)mdata);
                break;
            case mxINT64_CLASS:
                cpMatlabData((const int64_T *)mdata);
                break;
            case mxUINT64_CLASS:
                cpMatlabData((const uint64_T *)mdata);
                break;
            }
        }
    }

    /***********************************************************
     * the actual memory copy and base type conversion is then
     * performed by this routine that handles the annoying x-y
     * problem of MATLAB when dealing with images: we switch
     * line and column storage: the MATLAB A(x,y) becomes the
     * CImg img(y,x)
     */
    template <typename t> void cpMatlabData(const t* mdata)
    {
        if (cimg::type<t>::is_float())
        {
            cimg_forXYZV(*this, x, y, z, v)
            {
                (*this)(x, y, z, v) = (T)(mdata[((v*depth + z)*width+x)*height+y]);
            }
        }
        else
        {
            cimg_forXYZV(*this, x, y, z, v)
            {
                (*this)(x, y, z, v) = (T)(int)(mdata[((v*depth + z)*width+x)*height+y]);
            }
        }
    }

public:

    /******************************************************************
     * Consruct a CImg<T> object from a MATLAB mxArray.
     * The MATLAB array must be AT MOST 4-dimensional. The boolean
     * argument vdata is employed in the case the the input mxArray
     * has dimension 3, say M x N x K. In that case, if vdata is true,
     * the last dimension is assumed to be "vectorial" and the
     * resulting CImg<T> object has dimension N x M x 1 x K. Otherwise,
     * the resulting object has dimension N x M x K x 1.
     * When MATLAB array has dimension 2 or 4, vdata has no effects.
     * No shared memory mechanisms are used, it would be the easiest
     * to crash Matlab (from my own experience...)
     */
    CImg(const mxArray *matlabArray, bool vdata = false)
    : is_shared(false)
    {
        mwSize nbdims = mxGetNumberOfDimensions(matlabArray);
        mxClassID classID = mxGetClassID(matlabArray);
        if (nbdims > 4 || !isNumericalClassID(classID))
        {
            data=NULL;
            width=height=depth=dim=0;
#if cimg_debug>1
            cimg::warn("MATLAB array is more than 4D or/and "
                       "not numerical, returning null image.");
#endif
        }
        else
        {
            const mwSize *dims = mxGetDimensions(matlabArray);
            depth = dim = 1;
            width =  (unsigned)dims[1];
            height = (unsigned)dims[0];
            if (nbdims == 4)
            {
                depth = (unsigned)dims[2];
                dim =   (unsigned)dims[3];
            }
            else if (nbdims == 3)
            {
                if (vdata)
                {
                    dim = (unsigned)dims[2];
                }
                else
                {
                    depth = (unsigned)dims[2];
                }
            }

            data = new T[size()];
            makeImageFromMatlabData(matlabArray, classID);
        }
    }

    /*******************************************************************
     * operator=(). Copy  mxMarray data mArray into the current image
     * Works as the previous constructor, but without the vdata stuff.
     * don't know if it is of any use...
     */
    CImg & operator=(const mxArray *matlabArray)
    {
        int nbdims = (int)mxGetNumberOfDimensions(matlabArray);
        int classID = mxGetClassID(matlabArray);
        if (nbdims > 4 || !isNumericalClassID(classID))
        {
            delete [] data;
            data = NULL;
            width=height=depth=dim=0;
#if cimg_debug>1
            cimg::warn("MATLAB array is more than 4D or/and "
                       "not numerical, returning null image.");
#endif
        }
        else
        {
            const mwSize *dims = mxGetDimensions(matlabArray);
            depth = dim = 1;
            width =  (unsigned)dims[1];
            height = (unsigned)dims[0];
            if (nbdims > 2)
            {
                depth = (unsigned)dims[2];
            }
            if (nbdims > 3)
            {
                dim = (unsigned)dims[3];
            }

            delete [] data;
            data = new T[size()];

            makeImageFromMatlabData(matlabArray, classID);
        }
    }

private:
    /*****************************************************************
     * private routines used for transfering a CImg<T> to a mxArray
     * here also, we have to exchange the x and y dims so we get the
     * expected MATLAB array.
     */
    template <typename c> void populate_maltlab_array(c *mdata) const
    {
        cimg_forXYZV(*this, x, y, z, v)
        {
            mdata[((v*depth + z)*width+x)*height+y] = (c)(*this)(x, y, z, v);
        }
    }

    /*************************************************
     * the specialized version for "logical" entries
     */
    void populate_maltlab_array(mxLogical *mdata) const
    {
        cimg_forXYZV(*this, x, y, z, v)
        {
            mdata[((v*depth + z)*width+x)*height+y] = (mxLogical)((*this)(x, y, z, v)!=0);
        }
    }

public:
    /******************************************
     * export a CImg image to a MATLAB array.
     **/
    mxArray *toMatlab(mxClassID classID = mxDOUBLE_CLASS, bool squeeze = false) const
    {
        if (!isNumericalClassID(classID))
        {
#if cimg_debug>1
            cimg::warn("Invalid MATLAB Class Id Specified.");
#endif
            return NULL;
        }

        mwSize dims[4];
        dims[0] = (mwSize)height;
        dims[1] = (mwSize)width;
        dims[2] = (mwSize)depth;
        dims[3] = (mwSize)dim;

        if (squeeze && depth == 1)
        {
            dims[2] = (mwSize)dim;
            dims[3] = (mwSize)1;
        }

        mxArray *matlabArray = mxCreateNumericArray((mwSize)4, dims, classID, mxREAL);

        if (classID == mxLOGICAL_CLASS)
        {
            mxLogical *mdata = mxGetLogicals(matlabArray);
            populate_maltlab_array(mdata);
        }
        else
        {
            void *mdata = mxGetPr(matlabArray);
            switch (classID) {
            case mxDOUBLE_CLASS:
                populate_maltlab_array((real64_T *)mdata);
                break;
            case mxSINGLE_CLASS:
                populate_maltlab_array((real32_T *)mdata);
                break;
            case mxINT8_CLASS:
                populate_maltlab_array((int8_T *)mdata);
                break;
            case mxUINT8_CLASS:
                populate_maltlab_array((uint8_T *)mdata);
                break;
            case mxINT16_CLASS:
                populate_maltlab_array((int16_T *)mdata);
                break;
            case mxUINT16_CLASS:
                populate_maltlab_array((uint16_T *)mdata);
                break;
            case mxINT32_CLASS:
                populate_maltlab_array((int32_T *)mdata);
                break;
            case mxUINT32_CLASS:
                populate_maltlab_array((uint32_T *)mdata);
                break;
            case mxINT64_CLASS:
                populate_maltlab_array((int64_T *)mdata);
                break;
            case mxUINT64_CLASS:
                populate_maltlab_array((uint64_T *)mdata);
                break;
            }
        }
        return matlabArray;
    }

// end of cimgmatlab.h