openreadout_wsi/lib.rs
1//! Clean-room readers for whole-slide formats outside TIFF: 3DHISTECH MIRAX (`.mrxs`, format id
2//! `mirax`), whose pyramid is many stored images next to a settings file; Hamamatsu VMS (`.vms`,
3//! format id `hamamatsu-vms`), a grid of large JPEGs; and Philips iSyntax (`.isyntax`, format id
4//! `philips-isyntax`), a wavelet pyramid in one file.
5//!
6//! Layouts and vocabulary: `docs/formats/mirax.md`, `docs/formats/hamamatsu-vms.md`,
7//! `docs/formats/philips-isyntax.md`. Provenance: the files of the same names in
8//! `docs/provenance/`.
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_wsi::MiraxReader;
20//!
21//! let format = MiraxReader.descriptor();
22//! assert_eq!(format.id, openreadout_wsi::mirax::FORMAT_ID);
23//! println!("{} ({}): .{}", format.name, format.family, format.extensions.join(", ."));
24//! ```
25//!
26//! Reading a region of a slide:
27//!
28//! ```no_run
29//! use std::path::Path;
30//!
31//! use openreadout_core::{FormatReader, PlaneIndex, Region};
32//! use openreadout_wsi::MiraxReader;
33//!
34//! let mut dataset = MiraxReader.open(Path::new("slide.mrxs"))?;
35//! let info = dataset.info()?; // headers only: fast even on multi-gigabyte slides
36//! let level = &info.images[0].resolution_levels[2];
37//! println!("level 2: {} x {} px", level.size_x, level.size_y);
38//! let plane = dataset.read_region(0, PlaneIndex::default(), 2, Region::new(0, 0, 512, 512))?;
39//! assert_eq!(plane.data.len(), plane.expected_len());
40//! # Ok::<(), openreadout_core::Error>(())
41//! ```
42//!
43//! # API stability
44//!
45//! The supported API is what this page documents. The parser modules are public only so that
46//! tests and fuzz targets can reach them: they are hidden from this documentation and may change
47//! in any release.
48#![forbid(unsafe_code)]
49#![warn(missing_docs)]
50
51mod assurance;
52#[doc(hidden)]
53pub mod image;
54#[doc(hidden)]
55pub mod isyntax;
56#[doc(hidden)]
57pub mod mirax;
58#[doc(hidden)]
59pub mod vms;
60
61pub use isyntax::IsyntaxReader;
62pub use mirax::MiraxReader;
63pub use vms::VmsReader;