MblobControl

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

Control a blob analysis setting.

Syntax

void MblobControl(
    AIL_ID     ContextOrResultBlobId,  //out
    AIL_INT64  ControlType,            //in
    AIL_DOUBLE ControlValue            //in
)

Description

This function allows you to control a setting of the specified blob analysis context or result buffer.

For blob analysis contexts, these settings control the execution of MblobCalculate, and which blob features are enabled for calculation. For blob analysis result buffers, these settings control the post-manipulation of results. If MblobControl is not called, default processing controls and values are used in calculations.

You can inquire about most of these settings using MblobInquire.

Changing certain control type settings will cause MblobCalculate to discard all results currently in your result buffer prior to calculation. If this is the case, it will be mentioned in the preamble to the table containing these control types.

Parameters

`ContextOrResultBlobId` (out, AIL_ID)

Specifies the identifier of the blob analysis context or result buffer.

`ControlType` (in, AIL_INT64)

Specifies the setting to change.

`ControlValue` (in, AIL_DOUBLE)

Specifies the setting's new value.

Parameter Associations

For global processing settings of a blob analysis context that cause results to be recalculated

For the following global processing setting control types, you must set theContextOrResultBlobId parameter to a blob analysis context. Changing the value of the following control types between calls to MblobCalculate will cause all the results currently in your Blob analysis result buffer to be discarded upon the next call to MblobCalculate.

`M_BLOB_IDENTIFICATION_MODE`

Sets whether to calculate features for each blob, or to treat groups of blobs as single blobs and calculate the features of these blobs as if they were one blob.

Value	Description
`M_DEFAULT`
`M_INDIVIDUAL` (default)	Specifies that all blobs are measured individually.
`M_LABELED`	Specifies that blobs with the same label are grouped together, and that touching blobs with different labels are also grouped together. The foreground value of the blob identifier image will be used as the label value of the blob; therefore, when using `M_LABELED`, the `M_FOREGROUND_VALUE` control type cannot be set to `M_ZERO`, and the identifier image cannot be binary (1-bit). `M_LABELED` is not supported for merge operations using `MblobMerge`.
`M_LABELED_TOUCHING`	Specifies that blobs with the same label are grouped together, and that touching blobs with different labels are measured individually. The foreground value of the blob identifier image will be used as the label value of the blob; therefore, when using `M_LABELED_TOUCHING`, the `M_FOREGROUND_VALUE` control type cannot be set to `M_ZERO`. In addition, the blob identifier image cannot be binary (1-bit). `M_LABELED_TOUCHING` is not supported with the following: - `MblobCalculate`, when chain features are enabled for calculation (`MblobControl` with `M_CHAINS`, or `M_ALL_FEATURES`). - `MblobDraw` with `M_DRAW_BLOBS_CONTOUR`, `M_DRAW_HOLES_CONTOUR`, or a combination of the two. - `MblobSelect` with `M_MERGE`.
`M_WHOLE_IMAGE`	Specifies that all blobs are grouped together. If the blob identifier image is already binarized (for example, pixel values for an 8-bit image are either 0 or 0xff), you can set `M_IDENTIFIER_TYPE` to `M_BINARY` to calculate features faster.

`M_CONNECTIVITY`

Sets the image lattice for blob analysis.

Value	Description
`M_DEFAULT`
`M_4_CONNECTED`	Specifies that each pixel has 4 neighbors.
`M_8_CONNECTED` (default)	Specifies that each pixel has 8 neighbors.

`M_FERET_ANGLE_SEARCH_END`

Sets the upper limit of the angular search range in which to search for the maximum (M_FERET_MAX_DIAMETER) or minimum (M_FERET_MIN_DIAMETER) Feret diameters. > Note: Note that MblobCalculate only searches through the specified range when calculating Feret features. Better results for the features can exist outside of this search range.

Value	Description
`M_DEFAULT`
`0 <= Value <= 180` (default)	Specifies the upper limit of the angular search range. The end value must be greater than the start value.

`M_FERET_ANGLE_SEARCH_START`

Sets the lower limit of the angular search range in which to search for the maximum (M_FERET_MAX_DIAMETER) or minimum (M_FERET_MIN_DIAMETER) Feret diameters. > Note: Note that MblobCalculate only searches through the specified range when calculating Feret features. Better results for the features can exist outside of this search range.

Value	Description
`M_DEFAULT`
`0 <= Value <= 180` (default)	Specifies the lower limit of the angular search range. The start value must be less than the end value.

`M_FOREGROUND_VALUE`

Sets which pixel values are considered to be in the foreground.

Value	Description
`M_DEFAULT`
`M_NONZERO` (default)	Specifies the blobs consisting of non-zero pixels.
`M_ZERO`	Specifies the blobs consisting of zero pixels.

`M_NUMBER_OF_FERETS`

Sets the number of Feret angles to use when calculating a Feret feature (M_FERET_...) or a feature based on Ferets (that is, M_RECTANGULARITY, M_ROUGHNESS, or M_CONVEX_PERIMETER).

Value	Description
`M_DEFAULT`
`M_INFINITE`	Specifies the use of a high precision algorithm to accurately calculate Feret features (and features based on Feret features). > Note: The `M_FERET_DIAMETERS` result type is not supported when you use this setting.
`M_MIN_FERETS`	Specifies the minimum number of Feret angles. The minimum number of Feret angles is 2.
`Value > M_MIN_FERETS` (default)	Specifies the number of Feret angles. The first Feret angle used is always 0°, and the difference between successive angles is 180° / number of Ferets.

For global processing settings of a blob analysis context that do not cause results to be recalculated

