Main Content

Supporting ROIs

The toolbox supports the specification of regions of interest (ROIs) in both software and hardware. The following sections provide more information.

Implementing Software ROI

When using a software ROI, a toolbox user sets the dimensions of the ROI in the ROIPosition property. The device returns the entire image frame. Your adaptor specifies the ROI dimensions when it creates the Frame object to package up the image data.

User Scenario

Users set the value of the ROIPosition property to specify an ROI. Users specify the value as a four-element vector in the form:

[Xoffset Yoffset Width Height]

The x- and y-offsets define the position of the ROI in relation to the upper left corner of the image frame. For more information about this property, see the Image Acquisition Toolbox™ documentation.

Suggested Algorithm

To support software ROI, your adaptor must check the value of the ROIposition property before creating the frame object because you need to specify the ROI dimensions when you create the frame. This is typically done in the openDevice() or startCapture() functions.

In your frame acquisition loop, insert the following call to the IAdaptor function getROI(). Then, use the ROI width and height values when you create the IAdaptorFrame object, rather than the full image height and width returned by the device.

Note

You use the ROI width and height when you create the frame but you use the full image width and height when you copy the image data from the buffer into the frame object.

Example

The following is a version of the isSendFrame() loop in the acquisition thread function that checks the ROI. Note that you call the getROI() function to get the ROI values, and then use the width and height values in the call to makeFrame() and the offsets from the origin in the call to setImage().

if (adaptor->isSendFrame()) {

    // Get ROI information. 
    int roiOriginX, roiOriginY, roiWidth, roiHeight;
    adaptor->getROI(roiOriginX, 
                    roiOriginY,
                      roiWidth,
                     roiHeight);

    // Get frame type & dimensions
    imaqkit::frametypes::FRAMETYPE frameType = 
                                       adaptor->getFrameType();
    int imWidth = adaptor->getMaxWidth();
    int imHeight = adaptor->getMaxHeight();

    // Create a frame object
    imaqkit::IAdaptorFrame* frame = 
    adaptor->getEngine()->makeFrame(frameType,
                                     roiWidth,   // ROI width
                                     roiHeight); // ROI height

    // Copy data from buffer into frame object
    frame->setImage(imBuffer,
                     imWidth, // Full image width
                    imHeight, // Full image height
                  roiOriginX, // ROI origin
                  roiOriginY); // ROI origin

    // Set image's timestamp
    frame->setTime(imaqkit::getCurrentTime());
    // Send frame object to engine.
    adaptor->getEngine()->receiveFrame(frame);

} // if isSendFrame()

Implementing Hardware ROI

For hardware ROI, the user defines the ROI on the device. The device returns only the data in the specified ROI.

To implement hardware ROI, you must overload both the IAdaptor's getROI() and setROI() member functions in your implementation of your adaptor class. By default, if the IAdaptor object's getROI() member function is not overloaded, ROI configurations will be handled in software by imaqkit::IEngine.