rle_region op• Data kinds: voxel → rle_region
• Call: import fullseye as fs; fs.ledger.vol_rle_encode(vol_binary) -> 'VolRLE' (to call the implementation directly, import volregion; volregion.vol_rle_encode(vol_binary) -> 'VolRLE'; from the registry, ops3d.get("vol_rle_encode"))
Encode a binary volume as x-runs (the 3-D HALCON-region representation).
A non-{0, 1} input is thresholded at > 0.5 (the volops convention). NaN / Inf are rejected. An empty mask encodes to zero runs — a valid region that decodes back to all-background.
Memory: proportional to the number of runs (~surface complexity per plane row), not to the voxel count — measured 1/145 of the dense bool mask on a realistic 384**3 part.
What it builds: converts a binary (D, H, W) volume into a list of contiguous foreground intervals along the x axis (last axis) (runs). VolRLE is a frozen dataclass holding rows (plane row id z*H + y, int32, ascending), starts / ends (x range [start, end) of the run; end is exclusive), and shape (the original (D, H, W)). Run i represents vol[z, y, starts[i]:ends[i]].
Arguments and validation (fail-closed):
• vol_binary: 3-D array. bool is used as is; anything else is converted to float64, ValueError if it contains NaN/Inf, then binarised with > 0.5.
• If it is not 3-D, or the voxel count exceeds MAX_VOXELS (1 << 27 ≈ 1.34 × 10^8), ValueError.
• An empty mask becomes a VolRLE with 0 runs (not an error).
Caution: the axis order is [z, y, x] (depth, row, col). Runs only go along x, so shapes that break up finely along x (stripes, noise) have more runs and less compression benefit. vol_rle_volume / vol_rle_bbox / vol_rle_centroid answer on the runs without decoding. Set operations: vol_rle_union / vol_rle_intersect / vol_rle_difference; back to a dense array with vol_rle_decode.
• Sample-data catalog (download URLs / licences) — 2-D uses skimage.data (BSD/public domain) plus synthetic images; 3-D lists download URLs for real data sources (Stanford, PDS, …).
• Operator provenance and references — the sources of the research/methods this op family came from.
• rle_region_efficiency — py -3.11 examples_3d/rle_region_efficiency.py
rle_region as input)vol_rle_decode · vol_rle_volume · vol_rle_bbox · vol_rle_centroid · vol_rle_union · vol_rle_intersect · vol_rle_difference · fuse_to_voxel
rle_region)vol_rle_decode · vol_rle_volume · vol_rle_bbox · vol_rle_centroid · vol_rle_union · vol_rle_intersect · vol_rle_difference · vol_rle_components
*Provenance: volregion.py — 3D operator registry. This per-op note is generated by tools/opdocs.py md (do not hand-edit).*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.