MblobCalculate

Board	Supported
Host System	Yes
V4L2	Yes
Clarity UHD	Yes
Concord PoE	No
GenTL	Yes
GevIQ	Yes
GigE Vision	Yes
Indio	No
Iris GTX	Yes
Radient eV-CL	Yes
Rapixo CL	Yes
Rapixo CoF	Yes
Rapixo CXP	Yes
USB3 Vision	Yes

Perform blob analysis calculations.

Syntax

void MblobCalculate(
    AIL_ID ContextBlobId,        //in
    AIL_ID BlobIdentImageBufId,  //in
    AIL_ID GrayImageBufId,       //in
    AIL_ID ResultBlobId          //out
)

Description

This function calculates the specified features for all currently included blobs in the blob identifier image, and stores results in the specified result buffer. To specify the features to calculate, pass a blob analysis context that has the required features enabled for calculation. Use MblobControl to enable the features. You can select the blobs on which to perform the calculations using MblobSelect.

Calculations of features with a binary definition (such as M_BREADTH) are performed using only the blob identifier image (BlobIdentImageBufId). You can limit blob analysis calculations to a region of the blob identifier image using a region of interest (ROI) set using MbufSetRegion. In this case, the specified features are only calculated for included blobs (or parts of blobs) lying within the ROI. For more information, see Regions of interest.

If a feature with a grayscale definition (such as M_MAX_PIXEL) is enabled for calculation, you must pass a grayscale image buffer to the GrayImageBufId parameter. In this case, the blob identifier image is used to identify the blobs and the grayscale image is used to provide the blob pixel values. Note that the blob identifier image and the grayscale image must be the same size. Instead of passing the blob identifier image separately, you can pass an image buffer (or container) with an ROI that identifies the blobs to the GrayImageBufId parameter. In this case, the BlobIdentImageBufId parameter must be set to M_NULL.

When calculating depth map related features (using MblobControl with M_DEPTH_MAP_...), you must set BlobIdentImageBufId to M_NULL, and GrayImageBufId to a fully corrected depth map image buffer or 3D-processable depth map container that is associated with an ROI that acts as the blob identifier image as well as identifies invalid pixels. Note that if you don't pass a fully corrected depth map image buffer or 3D-processable depth map container, you will obtain an error if you try to retrieve a depth map feature result using MblobGetResult; MblobCalculate will not generate an error. Use MbufSetRegion with M_RASTERIZE_DEPTH_MAP_VALID_PIXELS to associate an ROI with the specified depth map image. Note that for a depth map container, the ROI is stored in the M_COMPONENT_REGION_AIL component of the container.

The blob identifier image identifies each blob as a group of touching pixels in the current foreground state (zero or non-zero, based on MblobControl with M_FOREGROUND_VALUE). The current M_CONNECTIVITY processing mode (also set with MblobControl), determines when to consider pixels as touching.

If the blob identifier image has been previously binarized so that it contains only two extreme values (0 and 1 for 1-bit images, 0 and 0xff for 8-bit images, and 0 and 0xffff for 16-bit images), blob analysis can be performed a little faster. However, you must first set MblobControl with M_IDENTIFIER_TYPE to M_BINARY, to let Aurora Imaging Library know that the blob identifier image has only two states.

Depending on the blob identification mode (MblobControl with M_BLOB_IDENTIFICATION_MODE), MblobCalculate either treats each blob individually (M_INDIVIDUAL), groups all blobs together (M_WHOLE_IMAGE), groups blobs according to their actual pixel value in the blob identifier image (M_LABELED or M_LABELED_TOUCHING). Both M_LABELED and M_LABELED_TOUCHING treat blobs with the same pixel value as being grouped together. However, M_LABELED treats touching blobs as the same blob (regardless of their label); while M_LABELED_TOUCHING treats them as separate.

If you are calculating chain features (enabled using MblobControl with M_CHAINS or M_ALL_FEATURES), you cannot use MblobControl with M_BLOB_IDENTIFICATION_MODE set to M_LABELED_TOUCHING.

If several calls are made to MblobCalculate with the same image or container, context, and result buffer, features calculated in one call remain in the result buffer and are not recalculated in subsequent calls. However, if you then use the result buffer with different images or a different container, or if you change the blob analysis context's processing settings using MblobControl (constants from the ProcSettings table), any results already in the buffer become invalid and are discarded. Therefore, it is more efficient to use a result buffer exclusively in one processing mode with the same images/container.

If you have associated the blob identifier image with a camera calibration context, and GrayImageBufId is set to M_NULL, the result buffer will be associated with the same camera calibration context as the blob identifier image. However, if you provide a grayscale image that is not calibrated or does not have the same camera calibration context as the blob identifier image, the result buffer will not be calibrated (both the identifier and grayscale images must have the same camera calibration context for the result buffer to be calibrated).

Most feature calculations are initially performed in the pixel coordinate system. It is typically possible to transform the result of these calculations to the relative coordinate system using MblobControl with M_RESULT_OUTPUT_UNITS. Those feature types whose calculation are not performed in the pixel coordinate system, or that cannot be transformed into the relative coordinate system, will have that fact stated in the result type's description in MblobGetResult. Refer to the description of a particular feature's result, in MblobGetResult, to determine if it can be transformed and returned in the relative coordinate system. Note that some feature results such as M_NUMBER_OF_HOLES do not have a different meaning in either the pixel coordinate system or the relative coordinate system.

Parameters

ContextBlobId (in, AIL_ID)

Specifies the identifier of the blob analysis context, that specifies the feature(s) to calculate, and other settings related to the blob analysis operation. The blob analysis context must have been previously allocated on the required system with MblobAlloc.

BlobIdentImageBufId (in, AIL_ID)

Specifies the identifier of the image buffer to use as the blob identifier image. This image is used to distinguish blob pixels from background pixels and which pixels belong to which blob. The blob identifier image buffer must be a packed binary, 8-, 16-, or 32-bit unsigned, single-band image buffer. 32-bit image buffers are only supported when the blob identification mode is set to M_LABELED_TOUCHING.

GrayImageBufId (in, AIL_ID)

Specifies the identifier of the depth map container or the image buffer to use as the grayscale image. This buffer is used to supply the intensity of blob pixels when calculating features with a grayscale definition. If this parameter is set to M_NULL, features with a grayscale definition, such as M_SUM_PIXEL, cannot be calculated. This parameter is ignored when calculating features with only a binary definition.

ResultBlobId (out, AIL_ID)

Specifies the identifier of a blob analysis result buffer, in which to store calculated results. The blob analysis result buffer must have been previously allocated on the required system using MblobAllocResult.