The Rustronomy watershed - a pure rust implementation of the segmenting and merging watershed algorithms

This crate is part of the Rustronomy Project

Rustronomy-watershed is a pure-rust implementation of the segmenting and merging watershed algorithms (see Digabel & Lantujoul, 1978[^1]).

Features (read the docs)

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.

Gallery

data from the Canadian Galactic Plane Survey (CGPS)

Merging watershed algorithm in action

Segmenting watershed algorithm in action

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.3.2"

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

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

Please do not use any versions before 0.3, as they contain a major bug in the implementation of the merging watershed algorithm

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

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. See the crate
  level docs for details on how to use this feature. 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.

License

All crates in the Rustronomy ecosystem are licensed under the EUPLv1.2 (or higher) license.

Rustronomy-watershed is explicitly not licensed under the dual Apache/MIT license common to the Rust ecosystem. Instead it is licensed under the terms of the European Union Public License v1.2.

Rustronomy is a science project and embraces the values of open science and free and open software. Closed and paid scientific software suites hinder the development of new technologies and research methods, as well as diverting much- needed public funds away from researchers to large publishing and software companies.

See the LICENSE.md file for the EUPL text in all 22 official languages of the EU, and LICENSE-EN.txt for a plain text English version of the license.

[^1]: H. Digabel and C. Lantujoul. Iterative algorithms. In Actes du Second Symposium Europen dAnalyse Quantitative des Microstructures en Sciences des Matriaux, Biologie et Medcine, October 1978.