MatLabInterface.hh

#ifndef __MATLABINTERFACE_HH__
#define __MATLABINTERFACE_HH__

/* This file is part of the BIAS library (Basic ImageAlgorithmS).

   Copyright (C) 2003-2009    (see file CONTACT for details)
   Multimediale Systeme der Informationsverarbeitung
   Institut fuer Informatik
   Christian-Albrechts-Universitaet Kiel
   
   
   BIAS is free software; you can redistribute it and/or modify
   it under the terms of the GNU Lesser General Public License as published by
   the Free Software Foundation; either version 2.1 of the License, or
   (at your option) any later version.
   
   BIAS is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU Lesser General Public License for more details.
   
   You should have received a copy of the GNU Lesser General Public License
   along with BIAS; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*/

/******************************************************************************/

/**
 * This header file provides some functions (and a little howto) that should 
 * make the usage of BIAS-libraries from within MATLAB ((C) by The MathWorks)
 * a bit easier.
 * 
 * All that is needed to be done to use C/C++ code from within MATLAB is to
 * write a small (shared) library -called mex-file- that exports the the 
 * function:
 *
 *    void mexFunction(int nlhs, mxArray *plhs[], 
 *                     int nrhs, const mxArray *prhs[])
 *
 * param nlhs: the number of returned vectors/matrices
 * param plhs: array of pointers to the returned vectors/matrices
 *
 * param nrhs: the number of vectors/matrices taken as arguments
 * param prhs: array of pointers to the vectors/matrices taken as arguments
 *
 * This function correspondes to a call from MATLAB:
 *   [ plhs[0] .. plhs[nlhs-1] ] = mexFileName(prhs[0], .. , prhs[nrhs-1])
 *
 * When the lib has been build (e.g. libMyLib.so) you'll have to rename it to
 * the form NameOfYourFunc.mexglx (Linux) or NameOfYourFunc.dll (Windows). 
 * Afterwards copy it to your matlab workspace folder. 
 * Be shure that MATLAB is able to find all libs needed to run your mex-file.
 * For Linux you might include the BIAS-library path in the LD_LIBRARY_PATH 
 * environment variable. Also it's advisable to include the standard-c libraries
 * into the lib-path (e.g. /usr/lib/ for linux) because else MATLAB might load
 * wrong dependencies.
 *
 * See the Examples-directory for a simple mex-library example.
 * 
 * IMPORTANT: For now there's a problem with the OpenMP-library to be loaded
 *            by MATLAB. So be sure to turn off OpenMP in BIAS (->CMake).
 *
 * Author: apetersen 04/04/2008
 *
 * TODO:
 *   -let libExampleMEX.so be copied/moved to ./Examples dir with correct name
 *    (e.g. matMult.mexglx)
 *   -get OpenMP running (should be possible)
 *   -test for windows-builds
 */

//get all definitions
#include <bias_config.h>


//OpenMP-library not loadable under MATLAB (for now)
#ifdef BIAS_HAVE_OPENMP
#  error MATLAB cannot load OpenMP-lib, please re-configure with USE_OPENMP=OFF
#endif //BIAS_HAVE_OPENMP


#ifndef BIAS_HAVE_MATLAB
#  error MATLAB mex-headers are needed, please re-configure with USE_MATLAB=ON
#endif //BIAS_HAVE_MATLAB


/** The definitions for MATLAB's functions and datatypes */
#include <mex.h>

#include <Base/Math/Vector.hh>
#include <Base/Math/Matrix.hh>

/** Use this to deliver error msgs to MATLAB (stops execution) */
#define MATLABERR(x) mexErrMsgTxt(x)

/** Use this to deliver warning msgs to MATLAB (execution continues) */
#define MATLABWARN(x) mexWarnMsgTxt(x)

// Some functions for converting types (see example) 

namespace BIAS {
  
  /** @brief Convert MATLAB-array to BIAS::Vector */
  inline int MxArrToBIASVector(const mxArray* mxVec, 
                               BIAS::Vector<double> &vec)
  {
    if (mxVec == NULL) {
      BIASERR("Given mxArray-pointer is NULL!");
      return -1;
    }

    //be sure we have real-valued variables with double precision
    if (!mxIsDouble(mxVec) || mxIsComplex(mxVec)) {
      BIASERR("Input is complex or not of double precision!");
      return -2;
    }

    const unsigned int m = mxGetM(mxVec);
    const unsigned int n = mxGetN(mxVec);

    //be sure we have a vector (mx1 or 1xn)
    if (m!=1 && n!=1) {
      BIASERR("Input is no vector, dim: " <<m<< "x" <<n<<" !");
      return -3;
    }

    //resize vec and copy values
    vec.newsize((m>n)?m:n);
    for (unsigned int i=0; i<((m>n)?m:n); i++)
      vec[i] = mxGetPr(mxVec)[i];

    return 0;
  }

  /** @brief Convert MATLAB-array to BIAS::Matrix */
  inline int MxArrToBIASMatrix(const mxArray* mxMat,
                               BIAS::Matrix<double> &mat)
  {
    if (mxMat == NULL) {
      BIASERR("Given mxArray-pointer is NULL!");
      return -1;
    }

    //be sure we have real-valued variables with double precision
    if (!mxIsDouble(mxMat) || mxIsComplex(mxMat)) {
      BIASERR("Input is complex or not of double precision!");
      return -2;
    }

    const unsigned int m = mxGetM(mxMat);
    const unsigned int n = mxGetN(mxMat);

    //resize vec and copy values
    mat.newsize(m ,n);
    const double* in = mxGetPr(mxMat);
    for (unsigned int j=0; j<n; j++)
      for (unsigned int i=0; i<m; i++)
        mat[i][j] = in[j*m + i];//mxArrays ist 'serialized' in columns

    return 0;
  }

  /** @brief Convert BIAS::Vector to MATLAB-array, inclusive allocation! */
  inline int BIASVectorToMxArr(const BIAS::Vector<double> &vec,
                               mxArray* &mxVec)
  {
    if (mxVec != NULL) {
      BIASERR("Given mxArray-pointer is not NULL, memory leak possible!");
      return -1;
    }

    mxVec = mxCreateDoubleMatrix(vec.Size(), 1, mxREAL);

    if (mxVec == NULL) {
      BIASERR("Error allocating mxArray, with (m,n)=("<<vec.Size()
              <<","<<1<<")");
      return -2;
    }

    for (unsigned int i=0; i<vec.Size(); i++)
      mxGetPr(mxVec)[i] = vec[i];

    return 0;
  }

  /** @brief Convert BIAS::Matrix to MATLAB-array, inclusive allocation! */
  inline int BIASMatrixToMxArr(const BIAS::Matrix<double> &mat,
                               mxArray* &mxMat)
  {
    if (mxMat != NULL) {
      BIASERR("Given mxArray-pointer is not NULL, memory leak possible!");
      return -1;
    }

    unsigned int m = mat.GetRows();
    unsigned int n = mat.GetCols();

    mxMat = mxCreateDoubleMatrix(m, n, mxREAL);

    if (mxMat == NULL) {
      BIASERR("Error allocating mxArray, with (m,n)=("<<m<<","<<n<<")");
      return -2;
    }

    for (unsigned int j=0; j<n; j++)
      for (unsigned int i=0; i<m; i++)
        mxGetPr(mxMat)[j*m + i] = mat[i][j];

    return 0;
  }

} //namespace BIAS

#endif //__MATLABINTERFACE_HH__