Your first pipeline

This program places one bright voxel in a small volume and applies a Gaussian filter. Its purpose is to expose the normal assembly and execution APIs. ArrayEnvironment deliberately keeps this demonstration input and its images in memory; use Zarr storage for large data.

flowchart LR
  A[Impulse image] --> B[Assemble the plan]
  B --> C[Gaussian phase]
  C --> D[Eight output blocks]
  D --> E[Smoothed image]
Figure 1: A single numerical operation becomes eight tasks without changing the filter definition.

The volume is [16,32,32], the block shape [8,16,16], and all shapes use z,y,x. Gaussian sigma is one voxel and truncation three standard deviations, so each output core needs a three-voxel input margin. You specify the filter, not a second independent halo setting.

use blockflow::{assemble::PlanBuilder, env::ArrayEnvironment,
    geometry::BlockGrid, op::Chain, ops::SmoothOp,
    strategy::{execute_phases, Hints}, voxels::Voxels, Dtype};

fn main() -> blockflow::error::Result<()> {
    let shape = [16, 32, 32];
    let block = [8, 16, 16];
    let mut input = Voxels::zeros(Dtype::F64, shape)?;
    input.view_mut::<f64>()?[[8, 16, 16]] = 1.0;

    let mut builder = PlanBuilder::new(
        shape, Dtype::F64, BlockGrid::new(shape, block)?);
    builder.pixels(Chain::op(SmoothOp::isotropic("smooth", 1.0, 3.0)?))?;
    let assembly = builder.finish()?;
    let environment = ArrayEnvironment::for_decomposition(
        input, &assembly.decomposition, block)?;
    execute_phases("first-pipeline", &assembly.workflow,
        &assembly.decomposition, &Hints::default(), &environment,
        &[], &assembly.work())?;

    let output = environment.output();
    println!("centre = {}", output.view::<f64>()?[[8, 16, 16]]);
    Ok(())
}

PlanBuilder::pixels adds a phase, PlanBuilder::finish derives its decomposition, and execute_phases runs the resulting work. The environment uses the decomposition’s output shapes and dtypes to allocate storage. The final output() is read only after execution finishes.

To run the code in an application, put it in src/main.rs, add the dependency described in installation, and run:

cargo run --release

The complete snippet is also available as a Rust source file. Try another block shape that divides the volume differently: the filter still needs the same neighboring voxels, and internal block seams must not become image boundaries.

Next, replace the in-memory environment with an attached OME-Zarr selection. Keep fixture creation separate from the actual large-image processing path.

Read the program as three contracts

The first contract is the numerical image: Voxels contains f64 values and the Gaussian filter accepts that type. The impulse is at the integer voxel center [8,16,16]. The output is a sampled, truncated Gaussian response, not a point relocated to the nearest block center.

The second contract is geometry. BlockGrid::new partitions [16,32,32] into eight [8,16,16] cores. The sigma-one filter truncated at three standard deviations needs a radius-three neighborhood. For the core beginning at [8,16,16], the unconstrained lower read edge is [5,13,13]: those neighboring input values are required even though their output positions belong to another block. At the real volume edges, the operation’s boundary convention applies. At an internal core edge, the actual neighboring image values must be used.

The third contract is execution. PlanBuilder::finish returns an Assembly containing the workflow, binding decomposition and owned phase work. ArrayEnvironment::for_decomposition allocates images according to that recorded layout. execute_phases receives all three pieces, the environment and runtime Hints. The kernel does not choose its own input region by reaching outside the buffer handed to it.

What changing the block shape means

Try [4,16,16] or [16,8,8] instead of [8,16,16]. The number of tasks and the amount of repeated halo work change. The sigma, boundary rule and owned result do not. Comparing several cuts is a useful check that the planned path is computing one image rather than independently filtering unrelated tiles.

Larger blocks can reduce halo overhead, but they also enlarge the input, output and scratch buffers of each active task. This example is tiny enough that memory is immaterial; on a real image, concurrency and block size must be chosen together. See blocks and memory for a numerical working-set example.

What to keep when moving to a real image

Keep the operation construction, plan assembly and execution order. Replace the synthetic allocation with an attached source, derive the shape and dtype from that source, and use ZarrEnvironment instead of a resident array environment. An integer acquisition may require a planned numeric conversion before a float-only operation. Treat this as an explicit algorithm input choice; do not silently reinterpret integer bytes as floats.

The complete source above is also the downloadable snippet. It was compiled and run against the release library when introduced. The region calculations in this explanation are illustrative arithmetic, not a second implementation of the planner. For real pipelines, let the operation declaration and plan derive those regions.