DIPlib-OpenCV interface module
#include "dip_opencv_interface.h"

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.