dip_opencv::ExternalInterface class

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


Use the following code when declaring images to be used as the output to a DIPlib function:

dip_opencv::ExternalInterface cvei;
dip::Image img_out0 = cvei.NewImage();
dip::Image img_out1 = cvei.NewImage();

This configures the images img_out0 and img_out1 such that, when they are forged later on, an cv::Mat object will be created to hold the pixel data.

However, there are many limitations to the images that can be mapped by a cv::Mat, see the description in the documentation to the module: DIPlib-OpenCV interface. For these images, the allocator will fail, prompting DIPlib to use its own, default allocator instead. The resulting dip::Image object cannot be converted back to an OpenCV object, though it might be possible to convert parts of it (for example each 2D plane separately).

The dip::ExternalInterface object owns the cv::Mat objects. You need to keep it around as long as you use the image objects returned by its dip_opencv::ExternalInterface::NewImage method, otherwise the data segments will be freed and the dip::Image objects will point to non-existing data segments.

To retrieve the cv::Mat object inside such a dip::Image, use the dip_opencv::ExternalInterface::GetMat method:

cv::Mat img0 = cvei.GetMat( img_out0 );
cv::Mat img1 = cvei.GetMat( img_out1 );

If you don’t use the dip_opencv::ExternalInterface::GetMat method, the cv::Mat that contains the pixel data will be destroyed when the dip::Image object goes out of scope. The GetMat method returns a cv::Mat object that owns the data segment used by the dip::Image object. In this case, the dip::Image object is still valid, and shares the data segment with the extracted cv::Mat. If the cv::Mat is destroyed, the data segment will be freed and the dip::Image object will point to a non-existing data segment.

Remember to not assign a result into the images created with dip_opencv::ExternalInterface::NewImage, as the pixel data will be copied in the assignment. 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 cv::Mat created for img_out0. In the second case, the result of the operation is directly written into the cv::Mat, no copies are necessary.

Base classes

class dip::ExternalInterface abstract
Support for external interfaces.


auto GetMat(dip::Image const& img) -> cv::Mat
Returns the OpenCV cv::Mat that holds the data for the dip::Image img.
auto NewImage() -> dip::Image
Constructs a dip::Image object with the external interface set so that, when forged, a OpenCV cv::Mat will be allocated to hold the samples.

Function documentation

cv::Mat GetMat(dip::Image const& img)

Returns the OpenCV cv::Mat that holds the data for the dip::Image img.

The OpenCV cv::Mat returned is the one allocated to hold the pixel data in the input img. If img is a view of another image, or has been manipulated through dip::Image::Mirror or dip::Image::Rotation90, the pixel data will be copied into a new cv::Mat object.

If the dip::Image object does not point to data in a cv::Mat object, the pixel data will be copied into a new cv::Mat object.