| MIL 10 Reference
| Customize Help
| Save Settings

MblobControl


See also
Availability
Not available in MIL-Lite
Available in MIL

Available on Windows
Available on Linux

Available on Non-Matrox computer
Available on Matrox 4Sight-X
Available on Matrox 4Sight GP
Available on Matrox Supersight
function map Function map
Examples
MblobCalculate
MblobDraw
Synopsis
Control a blob analysis processing control setting.
Syntax
void MblobControl(
MIL_ID BlobResId, //in
MIL_INT64 ControlType, //in
MIL_DOUBLE ControlValue //in
)
Description

This function changes a processing control associated with the specified blob analysis result buffer. This function is normally called immediately after allocating a blob analysis result buffer, using MblobAllocResult(), but can be called later (in which case, already calculated results are discarded). If not called, default processing controls and values are used in calculations.

Note that you can use MblobInquire() to inquire about specific processing controls associated with a blob analysis result buffer.

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see if there is complementary information.
Parameters
This function is not supported on the selected boards.
Parameters
BlobResId

Specifies the identifier of the blob analysis result buffer.

ControlType

Specifies the processing setting to control.

See the Parameter associations section for possible values that can be specified.

ControlValue

Specifies the setting required for the control for the processing setting.

See the Parameter associations section for possible values that can be specified.

Parameter associations

The table below lists possible values for the ControlType and ControlValue parameters.

function map For calculating the features of individual or groups of blobs
CollapseControlType Description
ControlValue
Collapse M_BLOB_IDENTIFICATION

Sets whether to calculate features for each blob, or to treat groups of blobs as single blobs and calculate the features of the blobs. INQ

(summarize)
Collapse M_INDIVIDUAL

Specifies that all blobs are measured individually.

This is the default value.

(summarize)
Collapse M_LABELED

Specifies that blobs with the same label are grouped together, and that touching blobs with different labels are also grouped together.

When using M_LABELED, M_FOREGROUND_VALUE cannot be set to M_ZERO, and the identifier image cannot be binary (1-bit). However, you can have the same behavior as M_LABELED with a binary (1-bit) identifier image, by setting M_BLOB_IDENTIFICATION to M_WHOLE_IMAGE and M_IDENTIFIER_TYPE to M_BINARY.

(summarize)
Collapse M_LABELED_TOUCHING

Specifies that blobs with the same label are grouped together, and that touching blobs with different labels are measured individually.

When using M_LABELED_TOUCHING, M_FOREGROUND_VALUE cannot be set to M_ZERO. In addition, the identifier image cannot be binary (1-bit); to achieve the same behavior as M_LABELED_TOUCHING when using a binary (1-bit) identifier image, set M_BLOB_IDENTIFICATION to M_WHOLE_IMAGE and M_IDENTIFIER_TYPE to M_BINARY.

M_LABELED_TOUCHING is not supported with the following:

(summarize)
Collapse M_WHOLE_IMAGE

Specifies that all blobs are grouped together.
Collapse 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 that the calculate operation (MblobCalculate()) will only search through the specified range for the selected Feret features. Better results for the selected features can exist outside of this search range.

(summarize)
Collapse 0 <= Value <= 180

Specifies the upper limit of the angular search range.

The end value must be greater than the start value.

The default value is 180.

(summarize)
Collapse 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 that the calculate operation (MblobCalculate()) will only search through the specified range for the selected Feret features. Better results for the selected features can exist outside of this search range.

(summarize)
Collapse 0 <= Value <= 180

Specifies the lower limit of the angular search range.

The start value must be less than the end value.

The default value is 0.

(summarize)
Collapse M_FOREGROUND_VALUE

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

(summarize)
Collapse M_NONZERO

Specifies the blobs consisting of non-zero pixels.

This is the default value.

(summarize)
Collapse M_ZERO

Specifies the blobs consisting of zero pixels.
Collapse M_IDENTIFIER_TYPE

Sets the values that non-zero pixels in the image can have.

If the identifier image is already binarized (for example, pixel values for an 8-bit image are either 0 or 0xff), you can change the identifier type to M_BINARY to calculate features faster. INQ

(summarize)
Collapse M_BINARY

Specifies that non-zero pixels must have the maximum value of the buffer (for example, 0xff for an 8-bit image).
Collapse M_GRAYSCALE

Specifies that non-zero pixels can have any value.

This is the default value.

(summarize)
Collapse 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. INQ

(summarize)
Collapse M_PIXEL

Specifies that the limit values passed to MblobSelect() be interpreted in pixel units, with respect to the pixel coordinate system.

This is the default value.

(summarize)
Collapse 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 calibration context.

