zarrmony
Convert any bioimage file to OME-Zarr v0.5, preserving metadata.
Zarrmony reads proprietary microscopy formats (CZI, LIF, ND2, OME-TIFF, ...) via bioio and writes them as OME-Zarr v0.5, with mean-pool pyramid generation and a full audit trail of the conversion. User-supplied metadata (study/treatment/etc.) is not handled by zarrmony — it is owned by aperture-backend, which associates OME-Zarr stores to a separate metadata database.
By default (--layout auto) the writer is chosen from the reader's layout_hint: a flat reader writes one self-describing <scene>.ome.zarr store per scene under the output directory; a plate-shaped reader writes a single OME-NGFF HCS plate store at the output. The legacy bundled bioformats2raw.layout shape is opt-in via --layout bf2raw (CLI) or layout="bf2raw" (library).
Status: v0.3 in active development. API and metadata schema are not yet stable.
Install
pip install zarrmony
Optional extras:
| Extra | Adds | When you need it |
|---|---|---|
gcs |
gcsfs |
Writing output to gs:// URIs |
s3 |
s3fs |
Writing output to s3:// URIs |
ome-tiff |
bioio-ome-tiff |
Reading OME-TIFF input |
all |
All of the above | |
dev |
pytest, ruff, pre-commit | Contributing |
CZI, LIF, and ND2 reader plugins are included by default.
Usage
CLI
# Auto (default): dispatches on the reader's layout_hint.
# flat readers (CZI, LIF, ND2, OME-TIFF) → per-scene stores under OUTPUT
# plate-shaped readers (e.g. zarrmony-phenix) → a single HCS plate store at OUTPUT
zarrmony convert input.czi output_dir/
# Force per-scene (one <scene>.ome.zarr store per scene under OUTPUT).
zarrmony convert input.czi output_dir/ --layout per-scene
# Force HCS plate (one <plate>.ome.zarr store at OUTPUT). Requires a
# plate-shaped reader; flat readers raise LayoutMismatchError.
zarrmony convert phenix-acquisition/ output.ome.zarr --layout plate
# Bundled bioformats2raw.layout (opt-in): writes a single store at OUTPUT.
zarrmony convert input.czi output.ome.zarr --layout bf2raw
# LIF-specific: write one OME-Zarr per mosaic tile (with stage positions in
# <Plane>) instead of bioio-lif's auto-stitched 1-pixel-overlap output.
# See docs/adr/0005-lif-mosaic-write-strategy.md.
zarrmony convert mosaic.lif output_dir/ --lif-mosaic per-tile
zarrmony inspect input.czi
Library
from zarrmony import convert
# Auto (default): for a flat reader, returns {"input": ..., "stores": [...]};
# for a plate-shaped reader, returns the single plate audit dict (schema 3,
# with "fields" and a top-level "plate" block). Switch on audit["layout"].
result = convert("input.lif", "output_dir/")
# Bundled: returns the single bundle's audit dict.
audit = convert("input.lif", "output.ome.zarr", layout="bf2raw")
# HCS plate: writes one OME-NGFF plate store at OUTPUT.
audit = convert("phenix-acquisition/", "output.ome.zarr", layout="plate")
Extending zarrmony
Add support for a new bioimage format by writing a reader plugin. See Writing a zarrmony reader plugin for the Reader Protocol, matcher conventions, entry-point registration, and a worked example.
License
Apache-2.0. See LICENSE.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file zarrmony-0.9.0.tar.gz.
File metadata
- Download URL: zarrmony-0.9.0.tar.gz
- Upload date:
- Size: 471.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f6799bba1ce8962b4339d680bd212b6444ca4944e6cc15646653a4f4d387a87a
|
|
| MD5 |
fd8d85de42917805f8beaf3449f497d3
|
|
| BLAKE2b-256 |
f801e992e475d77a85a421343ed92fb321630691bb8f045068994e4edec88a56
|
Provenance
The following attestation bundles were made for zarrmony-0.9.0.tar.gz:
Publisher:
release.yml on ferrinm/zarrmony
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
zarrmony-0.9.0.tar.gz -
Subject digest:
f6799bba1ce8962b4339d680bd212b6444ca4944e6cc15646653a4f4d387a87a - Sigstore transparency entry: 2229330155
- Sigstore integration time:
-
Permalink:
ferrinm/zarrmony@d53d11a0577f79b4aad2cff93892efd7e2604d01 -
Branch / Tag:
refs/tags/v0.9.0 - Owner: https://github.com/ferrinm
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@d53d11a0577f79b4aad2cff93892efd7e2604d01 -
Trigger Event:
push
-
Statement type:
File details
Details for the file zarrmony-0.9.0-py3-none-any.whl.
File metadata
- Download URL: zarrmony-0.9.0-py3-none-any.whl
- Upload date:
- Size: 93.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
bd917a12aee11bd422e8b649c48f4b4670881623f317c12df8a0f4ff9e0f2988
|
|
| MD5 |
bdf221edc4a1836b3ceeebf0e19ade67
|
|
| BLAKE2b-256 |
547e079f5483e63f073f0cd42ff6ff91e6d9c4bfde3bbc472c20607f7fbbb0c9
|
Provenance
The following attestation bundles were made for zarrmony-0.9.0-py3-none-any.whl:
Publisher:
release.yml on ferrinm/zarrmony
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
zarrmony-0.9.0-py3-none-any.whl -
Subject digest:
bd917a12aee11bd422e8b649c48f4b4670881623f317c12df8a0f4ff9e0f2988 - Sigstore transparency entry: 2229330759
- Sigstore integration time:
-
Permalink:
ferrinm/zarrmony@d53d11a0577f79b4aad2cff93892efd7e2604d01 -
Branch / Tag:
refs/tags/v0.9.0 - Owner: https://github.com/ferrinm
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@d53d11a0577f79b4aad2cff93892efd7e2604d01 -
Trigger Event:
push
-
Statement type:
