jmehami1/mex_cmake

Tutorial for compiling MATLAB MEX functions using cmake

MATLAB MEX tutorial using CMake

---

Table of Contents

• About
• Requirements
• File Extensions
• MEX Applications
• Building MEX with CMake
• Project 1: Sum of array elements
• Project 2: Edit images using openCV
• Project 3: Edit pointclouds using Eigen library
• TODO
• License
• Contact
• Acknowledgments

---

About

A small introduction tutorial to MATLAB's MEX applications, which are used for interfacing and running C/C++ programs inside of MATLAB.

(back to top)

Requirements

• MATLAB 2018a or higher (Tested with 2021b)
• GCC 7.0 or higher (Tested with 7.5.0)
• OpenCV 4.0 or higher
• CMake
• libeigen3-dev

You will need compatible gcc and g++ compilers to build MEX functions as listed here.

File Extensions

Summary of important file extensions from MATLAB and C++

File Extension	Description
.m	MATLAB script or function
.mlx	MATLAB live script or live function
.cpp	C++ Implementation file
.h	C++ header file
.mexa64	MEX function built in 64-bit Linux
.mexmaci64	MEX function built in 64-bit Mac
.mexw64	MEX function built in 64-bit Windows

Built MEX functions cannot be shared between different OS, and in many cases, cannot be shared between PCs with the same OS.

MEX Applications

There are two ways to write MEX applications:

1. C Matrix API

   #include "mex.h"
   
   void mexFunction(int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[]){
       /*
         Implemented MEX function
       /*
   };

NOTE:

• mexFunction function is the entry point into the MEX application from MATLAB. It must be present with that exact name.

• Link to the C/C++ API can be found here.

• Inputs and outputs from the function are stored as mxArray data structure. The data structure holds information such type, size (dimensions), is complex flag, and etc.

You would call the MEX function in MATLAB as follows:

[output1, output2, ...] = SomeFunction(input1, input2, ...);

Variable	Description
nlhs	Number of elements on the left-hand side (number of outputs expected by MATLAB)
*plhs[]	Array of pointers to the left-hand side outputs
nrhs	Number of elements on the right-hand side (number of inputs passed in by MATLAB)
*prhs[]	Array of pointers to the right-hand side outputs

2. C++ MEX API (newer)

   (Had issues working with this. I would suggest to stick with C MATRIX API)

   #include "mex.hpp"
   #include "mexAdapter.hpp"
   
   using matlab::mex::ArgumentList;
   using namespace matlab::data;
   
   class MexFunction : public matlab::mex::Function {
       std::shared_ptr<matlab::engine::MATLABEngine> matlabPtr = getEngine();
   public:
       void operator()(ArgumentList outputs, ArgumentList inputs) {
           
       }
   };

   Note: MexFunction class is the entry point into the MEX application from MATLAB. It must be present with that exact name.

Building MEX with CMake

Inspect the CMakeLists.txt files inside of the example projects to see further details and CMake syntax. To build a MEX function, follow these instructions:

1. Create a build directory inside the project directory.
2. In a terminal pointing to build run the following:

cmake ..
make

The built MEX function can be found in the bin directory.

Note: You may get a warning about gcc or g++ version being incompatible with the MEX compiler. The MEX function should still have been built.

Project 1: Sum of array elements

Create a MEX function which returns the sum of all elements of a passed in array.

In MATLAB we should call the function like this:

arrSum = SumOfArrElements(arr);

Project 2: Edit images using openCV

Obviously MATLAB can read in images and edit, but lets create a MEX file which edits an image using openCV and returns the edited image to MATLAB.

In MATLAB we should call the function like this:

imgEdit = OpenCV_Edit(img);

Project 3: Edit pointclouds using Eigen library

Obviously MATLAB can load pointclouds and edit them, but lets create a MEX file which edits a pointcloud using the C++ Eigen library and returns the edited pointcloud to MATLAB.

In MATLAB we should call the function like this:

modified_cloud = eigen_pointcloud(point_cloud, source_correspondences, target_correspondences);

TODO

• Check if MEX C++ API is working now

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Contact

Jasprabhjit Mehami

Email: [email protected]

(back to top)

Acknowledgments

• Eigen Library

• OpenCV

(back to top)