(summarize)
Collapse M_LATTICE

Sets the image lattice for blob analysis. INQ

(summarize)
Collapse M_4_CONNECTED

Specifies that each pixel has 4 neighbors.
Collapse M_8_CONNECTED

Specifies that each pixel has 8 neighbors.

This is the default value.

(summarize)
Collapse 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 unless M_RETURN_PARTIAL_RESULTS is enabled. INQ

(summarize)
Collapse M_DISABLE

Specifies that there is no limit on the maximum number of blobs.

This is the default value.

(summarize)
Collapse Value >= 0

Specifies the maximum number of blobs.
Collapse M_NUMBER_OF_FERETS

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

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 8.
Collapse M_INFINITE

Specifies the use of a high precision algorithm to accurately calculate Feret features (and features based on Feret features).

You cannot use this setting if calculating M_ALL_FERETS.

(summarize)
Collapse M_MIN_FERETS

Specifies the minimum number of Feret angles. The minimum number of Feret angles is 2.

(summarize)
Collapse Value > M_MIN_FERETS

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.

(summarize)
Collapse 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. INQ

(summarize)
Collapse Value

Specifies the pixel width/pixel height.

The default value is 1.0.

(summarize)
Collapse 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. INQ

(summarize)
Collapse M_DEFAULT

Same as M_ACCORDING_TO_CALIBRATION.
Collapse M_ACCORDING_TO_CALIBRATION

Specifies that results are returned in world units if the result was calculated on an image associated with a calibration context; otherwise, specifies that results are returned in pixel units.
Collapse M_PIXEL

Specifies that results are returned in pixel units, with respect to the pixel coordinate system.
Collapse M_WORLD

Specifies that results are returned in world units, with respect to the relative coordinate system. If world units are specifed, calling MblobGetResult() or MblobGetResultSingle() generates an error if the result was not calculated on a calibrated image.

(summarize)
Collapse M_RETURN_PARTIAL_RESULTS

Sets whether results from partially scanned images will be available after a stop condition is met.

The two stop conditions are:

  • The maximum number of blobs (M_MAX_BLOBS) has been processed.

  • The timeout limit (M_TIMEOUT) is exceeded.

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 that when using multi-processing 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.

(summarize)
Collapse M_DISABLE

Specifies to discard results of partially scanned images when processing is interrupted.

This is the default value.

(summarize)
Collapse M_ENABLE

Specifies to make results of partially scanned images available when processing is interrupted.
Collapse M_SAVE_RUNS

Sets whether to save run information when calling MblobCalculate(). INQ

(summarize)
Collapse 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 MblobFill(), MblobGetLabel(), MblobGetRuns(), or MblobLabel(). In addition, you cannot calculate the chained pixels feature (M_CHAINS), using MblobSelectFeature().

(summarize)
Collapse M_ENABLE

Specifies to save run information. Calls to MblobCalculate() will save run information from the blob identifier image in the result buffer.

This is the default value.

(summarize)
Collapse 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.

(summarize)
Collapse M_DEFAULT

This parameter must be set to M_DEFAULT.
Collapse M_TIMEOUT

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

(summarize)
Collapse M_DEFAULT

Same as M_DISABLE.
Collapse M_DISABLE

Specifies that there is no maximum processing time.
Collapse Value >= 0

Specifies the maximum processing time, in msec.
Type-specific versions of the function
void MblobControlInt64 (MIL_ID BlobResId, MIL_INT64 ControlType, MIL_INT64 ControlValue)
Details
Parameters

BlobResId

See BlobResId of the main function for a description.

ControlType

See ControlType of the main function for a description.

ControlValue

See ControlValue of the main function for a description.
Compilation information
Header Include mil.h.
Library Use mil.lib; milblob.lib.
DLL Requires mil.dll; milblob.dll.
BLOB IDENTIFICATION INDIVIDUAL LABELED LABELED TOUCHING WHOLE IMAGE FERET ANGLE SEARCH END FERET ANGLE SEARCH START FOREGROUND VALUE NONZERO ZERO IDENTIFIER TYPE BINARY GRAYSCALE INPUT SELECT UNITS PIXEL WORLD LATTICE 4 CONNECTED 8 CONNECTED MAX BLOBS DISABLE NUMBER OF FERETS DEFAULT INFINITE MIN FERETS MIN FERETS PIXEL ASPECT RATIO RESULT OUTPUT UNITS DEFAULT ACCORDING TO CALIBRATION PIXEL WORLD RETURN PARTIAL RESULTS DISABLE ENABLE SAVE RUNS DISABLE ENABLE STOP CALCULATE DEFAULT TIMEOUT DEFAULT DISABLE