Struct SegmentingWatershed

pub struct SegmentingWatershed<T = ()> { /* private fields */ }

Implementation of the segmenting watershed algorithm.

See crate-level documentation for a general introduction to the algorithm.

The segmenting watershed algorithm forms lakes from pre-defined local minima by raising an imaginary water level. Once the water level increases past the height of a minimum, it starts filling neighbouring pixels that are also below the water level. These poodles grow larger as the water level rises.

When two lakes originating from different local minima meet, an infinitely high wall separating the two is created. This is wall-building is what makes this version of the watershed algorithm an image segmentation algorithm.

Memory usage of transform_history

The transform_history method makes a copy of the Array2<usize> image used during the watershed transform to keep track of the intermediate images. As such, it allocates a new Array2<usize> for each water level, which increases memory usage by a factor equal to the maximum water level as configured by the TransformBuilder.

Output

The three methods of the Watershed trait each return a different set of parameters based on the watershed transform of the input image:

• transform simply returns the watershed transform of the image.
• transform_to_list returns a list of the areas of all the lakes at each water level. Its return type isVec<(u8, Vec<usize>)>, where the u8 equals the water level and the Vec<usize> is the list of areas of all the lakes at each water level. The Vec<usize> is the same length for each water level, but may contain zero-sided lakes. The water levels are returned in order.
• transform_history returns a list of intermediate images of the watershed transform at every water level. Its return type is Vec<(u8, ndarray::Array2<usize>), where the u8 holds the water level that each Array2 snapshot was taken at. The water levels are returned in order.

Artifacts and peculiarities

Due to some implementation details, the 1px-wide edges of the input array are not accessible to the watershed transform. They will thus remain unfilled for the entire duration of the transform.

A workaround can be enabled by calling enable_edge_correction on the TransformBuilder. Enabling this setting copies the input image into a new array, 1px wider on all sides. This padded array is then used as the actual input to the watershed transform. The final output of the transform is a copy of this intermediate array with the padding removed. The padding also does not show up in the output of intermediate plots.

Trait Implementations

impl<T> Watershed<T> for SegmentingWatershed<T>

fn transform_with_hook( &self, input: ArrayView2<'_, u8>, seeds: &[(usize, usize)], ) -> Vec<T>

Runs the watershed transform, executing the hook specified by the TransformBuilder (if there is one) each time the water level is raised. The results from running the hook each time are collected into a vec and returned by this function.

fn transform( &self, input: ArrayView2<'_, u8>, seeds: &[(usize, usize)], ) -> Array2<usize>

Returns watershed transform of input image.

fn transform_history( &self, input: ArrayView2<'_, u8>, seeds: &[(usize, usize)], ) -> Vec<(u8, Array2<usize>)>

Returns a list of images where each image corresponds to a snapshot of the watershed transform at a particular water level.

fn transform_to_list( &self, input: ArrayView2<'_, u8>, seeds: &[(usize, usize)], ) -> Vec<(u8, Vec<usize>)>

Returns a Vec containing the areas of all the lakes per water level. The length of the nested Vec is always equal to the number of seeds, although some lakes may have zero area (especially for the merging transform, see docs for MergingWatershed)

impl<T> WatershedUtils for SegmentingWatershed<T>

fn pre_processor<T, D>(&self, img: ArrayView<'_, T, D>) -> Array<u8, D>

where T: Num + Copy + ToPrimitive + PartialOrd, D: Dimension,

The pre_processor function can convert an array of any numeric data-type T into an array of u8. It converts special float values (if T is a float type) to u8 values that implementations of the watershed transform in this crate know how to handle.

fn pre_processor_with_max<const MAX: u8, T, D>( &self, img: ArrayView<'_, T, D>, ) -> Array<u8, D>

where T: Num + Copy + ToPrimitive + PartialOrd, D: Dimension,

T into an array of u8. It converts special float values (if T is a float type) to u8 values that implementations of the watershed transform in this crate know how to handle.

fn find_local_minima(&self, img: ArrayView2<'_, u8>) -> Vec<(usize, usize)>

returns a vec of the positions of all the pixels that have a lower value than all their 8-way connected neighbours. Useful for generating seeds for the watershed transform.