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

Functions to convert image data, function parameters and other arrays to and from MATLAB.

Contents

Namespaces

namespace dml
The dml namespace contains the interface between MATLAB and DIPlib. more...

Classes

class dml::MatlabInterface
This class is the dip::ExternalInterface for the MATLAB interface. more...
class dml::streambuf
An output stream buffer for MEX-files. more...

Enums

enum class dml::ArrayConversionMode: dip::uint8
dml::GetImage can optionally turn an input numeric array to a tensor image. If the numeric array is a short vector (up to 5 elements) or a small matrix (up to 5x5 elements) it will be seen as a 0D tensor image. more...
enum class dml::GetImageMode: dip::uint8
dml::GetImage can optionally create a shared copy of the input mxArray, which extends its lifetime. This is useful if the MEX-file needs to keep a reference to the object. more...

Functions

auto dml::CreateDouble2Vector(dip::dfloat v0, dip::dfloat v1) -> mxArray*
Create a two-element mxArray and write the two values in it.
auto dml::GetArray(bool in) -> mxArray*
Convert an boolean from bool to mxArray by copy.
auto dml::GetArray(dip::uint in) -> mxArray*
Convert an unsigned integer from dip::uint to mxArray by copy.
auto dml::GetArray(dip::sint in) -> mxArray*
Convert a signed integer from dip::sint to mxArray by copy.
auto dml::GetArray(dip::dfloat in) -> mxArray*
Convert a floating-point number from dip::dfloat to mxArray by copy.
auto dml::GetArray(dip::dcomplex in) -> mxArray*
Convert a complex floating-point number from dip::dcomplex to mxArray by copy.
template<typename T, typename <SFINAE>>
auto dml::GetArray(dip::DimensionArray const& in) -> mxArray*
Convert a numeric array from dip::DimensionArray to mxArray by copy. Works for dip::UnsignedArray, dip::IntegerArray and dip::FloatArray.
auto dml::GetArray(dip::CoordinateArray const& in) -> mxArray*
Convert a coordinates array from mxArray to dip::CoordinateArray by copy. more...
auto dml::GetArray(dip::String const& in) -> mxArray*
Convert a string from dip::String to mxArray by copy.
auto dml::GetArray(dip::StringArray const& in) -> mxArray*
Convert a string array from dip::StringArray to mxArray by copy.
auto dml::GetArray(dip::Image::Sample const& in) -> mxArray*
Convert a sample from dip::Image::Sample to mxArray by copy.
auto dml::GetArray(dip::Image::Pixel const& in) -> mxArray*
Convert a set of samples from dip::Image::Pixel to mxArray by copy.
auto dml::GetArray(dip::PixelSize const& pixelSize) -> mxArray*
Convert a pixel size object dip::PixelSize to mxArray by copy.
auto dml::GetArray(dip::FileInformation const& fileInformation) -> mxArray*
Convert a dip::FileInformation structure to mxArray by copy.
auto dml::GetArray(dip::Distribution const& in) -> mxArray*
Convert a dip::Distribution object to mxArray by copy.
auto dml::GetArray(dip::Image const& img, bool doNotSetToTrue = false) -> mxArray*
Find the mxArray that holds the data for the dip::Image img, and create a MATLAB dip_image object around it.
auto dml::GetArrayAsArray(dip::Image const& img, bool doNotSetToTrue = false) -> mxArray*
Find the mxArray that holds the data for the dip::Image img.
auto dml::GetArrayUnicode(dip::String const& in) -> mxArray*
Convert a UTF-8 encoded string from dip::String to mxArray by copy.
auto dml::GetBoolean(mxArray const* mx) -> bool
Convert a boolean (logical) from mxArray to bool by copy. Accepts "yes" and "no" as well.
auto dml::GetBooleanArray(mxArray const* mx) -> dip::BooleanArray
Convert a boolean (logical) array from mxArray to dip::BooleanArray by copy.
auto dml::GetComplex(mxArray const* mx) -> dip::dcomplex
Convert a complex floating-point number from mxArray to dip::dcomplex by copy.
auto dml::GetCoordinateArray(mxArray const* mx) -> dip::CoordinateArray
Convert a coordinates array from mxArray to dip::CoordinateArray by copy. more...
auto dml::GetFloat(mxArray const* mx) -> dip::dfloat
Convert a floating-point number from mxArray to dip::dfloat by copy.
auto dml::GetFloatArray(mxArray const* mx) -> dip::FloatArray
Convert a floating-point array from mxArray to dip::FloatArray by copy.
auto dml::GetFloatCoordinateArray(mxArray const* mx) -> dip::FloatCoordinateArray
Convert a coordinates array from mxArray to dip::FloatCoordinateArray by copy. more...
auto dml::GetHistogramConfiguration(mxArray const* mx) -> dip::Histogram::Configuration
Reads a histogram Configuration struct from a cell mxArray with key-value pairs.
auto dml::GetImage(mxArray const* mx, dml::GetImageMode mode = GetImageMode::REFERENCE, dml::ArrayConversionMode conversion = ArrayConversionMode::STANDARD) -> dip::Image
Passing an mxArray to DIPlib, keeping ownership of the data. more...
auto dml::GetImageArray(mxArray const* mx) -> dip::ImageArray
Convert a cell array of images from mxArray to dip::ImageArray, using dml::GetImage for each element of the cell array.
auto dml::GetInteger(mxArray const* mx) -> dip::sint
Convert a signed integer from mxArray to dip::sint by copy.
auto dml::GetIntegerArray(mxArray const* mx) -> dip::IntegerArray
Convert a signed integer array from mxArray to dip::IntegerArray by copy.
template<typename K>
auto dml::GetKernel(int nrhs, mxArray const*[] prhs, int& index, dip::uint nDims) -> K
Gets a structuring element or kernel from the input argument(s) at index, and index+1. index is updated to point to the next unused input argument.
auto dml::GetPixel(mxArray const* mx) -> dip::Image::Pixel
Convert a numeric array from mxArray to dip::Image::Pixel by copy.
template<typename T>
auto dml::GetPreference(dip::String const& preference) -> T
Get the value of a property, equivalent to calling dipgetpref in MATLAB. more...
auto dml::GetProcessArray(mxArray const* mx, dip::uint nDims) -> dip::BooleanArray
Convert an unsigned integer mxArray to a dip::BooleanArray, where elements of the input are indices where the output array is set. The output array has nDims elements. In MATLAB, dimensions start with 1. If mx is empty, all dimensions are to be processed.
auto dml::GetRange(mxArray const* mx) -> dip::Range
Convert an integer array from mxArray to dip::Range by copy. more...
auto dml::GetRangeArray(mxArray const* mx) -> dip::RangeArray
Convert a cell array of integer array from mxArray to dip::RangeArray by copy.
template<typename T>
auto dml::GetStdVector(mxArray const* mx) -> std::vector<T>
Convert a 1D real-valued numeric array from mxArray to std::vector< T > by copy. Data is cast as usual from doubles to the target type (see dip::clamp_cast).
auto dml::GetStdVectorOfFloats(mxArray const* mx) -> std::vector<dip::dfloat> deprecated
Convert a floating-point array from mxArray to std::vector<dip::dfloat> by copy.
auto dml::GetString(mxArray const* mx) -> dip::String
Convert a string from mxArray to dip::String by copy.
auto dml::GetStringArray(mxArray const* mx) -> dip::StringArray
Convert a cell array of strings from mxArray to dip::StringArray by copy.
auto dml::GetStringSet(mxArray const* mx) -> dip::StringSet
Convert a cell array of string from mxArray to dip::StringSet by copy.
auto dml::GetStringUnicode(mxArray const* mx) -> dip::String
Convert a string from mxArray to a UTF-8 encoded dip::String by copy.
auto dml::GetUnsigned(mxArray const* mx) -> dip::uint
Convert an unsigned integer from mxArray to dip::uint by copy.
auto dml::GetUnsignedArray(mxArray const* mx) -> dip::UnsignedArray
Convert an unsigned integer array from mxArray to dip::UnsignedArray by copy.
auto dml::HandleNewStyleString(mxArray const* mx) -> mxArray const*
If mx is a “string” class object, return a char vector or a cell array of char vectors.
auto dml::IsScalar(mxArray const* mx) -> bool
True if array is scalar (has single value)
auto dml::IsString(mxArray const* mx) -> bool
True if mx is a string (char vector or string class)
auto dml::IsVector(mxArray const* mx) -> bool
True if empty or a one-dimensional array

