A central package to unify helpful utilities for AI OnDemand that are useful/used across the Nextflow pipeline, Segment-Flow, and the Napari plugin. This primarily covers a centralisation of I/O and the implementation of RLE format.
Nothing here is AIoD-specific at the API level. The image I/O, RLE, and substack helpers are usable on their own in any bioimage analysis project!
Python 3.11 or 3.12.
Using uv:
uv add aiod_utils # or uv pip install aiod_utilsUsing pip:
pip install aiod_utilsFor Bio-Formats support, install the optional extra:
uv add "aiod_utils[bioformats]"Load an image with an automatically-selected reader, then round-trip a mask through the RLE format:
import aiod_utils.io as io
import aiod_utils.rle as rle
img = io.load_image("my_image.ome.tiff") # a BioIO BioImage
data = img.get_image_data("ZYX")
encoded = rle.encode(mask, mask_type="instance") # mask: np.ndarray, 2D or 3D
rle.save_encoding(encoded, "mask.rle")
decoded, metadata = rle.decode(rle.load_encoding("mask.rle"))aiod_utils.io— Load images via BioIO, with automatic reader selection for common formats (TIFF, OME-TIFF, Zarr, ND2, and more), and save them back out as OME-TIFF or OME-Zarr. Also centralises image/mask naming so the Napari front-end (and potential others) and Segment-Flow backend derive filenames identically.aiod_utils.rle— Encode and decode segmentation masks (binary and instance) as COCO-compatible Run-Length Encoding, with save/load support.- Note that there are some optimisations here to help improve encode/decode times for dense segmentation masks, particularly for storing instance masks!
aiod_utils.stacks— Utilities for splitting large volumetric images into memory-bounded substacks for use in our Nextflow pipeline (Segment-Flow). Is generally useful for dividing images/arrays into subsets to parallelise/iterate over, with optional memory budget.aiod_utils.preprocess— Modular image preprocessing steps (e.g. CLAHE, downsampling) with a base class for defining custom steps. Easily extendable for use in Segment-Flow or our Napari plugin.
Full documentation for AIoD lives at franciscrickinstitute.github.io/aiod_docs.
| Topic | Link |
|---|---|
| What each module does, in depth | Centralised Utilities |
| The RLE format and why it exists | Customised RLE format |
| How substacks are sized and used | Segmenting at scale |
| Adding a new preprocessing step | Expanding AIoD |
| How AIoD fits together | AIoD Concepts |
Contributions are very welcome — see the AIoD Developer Guide for setting up a cross-repo development environment.
This package is a pinned dependency of every model conda environment in Segment-Flow as well as the Napari plugin, so changes here have a wide blast radius. Run the tests before opening a PR:
uv sync
uv run pytestFound a bug or want to request a feature? Please open an issue. For usage problems, the docs Troubleshooting and Support pages are the best starting points.
MIT — see LICENSE.