HExtremaWatershedByBlock

Computes the watershed lines of a grayscale image in a low memory consumption mode.

Access to parameter description

For an introduction:

section Introduction To Watershed
section Geodesic Transformations

This algorithm is equivalent to the HExtremaWatershed algorithm, but uses a totally different strategy in order to require much less memory.

It is based on a block-wise implementation of the watershed algorithm, building a graph allowing the propagation of the catchments areas through the entire image.

Note:

This algorithm requires less free memory than the HExtremaWatershed algorithm but is much slower to execute.
As the implementation is totally different, the results of both algorithms may differ slightly, especially on areas where the input landscape image contains some plateaus.

See also

Function Syntax

This function returns outputImage.

// Function prototype
std::shared_ptr< iolink::ImageView >
hExtremaWatershedByBlock( std::shared_ptr< iolink::ImageView > inputGrayImage,
                          HExtremaWatershedByBlock::ObjectLightness objectLightness,
                          int32_t contrastValue,
                          HExtremaWatershedByBlock::OutputType outputType,
                          HExtremaWatershedByBlock::AlgorithmMode algorithmMode,
                          int32_t blockSize,
                          HExtremaWatershedByBlock::Neighborhood neighborhood,
                          std::shared_ptr< iolink::ImageView > outputImage = NULL );

This function returns outputImage.

// Function prototype.
h_extrema_watershed_by_block( input_gray_image,
                              object_lightness = HExtremaWatershedByBlock.ObjectLightness.DARK_OBJECTS,
                              contrast_value = 30,
                              output_type = HExtremaWatershedByBlock.OutputType.SEPARATED_OBJECTS,
                              algorithm_mode = HExtremaWatershedByBlock.AlgorithmMode.REPEATABLE,
                              block_size = 256,
                              neighborhood = HExtremaWatershedByBlock.Neighborhood.CONNECTIVITY_26,
                              output_image = None )

This function returns outputImage.

// Function prototype.
public static IOLink.ImageView
HExtremaWatershedByBlock( IOLink.ImageView inputGrayImage,
                          HExtremaWatershedByBlock.ObjectLightness objectLightness = ImageDev.HExtremaWatershedByBlock.ObjectLightness.DARK_OBJECTS,
                          Int32 contrastValue = 30,
                          HExtremaWatershedByBlock.OutputType outputType = ImageDev.HExtremaWatershedByBlock.OutputType.SEPARATED_OBJECTS,
                          HExtremaWatershedByBlock.AlgorithmMode algorithmMode = ImageDev.HExtremaWatershedByBlock.AlgorithmMode.REPEATABLE,
                          Int32 blockSize = 256,
                          HExtremaWatershedByBlock.Neighborhood neighborhood = ImageDev.HExtremaWatershedByBlock.Neighborhood.CONNECTIVITY_26,
                          IOLink.ImageView outputImage = null );

Class Syntax

// Command constructor.
HExtremaWatershedByBlock();

/// Gets the inputGrayImage parameter.
/// The input grayscale image.
std::shared_ptr< iolink::ImageView > inputGrayImage() const;
/// Sets the inputGrayImage parameter.
/// The input grayscale image.
void setInputGrayImage( std::shared_ptr< iolink::ImageView > inputGrayImage );

/// Gets the objectLightness parameter.
/// The lightness of objects to separate.
HExtremaWatershedByBlock::ObjectLightness objectLightness() const;
/// Sets the objectLightness parameter.
/// The lightness of objects to separate.
void setObjectLightness( const HExtremaWatershedByBlock::ObjectLightness& objectLightness );

/// Gets the contrastValue parameter.
/// The depth of the valley used to select the markers of the watershed.
int32_t contrastValue() const;
/// Sets the contrastValue parameter.
/// The depth of the valley used to select the markers of the watershed.
void setContrastValue( const int32_t& contrastValue );

/// Gets the outputType parameter.
/// The type of result image.
HExtremaWatershedByBlock::OutputType outputType() const;
/// Sets the outputType parameter.
/// The type of result image.
void setOutputType( const HExtremaWatershedByBlock::OutputType& outputType );

/// Gets the algorithmMode parameter.
/// The mode for applying the watershed algorithm.
HExtremaWatershedByBlock::AlgorithmMode algorithmMode() const;
/// Sets the algorithmMode parameter.
/// The mode for applying the watershed algorithm.
void setAlgorithmMode( const HExtremaWatershedByBlock::AlgorithmMode& algorithmMode );

/// Gets the blockSize parameter.
/// The size of blocks used to crop the input images.
int32_t blockSize() const;
/// Sets the blockSize parameter.
/// The size of blocks used to crop the input images.
void setBlockSize( const int32_t& blockSize );

