Installation and features

Start from a checkout so the library, examples and documentation have matching versions. Blockflow is an evolving Rust library; a Git revision is a more useful compatibility boundary than assuming an unreleased API stays unchanged.

git clone https://github.com/henriksson-lab/blockflow.git
cd blockflow
cargo build --release -p blockflow
cargo test --release -p blockflow --lib

Use release builds for programs, tests and benchmarks. Several example CLIs intentionally refuse debug builds. The commands above build and test the core package; they do not compile every workspace example or optional model backend.

Use it from an application

A local dependency is convenient while developing an example against a checkout:

[dependencies]
blockflow = { path = "../blockflow", features = ["zarr"] }

For a Git dependency, use the repository URL with rev set to the full commit you tested. Keep your application’s lockfile and record the revision with each processing run. Reproducing a result also requires the same model files, algorithm parameters and acquisition interpretation; a matching crate name is not enough.

The first pipeline needs only the core. Most real image examples need the Zarr feature:

cargo build --release -p blockflow --features zarr
cargo test --release -p blockflow --features zarr --lib

Choose capabilities rather than all features

Feature gates separate dependencies and execution backends. Enabling a backend makes its APIs available; it does not move every operation to that backend. The authoritative definitions are in Cargo.toml.

Feature What becomes available What still needs a deliberate choice
zarr Filesystem Zarr environments, OME-Zarr selection and output helpers Selected channel/time/level, codecs and correct physical metadata
gui Browser progress server and replay binary A listener connected to the run and browser assets supplied to the server
distributed Coordinator, worker and local multi-process binaries Shared storage, rendezvous, worker resources and supported phase kinds
model-segment Common segmentation integration An actual predictor/model implementation
cellpose, stardist, sam, yolo, yolo3d Particular model stacks Model files, inference settings and the model-specific execution route
gpu-cuda, gpu-wgpu Non-model GPU kernels through a selected runtime A supported kernel and compatible device/driver
fftw Selectable system FFTW backend alongside the Rust FFT backend System FFTW installation and explicit backend selection

The default FFT route uses Rust libraries. FFTW introduces a system link-time dependency and its own licensing obligations; it is an optional alternative, not a prerequisite for FFT-based processing. Zarr’s enabled codecs can require a C toolchain. If compilation fails in a native codec or device backend, inspect that dependency’s error rather than changing the image-processing parameters.

Model accelerator features are separate from the non-model GPU runtime. For example, enabling a generic CUDA kernel backend does not select the CUDA route of a particular neural network implementation. Follow the chosen example’s README for its feature combination, model download and device configuration.

Build one complete example first

A package selection avoids accidentally building every model and application in the workspace:

cargo run --release -p blockflow-camera-calibration -- \
  prepare --out /tmp/camera-demo

This example’s manifest enables the library capabilities it needs. Its prepared fixture is small and deterministic, so a successful run establishes that input selection, storage and executable setup work before you introduce real data. Use a fresh output directory: the examples generally refuse existing outputs to protect acquisitions and completed results.

When changing the library, test the relevant example in release mode as well as the numerical kernel. A kernel can pass its unit tests while a selected dtype, side output or publication path fails only through the actual CLI.