dml::MatlabInterface class

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

Contents

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.

Base classes

class dip::ExternalInterface abstract
Support for external interfaces.

Functions

auto AllocateData(void*& origin, dip::DataType datatype, dip::UnsignedArray const& sizes, dip::IntegerArray& strides, dip::Tensor const& tensor, dip::sint& tstride) -> dip::DataSegment override
This function overrides dip::ExternalInterface::AllocateData.
auto NewImage() -> dip::Image
Constructs a dip::Image object with the external interface set so that, when forged, a MATLAB mxArray will be allocated to hold the samples.

Function documentation

dip::DataSegment AllocateData(void*& origin, dip::DataType datatype, dip::UnsignedArray const& sizes, dip::IntegerArray& strides, dip::Tensor const& tensor, dip::sint& tstride) override

This function overrides dip::ExternalInterface::AllocateData.

It is called when an image with this ExternalInterface is forged. It allocates a MATLAB mxArray and returns a dip::DataSegment containing a pointer to the mxArray data pointer, with a custom deleter functor. It also adjusts strides to match the mxArray storage.

A user will never call this function directly.

dip::Image NewImage()

Constructs a dip::Image object with the external interface set so that, when forged, a MATLAB mxArray will be allocated to hold the samples.

Use dml::GetArray to obtain the mxArray and assign it as a lhs argument to your MEX-file.