For the following global processing setting control types, you must set the ContextOrResultBlobId parameter to a blob analysis context. These control types do not cause any results currently in the result buffer to be discarded when MblobCalculate is called.

`M_FERET_CONTACT_POINTS`

Sets whether to calculate Feret contact points for features that support it (for example, M_FERET_AT_PRINCIPAL_AXIS_ANGLE) if the feature has been enabled for calculation. This enables the use of the M_FERET_CONTACT_POINTS_... combination constants in MblobGetResult.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that the Feret contact points for supported features will not be calculated.
`M_ENABLE`	Specifies that the Feret contact points for supported features will be calculated.

`M_FERET_GENERAL_ANGLE`

Sets the angle to use when calculating M_FERET_GENERAL.

Value	Description
`M_DEFAULT`
`-360.0 <= Value <= 360.0` (default)	Specifies the angle, in degrees.

`M_IDENTIFIER_TYPE`

Sets the values that non-zero pixels in the blob identifier image can have. If the blob identifier image is already binarized (for example, pixel values for an 8-bit image are either 0 or 0xff), you can set this control type to M_BINARY to calculate features faster.

Value	Description
`M_DEFAULT`
`M_BINARY`	Specifies that non-zero pixels must have the maximum value of the buffer (for example, 0xff for an 8-bit image).
`M_GRAYSCALE` (default)	Specifies that non-zero pixels can have any value.

`M_MAX_BLOBS`

Sets the maximum number of blobs to process. If this number is reached, processing is stopped, and results available in the result buffer become invalid and are discarded unlessM_RETURN_PARTIAL_RESULTS is enabled.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that there is no limit on the maximum number of blobs.
`Value >= 0`	Specifies the maximum number of blobs.

`M_MOMENT_GENERAL_MODE`

Sets the type of moment to calculate when calculating a user-specified moment (M_MOMENT_GENERAL).

Value	Description
`M_DEFAULT`
`M_CENTRAL`	Specifies a central moment. A central moment is defined as [Image: mblobselectfeature_moment_central.png] , where i runs from 1 to the number of pixels in the blob, `_p<sub>i</sub> _` = value of a pixel (always 1 for binary moments), `_x<sub>i</sub> _` = its X-coordinate, _y_i _ = its Y-coordinate, [Image: mblob_xbar.png] = the weighted mean of _x_i _, [Image: mblob_ybar.png] = the weighted mean of _y_i _, q and r are the order of the moment in X and Y respectively. The weighted mean is the first-order ordinary moment divided by the sum of the pixel values (`M_SUM_PIXEL` for grayscale definitions, `M_AREA` for binary definitions). Central moments use coordinates relative to each blob's center of gravity, and are therefore independent of a blob's position within an image.
`M_ORDINARY` (default)	Specifies an ordinary moment. An ordinary moment is defined as [Image: mblobselectfeature_moment.png] , where i runs from 1 to the number of pixels in the blob, `_p<sub>i</sub> _` = value of a pixel (always 1 for binary moments), `_x<sub>i</sub> _` = its X-coordinate, _y_i _ = its Y-coordinate, and (q+r) are the order of the moment in X and Y respectively. Ordinary moments are affected by the blob position because they use coordinates relative to the image origin (top-left corner).

`M_MOMENT_GENERAL_ORDER_X`

Sets the order of the X-component of the user-specified moment. Use this control type when calculating a user-specified moment (M_MOMENT_GENERAL).

Value	Description
`M_DEFAULT`
`Value >= 0` (default)	Specifies the X-order of the moment.

`M_MOMENT_GENERAL_ORDER_Y`

Sets the order of the Y-component of the user-specified moment. Use this control type when calculating a user-specified moment (M_MOMENT_GENERAL).

Value	Description
`M_DEFAULT`
`Value >= 0` (default)	Specifies the Y-order of the moment.

`M_MOMENT_THIRD_ORDER_MODE`

Sets how to calculate third-order moments. M_FAST is faster than M_PRECISE, but it might cause some imprecisions.

Value	Description
`M_DEFAULT`
`M_FAST` (default)	Specifies that third-order moments will be calculated quickly.
`M_PRECISE`	Specifies that third-order moments will be calculated accurately.

`M_PIXEL_ASPECT_RATIO`

Sets the pixel aspect ratio of the image(s). This is only useful if the image has a uniform pixel aspect ratio with different X- and Y-scales. For non-uniform distortion, you can use McalGrid or McalList to calibrate the image, and McalTransformImage to physically correct the image. All results returned by MblobGetResult are affected by M_PIXEL_ASPECT_RATIO, including those that are simply positions within the image. For more information, see Pixel aspect ratio.

Value	Description
`M_DEFAULT`
`Value > 0` (default)	Specifies the pixel width/pixel height.

`M_RETURN_PARTIAL_RESULTS`

Sets whether results from partially scanned images will be available after a stop condition is met. The three stop conditions are: - The maximum number of blobs (M_MAX_BLOBS) has been processed. - The timeout limit (M_TIMEOUT) is exceeded. - The calculation has been stopped by the user (M_STOP_CALCULATE). When a stop condition is met, the image is only partially scanned and results about blobs found in the partially scanned image are discarded. When M_RETURN_PARTIAL_RESULTS is set to M_ENABLE, you can access the results of those blobs that are completely defined (those blobs whose entire perimeter was scanned) in the partially scanned image. > Note: Note that when using multi-processing (MappControlMp with M_MP_USE set to M_ENABLE) and this control type is enabled, it is possible that the number of blobs returned can exceed the number set using M_MAX_BLOBS. This is because multi-processing might divide the image into pieces and process each piece independently; in this case, there is no global number of blobs counted for the entire image until everything is processed. When a stop condition is met in one of the image pieces, processing is stopped everywhere. The total number of blobs is then combined and returned, which can be greater than M_MAX_BLOBS.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies to discard results of partially scanned images when processing is interrupted.
`M_ENABLE`	Specifies to make results of partially scanned images available when processing is interrupted.

