| MIL 10 Reference
| Customize Help
| Save Settings

MimWatershed


See also
Reference:
MbufInquire
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
MimWarp
MimWaveletDenoise
Synopsis
Perform a watershed transformation.
Syntax
void MimWatershed(
MIL_ID SrcImageBufId, //in
MIL_ID MarkerImageBufId, //in
MIL_ID DstImageBufId, //in
MIL_INT MinVariation, //in
MIL_INT64 ControlFlag //in
)
Description

This function performs a watershed transformation on the specified source buffer. The catchment basins of the source buffer can be determined from extrema (minima or maxima) in the source buffer and/or from a specified marker image. In the case when no marker image is specified, a valid catchment basin is determined from an extrema when the minimum variation in gray levels of an extremum's catchment basin is equal to or greater than the value specified by the MinVariation parameter. In the case when a marker image is specified, each marker of a marker image produces catchment basin(s) by forcing an extremum in the corresponding area(s) of the source buffer.

There are two types of marker images: non-labeled and labeled. In a non-labeled marker image, each group of touching pixels with the value zero in the marker image (known as a marker) starts a catchment basin in the corresponding area of the source image. Specifically, each marker in the marker image forces a extremum in the corresponding area of the source image. Pixels in the marker image are considered touching if they are vertically, horizontally, or diagonally adjacent, that is, if they are "8-connected". Note that each catchment basin in the destination image is given a unique grayscale value, starting at 1.

In a labeled marker image, a marker is a set of pixels that do not have to necessarily touch and that have all the same label value (pixel intensity). Each marker starts a catchment basin in the corresponding area of the source image and each catchment basin of the destination image is assigned the label value of the marker that generated it. Note that, in a labeled marker image, a marker can touch other markers, allowing you to specify adjacent catchment basins. Valid marker label values are 1 to 2 n - 2 (where n refers to the number of bits per pixel in the buffer). Pixels with the label value of zero are interpreted as the region of the image that is not a marker. Finally, pixels with the label value of 2 n - 1 are considered to be part of a "don't care" mask and are not processed, accelerating the watershed transformation.

You can specify that the destination buffer contain one of the following:

  • Watershed lines. The watershed lines are given the value 0 and all other pixels are given the maximum value in the destination buffer.

  • Labeled catchment basins, without watershed lines. Each catchment basin is assigned a grayscale value greater or equal to 1.

  • Labeled catchment basins and watershed lines. Each catchment basin is assigned a grayscale value greater or equal to 1. Watershed lines are given the value 0.

For more information, see the Watershed transformations section of Chapter 4: Advanced image processing.

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
SrcImageBufId

Specifies the buffer on which to perform the transform. This buffer can be 8-bit or 16-bit, signed or unsigned.

This image buffer must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

MarkerImageBufId

Specifies the buffer to use as a marker image. This buffer can be 8-bit or 16-bit, signed or unsigned. If you are not using a marker image, set this parameter to M_NULL.

This image buffer must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

The default marker image type is non-labeled. If you want to use a labeled marker image, you must add M_LABELED_MARKER to the ControlFlag parameter.

DstImageBufId

Specifies the buffer in which to place the results of the transformation. This buffer can be 8-bit or 16-bit, signed or unsigned. The destination buffer can hold 2 n - 5 catchment basins, where n refers to the number of bits per pixel in the buffer. Therefore, an 8-bit destination buffer can hold 251 catchment basins and a 16-bit destination buffer can hold 65531 catchment basins.

This image buffer must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

MinVariation

Specifies the minimum variation of gray-level of a catchment basin. This parameter must be set to one of the values below.

function map For specifying the minimum variation of gray-level
CollapseValue Description
Collapse M_DEFAULT

Produces a catchment basin from each extremum in the source buffer. Setting MinVariation to 1 will have the same effect.

(summarize)
Collapse M_OFF

Specifies that catchment basins will not be determined from extrema in the source buffer.
Collapse Value

Sets the minimum variation.
ControlFlag

Specifies how to perform the transformation. It can be set to any combination of the following seven sets of values below. It can also be set to M_DEFAULT, in which case the default value from each set is used (without M_SKIP_LAST_LEVEL, M_LABELED_MARKER and M_FILL_SOURCE). If no value from a set is specified, its default value is used.

function map For specifying how to perform the transformation
CollapseValue Description
Collapse M_DEFAULT

Same as M_WATERSHED + M_MINIMA_FILL + M_REGULAR + M_4_CONNECTED.
Collapse M_BASIN +

Labels catchment basins.
Collapse M_WATERSHED +

Calculates watershed lines.
Collapse M_WATERSHED + M_BASIN +

Labels catchment basin and calculates watershed lines.
Combination constants for any of the possible values of the ControlFlag parameter.

You can add one of the following values to the above-mentioned values to specify whether to use the source buffer's minima or maxima when determining catchment basins from extrema in the source buffer.

function map For specifying whether to use the source buffer's minima or maxima
CollapseCombination value Description
Collapse M_MAXIMA_FILL

Uses the source buffer's maxima.
Collapse M_MINIMA_FILL

Uses the source buffer's minima.

This is the default value.

(summarize)
Combination constants for any of the possible values of the ControlFlag parameter.

You can add one of the following values to the above-mentioned values to specify how the watershed lines are drawn.

function map For specifying how the watershed lines are drawn
CollapseCombination value Description
Collapse M_REGULAR

Traces the watershed lines exactly.

This is the default value.

(summarize)
Collapse M_STRAIGHT_WATERSHED

Forces the watershed lines to be straight. Note that selecting M_STRAIGHT_WATERSHED automatically selects the M_SKIP_LAST_LEVEL setting.

(summarize)
Combination constants for any of the possible values of the ControlFlag parameter.

You can add one of the following values to the above-mentioned values to specify whether 4 or 8-connected watershed lines will be used.

function map For specifying 4 or 8-connected watershed lines
CollapseCombination value Description
Collapse M_4_CONNECTED

Uses 4-connected watershed lines.

This is the default value.

(summarize)
Collapse M_8_CONNECTED

Uses 8-connected watershed lines.
Combination constant for any of the possible values of the ControlFlag parameter.

You can add the following value to the above-mentioned values to specify that an extremum's zone of influence cannot extend past the minimum and maximum gray level.

function map For preventing an extremum's zone of influence from extending past the minimum and maximum gray level
CollapseCombination value Description
Collapse M_SKIP_LAST_LEVEL

Prevents an extremum's zone of influence from extending beyond Lmax - 1 (for a minimum) or Lmin - 1 (for a maximum), where Lmax is the maximum gray level in the image and Lmin is the minimum gray level.
Combination constant for any of the possible values of the ControlFlag parameter.

You can add the following value to the above-mentioned values to specify that the marker image is a labeled marker image.

function map For denoting that the marker image is labeled
CollapseCombination value Description
Collapse M_LABELED_MARKER

Specifies that the marker image is a labeled marker image.
Combination constant for any of the possible values of the ControlFlag parameter.

You can add the following value to the above-mentioned values to specify that any unwanted extrema from the source image is removed.

It removes the extrema by filling the catchment basins of unwanted extrema until they become plateaus.

function map For removing unwanted extrema
CollapseCombination value Description
Collapse M_FILL_SOURCE

Fill all local basins of a valid catchment basin in the source image.
Compilation information
Header Include mil.h.
Library Use mil.lib; milim.lib.
DLL Requires mil.dll; milim.dll.
FLOAT PROC NONE FLOAT PROC NONE FLOAT PROC NONE DEFAULT OFF DEFAULT BASIN WATERSHED WATERSHED M BASIN MAXIMA FILL MINIMA FILL REGULAR STRAIGHT WATERSHED 4 CONNECTED 8 CONNECTED SKIP LAST LEVEL LABELED MARKER FILL SOURCE