MbufSetRegion
- See also
Availability
Function map
- Examples
MbufStream
- MbufTransfer
fixturedcoderead.cpp
fixturingusingblob.cpp
mgrainteractive.cpp
mgrainteractive.cs
mgrainteractive.vb
mimboundingbox.cpp
mmoddefinemodelatangle.cpp
mpatdefinemodelatangle.cpp
multipledatamatrixcoderead.cpp
pharmacodereader.cpp
regionmanager.cpp
simple3dbinpicking.cpp
sphereinspection.cpp
studinspection.cpp
| MIL_ID ImageBufId, | //in |
| MIL_ID ImageOrGraphicListId, | //in |
| MIL_INT64 Label, | //in |
| MIL_INT64 Operation, | //in |
| MIL_DOUBLE Param | //in |
DescriptionThis 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, delete, copy, extract, or link 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 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.
The image mask must be the same size as the image buffer.
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 copied and associated with 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 copied and associated with 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 2D graphics list or image mask is copied and the copy is associated with 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. Note that defining an M_VECTOR_AND_RASTER ROI with a 2D graphics list containing graphics created in world units will generate an error if the specified image buffer is not already 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 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.
If a child buffer is allocated using a parent buffer with an ROI, the child buffer's ROI is automatically linked with that of the parent buffer (the same as using this function with M_LINK_TO_PARENT and the MIL identifier of the child buffer). You can also set an ROI in the child buffer directly. Note that the ROI of the child buffer is only accessible using the child buffer's MIL identifier.
You cannot set an ROI in a YUV image buffer unless its format is YUV24 Planar, and it is not a child buffer.
ParametersSpecifies the identifier of the image buffer for which to set the ROI, or from which to copy or extract the ROI.
See the Parameter associations section for possible values that can be specified.
Specifies the identifier of the image buffer or 2D graphics list that contains the data to use to set the ROI, or to which to copy or extract the ROI information. If not used, set this parameter to M_NULL.
See the Parameter associations section for possible values that can be specified.
Specifies the type of operation to perform.
See the Parameter associations section for possible values that can be specified.
The table below lists possible values for the ImageBufId, ImageOrGraphicListId, and Operation parameters.
The following Operation and corresponding ImageBufId and ImageOrGraphicListId parameter settings are used to perform operations on ROIs related to the specified buffer(s).
|
For specifying the operation to perform for the
ROI(s)
|
|||||||||||||||||||||||||||||||||||||||
|
|
Description | ||||||||||||||||||||||||||||||||||||||
| ImageBufId | |||||||||||||||||||||||||||||||||||||||
| ImageOrGraphicListId | |||||||||||||||||||||||||||||||||||||||
| M_DEFAULT |
Same as M_RASTERIZE. (summarize)Same as M_RASTERIZE. (more details...) |
||||||||||||||||||||||||||||||||||||||
| M_COPY |
Specifies to copy the ROI of the source image buffer and set the copy as the ROI of the destination image buffer. If the source buffer has an ROI only in an M_RASTER format, and the destination buffer is smaller than the source buffer, the copied ROI is cropped to the size of the destination buffer. If the destination buffer is larger than the source buffer, the copied ROI retains the size of the source buffer's ROI. This is true even if the source buffer is a child buffer that has an ROI that is linked to the ROI of a larger parent buffer (by default, or using MbufSetRegion() with M_LINK_TO_PARENT); only the part of the linked ROI that is within the area of the source buffer is copied. If the source buffer has an ROI in an M_VECTOR format, the entire ROI is copied, including parts of the ROI that are outside the source image. If the ROI is in an M_VECTOR_AND_RASTER format, the entire vector portion of the ROI is copied, including parts of the ROI that are outside the source image. The raster portion of the ROI is recalculated based on the region that is visible in the destination image (if the source image and destination image are not the same size). (summarize)Specifies to copy the ROI of the source image buffer and set the copy as the ROI of the destination image buffer. (more details...) |
||||||||||||||||||||||||||||||||||||||
| ImageBufId |
Specifies the following. (summarize)Specifies the following. (more details...) |
||||||||||||||||||||||||||||||||||||||
|
Image buffer ID from which to copy the ROI |
Specifies the identifier of the source image buffer from which to copy the ROI. |
||||||||||||||||||||||||||||||||||||||
| ImageOrGraphicListId |
Specifies the following. (summarize)Specifies the following. (more details...) |
||||||||||||||||||||||||||||||||||||||
|
Image buffer ID for which to
define the ROI |
Specifies the identifier of the destination image buffer to which to copy the ROI. If the image buffer is already associated with an ROI, this association is removed and the image buffer is associated with the new ROI. If the image buffer is a child buffer with an ROI linked to that of its parent, the ROIs are unlinked. (summarize)Specifies the identifier of the destination image buffer to which to copy the ROI. (more details...) |
||||||||||||||||||||||||||||||||||||||
| M_DELETE |
Specifies to remove ROI information from the image buffer. (summarize)Specifies to remove ROI information from the image buffer. (more details...) |
||||||||||||||||||||||||||||||||||||||
| ImageBufId |
Specifies the following. (summarize)Specifies the following. (more details...) |
||||||||||||||||||||||||||||||||||||||
|
Image buffer ID for which to remove the ROI |
Specifies the MIL identifier of the image buffer from which to remove ROI information. |
||||||||||||||||||||||||||||||||||||||
| M_EXTRACT |
Specifies to extract the 2D graphics list or image mask used to define the ROI of the source image buffer, and store it in the destination image buffer or 2D graphics list. When you pass a 2D graphics list as a destination, the graphics used to define the source ROI are added to the destination 2D graphics list. Existing graphics in the destination 2D graphics list are not removed. If the source buffer has an ROI in an M_RASTER format, ImageOrGraphicListId must be set to the MIL identifier of an image buffer. If the source buffer has an ROI in an M_VECTOR format, ImageOrGraphicListId must be set to the MIL identifier of a 2D graphics list. If the source buffer has an M_VECTOR_AND_RASTER ROI, ImageOrGraphicListId can be set to the MIL identifier of either a 2D graphics list or an image buffer. If the destination image buffer is larger than the source image, the existing image mask is copied; the image mask is not recalculated based on the size of the destination image. (summarize)Specifies to extract the 2D graphics list or image mask used to define the ROI of the source image buffer, and store it in the destination image buffer or 2D graphics list. (more details...) |
||||||||||||||||||||||||||||||||||||||
| ImageBufId |
Specifies the following. (summarize)Specifies the following. (more details...) |
||||||||||||||||||||||||||||||||||||||
|
Image buffer ID from which to
extract the ROI |
Specifies the MIL identifier of the source image buffer from which to extract the 2D graphics list or image mask used to define the ROI. |
||||||||||||||||||||||||||||||||||||||
| ImageOrGraphicListId |
Specifies one of the following. (summarize)Specifies one of the following. (more details...) |
||||||||||||||||||||||||||||||||||||||
|
2D graphics list ID in which to
store the extracted 2D graphics |
Specifies the identifier of the destination 2D graphics list in which to store the 2D graphics of the extracted 2D graphics list. The 2D graphics list must have been previously allocated using MgraAlloc(). (summarize)Specifies the identifier of the destination 2D graphics list in which to store the 2D graphics of the extracted 2D graphics list. (more details...) |
||||||||||||||||||||||||||||||||||||||
|
Image buffer ID in which to store
the extracted image mask |
Specifies the identifier of the destination image buffer in which to store the extracted image mask. |
||||||||||||||||||||||||||||||||||||||
| M_LINK_TO_PARENT |
Specifies to link the ROI of the image buffer to the ROI of its parent buffer. The child buffer's offset and size are used to determine what portion of the parent's ROI to use for the child. The ROI information for the parent and child buffer occupy the same memory space. Therefore, modifying the ROI of the parent buffer affects the ROI of the child buffer. Modifying the ROI of the child buffer does not affect the ROI of the parent buffer; instead it unlinks the ROIs. The ROI of a child buffer is linked to the ROI of its parent buffer by default. This image shows the relationship between the linked ROIs of a parent and child buffer. 
You can unlink the ROI by setting an ROI for the child buffer using MbufSetRegion() with any other type of operation. To retain the child buffer's current ROI when unlinking, set the Operation parameter to M_COPY, and set both the ImageBufId and ImageOrGraphicListId parameters to the MIL identifier of the child buffer. If the specified buffer is not a child buffer, an error is generated. (summarize)Specifies to link the ROI of the image buffer to the ROI of its parent buffer. (more details...) |
||||||||||||||||||||||||||||||||||||||
| ImageBufId |
Specifies the following. (summarize)Specifies the following. (more details...) |
||||||||||||||||||||||||||||||||||||||
|
Child image buffer ID of which to link
the ROI |
Specifies the MIL identifier of the child image buffer, of which to link the ROI with that of its parent buffer. |
||||||||||||||||||||||||||||||||||||||
| M_NO_RASTERIZE + |
Specifies to create an M_VECTOR ROI, defined by the graphics of a 2D graphics list. The content of the 2D graphics list is copied, and this vectorial information is associated with the specified image buffer. Only the areas defined by the graphics of the 2D graphics list are processed by MIL functions. If a shape is not filled, only the pixels corresponding to its contour will be processed by MIL functions unless the combination constant M_FILL_REGION is specified. (summarize)Specifies to create an M_VECTOR ROI, defined by the graphics of a 2D graphics list. (more details...) |
||||||||||||||||||||||||||||||||||||||
| ImageBufId |
Specifies the following. (summarize)Specifies the following. (more details...) |
||||||||||||||||||||||||||||||||||||||
|
Image buffer ID for which to set
the ROI |
Specifies the MIL identifier of the image buffer for which to set the ROI. If the image buffer is already associated with an ROI, this association is removed and the image buffer is associated with the new ROI. If the image buffer is a child buffer with an ROI linked to that of its parent, the ROIs are unlinked. (summarize)Specifies the MIL identifier of the image buffer for which to set the ROI. (more details...) |
||||||||||||||||||||||||||||||||||||||
| ImageOrGraphicListId |
Specifies the following. (summarize)Specifies the following. (more details...) |
||||||||||||||||||||||||||||||||||||||
|
2D graphics list ID to use to
define the ROI |
Specifies the identifier of the 2D graphics list to use to define the ROI. The 2D graphics list must have been previously allocated and filled with 2D graphics using the graphics functions (Mgra...()). (summarize)Specifies the identifier of the 2D graphics list to use to define the ROI. (more details...) |
||||||||||||||||||||||||||||||||||||||
| M_RASTERIZE + |
Specifies to create an M_RASTER ROI defined by an image mask or 2D graphics list, or to change an M_VECTOR ROI to an M_VECTOR_AND_RASTER ROI. MIL functions will only operate on source image pixels corresponding to either non-zero value pixels of the image mask or areas defined by the graphics of the 2D graphics list, depending on whether the MIL function requires raster or vectorial information. When creating an ROI defined by an image mask, the content of the image mask is copied and this raster (bitmap) information is stored as the raster portion of the ROI associated with the specified image buffer. When creating an ROI defined by a 2D graphics list, or changing an M_VECTOR ROI to an M_VECTOR_AND_RASTER ROI, an image mask is generated from the 2D graphics list or existing vectorial information. This raster (bitmap) information and the vectorial information (from the existing ROI or specified 2D graphics list) are stored as the raster portion and vector portion of the ROI associated with the image buffer. When generating the mask, pixels corresponding to areas defined by the vectorial information are set to a non-zero value, and all other image mask pixels are set to a zero value. If a shape is not filled, only the pixels corresponding to its contour will be set to a non-zero value, unless the combination constant M_FILL_REGION is specified. M_FILL_REGION is not available when creating an ROI from an image mask. This is the default value. (summarize)Specifies to create an M_RASTER ROI defined by an image mask or 2D graphics list, or to change an M_VECTOR ROI to an M_VECTOR_AND_RASTER ROI. (more details...) |
||||||||||||||||||||||||||||||||||||||
| ImageBufId |
Specifies the following. (summarize)Specifies the following. (more details...) |
||||||||||||||||||||||||||||||||||||||
|
Image buffer ID for which to set
the ROI |
Specifies the MIL identifier of the image buffer for which to set the ROI. If the image buffer is already associated with an ROI, this association is removed and the image buffer is associated with the new ROI (except when ImageOrGraphicListId is set to M_NULL. If the image buffer is a child buffer with an ROI linked to that of its parent, the ROIs are unlinked. (summarize)Specifies the MIL identifier of the image buffer for which to set the ROI. (more details...) |
||||||||||||||||||||||||||||||||||||||
| ImageOrGraphicListId |
Specifies one of the following. (summarize)Specifies one of the following. (more details...) |
||||||||||||||||||||||||||||||||||||||
| M_NULL |
Specifies to rasterize the existing M_VECTOR ROI of the image buffer. This changes the M_VECTOR ROI to an M_VECTOR_AND_RASTER ROI. Note that this operation has no effect on an M_RASTER or M_VECTOR_AND_RASTER ROI. (summarize)Specifies to rasterize the existing M_VECTOR ROI of the image buffer. (more details...) |
||||||||||||||||||||||||||||||||||||||
|
2D graphics list ID to use to
define the ROI |
Specifies the identifier of the 2D graphics list to use to define the ROI. The 2D graphics list must have been previously allocated and filled with 2D graphics using the graphics functions (Mgra...()). (summarize)Specifies the identifier of the 2D graphics list to use to define the ROI. (more details...) |
||||||||||||||||||||||||||||||||||||||
|
Image mask buffer ID to use to
define the ROI |
Specifies the identifier of the image buffer to use as an image mask to define the ROI. The image mask must be the same size as the image buffer, and must be a 1-band image buffer. (summarize)Specifies the identifier of the image buffer to use as an image mask to define the ROI. (more details...) |
||||||||||||||||||||||||||||||||||||||
| M_RASTERIZE_AND_DISCARD_LIST + |
Specifies to create an M_RASTER ROI defined by a 2D graphics list. An image mask is generated from the specified 2D graphics list, and stored as the raster ROI associated with the image buffer. When generating the mask, pixels corresponding to areas defined by the 2D graphics list are set to a non-zero value, and all other mask pixels are set to a zero value. If a shape is not filled, only the pixels corresponding to its contour will be set to a non-zero value, unless the combination constant M_FILL_REGION is specified. This operation does not store the vectorial information from the 2D graphics list in the ROI. MIL functions will only operate on source image pixels corresponding to non-zero value pixels of the image mask. (summarize)Specifies to create an M_RASTER ROI defined by a 2D graphics list. (more details...) |
||||||||||||||||||||||||||||||||||||||
| ImageBufId |
Specifies the following. (summarize)Specifies the following. (more details...) |
||||||||||||||||||||||||||||||||||||||
|
Image buffer ID for which to set
the ROI |
Specifies the MIL identifier of the image buffer for which to set the ROI. If the image buffer is already associated with an ROI, this association is removed and the image buffer is associated with the new ROI. If the image buffer is a child buffer with an ROI linked to that of its parent, the ROIs are unlinked. (summarize)Specifies the MIL identifier of the image buffer for which to set the ROI. (more details...) |
||||||||||||||||||||||||||||||||||||||
|
ImageOrGraphicListId |
Specifies the following. (summarize)Specifies the following. (more details...) |
||||||||||||||||||||||||||||||||||||||
|
2D graphics list ID to use to
define the ROI |
Specifies the identifier of the 2D graphics list to use to define the ROI. The 2D graphics list must have been previously allocated and filled with 2D graphics using the graphics functions (Mgra...()). (summarize)Specifies the identifier of the 2D graphics list to use to define the ROI. (more details...) |
||||||||||||||||||||||||||||||||||||||
You can add the following value to the above-mentioned values to set whether to interpret the graphics in the 2D graphics list as being filled.
|
For interpreting the elements in the 2D graphics list
as being filled
|
|||||||||||||||||||||||||||||||||||||||
| Combination
value |
Description | ||||||||||||||||||||||||||||||||||||||
| M_FILL_REGION |
Specifies that the graphics in the 2D graphics list are interpreted as if they are filled when defining the ROI. If one or more graphics of the 2D graphics list are already filled (for example, a rectangle created with MgraRectFill()), M_FILL_REGION has no effect on the already filled graphics. (summarize)Specifies that the graphics in the 2D graphics list are interpreted as if they are filled when defining the ROI. (more details...) |
||||||||||||||||||||||||||||||||||||||
| Header | Include mil.h. |
| Library | Use mil.lib. |
| DLL | Requires mil.dll. |