`M_SAVE_RUNS`

Sets whether to save run information when calling MblobCalculate.

Value	Description
`M_DEFAULT`
`M_DISABLE`	Specifies not to save run information. Disabling saves time when performing the first call to `MblobCalculate` and reduces the memory requirements for the result buffer. However, you cannot use `MblobLabel`, or `MblobGetLabel`, and certain draw operations are disabled. See `MblobDraw` for more information on which draw operations require run information to be saved. In addition, using `MblobControl`, you cannot enable for calculation the chained pixels features (`M_CHAINS`), the convex hull features (`M_CONVEX_HULL`), `M_NUMBER_OF_FERETS` when it is set to `M_INFINITE`, and the Feret features (`M_FERETS`).
`M_ENABLE` (default)	Specifies to save run information. Calls to `MblobCalculate` will save run information from the blob identifier image in the result buffer.

`M_SORTn`

Sets the feature to use as the n ^th sorting key for results, where n stands for an integer between 1 and 3. Changes to this control type take effect upon the next call to MblobCalculate. If you select a feature as a sorting key that is not enabled, an error will occur on the next call to MblobCalculate.

Value	Description
`M_NO`	Specifies that the blob is not touching the borders of the image.
`M_YES`	Specifies that the blob is touching one or more borders of the image.
`M_DEFAULT`
`M_NO_SORT` (default)	Specifies to remove the sorting key.

`M_SORTn_DIRECTION`

Sets the direction in which the n ^th sorting key is sorted, where n stands for an integer between 1 and 3.

Value	Description
`M_DEFAULT`
`M_SORT_DOWN`	Specifies the feature as being sorted in descending order.
`M_SORT_UP` (default)	Specifies the feature as being sorted in ascending order.

`M_TIMEOUT`

Sets the maximum processing time, in msec. If the timeout limit is exceeded, processing is stopped, and results already available in the result buffer become invalid and will be discarded, unlessM_RETURN_PARTIAL_RESULTS is enabled.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that there is no maximum processing time.
`Value >= 0`	Specifies the maximum processing time, in msec.

For specifying to calculate all features in a single call

The following control type allows you to enable or disable all features for calculation using a single call. For the following control type, you must set the ContextOrResultBlobId parameter to a blob analysis context.

`M_ALL_FEATURES`

Sets whether to calculate all features. You can then selectively enable or disable specific features for calculation. It is not recommended to use M_ALL_FEATURES in your final application. This is because programs using M_ALL_FEATURES set to M_ENABLE might become slower when new Aurora Imaging Library versions are released, if new features have been added.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies to disable the calculation of all features, regardless of their previous setting. This can be used as a quick method to disable the calculation of all features.
`M_ENABLE`	Specifies that all of the features will be calculated, regardless of their previous setting.

For specifying to calculate features with only a binary definition

The following control types establish which of the blob features, that have only a binary definition, are calculated for each blob; these blob features are calculated using only the blob identifier image. For the following control types, you must set the ContextOrResultBlobId parameter to a blob analysis context. Note that, unless otherwise stated, these features are calculated in pixel units; although you can retrieve them in world units using MblobGetResult if calculated on a calibrated blob identifier image and M_RESULT_OUTPUT_UNITS is set to M_WORLD or M_ACCORDING_TO_CALIBRATION.

`M_BOX`

Sets whether to calculate all image-axis-aligned bounding box features plus X- and Y-Ferets. The image-axis-aligned bounding box is the bounding box that is aligned with the pixel coordinate system's axes. You can retrieve results for these features using MblobGetResult with M_BOX_X_MIN, M_BOX_Y_MIN, M_BOX_X_MAX, M_BOX_Y_MAX, M_BLOB_TOUCHING_IMAGE_BORDERS, M_BOX_AREA, M_BOX_ASPECT_RATIO, M_BOX_FILL_RATIO, M_FIRST_POINT_X, M_FIRST_POINT_Y, M_FERET_X, and M_FERET_Y.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that these features will not be calculated.
`M_ENABLE`	Specifies that these features will be calculated.

`M_BREADTH`

Sets whether to calculate the breadth of a blob. This feature has the same advantages and disadvantages as M_LENGTH; that is, this feature is more accurate for long thin blobs because it is derived from the perimeter (P) and area (A) assuming that P = 2(length + breadth) and A = length x breadth. You can retrieve results for this feature using MblobGetResult with M_BREADTH.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that this feature will not be calculated.
`M_ENABLE`	Specifies that this feature will be calculated.

`M_CHAINS`

Sets whether to calculate all 4 chain features. You can retrieve results for these features using MblobGetResult with M_CHAIN_X, M_CHAIN_Y, M_CHAIN_INDEX, M_NUMBER_OF_CHAINED_PIXELS, and M_TOTAL_NUMBER_OF_CHAINED_PIXELS. Note that the chain code is computed depending on the lattice and foreground values set with M_CONNECTIVITY and M_FOREGROUND_VALUE, respectively.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that these features will not be calculated.
`M_ENABLE`	Specifies that these features will be calculated.

`M_COMPACTNESS`

Sets whether to calculate the compactness value of a blob. This is defined as the ratio between the area of a circle with the same perimeter as the blob in question, and the area of the blob itself. You can retrieve results for this feature using MblobGetResult with M_COMPACTNESS.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that this feature will not be calculated.
`M_ENABLE`	Specifies that this feature will be calculated.