/// Gets the neighborhood parameter.
/// The 3D neighborhood configuration. This parameter is ignored with a 2D input image.
HExtremaWatershedByBlock::Neighborhood neighborhood() const;
/// Sets the neighborhood parameter.
/// The 3D neighborhood configuration. This parameter is ignored with a 2D input image.
void setNeighborhood( const HExtremaWatershedByBlock::Neighborhood& neighborhood );

/// Gets the outputImage parameter.
/// The output grayscale, binary or label image. Its dimensions are forced to the same values as the input image. Its type depends on the outputType parameter.
std::shared_ptr< iolink::ImageView > outputImage() const;
/// Sets the outputImage parameter.
/// The output grayscale, binary or label image. Its dimensions are forced to the same values as the input image. Its type depends on the outputType parameter.
void setOutputImage( std::shared_ptr< iolink::ImageView > outputImage );


// Method to launch the command.
void execute();

# Property of the inputGrayImage parameter.
HExtremaWatershedByBlock.input_gray_image
# Property of the objectLightness parameter.
HExtremaWatershedByBlock.object_lightness
# Property of the contrastValue parameter.
HExtremaWatershedByBlock.contrast_value
# Property of the outputType parameter.
HExtremaWatershedByBlock.output_type
# Property of the algorithmMode parameter.
HExtremaWatershedByBlock.algorithm_mode
# Property of the blockSize parameter.
HExtremaWatershedByBlock.block_size
# Property of the neighborhood parameter.
HExtremaWatershedByBlock.neighborhood
# Property of the outputImage parameter.
HExtremaWatershedByBlock.output_image

// Method to launch the command.
execute()

// Command constructor.
HExtremaWatershedByBlock()

// Property of the inputGrayImage parameter.
HExtremaWatershedByBlock.inputGrayImage
// Property of the objectLightness parameter.
HExtremaWatershedByBlock.objectLightness
// Property of the contrastValue parameter.
HExtremaWatershedByBlock.contrastValue
// Property of the outputType parameter.
HExtremaWatershedByBlock.outputType
// Property of the algorithmMode parameter.
HExtremaWatershedByBlock.algorithmMode
// Property of the blockSize parameter.
HExtremaWatershedByBlock.blockSize
// Property of the neighborhood parameter.
HExtremaWatershedByBlock.neighborhood
// Property of the outputImage parameter.
HExtremaWatershedByBlock.outputImage

// Method to launch the command.
Execute()

Parameters

Class Name	HExtremaWatershedByBlock

Parameter Name

Description

Type

Supported Values

Default Value

inputGrayImage

The input grayscale image.

Image

Grayscale

nullptr

objectLightness

The lightness of objects to separate.

DARK_OBJECTS	The watershed is directly applied on the input image in order to separate dark areas.
WHITE_OBJECTS	The watershed is applied on the negative of the input image in order to separate bright areas.

Enumeration

DARK_OBJECTS

contrastValue

The depth of the valley used to select the markers of the watershed.

Int32

>=0

outputType

The type of result image.

SEPARATED_OBJECTS	The result image is a grayscale image representing the original from which separation lines are added to dark objects or subtracted from bright objects (split areas).
WATERSHED_RIDGES	The result image is a binary image representing the separation lines (watershed).
SEPARATED_BASINS	The result image is a label image representing the catchment areas (labeled complement of the watershed).
CONTIGUOUS_OBJECTS	The result image is a label image representing the catchment areas with separation lines filled by a label.

Enumeration

SEPARATED_OBJECTS

algorithmMode

The mode for applying the watershed algorithm.

REPEATABLE	The result is repeatable but slower to compute.
FAST	The result is faster to compute but not repeatable because of asynchronous parallel computation. Since a watershed problem does not generally have a unique solution, two processings of the same image can lead to two different results (both exact).

Enumeration

REPEATABLE

blockSize

The size of blocks used to crop the input images.

Int32

>=32

256

neighborhood

The 3D neighborhood configuration. This parameter is ignored with a 2D input image.

CONNECTIVITY_6	The structuring element is composed of voxels with a common face with the voxel of interest.
CONNECTIVITY_18	The structuring element is composed of voxels with at least one common edge.
CONNECTIVITY_26	The structuring element is a full cube.

Enumeration

CONNECTIVITY_26

outputImage

The output grayscale, binary or label image. Its dimensions are forced to the same values as the input image. Its type depends on the outputType parameter.

Image

nullptr

Object Examples

auto foam = readVipImage( std::string( IMAGEDEVDATA_IMAGES_FOLDER ) + "foam.vip" );

