Skip to main content

openreadout_em/
lib.rs

1//! Clean-room readers for electron-microscopy formats, registered as separate formats:
2//!
3//! - [`MrcReader`]: MRC / CCP4 / MAP (MRC2014, an open CCP-EM specification), format id `mrc`;
4//! - [`DmReader`]: Gatan Digital Micrograph DM3 / DM4, format id `dm`;
5//! - [`SerReader`]: TIA / ES Vision series files `.ser` with their `.emi` sidecar, format id `ser`;
6//! - [`EmdReader`]: Velox EMD (HDF5-based) files, format id `emd`.
7//!
8//! Vocabulary: `docs/formats/{em,mrc,dm,ser}.md`. Provenance: `docs/provenance/{mrc,dm,ser}.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_em::MrcReader;
20//!
21//! let format = MrcReader.descriptor();
22//! assert_eq!(format.id, "mrc");
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_em::MrcReader;
33//!
34//! let mut dataset = MrcReader.open(Path::new("tomogram.mrc"))?;
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 dm;
63#[doc(hidden)]
64pub mod emd;
65#[doc(hidden)]
66pub mod mdoc;
67#[doc(hidden)]
68pub mod mrc;
69#[doc(hidden)]
70pub mod ser;
71mod util;
72
73pub use dm::DmReader;
74pub use emd::EmdReader;
75pub use mdoc::MdocReader;
76pub use mrc::MrcReader;
77pub use ser::SerReader;