`M_CONTACT_POINTS`

Sets whether to calculate the contact features of the image-axis-aligned bounding box. The image-axis-aligned bounding box is the bounding box that is aligned with the pixel coordinate system's axes. You can retrieve results for these features using MblobGetResult with M_X_MIN_AT_Y_MIN, M_X_MAX_AT_Y_MIN, M_X_MAX_AT_Y_MAX, M_X_MIN_AT_Y_MAX, M_Y_MIN_AT_X_MAX, M_Y_MAX_AT_X_MAX, M_Y_MAX_AT_X_MIN, and M_Y_MIN_AT_X_MIN.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that these features will not be calculated.
`M_ENABLE`	Specifies that these features will be calculated.

`M_CONVEX_HULL`

Sets whether to calculate all convex hull features. You can retrieve results for these features using MblobGetResult with M_CONVEX_HULL_AREA, M_CONVEX_HULL_COG_X, M_CONVEX_HULL_COG_Y, M_CONVEX_HULL_FILL_RATIO, M_CONVEX_HULL_PERIMETER, M_CONVEX_HULL_X, M_CONVEX_HULL_XY_PACKED, M_CONVEX_HULL_Y, M_NUMBER_OF_CONVEX_HULL_POINTS, and M_TOTAL_NUMBER_OF_CONVEX_HULL_POINTS. > Note: For a quicker result, you can select to calculateM_CONVEX_PERIMETER.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that these features will not be calculated.
`M_ENABLE`	Specifies that these features will be calculated.

`M_CONVEX_PERIMETER`

Sets whether to calculate the approximation of the perimeter of the convex hull of a blob. It is derived from several Feret diameters; so, a larger number of Ferets gives a more accurate result. You can use M_NUMBER_OF_FERETS to change the number of Ferets angles used when calculating this feature. You can retrieve results for this feature using MblobGetResult with M_CONVEX_PERIMETER. > Note: For a more accurate result, you can select to calculateM_CONVEX_HULL_PERIMETER by enabling M_CONVEX_HULL.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that this feature will not be calculated.
`M_ENABLE`	Specifies that this feature will be calculated.

`M_ELONGATION`

Sets whether to calculate a value that is equal to M_LENGTH / M_BREADTH. It is similar to M_FERET_ELONGATION, except that it should be used for long thin blobs. You can retrieve results for this feature using MblobGetResult with M_ELONGATION.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that this feature will not be calculated.
`M_ENABLE`	Specifies that this feature will be calculated.

`M_EULER_NUMBER`

Sets whether to calculate the number of blobs - number of holes. This value is more useful for M_WHOLE_IMAGE than for M_INDIVIDUAL processing mode. When using the M_WHOLE_IMAGE processing mode, each blob is treated individually, as opposed to grouping all of the blobs in an image together. When using the M_INDIVIDUAL processing mode, the number of blobs is effectively 1. You can retrieve results for this feature using MblobGetResult with M_EULER_NUMBER.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that this feature will not be calculated.
`M_ENABLE`	Specifies that this feature will be calculated.

`M_FERET_GENERAL`

Sets whether to calculate a Feret diameter at a user-specified angle specified using M_FERET_GENERAL_ANGLE. You can retrieve results for this feature using MblobGetResult with M_FERET_GENERAL.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that this feature will not be calculated.
`M_ENABLE`	Specifies that this feature will be calculated.

`M_FERET_MAX_DIAMETER_ELONGATION`

Sets whether to calculate the ratio between the maximum Feret diameter and its perpendicular Feret diameter. Use the M_FERET_ANGLE_SEARCH_... constants to control the angular range in which to find the maximum Feret diameter. You can retrieve results for this feature using MblobGetResult with M_FERET_MAX_DIAMETER_ELONGATION.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that this feature will not be calculated.
`M_ENABLE`	Specifies that this feature will be calculated.

`M_FERET_MIN_DIAMETER_ELONGATION`

Sets whether to calculate the ratio between the minimum Feret diameter and its perpendicular Feret diameter. Use the M_FERET_ANGLE_SEARCH_... constants to control the angular range in which to find the minimum Feret diameter. You can retrieve results for this feature using MblobGetResult with M_FERET_MIN_DIAMETER_ELONGATION.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that this feature will not be calculated.
`M_ENABLE`	Specifies that this feature will be calculated.

`M_FERET_PERPENDICULAR_TO_MAX_DIAMETER`

Sets whether to calculate the Feret diameter that is perpendicular to the maximum Feret diameter. Use the M_FERET_ANGLE_SEARCH_... constants to control the angular range in which to find the maximum Feret diameter. You can retrieve results for this feature using MblobGetResult with M_FERET_PERPENDICULAR_TO_MAX_DIAMETER.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that this feature will not be calculated.
`M_ENABLE`	Specifies that this feature will be calculated.

`M_FERET_PERPENDICULAR_TO_MIN_DIAMETER`

Sets whether to calculate the Feret diameter that is perpendicular to the minimum Feret diameter. Use the M_FERET_ANGLE_SEARCH_... constants to control the angular range in which to find the minimum Feret diameter. You can retrieve results for this feature using MblobGetResult with M_FERET_PERPENDICULAR_TO_MIN_DIAMETER.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that this feature will not be calculated.
`M_ENABLE`	Specifies that this feature will be calculated.

`M_FERETS`

Sets whether to calculate the Feret features. You can retrieve results for these features using MblobGetResult with M_FERET_DIAMETERS, M_TOTAL_NUMBER_OF_FERETS,M_NUMBER_OF_FERETS, M_FERET_ELONGATION, M_FERET_MAX_ANGLE, M_FERET_MIN_ANGLE, M_FERET_MAX_DIAMETER, M_FERET_MIN_DIAMETER, and M_FERET_MEAN_DIAMETER.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that these features will not be calculated.
`M_ENABLE`	Specifies that these features will be calculated.

