1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
//! Clean-room readers for electron-microscopy formats, registered as separate formats:
//!
//! - [`MrcReader`]: MRC / CCP4 / MAP (MRC2014, an open CCP-EM specification), format id `mrc`;
//! - [`DmReader`]: Gatan Digital Micrograph DM3 / DM4, format id `dm`;
//! - [`SerReader`]: TIA / ES Vision series files `.ser` with their `.emi` sidecar, format id `ser`;
//! - [`EmdReader`]: Velox EMD (HDF5-based) files, format id `emd`.
//!
//! Vocabulary: `docs/formats/{em,mrc,dm,ser}.md`. Provenance: `docs/provenance/{mrc,dm,ser}.md`.
//!
//! # Example
//!
//! Every reader implements [`openreadout_core::FormatReader`]: `descriptor`
//! says what it reads, `sniff` recognises a file from its first bytes, and `open` returns a
//! [`openreadout_core::Dataset`] with a header-only `info()` summary and lazy data
//! access.
//!
//! ```
//! use openreadout_core::FormatReader;
//! use openreadout_em::MrcReader;
//!
//! let format = MrcReader.descriptor();
//! assert_eq!(format.id, "mrc");
//! println!("{} ({}): .{}", format.name, format.family, format.extensions.join(", ."));
//! ```
//!
//! Reading a file:
//!
//! ```no_run
//! use std::path::Path;
//!
//! use openreadout_core::{FormatReader, PlaneIndex};
//! use openreadout_em::MrcReader;
//!
//! let mut dataset = MrcReader.open(Path::new("tomogram.mrc"))?;
//! let info = dataset.info()?; // headers only: fast even on multi-gigabyte files
//! for image in &info.images {
//! println!(
//! "image {}: {} x {} px, {} channel(s), {} plane(s)",
//! image.index, image.size_x, image.size_y, image.size_c, image.plane_count
//! );
//! }
//! // Pixels are read one plane at a time: image 0, channel 0, first Z slice, first time point.
//! let plane = dataset.read_plane(0, PlaneIndex { c: 0, z: 0, t: 0 })?;
//! assert_eq!(plane.data.len(), plane.expected_len());
//! # Ok::<(), openreadout_core::Error>(())
//! ```
//!
//! Applications that accept any instrument file usually register every reader in an
//! [`openreadout_core::Registry`] and let it detect the format; that is what the
//! `openreadout` command-line tool does.
//!
//! # API stability
//!
//! The supported API is what this page documents. The parser modules are public only so that
//! tests and fuzz targets can reach them: they are hidden from this documentation and may change
//! in any release.
pub use DmReader;
pub use EmdReader;
pub use MdocReader;
pub use MrcReader;
pub use SerReader;