| MIL 10 Reference
| Customize Help
| Save Settings

MimBinarize


See also
Availability
Available in MIL-Lite
Available in MIL

Available on Windows
Available on Linux

Partially supported on:
Partially supported on Matrox GPU processing driver

Fully supported on:
Fully supported on Host system
Fully supported on Matrox CronosPlus
Fully supported on Matrox GigE Vision driver
Fully supported on Matrox IEEE 1394 IIDC driver
Fully supported on Matrox Iris GT
Fully supported on Matrox Morphis
Fully supported on Matrox Morphis QxT
Fully supported on Matrox Orion HD
Fully supported on Matrox Radient eCL
Fully supported on Matrox Radient eV-CXP
Fully supported on Matrox Solios eA/XA
Fully supported on Matrox Solios ecl/xcl/ev-cl
Fully supported on Matrox USB3 Vision driver (requires Update 19)
Fully supported on Matrox Vio

For any information regarding a MIL system added during a MIL Update, see the MIL system’s release note

Available on Non-Matrox computer
Available on Matrox 4Sight-X
Available on Matrox 4Sight GP
Available on Matrox Supersight
function map Function map
Examples
MimArithMultiple
MimBinarizeAdaptive
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).

When establishing a manually set threshold value (using M_FIXED), the source and destination image buffers 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).

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.

When establishing a fixed threshold value, if you specify an image buffer that has an ROI associated with it, the ROI must be in raster format; otherwise, you will get an error.

[Matrox GPU processing driver]

The source image buffer must be unsigned monochrome 1- (packed binary), 8-, or 16-bit, or M_BGR32 packed.

DstImageBufId

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

When establishing a fixed threshold value, if you specify an image buffer that has an ROI associated with it, the ROI must be in raster format; otherwise, you will get an error.

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.

[Matrox GPU processing driver]

The destination image buffer must be unsigned monochrome 1- (packed binary), 8-, or 16-bit, or M_BGR32 packed. This parameter must not be set to M_NULL.

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
CollapseConditionAndThreshMode Description
LowParam
HighParam
Collapse 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)
Collapse LowParam

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

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

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

(summarize)
Collapse HighParam

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

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

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

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

Sets the upper limit of the selected condition.

(summarize)
Collapse M_NULL

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

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

Sets the lower limit of the selected condition.

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

Sets the upper limit of the selected condition.

(summarize)
Collapse M_NULL

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

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

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

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

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

(summarize)
Collapse HighParam

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

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

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

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

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

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

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

(summarize)
Collapse HighParam

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

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

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

(summarize)

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
CollapseCombination value Description
Collapse 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)
Collapse 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)
Collapse 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)
Collapse 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)
Collapse 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)
Collapse 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)
Collapse 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)
Collapse 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 NONE NONE RASTER VECTOR AND RASTER RASTER VECTOR AND RASTER FIXED PERCENTILE VALUE