Macros

#define DML_CATCH
Catch exceptions thrown in a MEX-file. more...
#define DML_MAX_ARGS
Tests to ensure the MEX-file has not been called with too many inputs. more...
#define DML_MIN_ARGS
Tests to ensure the MEX-file has been called with sufficient inputs. more...

Enum documentation

enum class dml::GetImageMode: dip::uint8

dml::GetImage can optionally create a shared copy of the input mxArray, which extends its lifetime. This is useful if the MEX-file needs to keep a reference to the object.

Enumerators
REFERENCE = 0 Reference the mxArray in the dip::Image object.
SHARED_COPY = 1 Make a shared copy of the mxArray and take ownership of the copy.

enum class dml::ArrayConversionMode: dip::uint8

dml::GetImage can optionally turn an input numeric array to a tensor image. If the numeric array is a short vector (up to 5 elements) or a small matrix (up to 5x5 elements) it will be seen as a 0D tensor image.

Enumerators
STANDARD = 0 All arrays are scalar images.
TENSOR_OPERATOR = 1 Small arrays are 0D tensor images.

Function documentation

bool dml::IsScalar( mxArray const* mx)

True if array is scalar (has single value)

bool dml::IsVector( mxArray const* mx)

True if empty or a one-dimensional array

bool dml::IsString( mxArray const* mx)

