7 unstable releases (3 breaking)
0.4.1 | Mar 16, 2023 |
---|---|
0.4.0 | Mar 16, 2023 |
0.3.2 | Feb 16, 2023 |
0.3.1 | Jan 28, 2023 |
0.1.0 | Dec 22, 2022 |
#598 in Algorithms
41 downloads per month
160KB
2K
SLoC
The Rustronomy watershed - a pure rust implementation of the segmenting and merging watershed algorithms
Rustronomy-watershed is a pure-rust implementation of the segmenting and merging watershed algorithms (see Digabel & Lantuéjoul, 1978[^1]).
Features (read the docs)
Two main versions of the watershed algorithm are included in this crate.
- The merging watershed algorithm, which is a void-filling algorithm that can be used to identify connected regions in image.
- 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 purposemalloc
(3) implementation that emphasizes fragmentation avoidance and scalable concurrency support.". Jemalloc is enabled though usage of thejemalloc
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 compilerustronomy-watershed
with thejemalloc
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 theplotters
crate as a dependency, which increases compile times and requires the installation of some packages on linux systems, see theplotters
documentation for details.progress
: this feature enables progress bars for the watershed algorithm. Enabling this feature adds theindicatif
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. 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.
Dependencies
~3–12MB
~145K SLoC