`M_INTERCEPT`

Sets whether to calculate the intercept features. You can retrieve results for these features using MblobGetResult with M_INTERCEPT_0, M_INTERCEPT_45, M_INTERCEPT_90, and M_INTERCEPT_135.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that these features will not be calculated.
`M_ENABLE`	Specifies that these features will be calculated.

`M_LENGTH`

Sets whether to calculate the length of a blob. This feature is more accurate for long thin blobs because it is derived from the perimeter (P) and area (A) assuming that P = 2(length + breadth) and A = length x breadth. You can retrieve results for this feature using MblobGetResult with M_LENGTH.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that this feature will not be calculated.
`M_ENABLE`	Specifies that this feature will be calculated.

`M_MIN_AREA_BOX`

Sets whether to calculate all the minimum-area bounding box features. You can retrieve results for these features using MblobGetResult with M_MIN_AREA_BOX_AREA, M_MIN_AREA_BOX_ANGLE, M_MIN_AREA_BOX_CENTER_X, M_MIN_AREA_BOX_CENTER_Y, M_MIN_AREA_BOX_HEIGHT, M_MIN_AREA_BOX_PERIMETER, M_MIN_AREA_BOX_WIDTH, M_MIN_AREA_BOX_Xn, and M_MIN_AREA_BOX_Yn.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that these features will not be calculated.
`M_ENABLE`	Specifies that these features will be calculated.

`M_MIN_PERIMETER_BOX`

Sets whether to calculate all the minimum-perimeter bounding box features. You can retrieve results for these features using MblobGetResult with M_MIN_PERIMETER_BOX_AREA, M_MIN_PERIMETER_BOX_ANGLE, M_MIN_PERIMETER_BOX_CENTER_X, M_MIN_PERIMETER_BOX_CENTER_Y, M_MIN_PERIMETER_BOX_HEIGHT, M_MIN_PERIMETER_BOX_PERIMETER, M_MIN_PERIMETER_BOX_WIDTH, M_MIN_PERIMETER_BOX_Xn, and M_MIN_PERIMETER_BOX_Yn.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that these features will not be calculated.
`M_ENABLE`	Specifies that these features will be calculated.

`M_NUMBER_OF_HOLES`

Sets whether to calculate the number of holes in a blob. Holes that intersect the edge of the image are not counted (they might not be holes). This value is equal to 1 - M_EULER_NUMBER and is therefore a true hole count only in M_INDIVIDUAL processing mode. You can retrieve results for this feature using MblobGetResult with M_NUMBER_OF_HOLES.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that this feature will not be calculated.
`M_ENABLE`	Specifies that this feature will be calculated.

`M_PERIMETER`

Sets whether to calculate the total length of edges in a blob (including the edges of any holes), with an allowance made for the staircase effect that is produced when diagonal edges are digitized (inside corners are counted as 1.414, rather than 2.0). A single pixel blob (area = 1) has a perimeter of 4.0. You can retrieve results for this feature using MblobGetResult with M_PERIMETER.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that this feature will not be calculated.
`M_ENABLE`	Specifies that this feature will be calculated.

`M_RECTANGULARITY`

Sets whether to calculate the degree to which a blob resembles a rectangle. You can retrieve results for this feature using MblobGetResult with M_RECTANGULARITY.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that this feature will not be calculated.
`M_ENABLE`	Specifies that this feature will be calculated.

`M_ROUGHNESS`

Sets whether to calculate the roughness and irregularity of a blob, and is equal to M_PERIMETER / M_CONVEX_PERIMETER. You can retrieve results for this feature using MblobGetResult with M_ROUGHNESS.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that this feature will not be calculated.
`M_ENABLE`	Specifies that this feature will be calculated.

`M_RUNS`

Sets whether to calculate the blob run-length encoding information. You can retrieve results for these features using MblobGetResult with M_RUN_X, M_RUN_Y, M_RUN_LENGTH, M_NUMBER_OF_RUNS, and M_TOTAL_NUMBER_OF_RUNS.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that these features will not be calculated.
`M_ENABLE`	Specifies that these features will be calculated.

`M_WORLD_BOX`

Sets whether to calculate all of the features related to the world-axis-aligned bounding box. The world-axis-aligned bounding box is the bounding box that is aligned with the relative coordinate system's axes. You can retrieve results for these features using MblobGetResult with M_WORLD_FERET_X, M_WORLD_FERET_Y, M_WORLD_BOX_X_MIN, M_WORLD_BOX_Y_MIN, M_WORLD_BOX_X_MAX, M_WORLD_BOX_Y_MAX, M_WORLD_X_AT_Y_MAX, M_WORLD_X_AT_Y_MIN, M_WORLD_Y_AT_X_MAX, andM_WORLD_Y_AT_X_MIN. In a case where more than one X-coordinate touches the minimum Y-coordinate of a blob, it is not possible to predict which coordinate will be calculated and returned. This also applies to a Y-coordinate touching the minimum X-coordinate of a blob. > Note: These features are actually calculated in the world coordinate system. If enabled for calculation, you should pass MblobCalculate a calibrated blob identifier image. If an uncalibrated image is passed to MblobCalculate, these features are the equivalent of the M_BOX feature group.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that these features will not be calculated.
`M_ENABLE`	Specifies that these features will be calculated.

For specifying to calculate features with only a grayscale definition

