Struct TransformBuilder

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

Builder for configuring a watershed transform.

Use the new_segmenting() associated function to start configuring a segmenting watershed transform. Use the default() method to start configuring a watershed transform. Once you have enabled the desired functionality, a watershed transform struct can be generated with the build_segmenting() and build_merging() associated functions. These return a struct of the type SegmentingWatershed and MergingWatershed respectively, which can be shared between threads.

default() vs new() and custom hooks

tl;dr: Use new() if you want to run a custom hook each time a the water level is raised during the watershed transform. Otherwise, use default().

A TransformBuilder struct can be obtained with both the default() and new() functions implemented for both. The main difference between the two is the resulting type:

• default() results in a TransformBuilder<()>
• new() results in a TransformBuilder<T> The default type for T is (). T is only used when specifying a custom function run by the watershed transform each time the water level is raised. This “hook” has the type fn(HookCtx) -> T.

Sadly, Rust is not able to determine that T should take the default () type if no hook is configured during the builder phase (which can be done with the set_wlvl_hook function). Therefore, Default is only implemented for TransformBuilder<()> (so not for all T) and can be used to circumvent this limitation of the type inference engine.

plots feature

Enabling the plots feature gate adds two new methods to the TransformBuilder struct: set_plot_colour_map, which can be used to set the colour map that will be used by plotters to generate the images and set_plot_folder, which can be used to specify folder where the generated images should be placed. If no output folder is specified when the plots feature is enabled, no plots will be generated (code will still compile).

enable_edge_correction

Calling the enable_edge_correction method on the builder signals the watershed implementations that they should make sure that the edges of the image are properly included in the watershed transform. This option is disabled by default since performing this “edge correction” can incur a significant performance/memory usage hit.

Implementations

impl<T> TransformBuilder<T>

pub const fn new() -> Self

Creates a new instance of TransformBuilder<T> which can be used to construct a watershed transform that runs custom code each time the water level is raised. If you do not use this functionality, use default() instead.

pub const fn set_max_water_lvl(self, max_water_lvl: u8) -> Self

Set the maximum water level that the transform will reach. Note that the maximum water level may not be set higher than u8::MAX - 1 (254).

pub const fn enable_edge_correction(self) -> Self

Enables edge correction. Turning this setting on properly colours the edges of the input image at the cost of increased memory consumption and two full-image copies.

pub const fn set_wlvl_hook(self, hook: fn(HookCtx<'_>) -> T) -> Self

Sets the water level hook. This function pointer is called every time the water level is raised and may be used to implement custom statistics. Implementations of the watershed algorithm that do no visit all water levels are not guaranteed to call this hook at all.

pub fn build_merging(self) -> Result<MergingWatershed<T>, BuildErr>

Build a MergingWatershed<T> from the current builder configuration.

pub fn build_segmenting(self) -> Result<SegmentingWatershed<T>, BuildErr>

Build a SegmentingWatershed<T> from the current builder configuration.

Trait Implementations

impl<T: Clone> Clone for TransformBuilder<T>

fn clone(&self) -> TransformBuilder<T>

Returns a duplicate of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for TransformBuilder<()>

fn default() -> Self

Returns the “default value” for a type.