Skip to main content

openreadout_zarr/
lib.rs

1//! OME-Zarr (OME-NGFF) reader: NGFF 0.1–0.5 on Zarr v2 and v3, directory and zip stores.
2//!
3//! Images come from `multiscales` groups, HCS plates (one image per field of view) and
4//! `bioformats2raw.layout` collections (one image per series, with `OME/METADATA.ome.xml` parsed
5//! by the TIFF crate's OME-XML parser). Arrays are read through the pure-Rust `zarrs` crate;
6//! the `blosc`, `zstd` and numcodecs `lz4` codecs are decoded by `openreadout-codecs` (see
7//! [`codecs`]) so that no C library is needed.
8//!
9//! Layout and vocabulary: `docs/formats/ome-zarr.md`. Provenance: `docs/provenance/ome-zarr.md`.
10//!
11//! # Example
12//!
13//! Every reader implements [`openreadout_core::FormatReader`]: `descriptor`
14//! says what it reads, `sniff` recognises a file from its first bytes, and `open` returns a
15//! [`openreadout_core::Dataset`] with a header-only `info()` summary and lazy data
16//! access.
17//!
18//! ```
19//! use openreadout_core::FormatReader;
20//! use openreadout_zarr::ZarrReader;
21//!
22//! let format = ZarrReader.descriptor();
23//! assert_eq!(format.id, openreadout_zarr::FORMAT_ID);
24//! println!("{} ({}): .{}", format.name, format.family, format.extensions.join(", ."));
25//! ```
26//!
27//! Reading a file:
28//!
29//! ```no_run
30//! use std::path::Path;
31//!
32//! use openreadout_core::{FormatReader, PlaneIndex};
33//! use openreadout_zarr::ZarrReader;
34//!
35//! let mut dataset = ZarrReader.open(Path::new("plate.ome.zarr"))?;
36//! let info = dataset.info()?; // headers only: fast even on multi-gigabyte files
37//! for image in &info.images {
38//!     println!(
39//!         "image {}: {} x {} px, {} channel(s), {} plane(s)",
40//!         image.index, image.size_x, image.size_y, image.size_c, image.plane_count
41//!     );
42//! }
43//! // Pixels are read one plane at a time: image 0, channel 0, first Z slice, first time point.
44//! let plane = dataset.read_plane(0, PlaneIndex { c: 0, z: 0, t: 0 })?;
45//! assert_eq!(plane.data.len(), plane.expected_len());
46//! # Ok::<(), openreadout_core::Error>(())
47//! ```
48//!
49//! Applications that accept any instrument file usually register every reader in an
50//! [`openreadout_core::Registry`] and let it detect the format; that is what the
51//! `openreadout` command-line tool does.
52//!
53//! # API stability
54//!
55//! The supported API is what this page documents. The parser modules are public only so that
56//! tests and fuzz targets can reach them: they are hidden from this documentation and may change
57//! in any release.
58#![forbid(unsafe_code)]
59#![warn(missing_docs)]
60
61mod assurance;
62#[doc(hidden)]
63pub mod codecs;
64#[doc(hidden)]
65pub mod dataset;
66#[doc(hidden)]
67pub mod ngff;
68#[doc(hidden)]
69pub mod store;
70
71use std::path::Path;
72
73use openreadout_core::Result;
74use openreadout_core::model::{DetectConfidence, FormatDescriptor};
75use openreadout_core::reader::{Dataset, Detection, FormatReader, has_extension};
76use openreadout_core::source::{Fs, Input};
77
78#[doc(hidden)]
79pub use dataset::{ArrayMeta, AxisRole, ZarrDataset, ZarrImage, array_meta, axis_roles};
80
81/// Format id used on the command line and in JSON.
82pub const FORMAT_ID: &str = "ome-zarr";
83
84/// Group metadata keys that make a Zarr group an OME-NGFF entry point.
85const NGFF_KEYS: [&str; 4] = [
86    "\"multiscales\"",
87    "\"plate\"",
88    "\"bioformats2raw.layout\"",
89    "\"well\"",
90];
91
92/// The OME-Zarr reader.
93#[derive(Debug, Default, Clone, Copy)]
94pub struct ZarrReader;
95
96fn ngff_text(s: &str) -> bool {
97    NGFF_KEYS.iter().any(|k| s.contains(k))
98}
99
100/// Does this directory hold a Zarr hierarchy root, and does its metadata name NGFF keys?
101fn sniff_dir(fs: &Fs, dir: &Path) -> Option<DetectConfidence> {
102    let mut any = false;
103    for doc in ["zarr.json", ".zattrs", ".zgroup"] {
104        let p = dir.join(doc);
105        let Ok(meta) = fs.metadata(&p) else {
106            continue;
107        };
108        any = true;
109        if meta.len() > 16 << 20 {
110            continue;
111        }
112        if let Ok(text) = fs.read_to_string(&p)
113            && ngff_text(&text)
114        {
115            return Some(DetectConfidence::Definite);
116        }
117    }
118    any.then_some(DetectConfidence::Likely)
119}
120
121impl FormatReader for ZarrReader {
122    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
123        Some(&assurance::OME_ZARR)
124    }
125
126    fn descriptor(&self) -> FormatDescriptor {
127        FormatDescriptor {
128            id: FORMAT_ID.into(),
129            name: "OME-Zarr (OME-NGFF)".into(),
130            vendor: "open standard (OME-NGFF, Zarr)".into(),
131            extensions: vec!["zarr".into(), "ome.zarr".into(), "zip".into()],
132            family: "microscopy".into(),
133            can_read: true,
134            can_write: true,
135            confidence: assurance::OME_ZARR.confidence,
136            known_gaps: vec![
137                "Label images are exposed as images after the others (label ids as stored); their colours and properties are copied, not interpreted".into(),
138                "Codecs other than blosc (blosclz/lz4/snappy/zlib/zstd, byte and bit shuffle)/zstd/gzip/zlib/lz4/crc32c/sharding/transpose are not decoded (exit 4 on read, reported by `check`)".into(),
139                "String, structured and datetime data types are not read (exit 6); float16 is widened to float32, bool is uint8 0/1".into(),
140                "Scale and translation transformations are composed (physical sizes, `extra.origin_um`); NGFF 0.6 coordinate systems and affine/rotation transformations are reported, not applied".into(),
141                "Axes other than t/c/z/y/x are read at index 0".into(),
142                "Remote (HTTP/S3) stores are not opened: the binary has no network access".into(),
143            ],
144        }
145    }
146
147    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
148        self.sniff_input(head, &Input::local(path))
149    }
150
151    /// Directory stores are recognised by their root metadata, read through the namespace.
152    fn sniff_input(&self, head: &[u8], input: &Input) -> Option<Detection> {
153        let (path, fs) = (input.path(), input.fs());
154        if fs.is_dir(path) {
155            return sniff_dir(fs, path).map(|confidence| Detection {
156                format_id: FORMAT_ID,
157                confidence,
158                note: Some(if confidence == DetectConfidence::Definite {
159                    "Zarr directory store with OME-NGFF metadata".into()
160                } else {
161                    "Zarr directory store (no OME-NGFF keys at the root)".into()
162                }),
163            });
164        }
165        let name = path
166            .file_name()
167            .and_then(|n| n.to_str())
168            .unwrap_or_default();
169        if matches!(name, "zarr.json" | ".zattrs" | ".zgroup")
170            && ngff_text(&String::from_utf8_lossy(head))
171        {
172            return Some(Detection {
173                format_id: FORMAT_ID,
174                confidence: DetectConfidence::Definite,
175                note: Some("metadata document at the root of a Zarr directory store".into()),
176            });
177        }
178        if head.starts_with(b"PK\x03\x04") && has_extension(path, &["zip"]) {
179            let names_zarr = [
180                b"zarr.json".as_slice(),
181                b".zgroup".as_slice(),
182                b".zattrs".as_slice(),
183                b".zarray".as_slice(),
184            ]
185            .iter()
186            .any(|n| head.windows(n.len()).any(|w| w == *n));
187            if names_zarr {
188                return Some(Detection {
189                    format_id: FORMAT_ID,
190                    confidence: DetectConfidence::Definite,
191                    note: Some("zip archive holding a Zarr store".into()),
192                });
193            }
194        }
195        None
196    }
197
198    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
199        Ok(Box::new(ZarrDataset::open(path)?))
200    }
201
202    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
203        Ok(Box::new(ZarrDataset::open_input(input)?))
204    }
205
206    fn reads_any_source(&self) -> bool {
207        true
208    }
209}