Crate rustronomy_watershed

source ·
Expand description

Rustronomy-watershed is a pure-rust implementation of the segmenting and merging watershed algorithms (see Digabel & Lantuéjoul, 19781).

Features

Two main versions of the watershed algorithm are included in this crate.

  1. The merging watershed algorithm, which is a void-filling algorithm that can be used to identify connected regions in image.
  2. The segmenting watershed algorithm, which is a well-known image segmentation algorithm.

In addition, rustronomy-watershed provides extra functionality which can be accessed via cargo feature gates. A list of all additional features can be found below.

Quickstart

To use the latest release of Rustronomy-watershed in a cargo project, add the rustronomy-watershed crate as a dependency to your Cargo.toml file:

[dependencies]
rustronomy-watershed = "0.2.0"

To use Rustronomy-fits in a Jupyter notebook, execute a cell containing the following code:

:dep rustronomy-watershed = {version = "0.2"}

If you want to use the latest (unstable) development version of rustronomy-watershed, you can do so by using the git field (which fetches the latest version from the repo) rather than the version field (which downloads the latest released version from crates.io).

{git = "https://github.com/smups/rustronomy-watershed"}

Short example: computing the Watershed transform of a random field

rustronomy-watershed uses the commonly used “builder pattern” to configure the watershed transform before executing it. To configure a transform, create an instance of the TransformBuilder struct. Once you are done specifying options for the builder struct using its associated functions, call the build_merging() or build_segmenting() functions to generate a (Sync&Send) watershed transform struct, which you can now use to execute the configured transform.

In this example, we compute the watershed transform of a uniform random field. The random field can be generated with the ndarray_rand crate. To configure a new watershed transform, one can use the TransformBuilder struct which is included in the rustronomy_watershed prelude.

use ndarray as nd;
use rustronomy_watershed::prelude::*;
use ndarray_rand::{rand_distr::Uniform, RandomExt};

//Create a random uniform distribution
let rf = nd::Array2::<u8>::random((512, 512), Uniform::new(0, 254));
//Set-up the watershed transform
let watershed = TransformBuilder::default().build_segmenting().unwrap();
//Find minima of the random field (to be used as seeds)
let rf_mins = watershed.find_local_minima(rf.view());
//Execute the watershed transform
let output = watershed.transform(rf.view(), &rf_mins);

Cargo feature gates

By default, all features behind cargo feature gates are disabled

  • jemalloc: this feature enables the jemalloc allocator. From the jemalloc website: “jemalloc is a general purpose malloc(3) implementation that emphasizes fragmentation avoidance and scalable concurrency support.”. Jemalloc is enabled though usage of the jemalloc crate, which increases compile times considerably. However, enabling this feature can also greatly improve run-time performance, especially on machines with more (>6 or so) cores. To compile rustronomy-watershed with the jemalloc feature, jemalloc must be installed on the host system.
  • plots: with this feature enabled, rustronomy-watershed will generate a plot of the watershed-transform each time the water level is increased. Plotting support adds the plotters crate as a dependency, which increases compile times and requires the installation of some packages on linux systems, see the plotters documentation for details.
  • progress: this feature enables progress bars for the watershed algorithm. Enabling this feature adds the indicatif crate as a dependency, which should not considerably slow down compile times.
  • debug: this feature enables debug and performance monitoring output. This can negatively impact performance. Enabling this feature does not add additional dependencies.

plots feature gate

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).

The generated plots are png files with no text. Each pixel in the generated images corresponds 1:1 to a pixel in the input array.

  1. H. Digabel and C. Lantuéjoul. Iterative algorithms. In Actes du Second Symposium Européen d’Analyse Quantitative des Microstructures en Sciences des Matériaux, Biologie et Medécine, October 1978. ↩

Modules

Structs

Enums

  • BuildErr
    Errors that may occur during the build process

Constants

Traits

  • Watershed
    Actual trait for performing the watershed transform. It is implemented in different ways by different versions of the algorithm. This trait is dyn-safe, which means that trait objects may be constructed from it.
  • WatershedUtils
    This trait contains useful functions for preparing images to be used as input for a watershed transform