The following control types establish which of the features, that have only a grayscale definition, are calculated for each blob. These blob features can only be calculated if you pass MblobCalculate both a blob identifier image and a grayscale buffer (or a grayscale buffer with an ROI that acts as the blob identifier image). For the following control types, you must set the ContextOrResultBlobId parameter to a blob analysis context.

`M_BLOB_CONTRAST`

Sets whether to calculate the difference between the maximum and minimum pixel values of a blob. You can retrieve results for this feature using MblobGetResult with M_BLOB_CONTRAST.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that this feature will not be calculated.
`M_ENABLE`	Specifies that this feature will be calculated.

`M_MAX_PIXEL`

Sets whether to calculate the maximum pixel value in a blob. You can retrieve results for this feature using MblobGetResult with M_MAX_PIXEL.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that this feature will not be calculated.
`M_ENABLE`	Specifies that this feature will be calculated.

`M_MEAN_PIXEL`

Sets whether to calculate the mean pixel value in a blob. You can retrieve results for this feature using MblobGetResult with M_MEAN_PIXEL.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that this feature will not be calculated.
`M_ENABLE`	Specifies that this feature will be calculated.

`M_MIN_PIXEL`

Sets whether to calculate the minimum pixel value in a blob. You can retrieve results for this feature using MblobGetResult with M_MIN_PIXEL.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that this feature will not be calculated.
`M_ENABLE`	Specifies that this feature will be calculated.

`M_SIGMA_PIXEL`

Sets whether to calculate the standard deviation of pixel values in a blob. You can retrieve results for this feature using MblobGetResult with M_SIGMA_PIXEL.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that this feature will not be calculated.
`M_ENABLE`	Specifies that this feature will be calculated.

`M_SUM_PIXEL`

Sets whether to calculate the sum of all pixel values in a blob. You can retrieve results for this feature using MblobGetResult with M_SUM_PIXEL.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that this feature will not be calculated.
`M_ENABLE`	Specifies that this feature will be calculated.

`M_SUM_PIXEL_SQUARED`

Sets whether to calculate the sum of the squares of each pixel value in a blob. You can retrieve results for this feature using MblobGetResult with M_SUM_PIXEL_SQUARED.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that this feature will not be calculated.
`M_ENABLE`	Specifies that this feature will be calculated.

For specifying to calculate features with two definitions (binary and grayscale)

The following control types establish which of the features, that have both a binary and a grayscale definition, are calculated for each blob. The binary definition considers all pixels equal; the grayscale definition weighs pixels by their value in the grayscale buffer (the grayscale definition is much slower to calculate). When you do not specify a combination value for the following control types, both versions of the feature (or groups of features) are enabled for calculation by default. If you do not provide a grayscale buffer to MblobCalculate, only the binary version can be calculated. Specifying a combination value for the following control types will overwrite the settings that were set when no combination value was specified. If a combination value was initially specified for a control type, and a different setting was specified for the same control type without a combination value, it will also overwrite the previous setting. For example, if you specify M_MOMENT_GENERAL with M_ENABLE, both the binary and grayscale versions of the feature will be calculated. If you subsequently specify M_MOMENT_GENERAL + M_GRAYSCALE with M_DISABLE, only the binary version of the feature will be calculated. For the following control types, you must set the ContextOrResultBlobId parameter to a blob analysis context.

`M_CENTER_OF_GRAVITY`

Sets whether to calculate both X- and Y-coordinates of the center of gravity. You can retrieve results for these features using MblobGetResult with M_CENTER_OF_GRAVITY_X, and M_CENTER_OF_GRAVITY_Y.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that these features will not be calculated.
`M_ENABLE`	Specifies that these features will be calculated.

`M_FERET_AT_PRINCIPAL_AXIS_ANGLE`

Sets whether to calculate the Feret diameter at the principal axis of a blob. Use the M_NUMBER_OF_FERETS control type to set the number of Feret angles that are evaluated. You can retrieve results for this feature using MblobGetResult with M_FERET_AT_PRINCIPAL_AXIS_ANGLE.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that this feature will not be calculated.
`M_ENABLE`	Specifies that this feature will be calculated.

`M_FERET_AT_SECONDARY_AXIS_ANGLE`

Sets whether to calculate the Feret diameter at the secondary axis of a blob. Use the M_NUMBER_OF_FERETS control type to set the number of Feret angles that are evaluated. You can retrieve results for this feature using MblobGetResult with M_FERET_AT_SECONDARY_AXIS_ANGLE.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that this feature will not be calculated.
`M_ENABLE`	Specifies that this feature will be calculated.

`M_FERET_PRINCIPAL_AXIS_ELONGATION`

Sets whether to calculate the ratio between the Feret diameter at the principal axis and the Feret diameter at the secondary axis. Use the M_NUMBER_OF_FERETS control type to set the number of Feret angles that are evaluated. You can retrieve results for this feature using MblobGetResult with M_FERET_PRINCIPAL_AXIS_ELONGATION.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that this feature will not be calculated.
`M_ENABLE`	Specifies that this feature will be calculated.

`M_MOMENT_FIRST_ORDER`

Sets whether to calculate the first-order moments where the order of either the X- or Y-component equals 0 and the order of the other component equals 1. You can retrieve results for these features using MblobGetResult with M_MOMENT_X0_Y1, and M_MOMENT_X1_Y0. To calculate higher order moments, use M_MOMENT_SECOND_ORDER for predefined second-order moments, M_MOMENT_THIRD_ORDER for predefined third-order moments, or M_MOMENT_GENERAL for user-specified moments. Note that first-order moment features are calculated faster when usingM_MOMENT_FIRST_ORDER than when using M_MOMENT_GENERAL.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that these features will not be calculated.
`M_ENABLE`	Specifies that these features will be calculated.

