MblobCalculate

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). 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.

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 MIL 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, 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 if you change the Blob Analysis context's processing settings using MblobControl() (constants from the For global processing settings of a Blob Analysis context that cause results to be recalculated 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 one blob identifier image (or one identifier/grayscale image pair if features with a grayscale definition are needed).

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).

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. Alternatively, you can define an ROI for the grayscale image. In this case, the ROI of the grayscale image is used as the blob identifier image and BlobIdentImageBufId must be set to M_NULL. For more information, see the Regions of interest subsection of the Child buffers, regions of interest, and fixturing section of Chapter 2: Building an application.

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.