openreadout_hdf5/lib.rs
1//! HDF5-based formats through the pure-Rust `hdf5-pure` crate: Imaris `.ims` volumes
2//! (pyramids, LZ4/deflate chunks), NWB 2.x (session fields, plain `TimeSeries` as traces),
3//! NeXus NXmx diffraction images (EIGER master and data files, bitshuffle/LZ4 chunks) and a
4//! generic HDF5 fallback whose `info --view structure` lists groups, datasets and attributes.
5//!
6//! Layout and vocabulary: `docs/formats/ims.md`, `docs/formats/hdf5.md`,
7//! `docs/formats/nxmx.md`. Provenance: `docs/provenance/ims.md`, `docs/provenance/hdf5.md`,
8//! `docs/provenance/nxmx.md`.
9//!
10//! # Example
11//!
12//! Every reader implements [`openreadout_core::FormatReader`]: `descriptor`
13//! says what it reads, `sniff` recognises a file from its first bytes, and `open` returns a
14//! [`openreadout_core::Dataset`] with a header-only `info()` summary and lazy data
15//! access.
16//!
17//! ```
18//! use openreadout_core::FormatReader;
19//! use openreadout_hdf5::ImsReader;
20//!
21//! let format = ImsReader.descriptor();
22//! assert_eq!(format.id, openreadout_hdf5::IMS_FORMAT_ID);
23//! println!("{} ({}): .{}", format.name, format.family, format.extensions.join(", ."));
24//! ```
25//!
26//! Reading a file:
27//!
28//! ```no_run
29//! use std::path::Path;
30//!
31//! use openreadout_core::{FormatReader, PlaneIndex};
32//! use openreadout_hdf5::ImsReader;
33//!
34//! let mut dataset = ImsReader.open(Path::new("volume.ims"))?;
35//! let info = dataset.info()?; // headers only: fast even on multi-gigabyte files
36//! for image in &info.images {
37//! println!(
38//! "image {}: {} x {} px, {} channel(s), {} plane(s)",
39//! image.index, image.size_x, image.size_y, image.size_c, image.plane_count
40//! );
41//! }
42//! // Pixels are read one plane at a time: image 0, channel 0, first Z slice, first time point.
43//! let plane = dataset.read_plane(0, PlaneIndex { c: 0, z: 0, t: 0 })?;
44//! assert_eq!(plane.data.len(), plane.expected_len());
45//! # Ok::<(), openreadout_core::Error>(())
46//! ```
47//!
48//! Applications that accept any instrument file usually register every reader in an
49//! [`openreadout_core::Registry`] and let it detect the format; that is what the
50//! `openreadout` command-line tool does.
51//!
52//! # API stability
53//!
54//! The supported API is what this page documents. The parser modules are public only so that
55//! tests and fuzz targets can reach them: they are hidden from this documentation and may change
56//! in any release.
57#![forbid(unsafe_code)]
58#![warn(missing_docs)]
59
60mod assurance;
61#[doc(hidden)]
62pub mod generic;
63#[doc(hidden)]
64pub mod h5util;
65#[doc(hidden)]
66pub mod ims;
67#[doc(hidden)]
68pub mod ims_scene;
69#[doc(hidden)]
70pub mod nwb;
71#[doc(hidden)]
72pub mod nwb_tables;
73#[doc(hidden)]
74pub mod nwb_write;
75#[doc(hidden)]
76pub mod nxmx;
77
78pub use generic::{HDF5_FORMAT_ID, Hdf5Reader};
79pub use ims::{IMS_FORMAT_ID, ImsReader};
80pub use nwb::{NWB_FORMAT_ID, NwbReader};
81pub use nwb_write::{
82 NWB_VERSION, NwbExportOptions, NwbExportReport, NwbSeriesReport, default_nwb_output, export_nwb,
83};
84pub use nxmx::{NXMX_FORMAT_ID, NxmxReader};
85
86#[doc(hidden)]
87pub use generic::Hdf5Dataset;
88#[doc(hidden)]
89pub use ims::{ImsDataset, ImsLevel};
90#[doc(hidden)]
91pub use nwb::{NwbDataset, NwbSeries};
92#[doc(hidden)]
93pub use nxmx::NxmxDataset;