DIPlib-MATLAB interface module
#include "dip_matlab_interface.h"

dml::MatlabInterface class

This class is the dip::ExternalInterface for the MATLAB interface.

In a MEX-file, use the following code when declaring images to be used as the output to a function:

dml::MatlabInterface mi;
dip::Image img_out0 = mi.NewImage();
dip::Image img_out1 = mi.NewImage();

This configures the images img_out0 and img_out1 such that, when they are forged later on, an mxArray structure will be created to hold the pixel data. mxArray is MATLAB’s representation of arrays. To return those images back to MATLAB, use dml::GetArray, which returns the mxArray created when the image was forged:

plhs[ 0 ] = dm::GetArray( img_out0 );
plhs[ 1 ] = dm::GetArray( img_out1 );

If you don’t use dml::GetArray, the mxArray that contains the pixel data will be destroyed when the dip::Image object goes out of scope.

Note that the dml::MatlabInterface object needs to persist for the duration of the lifetime of the images returned by the NewImage method, since these images hold a pointer to it.

Remember to not assign a result into the images created with NewImage, as the pixel data will be copied in the assignment into a MATLAB array. Instead, use the DIPlib functions that take output images as function arguments:

img_out0 = in1 + in2;           // Bad! Incurs an unnecessary copy
dip::Add( in1, in2, img_out0 ); // Correct, the operation writes directly in the output data segment

In the first case, in1 + in2 is computed into a temporary image, whose pixels are then copied into the mxArray created for img_out0. In the second case, the result of the operation is directly written into the mxArray, no copies are necessary.

This interface handler doesn’t own any image data.