| Customize Help
| Save Settings

MimBinarize


Function Map
Syntax
Description
Parameters
- SrcImageBufId
- DstImageBufId
- ConditionAndThreshMode
- LowParam
- HighParam
Parameter Associations
Table: For controlling the threshold determination mode
+ combination: For specifying a threshold condition
Return value
Remarks
Compilation information
Synopsis
Perform a point-to-point binary threshold operation.
Syntax
MIL_INT MimBinarize(
MIL_ID SrcImageBufId, //in
MIL_ID DstImageBufId, //in
MIL_INT64 ConditionAndThreshMode, //in
MIL_DOUBLE LowParam, //in
MIL_DOUBLE HighParam //in
)
Description

This function performs a binary threshold operation on the specified image. Each pixel that meets the specified condition is set to the highest unsigned destination buffer value, while other pixels are set to 0. For example, the highest buffer value for an 8-bit buffer is 0xff (regardless if the source buffer is signed). If a floating-point destination buffer is specified, pixels that meet the condition are set to 1.

There are 5 ways to establish the threshold value(s); two that manually set the threshold value(s) (M_FIXED and M_PERCENTILE_VALUE) and three that automatically base the threshold value(s) on the histogram (M_BIMODAL, M_TRIANGLE_BISECTION_DARK, and M_TRIANGLE_BISECTION_BRIGHT).

You can limit this function's results to a region of an image buffer using a region of interest (ROI) set using MbufSetRegion(). The ROI must be defined in raster format (M_RASTER or M_VECTOR_AND_RASTER). An error is generated if the ROI is only in vector format (M_VECTOR).

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 which MIL system’s documentation you should use in its place and any possible differences.
Parameters
This function is not supported on the selected boards.
This function reference has not been updated for the selected MIL system. To show the content of this page, choose a second MIL system; refer to the MIL system's release note to see which MIL system’s documentation to choose and any possible differences.
Parameters
SrcImageBufId

Specifies the identifier of the data source of the operation. This parameter must be given an image buffer identifier.

This image buffer can have an ROI set using MbufSetRegion(). The ROI must be defined in raster format (M_RASTER or M_VECTOR_AND_RASTER). An error is generated if the ROI is only in vector format (M_VECTOR).

DstImageBufId

Specifies the identifier of the destination image buffer in which to write the results. In general, this parameter must be given an image buffer identifier.

This image buffer can have an ROI set using MbufSetRegion(). The ROI must be defined in raster format (M_RASTER or M_VECTOR_AND_RASTER). An error is generated if the ROI is only in vector format (M_VECTOR).

To return only the automatically calculated threshold value, if applicable, set the DstImageBufId parameter to M_NULL. Note that if the DstImageBufId parameter is set to M_NULL, the MimBinarize() function will be forced to run synchronously.

ConditionAndThreshMode

Specifies the condition, as well as the threshold mode to use to establish the threshold value(s) of the condition.

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

LowParam

Specifies either the lower limit of the selected condition or the minimum value to use when establishing the threshold.

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

HighParam

Specifies either the upper limit of the selected condition or the maximum value to use when establishing the threshold.

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

Parameter associations

The table below lists possible values for the ConditionAndThreshMode, LowParam, and HighParam parameters.

The following conditions allow you to control the threshold determination mode used.

function map For controlling the threshold determination mode
Click to summarizeConditionAndThreshMode Description
LowParam
HighParam
Click to summarize M_BIMODAL +

Specifies to automatically establish the threshold value for the condition from the source image's histogram, using the bimodal threshold mode.

This threshold mode can only be used if the condition uses one limit.

In this mode, if the source image's histogram contains only two peaks, the threshold value is set to the intensity value at the lowest point between these two peaks of the histogram, on the assumption that these peaks represent the object and the background. If the histogram contains more than two peaks, the threshold value will typically be set between the intensity values at the two principal peaks, although exceptions exist for the situations where the principal peaks occur are closest to the minimum intensity value (pure black) or the maximum intensity value (full saturation). Note that the bimodal threshold mode works best when the histogram contains two visible peaks.

You can limit the intensity value range of the histogram from which the threshold value is established. To do so, use the LowParam and HighParam parameters.


You must specify a combination value from the following table:
(summarize)
Click to summarize LowParam

Sets the minimum pixel value in the source image's histogram to use when establishing the threshold value.

(summarize)
Click to summarize M_NULL

Specifies to use the full range of pixel values in the histogram. This setting is only valid when HighParam is also set to M_NULL.

