MbufSetRegion

This function sets the region of interest (ROI) of an image buffer; if supported, MIL functions will only operate on this region of the buffer. MbufSetRegion() can also be used to modify or delete the ROI.

The ROI of an image buffer can be of any shape and can be composed of several non-contiguous areas. When dealing with processing operations that respect the ROI, all pixels outside the ROI are ignored.

You can define an ROI with either an image mask or a graphics list. The ROI should be equal to or smaller than the source image buffer. When defined from an image mask, the region of interest consists of the pixels corresponding to the non-zero pixels in the image mask. When defined from the graphics contained in a graphics list, only areas corresponding to the graphics are processed. If the graphics defining the ROI are not filled, the ROI will consist of only the graphics' outline, which is one pixel thick. However, if the combination constant M_FILL_REGION is specified when calling MbufSetRegion(), the ROI will consider non-filled graphics as being filled. This is useful if you want to display the graphics list defining the region of interest, or modify it interactively,without obstructing the target image.

Note that, unlike a child buffer, an ROI does not have its own MIL identifier and cannot have results returned with respect to it.

When defining the ROI with an image mask, this raster (bitmap) information is stored in the image buffer, creating an M_RASTER ROI. When defining the ROI with a graphics list, this vectorial information and/or its corresponding raster (bitmap) version is stored in the image buffer, creating an M_VECTOR ROI, an M_RASTER ROI, or an M_VECTOR_AND_RASTER ROI, depending on how you set the Operation parameter. Some functions (for example, MblobCalculate()) expect an M_RASTER ROI, while other functions (for example, McodeRead()) expect an M_VECTOR ROI; creating an M_VECTOR_AND_RASTER ROI allows more MIL modules to use the ROI in the source image.

When an ROI is defined, the information from the specified graphics list or image mask is copied to the source image buffer. Any subsequent changes to the original graphics list or image mask will not affect the ROI. To update the ROI using a new or modified graphics list or image mask, call MbufSetRegion() again with the new information. The old ROI information is replaced with the new ROI information.

An M_VECTOR ROI or an M_VECTOR_AND_RASTER ROI can be associated with the same calibration information as the image. This ensures that whenever the relative coordinate system moves (using McalRelativeOrigin(), McalSetCoordinateSystem(), or McalFixture()), the ROI moves accordingly. To associate an ROI with calibration information, you must define the ROI with a graphics list. All graphics in the graphics list that were created in world units (using MgraControl() with M_INPUT_UNITS set to M_WORLD) will be associated with the same callibration information as the image; all other graphics in the graphics list, as well as any generated raster information, will not be calibrated. Note that defining an M_VECTOR_AND_RASTER ROI with a graphics list containing graphics created in world units will generate an error if the specified image buffer is not already calibrated.

If the calibration information associated with the image buffer changes, the raster information of an M_VECTOR_AND_RASTER ROI will be discarded, causing the ROI to become an M_VECTOR ROI. Calling MbufSetRegion() with the Operation parameter set to M_RASTERIZE and the ImageOrGraphicListId parameter set to M_NULL transforms the ROI to an M_VECTOR_AND_RASTER ROI, such that the raster data is synchronized with the vector information.

Not all functions support an image buffer with an ROI. If you pass an image buffer with an ROI to a processing or analysis function that does not use the ROI of an image buffer, an error will be generated. The functions' descriptions state whether they support the use of an ROI.

It is not possible to set an ROI in an image buffer that has one or more child buffers. However, it is possible to define an ROI directly in a child buffer. The child buffer's ROI is not accessible from the parent buffer.

You cannot set an ROI in a YUV image buffer unless its format is YUV24, and you are using all 3 bands.