True if mx is a string (char vector or string class)

dip::uint dml::GetUnsigned( mxArray const* mx)

Convert an unsigned integer from mxArray to dip::uint by copy.

dip::sint dml::GetInteger( mxArray const* mx)

Convert a signed integer from mxArray to dip::sint by copy.

dip::dfloat dml::GetFloat( mxArray const* mx)

Convert a floating-point number from mxArray to dip::dfloat by copy.

dip::dcomplex dml::GetComplex( mxArray const* mx)

Convert a complex floating-point number from mxArray to dip::dcomplex by copy.

dip::BooleanArray dml::GetBooleanArray( mxArray const* mx)

Convert a boolean (logical) array from mxArray to dip::BooleanArray by copy.

dip::UnsignedArray dml::GetUnsignedArray( mxArray const* mx)

Convert an unsigned integer array from mxArray to dip::UnsignedArray by copy.

dip::IntegerArray dml::GetIntegerArray( mxArray const* mx)

Convert a signed integer array from mxArray to dip::IntegerArray by copy.

dip::FloatArray dml::GetFloatArray( mxArray const* mx)

Convert a floating-point array from mxArray to dip::FloatArray by copy.

template<typename T>
std::vector<T> dml::GetStdVector( mxArray const* mx)

Convert a 1D real-valued numeric array from mxArray to std::vector< T > by copy. Data is cast as usual from doubles to the target type (see dip::clamp_cast).

std::vector<dip::dfloat> dml::GetStdVectorOfFloats( mxArray const* mx) deprecated

Convert a floating-point array from mxArray to std::vector<dip::dfloat> by copy.

dip::BooleanArray dml::GetProcessArray( mxArray const* mx, dip::uint nDims)

Convert an unsigned integer mxArray to a dip::BooleanArray, where elements of the input are indices where the output array is set. The output array has nDims elements. In MATLAB, dimensions start with 1. If mx is empty, all dimensions are to be processed.

dip::CoordinateArray dml::GetCoordinateArray( mxArray const* mx)

Convert a coordinates array from mxArray to dip::CoordinateArray by copy.

A coordinates array is either a cell array with arrays of unsigned integers (all of them the same length), or a matrix with a row per coordinate and a column per dimension.

dip::FloatCoordinateArray dml::GetFloatCoordinateArray( mxArray const* mx)

Convert a coordinates array from mxArray to dip::FloatCoordinateArray by copy.

A coordinates array is either a cell array with arrays of double floats (all of them the same length), or a matrix with a row per coordinate and a column per dimension.

mxArray const* dml::HandleNewStyleString( mxArray const* mx)

If mx is a “string” class object, return a char vector or a cell array of char vectors.

dip::String dml::GetString( mxArray const* mx)

Convert a string from mxArray to dip::String by copy.

dip::String dml::GetStringUnicode( mxArray const* mx)

Convert a string from mxArray to a UTF-8 encoded dip::String by copy.

dip::StringArray dml::GetStringArray( mxArray const* mx)

Convert a cell array of strings from mxArray to dip::StringArray by copy.

dip::StringSet dml::GetStringSet( mxArray const* mx)

Convert a cell array of string from mxArray to dip::StringSet by copy.

bool dml::GetBoolean( mxArray const* mx)

Convert a boolean (logical) from mxArray to bool by copy. Accepts "yes" and "no" as well.

dip::Range dml::GetRange( mxArray const* mx)

Convert an integer array from mxArray to dip::Range by copy.

A range is an integer array with zero to three elements, ordered the same way as in the constructors for dip::Range.

dip::RangeArray dml::GetRangeArray( mxArray const* mx)

Convert a cell array of integer array from mxArray to dip::RangeArray by copy.

dip::Image::Pixel dml::GetPixel( mxArray const* mx)

Convert a numeric array from mxArray to dip::Image::Pixel by copy.

dip::Histogram::Configuration dml::GetHistogramConfiguration( mxArray const* mx)

Reads a histogram Configuration struct from a cell mxArray with key-value pairs.

mxArray* dml::CreateDouble2Vector( dip::dfloat v0, dip::dfloat v1)

Create a two-element mxArray and write the two values in it.

mxArray* dml::GetArray( bool in)

Convert an boolean from bool to mxArray by copy.

mxArray* dml::GetArray( dip::uint in)

Convert an unsigned integer from dip::uint to mxArray by copy.

mxArray* dml::GetArray( dip::sint in)

