Using child buffers, ROIs, or a copy to manipulate specific data areas

See also

Availability

Available in MIL-Lite

Available in MIL

You can manipulate or control specific parts of a data buffer by creating a child buffer within it, by specifying a region of interest, or by copying specific parts of it to another buffer.

Child buffers

A child buffer is a specified subset of a given data buffer (known as the parent buffer), associated with a MIL identifier. Child buffers occupy a specific rectangular area of the parent buffer. Since this area is part of the same physical memory space as the parent buffer, changes made to the data of the child buffer affect the data of the parent buffer and vice versa.

Since a child buffer has a MIL identifier, it is considered a data buffer, and it can be used in the same context as its parent buffer; for example, it can be selected to a MIL 2D display and be the only data that is displayed. A child buffer takes on the same attributes and type as the parent buffer. However, any pixel coordinates specified or returned when using a child buffer are relative to the child buffer's top-left corner.

One major benefit of the child buffer is being able to handle several buffers simultaneously, in contexts where normally only one buffer can be handled. For example, a MIL 2D display can only display one image buffer at a time. However, you might want to display the source and destination buffer of an operation in the same window. You can get around this situation by allocating a displayable image buffer as large as the 2D display and then allocating two child buffers from this buffer. You can then use one as the source data buffer and one as the destination. When the parent buffer is selected on the 2D display (MdispSelect()), both the source and the destination child buffers can be seen.

When the parent buffer is multi-band, the child buffer can occupy one or all bands. The following example shows some child buffers that can be created from a multi-band image parent buffer.

Just as its parent buffer, a child buffer must be allocated so that it can be associated with an identifier and recognized as an entity by MIL. You can use one of the MIL functions from the table below to allocate the child buffer.

MIL function	Monochrome parent buffer	Multi-band parent buffer
MbufChild1d()	1D region of first row of band.	1D region of first row of all bands.
MbufChild2d()	2D region of band.	2D region of all bands.
MbufChildColor()	-	Entire area of band chosen.
MbufChildColor2d()	-	2D region of band chosen or 2D region of all bands.

Allocate a child buffer by specifying its size and offset with respect to each of the parent buffer dimensions. Note that, as a subset of the parent buffer, a child buffer cannot exceed the bounds of its parent in any dimension. For example, a color child buffer cannot be created from a monochrome parent buffer.

Once you have finished using a child buffer, you must free it using MbufFree(), before freeing the parent buffer.

Specifying a region of interest

A region of interest (ROI) is similar to a child buffer in that it identifies a subset of data in an image buffer. 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 have the ROI move within the image buffer according to the relative coordinate system if the image is calibrated. Note that, unlike a child buffer, an ROI does not have its own MIL identifier and cannot have results returned with respect to it.

Use MbufSetRegion() to create an ROI from an image mask or from the graphics in a 2D graphics list.

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 2D 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 2D graphics list defining the region of interest, or modify it interactively,without obstructing the target image.

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 2D 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 of MbufSetRegion(). 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. To inquire an ROI's type, use MbufInquire() with M_REGION_TYPE.

When an ROI is defined, the information from the specified 2D graphics list or image mask is copied to the source image buffer. Any subsequent changes to the original 2D graphics list or image mask will not affect the ROI. To update the ROI using a new or modified 2D 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 camera 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 camera calibration information, you must define the ROI with a 2D graphics list. All graphics in the 2D graphics list that were created in world units (using MgraControl() with M_INPUT_UNITS set to M_WORLD), will be associated with the same camera calibration information as the image; all other graphics in the 2D graphics list, as well as any generated raster information, will not be calibrated.

If the camera 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 back to an M_VECTOR_AND_RASTER ROI, such that the raster data is synchronized with the vector information.

By default, the ROI of a child buffer is dynamically linked with that of its parent. You can define different ROIs for a parent buffer and its child buffer, or relink the ROIs using MbufSetRegion() with the Operation parameter set to M_LINK_TO_PARENT. Note that a child buffer's ROI is not accessible from its parent buffer.

To remove the ROI from a source image buffer, call MbufSetRegion() with the Operation parameter set to M_DELETE.

The following table gives a broad overview of the modules that support the raster and vector-based ROIs. This table is meant as a general guideline and every module will have exceptions. For example, in most modules which do support ROIs, the M...Draw() function will not support any type of ROI. For functions that take an image buffer, the MIL Reference indicates if the function does not support an ROI or if there are ROI limitations. If the function takes an image buffer but does not specify whether it does or does not support an ROI, it is safe to assume it does support an ROI without any restrictions.

Module	ROI		ROI in world units
Module	M_RASTER ²	M_VECTOR ²	ROI in world units
M3dMap	N	N	N
Mbead	N	N	N
Mblob	Y	N	N
Mcode	N	Y	Y
Mcol (in general)	N	N	N
McolDefine()	Y	N	N
Mdmr	N	Y	Y
Medge	N	N	N
Mgra	N	N	N
Mim (in general)	N	N	N
MimStatCalculate() (for stats)	Y ¹	N ¹	N
MimArith...()	Y	N	N
MimLutMap()	Y	N	N
Mmeas	N	Y	Y
Mmet	N	N	N
Mmod	N	N	N
Mocr	N	Y	Y
Mpat	N	Y	Y
Mreg	N	N	N
Mstr	N	Y	Y

¹ Note that not all statistics operations support ROIs; for a list of those that do, see MimControl().

² These types of ROI will also support M_VECTOR_AND_RASTER ROIs.

Processing a non-rectangular area when an ROI is not supported

To process a non-rectangular area when an ROI is not supported, you can apply a mask to the source image. For example:

Allocate an image buffer, using MbufAlloc...(). The buffer should be at least the same size as the area in the source image to process. This buffer will be used as a mask buffer.
Draw a filled shape in the mask buffer corresponding to the pixels to be modified, using the graphics functions (Mgra...()) or the drawing functions (M...Draw()). You can also annotate the image with Windows GDI annotations. For more information, see the Using GDI annotations subsection of the Annotating the displayed image non-destructively section of Chapter 23: Displaying an image.
Allocate a temporary destination buffer, using MbufAlloc...(). The temporary destination buffer should be at least the same size as the area to process.
Perform the required operation from the source buffer to the temporary destination buffer.
Copy the temporary destination buffer to the required destination buffer, using MbufCopyCond(), with the mask buffer as the condition buffer.

Copying specific buffer areas

As an alternative to using a child buffer or an ROI, you can restrict operations to specific areas or bits of a buffer (child or parent) by copying the required portions to another buffer. For information about the functions allowing you to copy specific buffer areas, see Managing data buffers.