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 --libUse 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 --libChoose 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-demoThis 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.