openreadout_core/lib.rs
1//! Core types shared by every `OpenReadout` format reader and front end.
2//!
3//! The vocabulary here is deliberately vendor-neutral and mirrors the OME data model
4//! (the open standard for microscopy metadata), so that an agent sees the same field
5//! names whether a file came from ZEISS, Nikon or Leica. Vendor-specific metadata is
6//! preserved verbatim under a separate `vendor` tree.
7//!
8//! # Overview
9//!
10//! - [`FormatReader`] is implemented once per file format (in the `openreadout-<format>`
11//! crates). It recognises a file from its first bytes and opens it.
12//! - [`Dataset`] is an opened file. `info()` reads headers only and returns a [`FileInfo`];
13//! pixels, table rows, spectra and signal samples are read lazily, one piece at a time.
14//! - [`Registry`] holds readers in detection order and picks the right one for a file.
15//! - [`source`] is where the bytes come from: a local file, a buffer in memory, or a callback
16//! the host provides (a Python file-like object, a browser `File`). Readers open an
17//! [`Input`] and read it through [`SourceFile`] and [`Fs`], which behave like `std::fs`.
18//! - [`model`] is the normalized metadata. A file holds any mix of *images* (microscopy
19//! planes), *tables* (flow-cytometry events, plate-reader wells), *spectra* (mass
20//! spectrometry scans) and *traces* (uniformly sampled signals: electrophysiology sweeps,
21//! chromatograms, NMR signals).
22//! - [`Error`] carries a stable code, a process exit code and an actionable hint;
23//! [`Envelope`] is the JSON wrapper every `--json` command prints.
24//! - [`provenance`] records where the meaning of each normalized field came from.
25//! - [`experiment`] derives the experiment (sample, instrument, method, acquisition,
26//! measurements) from the normalized model, with terms from [`vocab`]; `info` prints it as
27//! [`InfoOutput`].
28//! - [`stats`] and [`trace`] implement those commands; [`batch`] and [`select`] parse their
29//! inputs. Other command-level operations (`compare`, `info --view explain`,
30//! `extract`, `--only`) live in the `openreadout-ops` crate.
31//! - [`live`] judges whether an incomplete file is still being written (`acquisition` in
32//! `info`, `info --view structure`, `check` and `planes`).
33//! - [`bytes`], [`cfb`], [`xml`], [`xmljson`], [`zip`], [`time`] and [`parallel`] are helpers for
34//! format crates.
35//!
36//! # Exit codes
37//!
38//! Part of the public interface (agents branch on them):
39//!
40//! | code | meaning | [`Error`] variant |
41//! | --- | --- | --- |
42//! | 0 | success | |
43//! | 1 | other error | [`Error::Other`] |
44//! | 2 | bad arguments or impossible request | [`Error::Usage`] |
45//! | 3 | unrecognised file format | [`Error::UnknownFormat`] |
46//! | 4 | corrupt or truncated file | [`Error::Corrupt`] |
47//! | 5 | I/O error | [`Error::Io`] |
48//! | 6 | known format, unsupported feature | [`Error::Unsupported`] |
49//!
50//! # Example
51//!
52//! ```
53//! use std::path::Path;
54//!
55//! use openreadout_core::{Error, Registry};
56//!
57//! // Format crates register their readers: `Registry::new().with(Box::new(CziReader))`.
58//! // An empty registry recognises nothing, which shows the error contract.
59//! let registry = Registry::new();
60//! let err = registry
61//! .detect_bytes(b"not an instrument file", Path::new("notes.txt"))
62//! .map(|_| ())
63//! .unwrap_err();
64//! assert!(matches!(err, Error::UnknownFormat { .. }));
65//! assert_eq!(err.code(), "unknown_format");
66//! assert_eq!(err.exit_code(), 3);
67//! assert!(err.hint().is_some());
68//! ```
69//!
70//! Enums and option structs that will grow are `#[non_exhaustive]`: match them with a
71//! wildcard arm, and build option structs from `Default::default()`.
72#![forbid(unsafe_code)]
73#![deny(missing_docs)]
74
75pub mod acquisition_mode;
76pub mod annotation;
77pub mod assurance;
78pub mod batch;
79pub mod bytes;
80pub mod cfb;
81pub mod diffraction;
82pub mod envelope;
83pub mod error;
84pub mod experiment;
85pub mod flow;
86pub mod gzip;
87pub mod jet;
88pub mod limits;
89pub mod live;
90pub mod measure;
91pub mod model;
92pub mod output;
93pub mod parallel;
94pub mod pixel;
95pub mod plate;
96pub mod provenance;
97pub mod reader;
98pub mod region;
99pub mod scans;
100pub mod select;
101pub mod series;
102pub mod session;
103pub mod source;
104pub mod stats;
105pub mod strict;
106pub mod time;
107pub mod trace;
108pub mod transitions;
109pub mod vocab;
110pub mod xml;
111pub mod xmljson;
112pub mod zip;
113
114pub use envelope::{Envelope, ErrorBody, SCHEMA_VERSION};
115pub use error::{Error, Result};
116pub use experiment::{Experiment, InfoOutput};
117pub use model::*;
118pub use pixel::{PixelType, Plane};
119pub use provenance::{Confidence, ProvenanceMap, Source};
120pub use reader::{Dataset, Detection, FormatReader, PlaneIndex, Registry, SpectrumView};
121pub use region::{Region, ResolutionLevel};
122pub use scans::{ScanFilter, ScanHeader, ScanList};
123pub use source::{ByteSource, DirSource, Fs, Input, SourceFile};