odon is an ultra-fast native Rust desktop viewer for multiplexed spatial proteomics and spatial transcriptomics data, specifically for OME-Zarr files.

odon derives its name from the dragonfly (Odonata), which are reported to exhibit ultra-fast sensitivity to flickering light.

Most users should download a precompiled binary from the GitHub releases page:

• Latest releases
• Full documentation
• Biorxiv preprint (please cite us if you benefit from Odon!)

Release builds are intended to be the main distribution path for:

• macOS
• Windows
• Linux

Release artifacts include the Odon GUI and, where supported, installer-style packages:

The optional MCP helper, odon_mcp, is bundled with release artifacts. Users launch only the Odon desktop app; MCP clients launch odon_mcp automatically from the installed location. See Odon MCP for configuration paths.

odon is intended for rapid visual exploration of spatial omics data, especially when you need to:

• inspect large OME-Zarr image pyramids interactively
• compare many markers quickly on the same tissue section
• review segmentation objects, masks, points, and polygon annotations
• browse many ROIs at once in mosaic mode
• work with project files or samplesheets that define a spatial proteomics workspace

Primary workflows:

• OME-Zarr / OME-NGFF imagery
• Project JSON workspaces
• mosaic viewing across many ROIs
• GeoParquet, GeoJSON, CSV, and Parquet object overlays
• SpatialData and selected Xenium workflows

• GPU-backed image compositing for high-plex channel panels
• viewport-driven tile loading for local and remote datasets
• interactive overlays for objects, masks, labels, and points
• integrated thresholding and live cell-selection workflows
• mosaic mode for simultaneous viewing of hundreds of ROIs
• native Rust implementation designed for responsive performance on standard hardware

Detailed user documentation is available at:

• https://alexcoulton.github.io/odon/

The documentation source lives in docs/, with MkDocs configured by mkdocs.yml.

The repository includes synthetic example data for learning the GUI workflows, running local checks, and preparing demonstrations.

fixtures/synthetic_5ch.ome.zarr is a small OME-Zarr pyramid for first-load checks and single-image viewer testing. It has 5 channels (DAPI, CD3, PanCK, Ki67, and Collagen), 4 pyramid levels, and a level 0 shape of 5 x 512 x 512.

Release packages include this example with a project file and a local deep-link test page. The installed example can also be opened with:

odon://open?example=synthetic_5ch

To open it in the GUI, launch Odon, click Add OME-Zarr Root..., choose the fixtures/ folder or the dataset folder directly, select the discovered ROI, and click Open.

fixtures/tma_100x1mb.zip is a portable synthetic TMA example for mosaic mode. After unzipping, the tma_100x1mb/ folder contains synthetic_tma_samplesheet.csv, manifest.json, and 100 core folders. Each core has an image.ome.zarr, objects/cells.parquet, objects/cells.geojson, and preview.png.

The samplesheet uses relative paths such as cores/core_0001/image.ome.zarr and cores/core_0001/objects/cells.parquet, so the unzipped folder can be moved as a unit without editing the CSV.

To open it in the GUI, launch Odon, click Import Samplesheet CSV..., choose tma_100x1mb/synthetic_tma_samplesheet.csv, click Select all, and click Open mosaic (100). Use the right-panel Layout tab to group, sort, and label cores by metadata columns such as cohort, response, patient_id, and core_quality.

See the Example Datasets documentation for the full walkthrough.

For broader conversion from existing microscopy formats into pyramidal OME-Zarr, we recommend bioformats2raw.

Install with conda:

conda install -c ome bioformats2raw

A validated command pattern for odon is:

bioformats2raw input_file output.ome.zarr \
  --series 0 \
  --scale-format-string '%2$d/' \
  --resolutions 5 \
  -c zlib

This writes a single multiscale image pyramid with resolution levels at the dataset root, which is a layout odon opens directly.

Key options:

• --series 0: convert a single image series
• --scale-format-string '%2$d/': place pyramid levels at the OME-Zarr root
• --resolutions 5: generate five pyramid levels
• -c zlib: use zlib compression

For files with multiple image series, convert each required series separately using the appropriate --series index.

After conversion, verify:

• channel count and order
• channel names
• pyramid loading across zoom levels

If you want to build odon yourself instead of using the release binaries:

cargo run

Open a dataset directly:

cargo run -- "/path/to/dataset.ome.zarr"

Open a project:

cargo run -- --project "/path/to/project.json"

Open a mosaic from a project:

cargo run -- --project "/path/to/project.json" --mosaic "TMA1v3,TMA2"

Open a mosaic from a samplesheet:

cargo run -- --mosaic-samplesheet "/path/to/samplesheet.csv"

Show CLI help:

cargo run -- --help

To build the documentation locally:

uv venv .venv-docs
source .venv-docs/bin/activate
uv pip install -r requirements-docs.txt
mkdocs serve

Regenerate fixtures/synthetic_5ch.ome.zarr with:

python3 scripts/generate_ome_zarr_fixture.py --overwrite

scripts/tif_to_omezarr.py converts TIFF imagery into OME-Zarr using tifffile, zarr, and ome-zarr.

It was used to convert .tif files from the Synapse repository into the OME-Zarr datasets used for testing in the manuscript.

The script infers axes from the TIFF dimensionality:

• YX for 2D images
• CYX for 3D channel-first images
• CZYX for 4D channel-first volumes
• TCZYX for 5D time-series channel-first volumes

It then writes an OME-Zarr hierarchy and generates a multiscale pyramid with ome-zarr's Scaler.

Example:

python3 scripts/tif_to_omezarr.py input.tif output.ome.zarr

scripts/rechunk_omezarr.py creates a viewer-optimized derivative OME-Zarr by rewriting arrays with plane-friendly chunks.

This is useful for datasets that are chunked for volumetric access rather than XY plane scrubbing. A good starting point for odon's current access pattern is:

• --c-chunk 1
• --z-chunk 1
• --yx-chunk 512

Example:

python3 scripts/rechunk_omezarr.py \
  input.ome.zarr \
  input.viewer.ome.zarr \
  --c-chunk 1 \
  --z-chunk 1 \
  --yx-chunk 512

The script requires numpy and zarr. If they are not installed in your environment, one option is:

uv venv .venv
source .venv/bin/activate
uv pip install numpy zarr numcodecs

• src/: Rust application source
• assets/: runtime assets bundled with the app
• docs/: MkDocs user documentation
• fixtures/: small checked-in synthetic datasets for tests and manual checks
• scripts/: utility and packaging scripts
• vendor/: vendored crate patches

This project is licensed under GPL-3.0-only. See LICENSE.