Pronounced water-zed. A simple watershed and region agglomeration library for affinity graphs.
Based on the watershed implementation of Aleksandar Zlateski and Chandan Singh.
pip install waterzThe wheels on PyPI contain waterz.evaluate and waterz.agglomerate,
precompiled for the most common scoring functions (see below). No compiler is
needed to use those.
The scoring_function and discretize_queue arguments of agglomerate are
C++ template parameters, such that each combination is a separate compiled
module. The following are precompiled, each with discretize_queue=0 and
discretize_queue=256:
OneMinus<MeanAffinity<RegionGraphType, ScoreValue>>(the default)OneMinus<HistogramQuantileAffinity<RegionGraphType, Q, ScoreValue, 256, B>>forQin 10, 15, 20, ..., 95 andBintrue,false(andOneMinus<HistogramQuantileAffinity<RegionGraphType, Q, ScoreValue, 256>>, which is the same asB = true)Divide<Subtract<MaxSize<RegionGraphType>, MinSize<RegionGraphType>>, Add<MaxSize<RegionGraphType>, MinSize<RegionGraphType>>>(the relative difference of the region sizes, ignoring the affinities)
Any other combination is compiled the first time it is used, which requires a
C++ compiler and the boost headers (see below). The compiled module is cached
(in the cache directory of witty, which can
be set with WITTY_CACHE_DIR).
Set WATERZ_NO_PREBUILT=1 to compile all scoring functions on first use,
ignoring the precompiled ones.
Install c++ dependencies:
# linux
sudo apt install libboost-dev
# macos
brew install boost
# windows
vcpkg install boost-multi-array:x64-windowsIf boost is installed elsewhere, point BOOST_ROOT (or BOOST_INCLUDEDIR) to it.
Then
# make and activate env then:
pip install -e .or
uv syncSet WATERZ_NO_PREBUILT=1 to skip precompiling the scoring functions (all of
them are then compiled on first use), which makes for a faster build. After
changing the C++, run uv sync (or pip install -e .) again: the precompiled
modules do not notice, the compiled-on-first-use ones do.
import waterz
import numpy as np
# affinities is a [3,depth,height,width] numpy array of float32
affinities = ...
thresholds = [0, 100, 200]
segmentations = waterz.agglomerate(affinities, thresholds)The version is derived from the git tag. Pushing a tag builds the wheels, tests them, and publishes them to PyPI:
git tag -a v0.9.7 -m v0.9.7
git push upstream --follow-tags