Coordinates, painting and row operations
These operations bridge image arrays and spatial records generated by image analysis. Coordinate ownership ensures an object emitted near a compute seam is written once. A row stream’s storage schema and spatial indexing are part of its contract.
Available operations
coordinates
Entry points: SetVoxelsOp, set_voxel_rows, collect_coordinates.
Extract set voxel coordinates, optionally with values, into fragments and reconstruct masks from coordinates. A dense foreground produces a correspondingly large coordinate population.
Execution: Planned image-to-fragment extraction and resident merge helpers; not automatically smaller than the source image.
Output size follows occupancy. Emitting one record for every set voxel is efficient for a sparse mask but can expand a dense image into a much larger table. The extraction task emits only coordinates owned by its core, so read halos must not contribute duplicate rows.
Keep axis order and value interpretation with the row schema. Reconstructing a boolean support mask from these coordinates differs from carrying intensity or label identities. A collect helper intentionally turns the fragment population into a resident result; use it only after verifying that the expected number of records fits memory.
rows
Entry points: RowSourceOp, GatherRowsOp, FilterRowsOp, append_group_phases.
Start row streams, rescale spatial keys, gather co-located image values, filter columns and aggregate by typed keys. Grouping exposes explicit reduction/fold rules.
Execution: Planned row transforms and group reduction. Some collect helpers intentionally materialize results in memory.
Three kinds of work share a row schema. A row source assigns existing coordinates to owner blocks, a gather appends a value sampled from an explicitly named image at that key, and grouping merges rows by typed keys. A filter can remove rows locally, but a global aggregate needs the appropriate merge stage.
These operations preserve coordinate ownership; they do not automatically interpret arbitrary physical positions as voxel keys. Convert coordinates using the correct frame before gathering. A zero spatial gather radius is valid for a co-located keyed value; a windowed object fit is a different operation that must declare its source support. Keep exact integer IDs separate from display-valued numeric columns.
voxelize
Entry points: VoxelizeOp, single_voxel, ball.
Paint point weights/densities with a selected footprint. Source point reach must cover every point whose stamp intersects the output core.
Execution: Planned neighboring point-fragment reads and bounded image kernels.
The painter depends on nearby producers. A point owned by a neighboring block can stamp pixels inside the current output core. The input fragment reach therefore derives from the stamp footprint and the block grid. Reading only the current block’s point rows would leave seams even though every point was emitted exactly once.
Choose the stamp and aggregation rule according to the intended image: a single-voxel count, a ball of occupancy and a weighted density kernel are different outputs. The kernel’s finite extent bounds neighbor gathering. Overlap combines according to that rule rather than implicitly assigning connected-object identity.
rasterise
Entry points: RasteriseOutlinesOp, Ring, Shape, rasterise_into.
Fill outlined shapes from vertex rows, supporting rings and their geometric conventions. Validate extents rather than silently clipping an incorrectly framed outline.
Execution: Planned shape-fragment rasterization and resident kernels.
Shape ownership differs from pixel ownership. The row anchor identifies who stores an outline, while its vertices and plane extent determine all pixels it can cover. A painter must gather every neighboring shape that can intersect its core, including shapes anchored outside it. The configured maximum extent bounds that search and is validated against the geometry.
Ring orientation/hole conventions and interpolation between outline planes determine the filled object. Do not infer them from the order in which worker tasks happen to run. For a shape extending beyond its declared extent, fail or correct the frame instead of silently truncating it to make the current fetch sufficient.
walk
Entry points: OffsetWalkOp, OffsetSequence, walked_distance.
Follow supplied offsets from each coordinate and report positions/accumulated distances. The offset sequence defines the reachable image neighborhood.
Execution: Planned row/image walks with declared bounds; resident row helpers also exist.
The offset sequence defines the search support. OffsetSequence records offsets and their ordering/distance keys; its maximum absolute offset per axis supplies the bounded source reach. The operation can then examine the ordered samples from each row position without asking the scheduler for unknown future reads.
Tie groups and physical distance weights matter when several offsets share the same reported distance. A walk stops or selects according to its configured image predicate; it does not trace an arbitrary unbounded path. For adaptive vessel paths, use the specialized crop-tracing API with explicit expansion limits rather than hiding recursive image fetches inside a fixed-offset walk.
The surrounding infrastructure includes table for typed schemas, points for the compact point format and feature_index for disk-backed physical-neighborhood queries. With zarr, object_table::finalize_object_table externally sorts fragment rows into typed spatially indexed tables using bounded working memory. These are image-analysis infrastructure, not additional image filters.