Convert a signed integer from dip::sint to mxArray by copy.

mxArray* dml::GetArray( dip::dfloat in)

Convert a floating-point number from dip::dfloat to mxArray by copy.

mxArray* dml::GetArray( dip::dcomplex in)

Convert a complex floating-point number from dip::dcomplex to mxArray by copy.

template<typename T, typename <SFINAE>>
mxArray* dml::GetArray( dip::DimensionArray const& in)

Convert a numeric array from dip::DimensionArray to mxArray by copy. Works for dip::UnsignedArray, dip::IntegerArray and dip::FloatArray.

mxArray* dml::GetArray( dip::CoordinateArray const& in)

Convert a coordinates array from mxArray to dip::CoordinateArray by copy.

The output mxArray is a matrix with a row per coordinate and a column per dimension.

mxArray* dml::GetArray( dip::String const& in)

Convert a string from dip::String to mxArray by copy.

mxArray* dml::GetArray( dip::StringArray const& in)

Convert a string array from dip::StringArray to mxArray by copy.

mxArray* dml::GetArrayUnicode( dip::String const& in)

Convert a UTF-8 encoded string from dip::String to mxArray by copy.

mxArray* dml::GetArray( dip::Image::Sample const& in)

Convert a sample from dip::Image::Sample to mxArray by copy.

mxArray* dml::GetArray( dip::Image::Pixel const& in)

Convert a set of samples from dip::Image::Pixel to mxArray by copy.

mxArray* dml::GetArray( dip::PixelSize const& pixelSize)

Convert a pixel size object dip::PixelSize to mxArray by copy.

mxArray* dml::GetArray( dip::FileInformation const& fileInformation)

Convert a dip::FileInformation structure to mxArray by copy.

mxArray* dml::GetArray( dip::Distribution const& in)

Convert a dip::Distribution object to mxArray by copy.

dip::Image dml::GetImage( mxArray const* mx, dml::GetImageMode mode = GetImageMode::REFERENCE, dml::ArrayConversionMode conversion = ArrayConversionMode::STANDARD)

Passing an mxArray to DIPlib, keeping ownership of the data.

This function “converts” an mxArray with image data to a dip::Image object. The dip::Image object will point to the data in the mxArray, unless the array contains complex numbers. Complex data needs to be copied because MATLAB represents it internally as two separate data blocks. In that case, the dip::Image object will own its own data block.

When calling GetImage with a prhs argument in mexFunction(), use a const modifier for the output argument. This should prevent accidentally modifying an input array, which is supposed to be illegal in mexFunction():

dip::Image const in1 = dml::GetImage( prhs[ 0 ] );

An empty mxArray produces a non-forged image.

dip::ImageArray dml::GetImageArray( mxArray const* mx)

Convert a cell array of images from mxArray to dip::ImageArray, using dml::GetImage for each element of the cell array.

mxArray* dml::GetArrayAsArray( dip::Image const& img, bool doNotSetToTrue = false)

Find the mxArray that holds the data for the dip::Image img.

mxArray* dml::GetArray( dip::Image const& img, bool doNotSetToTrue = false)

Find the mxArray that holds the data for the dip::Image img, and create a MATLAB dip_image object around it.

template<typename K>
K dml::GetKernel( int nrhs, mxArray const*[] prhs, int& index, dip::uint nDims)

Gets a structuring element or kernel from the input argument(s) at index, and index+1. index is updated to point to the next unused input argument.

template<typename T>
T dml::GetPreference( dip::String const& preference)

Get the value of a property, equivalent to calling dipgetpref in MATLAB.

The template parameter T should be set to either bool, dip::dfloat or dip::String depending on the value selected. An exception will be thrown if the type of the value returned by dipgetpref doesn’t match the template parameter. Note that both ‘integer’ and ‘float’ parameter values are stored as a double. Parameters that store an array are currently not supported.

Macro documentation

#define DML_MIN_ARGS

Tests to ensure the MEX-file has been called with sufficient inputs.

DML_MIN_ARGS(n); throws an error if nrhs is smaller than n. Use this in a mexFunction to ensure there are at least n input arguments to the MEX-file.

#define DML_MAX_ARGS

Tests to ensure the MEX-file has not been called with too many inputs.

DML_MAX_ARGS(n); throws an error if nrhs is larger than n. Use this in a mexFunction to ensure there are no more than n input arguments to the MEX-file.

#define DML_CATCH

Catch exceptions thrown in a MEX-file.

This macro forms the catch section to a try statement. It will catch exceptions thrown by DIPlib and present them as standard MATLAB error messages. Your MEX-file function should look like this:

void mexFunction( int nlhs, mxArray* plhs[], int nrhs, const mxArray* prhs[] ) {
   try {
      // Your code here
   } DML_CATCH
}

Note that there should not be a semicolon after this macro.