ImageDev

Waterpixel

Computes an image of atomic regions that share common characteristics.

Access to parameter description

For an introduction: Superpixel techniques consist in segmenting an image into regions by considering similarity measures. The idea is to create a group of pixels that share common characteristics (like pixel intensity). The motivation is to obtain regions that represent meaningful descriptions with far less data than when using all image pixels.

Superpixels replace the rigid pixel structure by delineating regions that maintain meaning in the image, so the regions provide information about the structure of the scene, making other processing tasks simpler than using single image pixels.

The Waterpixel algorithm computes an image of binary borders or labeled regions associated to a grid of user-defined cell size. This grid is warped to fit the input image high intensities, generally representing edges. The warping is performed by applying a watershed on the input image. Markers used by the watershed are choosen as local minima close to the cell centers.
In order to ensure a regular size to the output superpixels, the input image is blended with the grid. A regularization factor is used to control the weight given to the grid relatively to the original intensities.

(a)
(a)
(b)
(b)
(c)
(c)
Figure 1. Superpixel generation with the waterpixel algorithm:(a) Input image given by a morphological gradient,
(b) waterpixels emphasizing the regular grid (high regularization factor), (c) waterpixels emphasizing the input image (low regularization factor)


Reference:
V. Machairas, E. Decenciere, T. Walter. "Waterpixels: Superpixels based on the watershed transformation". IEEE International Conference On Image Processing, Paris, France, Oct 2014.

See also

Function Syntax

This function returns the outputImage output parameter. 
// Function prototype.
std::shared_ptr< iolink::ImageView >
waterpixel( std::shared_ptr< iolink::ImageView > inputImage,
            uint32_t cellSize,
            uint32_t factor,
            Waterpixel::AlgorithmMode algorithmMode,
            Waterpixel::OutputType outputType,
            std::shared_ptr< iolink::ImageView > outputImage = NULL );
This function returns the outputImage output parameter. 
// Function prototype.
waterpixel( input_image,
            cell_size = 25,
            factor = 10,
            algorithm_mode = Waterpixel.AlgorithmMode.REPEATABLE,
            output_type = Waterpixel.OutputType.SEPARATED_REGIONS,
            output_image = None )
This function returns the outputImage output parameter. 
// Function prototype.
public static IOLink.ImageView
Waterpixel( IOLink.ImageView inputImage,
            UInt32 cellSize = 25,
            UInt32 factor = 10,
            Waterpixel.AlgorithmMode algorithmMode = ImageDev.Waterpixel.AlgorithmMode.REPEATABLE,
            Waterpixel.OutputType outputType = ImageDev.Waterpixel.OutputType.SEPARATED_REGIONS,
            IOLink.ImageView outputImage = null );

Class Syntax

Parameters

Class Name Waterpixel

Parameter Name Description Type Supported Values Default Value
input
inputImage
The input grayscale image highlighting object boundaries, generally a gradient image. Image Grayscale nullptr
input
cellSize
The side size, in pixels, of the square cells used to generate superpixels. UInt32 >=3 25
input
factor
The spatial regularization factor.
A low value makes the output superpixels fit on original intensities and generates irregular regions.
A high value makes the output superpixels fit on cell boundaries. 		UInt32 Any value 10
input
outputType
The type of output.
LINES The output image is a binary image containing superpixels boundaries.
CONTIGUOUS_REGIONS The output image is a label image representing connected superpixels.
SEPARATED_REGIONS The output image is a label image representing superpixels separated by a line of background.
Enumeration SEPARATED_REGIONS
input
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
output
outputImage
The output 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

std::shared_ptr< iolink::ImageView > ateneub_grad = ioformat::readImage( std::string( IMAGEDEVDATA_IMAGES_FOLDER ) + "ateneub_grad.tif" );

Waterpixel waterpixelAlgo;
waterpixelAlgo.setInputImage( ateneub_grad );
waterpixelAlgo.setCellSize( 25 );
waterpixelAlgo.setFactor( 10 );
waterpixelAlgo.setAlgorithmMode( Waterpixel::AlgorithmMode::REPEATABLE );
waterpixelAlgo.setOutputType( Waterpixel::OutputType::SEPARATED_REGIONS );
waterpixelAlgo.execute();

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

ateneub_grad = ioformat.read_image(imagedev_data.get_image_path("ateneub_grad.tif"))

waterpixel_algo = imagedev.Waterpixel()
waterpixel_algo.input_image = ateneub_grad
waterpixel_algo.cell_size = 25
waterpixel_algo.factor = 10
waterpixel_algo.algorithm_mode = imagedev.Waterpixel.REPEATABLE
waterpixel_algo.output_type = imagedev.Waterpixel.SEPARATED_REGIONS
waterpixel_algo.execute()

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

ImageView ateneub_grad = ViewIO.ReadImage( @"Data/images/ateneub_grad.tif" );

Waterpixel waterpixelAlgo = new Waterpixel
{
    inputImage = ateneub_grad,
    cellSize = 25,
    factor = 10,
    algorithmMode = Waterpixel.AlgorithmMode.REPEATABLE,
    outputType = Waterpixel.OutputType.SEPARATED_REGIONS
};
waterpixelAlgo.Execute();

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

Function Examples

std::shared_ptr< iolink::ImageView > ateneub_grad = ioformat::readImage( std::string( IMAGEDEVDATA_IMAGES_FOLDER ) + "ateneub_grad.tif" );

auto result = waterpixel( ateneub_grad, 25, 10, Waterpixel::AlgorithmMode::REPEATABLE, Waterpixel::OutputType::SEPARATED_REGIONS );

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

ateneub_grad = ioformat.read_image(imagedev_data.get_image_path("ateneub_grad.tif"))

result = imagedev.waterpixel( ateneub_grad, 25, 10, imagedev.Waterpixel.REPEATABLE, imagedev.Waterpixel.SEPARATED_REGIONS )

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

ImageView ateneub_grad = ViewIO.ReadImage( @"Data/images/ateneub_grad.tif" );

IOLink.ImageView result = Processing.Waterpixel( ateneub_grad, 25, 10, Waterpixel.AlgorithmMode.REPEATABLE, Waterpixel.OutputType.SEPARATED_REGIONS );

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