Skip to main content

openreadout_vsi/
lib.rs

1//! Clean-room reader for Olympus/Evident cellSens VSI files (cellSens, VS120/VS200 slide
2//! scanners): the `.vsi` holds a TIFF preview and a tagged record tree with the metadata; the
3//! pixels live in `_<name>_/stack<id>/frame_t*.ets` tile files (raw, JPEG or JPEG 2000 tiles,
4//! pyramids for whole slides). A standalone `.ets` can be opened too.
5//!
6//! Layout and vocabulary: `docs/formats/vsi.md`. Provenance: `docs/provenance/vsi.md`.
7//!
8//! # Example
9//!
10//! Every reader implements [`openreadout_core::FormatReader`]: `descriptor`
11//! says what it reads, `sniff` recognises a file from its first bytes, and `open` returns a
12//! [`openreadout_core::Dataset`] with a header-only `info()` summary and lazy data
13//! access.
14//!
15//! ```
16//! use openreadout_core::FormatReader;
17//! use openreadout_vsi::VsiReader;
18//!
19//! let format = VsiReader.descriptor();
20//! assert_eq!(format.id, openreadout_vsi::FORMAT_ID);
21//! println!("{} ({}): .{}", format.name, format.family, format.extensions.join(", ."));
22//! ```
23//!
24//! Reading a file:
25//!
26//! ```no_run
27//! use std::path::Path;
28//!
29//! use openreadout_core::{FormatReader, PlaneIndex};
30//! use openreadout_vsi::VsiReader;
31//!
32//! let mut dataset = VsiReader.open(Path::new("slide.vsi"))?;
33//! let info = dataset.info()?; // headers only: fast even on multi-gigabyte files
34//! for image in &info.images {
35//!     println!(
36//!         "image {}: {} x {} px, {} channel(s), {} plane(s)",
37//!         image.index, image.size_x, image.size_y, image.size_c, image.plane_count
38//!     );
39//! }
40//! // Pixels are read one plane at a time: image 0, channel 0, first Z slice, first time point.
41//! let plane = dataset.read_plane(0, PlaneIndex { c: 0, z: 0, t: 0 })?;
42//! assert_eq!(plane.data.len(), plane.expected_len());
43//! # Ok::<(), openreadout_core::Error>(())
44//! ```
45//!
46//! Applications that accept any instrument file usually register every reader in an
47//! [`openreadout_core::Registry`] and let it detect the format; that is what the
48//! `openreadout` command-line tool does.
49//!
50//! # API stability
51//!
52//! The supported API is what this page documents. The parser modules are public only so that
53//! tests and fuzz targets can reach them: they are hidden from this documentation and may change
54//! in any release.
55#![forbid(unsafe_code)]
56#![warn(missing_docs)]
57
58mod assurance;
59#[doc(hidden)]
60pub mod dataset;
61#[doc(hidden)]
62pub mod ets;
63#[doc(hidden)]
64pub mod meta;
65#[doc(hidden)]
66pub mod tiff;
67#[doc(hidden)]
68pub mod tree;
69
70use std::path::Path;
71
72use openreadout_core::model::{DetectConfidence, FormatDescriptor};
73use openreadout_core::reader::{Dataset, Detection, FormatReader, has_extension};
74use openreadout_core::source::Input;
75use openreadout_core::{Error, Result};
76
77#[doc(hidden)]
78pub use dataset::VsiDataset;
79#[doc(hidden)]
80pub use ets::{ETS_MAGIC, EtsCompression, EtsFile, EtsHeader, SIS_MAGIC, Tile, looks_like_ets};
81#[doc(hidden)]
82pub use meta::{
83    ChannelMeta, DimKind, DimMeta, ObjectiveMeta, StackMeta, VsiMeta, read_meta, unit_factor,
84};
85#[doc(hidden)]
86pub use tiff::{PreviewInfo, looks_like_vsi, preview_info, preview_jpeg};
87#[doc(hidden)]
88pub use tree::{TREE_OFFSET, TagRecord, TagTree, TagValue, VOLUME_MAGIC};
89
90/// Format id used on the command line and in JSON.
91pub const FORMAT_ID: &str = "vsi";
92
93/// The Olympus/Evident cellSens VSI reader.
94#[derive(Debug, Default, Clone, Copy)]
95pub struct VsiReader;
96
97impl FormatReader for VsiReader {
98    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
99        Some(&assurance::VSI)
100    }
101
102    fn descriptor(&self) -> FormatDescriptor {
103        FormatDescriptor {
104            id: FORMAT_ID.into(),
105            name: "Olympus/Evident cellSens VSI".into(),
106            vendor: "Evident (Olympus)".into(),
107            extensions: vec!["vsi".into(), "ets".into()],
108            family: "microscopy".into(),
109            can_read: true,
110            can_write: false,
111            confidence: assurance::VSI.confidence,
112            known_gaps: vec![
113                "No specification: the .vsi record tree and ETS layout are derived from 27 corpus files (11 with pixel data: cellSens Dimension 1.18/3.2/3.x, VS200 ASW, VS120 dotSlide 2.5, Stream Essentials 1.7; ETS versions 0x00030003/5/6); names, calibration, channels, exposure, objective, camera, times and dimension kinds come from records identified by comparison with Bio-Formats; everything else is only in `vendor` under numeric tags".into(),
114                "Dimension kinds other than Z (1), T (2) and channel (4) never occurred in the corpus; one would be exposed as T with a note and a `check` warning".into(),
115                "ETS sample types other than 8-bit (2) and 16-bit (4) unsigned, and compressions other than raw (0), JPEG (2), JPEG 2000 (3) and lossless JPEG (5), are not decoded (exit 6)".into(),
116                "Unstored whole-slide tiles are filled with the ETS background value (as Bio-Formats does); JPEG tiles are decoded with jpeg-decoder and may differ by a few levels from other decoders".into(),
117                "Where the tile grid is offset from the image corner (record 2410), coarser pyramid levels place it at the nearest pixel of offset/2^L; Bio-Formats truncates, so such levels can differ from it by one pixel".into(),
118                "Planes larger than 4 GiB (full-resolution whole slides) are read by region (`--region`) or at a pyramid level (`--level`), not whole".into(),
119                "Stacks without an ETS file (focus maps, sample masks, measurement/ROI layers) and blob_*.ets focus data are listed, not decoded; a stack directory holding several frame_t*.ets files is read from the first only".into(),
120                "The excitation wavelength (record 2474) is inferred from plausibility across 9 channels (Bio-Formats reports only emission)".into(),
121            ],
122        }
123    }
124
125    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
126        if tiff::looks_like_vsi(head) {
127            return Some(Detection {
128                format_id: FORMAT_ID,
129                confidence: DetectConfidence::Definite,
130                note: None,
131            });
132        }
133        if ets::looks_like_ets(head) {
134            return Some(Detection {
135                format_id: FORMAT_ID,
136                confidence: DetectConfidence::Definite,
137                note: Some("cellSens ETS tile file; open the .vsi next to its _<name>_ directory for names and calibration".into()),
138            });
139        }
140        if has_extension(path, &["vsi", "ets"]) {
141            return Some(Detection {
142                format_id: FORMAT_ID,
143                confidence: DetectConfidence::ExtensionOnly,
144                note: Some(
145                    "`.vsi`/`.ets` extension, but the content does not match a cellSens header"
146                        .into(),
147                ),
148            });
149        }
150        None
151    }
152
153    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
154        self.open_input(&Input::local(path))
155    }
156
157    fn reads_any_source(&self) -> bool {
158        true
159    }
160
161    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
162        let path = input.path();
163        if !input.fs().is_file(path) {
164            return Err(Error::io(
165                path,
166                std::io::Error::new(std::io::ErrorKind::NotFound, "not a file"),
167            ));
168        }
169        Ok(Box::new(dataset::VsiDataset::open(input)?))
170    }
171}