`M_MOMENT_GENERAL`

Sets whether to calculate a user-specified moment. Use the M_MOMENT_GENERAL_MODE, M_MOMENT_GENERAL_ORDER_X, and M_MOMENT_GENERAL_ORDER_Y control types to specify the settings of the user-specified moment. You can retrieve results for this feature using MblobGetResult with M_MOMENT_GENERAL. You could alternatively enable the calculation of M_MOMENT_FIRST_ORDER, M_MOMENT_SECOND_ORDER, or M_MOMENT_THIRD_ORDER to calculate a set of first, second, or third-order moments, respectively. Note that first and second-order moment features are calculated faster when using M_MOMENT_FIRST_ORDER or M_MOMENT_SECOND_ORDER than when using M_MOMENT_GENERAL.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that this feature will not be calculated.
`M_ENABLE`	Specifies that this feature will be calculated.

`M_MOMENT_SECOND_ORDER`

Sets whether to calculate the second-order moments. You can retrieve results for these features using MblobGetResult with M_MOMENT_X0_Y2, M_MOMENT_X1_Y1, M_MOMENT_X2_Y0, M_MOMENT_CENTRAL_X0_Y2, M_MOMENT_CENTRAL_X1_Y1, M_MOMENT_CENTRAL_X2_Y0, M_AXIS_PRINCIPAL_ANGLE, and M_AXIS_SECONDARY_ANGLE. To calculate higher order moments, use M_MOMENT_THIRD_ORDER for predefined third-order moments, or M_MOMENT_GENERAL for user-specified moments. Note that second-order moment features are calculated faster when using M_MOMENT_SECOND_ORDER than when using M_MOMENT_GENERAL.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that these features will not be calculated.
`M_ENABLE`	Specifies that these features will be calculated.

`M_MOMENT_THIRD_ORDER`

Sets whether to calculate the third-order moments. Calculating these moments makes the Hu moment invariants available. You can retrieve results for these features using MblobGetResult with M_MOMENT_X1_Y2, M_MOMENT_X3_Y0, M_MOMENT_X0_Y3, M_MOMENT_CENTRAL_X1_Y2, M_MOMENT_CENTRAL_X2_Y1, M_MOMENT_CENTRAL_X3_Y0, M_MOMENT_CENTRAL_X0_Y3, and M_MOMENT_HU_n, where _n_ ranges from 1 to 7. To calculate higher order moments, use M_MOMENT_GENERAL.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that these features will not be calculated.
`M_ENABLE`	Specifies that these features will be calculated.

Combination Constants — For feature parameters that have two definitions

Optional.

Usage: You can add one of the following values to the above-mentioned values to set whether to enable, disable, or sort on only the binary or grayscale calculation of the feature.

For control values of the M_SORTn control type, this combination is essential (that is, you must add one of these combination values to the control value).

Value	Description
`M_BINARY`	Selects the binary definition of the selected feature.
`M_GRAYSCALE` (default)	Selects the grayscale definition of the selected feature.

The following control types establish which of the features, that are related to depth maps, are calculated for each blob. These blob features can only be calculated if you pass MblobCalculate a grayscale buffer that is a fully corrected depth map image buffer or 3D-processable depth map container, and has an ROI that acts as the blob identifier image as well as identifies invalid pixels. If you passed an image buffer, you can verify that it contains a fully corrected depth map using McalInquire with M_DEPTH_MAP. You can use MbufSetRegion with M_RASTERIZE_DEPTH_MAP_VALID_PIXELS to merge confidence information with the blob identifier image. If you passed a container, you can use MbufInquireContainer with M_3D_PROCESSABLE_DEPTH_MAP to ensure that the container contains a 3D-processable depth map. For the following control types, you must set the ContextOrResultBlobId parameter to a blob analysis context.

`M_DEPTH_MAP_MAX_ELEVATION`

Sets whether to calculate the maximum elevation of a blob.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that the maximum elevation of the blob will not be calculated.
`M_ENABLE`	Specifies that the maximum elevation of the blob will be calculated.

`M_DEPTH_MAP_MEAN_ELEVATION`

Sets whether to calculate the mean elevation of a blob.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that the mean elevation of the blob will not be calculated.
`M_ENABLE`	Specifies that the mean elevation of the blob will be calculated.

`M_DEPTH_MAP_MIN_ELEVATION`

Sets whether to calculate the minimum elevation of a blob.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that the minimum elevation of the blob will not be calculated.
`M_ENABLE`	Specifies that the minimum elevation of the blob will be calculated.

`M_DEPTH_MAP_SIZE_Z`

Sets whether to calculate the Z-size (difference between maximum and minimum elevation) of a blob.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that the Z-size of the blob will not be calculated.
`M_ENABLE`	Specifies that the Z-size of the blob will be calculated.

`M_DEPTH_MAP_VOLUME`

Sets whether to calculate the volume of a blob.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies that the volume of the blob will not be calculated.
`M_ENABLE`	Specifies that the volume of the blob will be calculated.

For a blob analysis result buffer

For the following control types, you must set the ContextOrResultBlobId parameter to a blob analysis result buffer.

`M_INDEX_MODE`

Sets the index mode to use when retrieving results usingMblobGetResult and when drawing results using MblobDraw.

Value	Description
`M_DEFAULT`
`M_INDEX`	Specifies that the index will be passed directly to the`LabelOrIndex` parameter of `MblobGetResult` or `MblobDraw`, without any macros.
`M_LABEL`	Specifies that the label will be passed directly to the`LabelOrIndex` parameter of `MblobGetResult` or `MblobDraw`, without any macros.
`M_USE_MACRO` (default)	Specifies that the values passed to the `LabelOrIndex` parameter of `MblobGetResult` or `MblobDraw` can be the macros `M_BLOB_INDEX()` or `M_BLOB_LABEL()`. Note that `M_USE_MACRO` cannot be used in`M_LABELED_TOUCHING` mode with a 32-bit blob identifier image.

