Start here

Blockflow is a Rust library for processing images that do not fit into memory. It separates the numerical operation from the geometry and execution needed to run that operation over blocks. A filter declares the pixels it needs; a plan records which blocks supply them; the executor schedules work only when those inputs are available.

The four parts of a run

  1. Select an image. Choose the channel, time point, resolution level and physical frame. A storage path alone does not identify all of these choices.
  2. Assemble computation. Add operations and name any extra inputs. Decide where an intermediate image should be stored and where a composed chain can keep intermediate values local to one task.
  3. Execute with resources. Attach storage and choose worker concurrency, memory limits and optional diagnostics. These settings must preserve the recorded image dependencies.
  4. Publish an image. Install completed results with their axes, spacing, translation and label conventions. A scratch array is not yet a complete OME-Zarr image.
flowchart TB
  I["Channel, time, level and physical frame"] --> P["Operations and plan"]
  P --> E["Executor"]
  S["Chunked image storage"] <--> E
  R["Workers and memory budget"] --> E
  E --> O["Completed image and diagnostics"]
  O --> M["Published image with metadata"]
Figure 1: Image selection, numerical declarations and storage meet at execution; publication preserves the result’s image meaning.

A useful learning route

Start with installation, then run the complete first pipeline. The first pipeline deliberately uses a small resident image so you can inspect its values and understand the assembly API. Next, attach an OME-Zarr selection: the storage adapter reads required regions rather than loading the acquisition.

Choose an existing example before designing a large application. Calibration, restoration, segmentation and registration examples have different numerical assumptions. They demonstrate how the same execution contracts support different workflows, not a single universal microscopy recipe.

For explanations of the underlying choices, follow the design pages on halos, fusion and scheduling. Those choices become practical when a small crop works but the full acquisition is slow or exceeds memory.

What block processing does and does not guarantee

A planned operation exposes dependencies to the framework. A resident helper accepts an already loaded array. Both can be useful, but putting a resident whole-volume solve between two blockwise stages does not make that solve out-of-core. The operation catalog distinguishes bounded neighborhoods, whole-axis processing and global solves.

Likewise, changing block shape should preserve a local algorithm’s answer, but changing an algorithm’s interpolation, boundary or stopping policy can change its answer. Test multiple grids while holding those mathematical choices fixed. Blockflow is experimental: pin a Git revision and use examples from that same revision while the API evolves.