HExtremaWatershedByBlock hExtremaWatershedByBlockAlgo;
hExtremaWatershedByBlockAlgo.setInputGrayImage( foam );
hExtremaWatershedByBlockAlgo.setObjectLightness( HExtremaWatershedByBlock::ObjectLightness::DARK_OBJECTS );
hExtremaWatershedByBlockAlgo.setContrastValue( 30 );
hExtremaWatershedByBlockAlgo.setOutputType( HExtremaWatershedByBlock::OutputType::SEPARATED_OBJECTS );
hExtremaWatershedByBlockAlgo.setAlgorithmMode( HExtremaWatershedByBlock::AlgorithmMode::REPEATABLE );
hExtremaWatershedByBlockAlgo.setBlockSize( 256 );
hExtremaWatershedByBlockAlgo.setNeighborhood( HExtremaWatershedByBlock::Neighborhood::CONNECTIVITY_26 );
hExtremaWatershedByBlockAlgo.execute();

std::cout << "outputImage:" << hExtremaWatershedByBlockAlgo.outputImage()->toString();

foam = imagedev.read_vip_image(imagedev_data.get_image_path("foam.vip"))

h_extrema_watershed_by_block_algo = imagedev.HExtremaWatershedByBlock()
h_extrema_watershed_by_block_algo.input_gray_image = foam
h_extrema_watershed_by_block_algo.object_lightness = imagedev.HExtremaWatershedByBlock.DARK_OBJECTS
h_extrema_watershed_by_block_algo.contrast_value = 30
h_extrema_watershed_by_block_algo.output_type = imagedev.HExtremaWatershedByBlock.SEPARATED_OBJECTS
h_extrema_watershed_by_block_algo.algorithm_mode = imagedev.HExtremaWatershedByBlock.REPEATABLE
h_extrema_watershed_by_block_algo.block_size = 256
h_extrema_watershed_by_block_algo.neighborhood = imagedev.HExtremaWatershedByBlock.CONNECTIVITY_26
h_extrema_watershed_by_block_algo.execute()

print( "output_image:", str( h_extrema_watershed_by_block_algo.output_image ) )

ImageView foam = Data.ReadVipImage( @"Data/images/foam.vip" );

HExtremaWatershedByBlock hExtremaWatershedByBlockAlgo = new HExtremaWatershedByBlock
{
    inputGrayImage = foam,
    objectLightness = HExtremaWatershedByBlock.ObjectLightness.DARK_OBJECTS,
    contrastValue = 30,
    outputType = HExtremaWatershedByBlock.OutputType.SEPARATED_OBJECTS,
    algorithmMode = HExtremaWatershedByBlock.AlgorithmMode.REPEATABLE,
    blockSize = 256,
    neighborhood = HExtremaWatershedByBlock.Neighborhood.CONNECTIVITY_26
};
hExtremaWatershedByBlockAlgo.Execute();

Console.WriteLine( "outputImage:" + hExtremaWatershedByBlockAlgo.outputImage.ToString() );

Function Examples

auto foam = readVipImage( std::string( IMAGEDEVDATA_IMAGES_FOLDER ) + "foam.vip" );

auto result = hExtremaWatershedByBlock( foam, HExtremaWatershedByBlock::ObjectLightness::DARK_OBJECTS, 30, HExtremaWatershedByBlock::OutputType::SEPARATED_OBJECTS, HExtremaWatershedByBlock::AlgorithmMode::REPEATABLE, 256, HExtremaWatershedByBlock::Neighborhood::CONNECTIVITY_26 );

std::cout << "outputImage:" << result->toString();

foam = imagedev.read_vip_image(imagedev_data.get_image_path("foam.vip"))

result = imagedev.h_extrema_watershed_by_block( foam, imagedev.HExtremaWatershedByBlock.DARK_OBJECTS, 30, imagedev.HExtremaWatershedByBlock.SEPARATED_OBJECTS, imagedev.HExtremaWatershedByBlock.REPEATABLE, 256, imagedev.HExtremaWatershedByBlock.CONNECTIVITY_26 )

print( "output_image:", str( result ) )

ImageView foam = Data.ReadVipImage( @"Data/images/foam.vip" );

IOLink.ImageView result = Processing.HExtremaWatershedByBlock( foam, HExtremaWatershedByBlock.ObjectLightness.DARK_OBJECTS, 30, HExtremaWatershedByBlock.OutputType.SEPARATED_OBJECTS, HExtremaWatershedByBlock.AlgorithmMode.REPEATABLE, 256, HExtremaWatershedByBlock.Neighborhood.CONNECTIVITY_26 );

Console.WriteLine( "outputImage:" + result.ToString() );

HExtremaWatershedByBlock

- Function Syntax

+ Class Syntax

Parameters

Object Examples

Function Examples

Function Syntax

Class Syntax