(summarize)
Click to summarize Value

Specifies the minimum pixel value. The minimum value must be less than or equal to the maximum value.

(summarize)
Click to summarize HighParam

Sets the maximum pixel value in the source image's histogram to use when establishing the threshold value.

(summarize)
Click to summarize M_NULL

Specifies to use the full range of pixel values in the histogram. This setting is only valid when LowParam is also set to M_NULL.

(summarize)
Click to summarize Value

Specifies the maximum pixel value. The maximum value must be greater than or equal to the minimum value.

(summarize)
Click to summarize M_FIXED +

Specifies that the threshold value(s) for the condition are specified explicitly.


You must specify a combination value from the following table:
(summarize)
Click to summarize LowParam

Sets the threshold value to use as the lower limit of the selected condition. The lower limit must be less than or equal to the upper limit.

(summarize)
Click to summarize HighParam

Sets the upper limit of the selected condition.

(summarize)
Click to summarize M_NULL

Specifies not to use an upper limit. Use this setting when the condition uses only one limit.

(summarize)
Click to summarize Value

Specifies the threshold value to use as the upper limit of the selected condition. The upper limit must be greater than or equal to the lower limit.

(summarize)
Click to summarize M_PERCENTILE_VALUE +

Specifies that the threshold value(s) for the condition are specified as a percentage of the source image's histogram data. In this mode, you specify a threshold value by specifying the percentage of pixels that must be equal to or less than the required threshold value.


You must specify a combination value from the following table:
(summarize)
Click to summarize LowParam

Sets the lower limit of the selected condition.

(summarize)
Click to summarize 0 <= Value <= 100

Specifies the lower limit as a percentage of the source image's histogram data. The lower limit must be less than or equal to the upper limit.

(summarize)
Click to summarize HighParam

Sets the upper limit of the selected condition.

(summarize)
Click to summarize M_NULL

Specifies not to use an upper limit. Use this setting when the condition uses only one limit.

(summarize)
Click to summarize 0 <= Value <= 100

Specifies the upper limit as a percentage of the source image's histogram data. The upper limit must be greater than or equal to the lower limit.

(summarize)
Click to summarize M_TRIANGLE_BISECTION_BRIGHT +

Specifies to automatically establish the threshold value for the condition from the source image's histogram, using the bright triangle bisection threshold mode.

This threshold mode can only be used if the condition uses one limit.

In bright triangular bisection threshold mode, MIL establishes the tallest peak in the source image's histogram (the most commonly-occurring value) and the lowest point (the least commonly-occurring value) when heading from the peak toward its maximum intensity value. It then connects these two points by a line. The threshold value is the intensity value at the point furthest below that line (the inflection point). Note that all points above the line are ignored.

You can limit the intensity value range of the histogram from which the threshold value is established. To do so, use the LowParam and HighParam parameters.


You must specify a combination value from the following table:
(summarize)
Click to summarize LowParam

Sets the minimum pixel value in the source image's histogram to use when establishing the threshold value.

(summarize)
Click to summarize M_NULL

Specifies to use the full range of pixel values in the histogram. This setting is only valid when HighParam is also set to M_NULL.

(summarize)
Click to summarize Value

Specifies the minimum pixel value. The minimum value must be less than or equal to the maximum value.

(summarize)
Click to summarize HighParam

Sets the maximum pixel value in the source image's histogram to use when establishing the threshold value.

(summarize)
Click to summarize M_NULL

Specifies to use the full range of pixel values in the histogram. This setting is only valid when LowParam is also set to M_NULL.

(summarize)
Click to summarize Value

Specifies the maximum pixel value. The maximum value must be greater than or equal to the minimum value.

(summarize)
Click to summarize M_TRIANGLE_BISECTION_DARK +

Specifies to automatically establish the threshold value for the condition from the source image's histogram, using the dark triangle bisection threshold mode.

This threshold mode can only be used if the condition uses one limit.

In dark triangular bisection threshold mode, MIL establishes the tallest peak in the source image's histogram (the most commonly-occurring value) and the lowest point (the least commonly-occurring value) when heading from the peak toward its minimum intensity value. It then connects these two points by a line. The threshold value is the intensify value at the point furthest below that line (the inflection point). Note that all points above the line are ignored.

You can limit the intensity value range of the histogram from which the threshold value is established. To do so, use the LowParam and HighParam parameters.


You must specify a combination value from the following table:
(summarize)
Click to summarize LowParam