`M_INPUT_SELECT_UNITS`

Sets which units to use with the CondLow and CondHigh parameters of the MblobSelect function, when specifying the limit values of the blob selection condition. This essentially sets the input coordinate system to use.

Value	Description
`M_PIXEL` (default)	Specifies that the limit values passed to `MblobSelect` be interpreted in pixel units, with respect to the pixel coordinate system.
`M_WORLD`	Specifies that the limit values passed to `MblobSelect` be interpreted in world units, with respect to the relative coordinate system. If world units are specified, calling `MblobSelect` generates an error if the specified result buffer is not associated with a camera calibration context.

`M_RESULT_OUTPUT_UNITS`

Sets whether to return results in pixels or world units. This essentially sets the output coordinate system to use. The setting of this control type will only affect functions within this module which return positional results. This control type can be changed at any time to return results in the required output units. Note that when returned in world units, some results are only precise if calculated on a physically corrected image. If you require precise results in world units, you should correct the image using McalTransformImage before calling MblobCalculate.

Value	Description
`M_DEFAULT`
`M_ACCORDING_TO_CALIBRATION` (default)	Specifies that results are returned in world units if the result was calculated on an image associated with a camera calibration context; otherwise, specifies that results are returned in pixel units.
`M_PIXEL`	Specifies that results are returned in pixel units, with respect to the pixel coordinate system.
`M_WORLD`	Specifies that results are returned in world units, with respect to the relative coordinate system. If world units are specified, calling `MblobGetResult` generates an error if the result was not calculated on a calibrated image.

`M_STOP_CALCULATE`

Stops the current blob analysis calculation. You must call MblobControl with M_STOP_CALCULATE from another thread (typically of higher priority). Results already available in the result buffer become invalid and will be discarded, unlessM_RETURN_PARTIAL_RESULTS is enabled.

Value	Description
`M_DEFAULT`	Specifies the default behavior.

Syntax
Description
Parameters
Parameter Associations

Syntax​

Description​

Parameters​

ContextOrResultBlobId (out, AIL_ID)​

ControlType (in, AIL_INT64)​

ControlValue (in, AIL_DOUBLE)​

Parameter Associations​

For global processing settings of a blob analysis context that cause results to be recalculated​

M_BLOB_IDENTIFICATION_MODE​

M_CONNECTIVITY​

M_FERET_ANGLE_SEARCH_END​

M_FERET_ANGLE_SEARCH_START​

M_FOREGROUND_VALUE​

M_NUMBER_OF_FERETS​

For global processing settings of a blob analysis context that do not cause results to be recalculated​

M_FERET_CONTACT_POINTS​

M_FERET_GENERAL_ANGLE​

M_IDENTIFIER_TYPE​

M_MAX_BLOBS​

M_MOMENT_GENERAL_MODE​

M_MOMENT_GENERAL_ORDER_X​

M_MOMENT_GENERAL_ORDER_Y​

M_MOMENT_THIRD_ORDER_MODE​

M_PIXEL_ASPECT_RATIO​

M_RETURN_PARTIAL_RESULTS​

M_SAVE_RUNS​

M_SORTn​

M_SORTn_DIRECTION​

M_TIMEOUT​

For specifying to calculate all features in a single call​

M_ALL_FEATURES​

For specifying to calculate features with only a binary definition​

M_BOX​

M_BREADTH​

M_CHAINS​

M_COMPACTNESS​

M_CONTACT_POINTS​

M_CONVEX_HULL​

M_CONVEX_PERIMETER​

M_ELONGATION​

M_EULER_NUMBER​

M_FERET_GENERAL​

M_FERET_MAX_DIAMETER_ELONGATION​

M_FERET_MIN_DIAMETER_ELONGATION​

M_FERET_PERPENDICULAR_TO_MAX_DIAMETER​

M_FERET_PERPENDICULAR_TO_MIN_DIAMETER​

M_FERETS​

M_INTERCEPT​

M_LENGTH​

M_MIN_AREA_BOX​

M_MIN_PERIMETER_BOX​

M_NUMBER_OF_HOLES​

M_PERIMETER​

M_RECTANGULARITY​

M_ROUGHNESS​

M_RUNS​

M_WORLD_BOX​

For specifying to calculate features with only a grayscale definition​

M_BLOB_CONTRAST​

M_MAX_PIXEL​

M_MEAN_PIXEL​

M_MIN_PIXEL​

M_SIGMA_PIXEL​

M_SUM_PIXEL​

M_SUM_PIXEL_SQUARED​

For specifying to calculate features with two definitions (binary and grayscale)​

M_CENTER_OF_GRAVITY​

M_FERET_AT_PRINCIPAL_AXIS_ANGLE​

M_FERET_AT_SECONDARY_AXIS_ANGLE​

M_FERET_PRINCIPAL_AXIS_ELONGATION​

M_MOMENT_FIRST_ORDER​

M_MOMENT_GENERAL​

M_MOMENT_SECOND_ORDER​

M_MOMENT_THIRD_ORDER​

Combination Constants — For feature parameters that have two definitions​

For specifying to calculate features related to depth maps​

M_DEPTH_MAP_MAX_ELEVATION​

M_DEPTH_MAP_MEAN_ELEVATION​

M_DEPTH_MAP_MIN_ELEVATION​

M_DEPTH_MAP_SIZE_Z​