Sets the minimum pixel value in the source image's histogram to use when establishing the threshold value.

(summarize)
Click to summarize M_NULL

Specifies to use the full range of pixel values in the histogram. This setting is only valid when HighParam is also set to M_NULL.

(summarize)
Click to summarize Value

Specifies the minimum pixel value. The minimum value must be less than or equal to the maximum value.

(summarize)
Click to summarize HighParam

Sets the maximum pixel value in the source image's histogram to use when establishing the threshold value.

(summarize)
Click to summarize M_NULL

Specifies to use the full range of pixel values in the histogram. This setting is only valid when LowParam is also set to M_NULL.

(summarize)
Click to summarize Value

Specifies the maximum pixel value. The maximum value must be greater than or equal to the minimum value.

(summarize)
Combination values for the values listed in For controlling the threshold determination mode.

You must add one of the following values to the above-mentioned values to specify a threshold condition.

function map For specifying a threshold condition
Click to summarize
Combination value		 Description
Click to summarize M_EQUAL

Sets pixel values equal to the threshold value to the highest buffer value possible, while other pixels are set to zero.

Note that if using a floating-point destination buffer, pixels that meet the condition are set to 1.

(summarize)
Click to summarize M_GREATER

Sets pixel values greater than the threshold value to the highest buffer value possible, while other pixels are set to zero.

Note that if using a floating-point destination buffer, pixels that meet the condition are set to 1.

(summarize)
Click to summarize M_GREATER_OR_EQUAL

Sets pixel values greater than or equal to the threshold value to the highest buffer value possible, while other pixels are set to zero.

Note that if using a floating-point destination buffer, pixels that meet the condition are set to 1.

(summarize)
Click to summarize M_IN_RANGE

Sets pixels with values between the lower threshold value and the higher threshold value, inclusive, to the highest buffer value. Other pixels are set to 0.

Note that this is only applicable to constants that can use two limits (M_FIXED and M_PERCENTILE_VALUE).

If a floating-point destination buffer is specified, pixels that meet the condition are set to 1.

(summarize)
Click to summarize M_LESS

Sets pixel values less than the threshold value to the highest buffer value possible, while other pixels are set to zero.

Note that if using a floating-point destination buffer, pixels that meet the condition are set to 1.

(summarize)
Click to summarize M_LESS_OR_EQUAL

Sets pixel values less than or equal to the threshold value to the highest buffer value possible, while other pixels are set to zero.

Note that if using a floating-point destination buffer, pixels that meet the condition are set to 1.

(summarize)
Click to summarize M_NOT_EQUAL

Sets pixel values not equal to the threshold value to the highest buffer value possible, while other pixels are set to zero.

Note that if using a floating-point destination buffer, pixels that meet the condition are set to 1.

(summarize)
Click to summarize M_OUT_RANGE

Sets pixels with values less than the lower threshold value or greater than the higher threshold value, to the highest buffer value. Other pixels are set to 0.

Note that this is only applicable to constants that can use two limits (M_FIXED and M_PERCENTILE_VALUE).

If a floating-point destination buffer is specified, pixels that meet the condition are set to 1.

(summarize)
Return value
When DstImageBufId is given an image buffer identifier, this function returns the specified value of the LowParam parameter. When DstImageBufId is set to M_NULL and the ConditionAndThreshMode parameter is set to one of the automatic threshold modes (M_BIMODAL, M_TRIANGLE_BISECTION_DARK, or M_TRIANGLE_BISECTION_BRIGHT), this function returns the automatically calculated threshold value. If the ConditionAndThreshMode parameter is set to M_PERCENTILE_VALUE, this function returns the threshold value established from the specified lower limit. When dealing with floating-point source buffers, the returned threshold is truncated to an integer value. Therefore, the returned threshold and the actual threshold used to binarize can differ.
Remark
Compilation information
Header Include mil.h.
Library Use mil.lib; milim.lib.
DLL Requires mil.dll; milim.dll.
PROC NONE RASTER VECTOR AND RASTER PROC NONE RASTER VECTOR AND RASTER BIMODAL NULL NULL FIXED NULL PERCENTILE VALUE NULL TRIANGLE BISECTION BRIGHT NULL NULL TRIANGLE BISECTION DARK NULL NULL EQUAL GREATER GREATER OR EQUAL IN RANGE LESS LESS OR EQUAL NOT EQUAL OUT RANGE FIXED PERCENTILE VALUE