openreadout_zvi/lib.rs
1//! Clean-room reader for Zeiss AxioVision ZVI files (OLE2 / MS-CFB compound files).
2//!
3//! The compound-file container comes from Microsoft's public MS-CFB specification (the shared
4//! reader in `openreadout-core::cfb`); the ZVI streams, value encoding and tag ids were read off
5//! hex dumps of corpus files and identified by comparing values across files and with
6//! Bio-Formats' output (run as a black box). Layout and vocabulary: `docs/formats/zvi.md`.
7//! Provenance: `docs/provenance/zvi.md`.
8//!
9//! # Example
10//!
11//! Every reader implements [`openreadout_core::FormatReader`]: `descriptor`
12//! says what it reads, `sniff` recognises a file from its first bytes, and `open` returns a
13//! [`openreadout_core::Dataset`] with a header-only `info()` summary and lazy data
14//! access.
15//!
16//! ```
17//! use openreadout_core::FormatReader;
18//! use openreadout_zvi::ZviReader;
19//!
20//! let format = ZviReader.descriptor();
21//! assert_eq!(format.id, openreadout_zvi::FORMAT_ID);
22//! println!("{} ({}): .{}", format.name, format.family, format.extensions.join(", ."));
23//! ```
24//!
25//! Reading a file:
26//!
27//! ```no_run
28//! use std::path::Path;
29//!
30//! use openreadout_core::{FormatReader, PlaneIndex};
31//! use openreadout_zvi::ZviReader;
32//!
33//! let mut dataset = ZviReader.open(Path::new("image.zvi"))?;
34//! let info = dataset.info()?; // headers only: fast even on multi-gigabyte files
35//! for image in &info.images {
36//! println!(
37//! "image {}: {} x {} px, {} channel(s), {} plane(s)",
38//! image.index, image.size_x, image.size_y, image.size_c, image.plane_count
39//! );
40//! }
41//! // Pixels are read one plane at a time: image 0, channel 0, first Z slice, first time point.
42//! let plane = dataset.read_plane(0, PlaneIndex { c: 0, z: 0, t: 0 })?;
43//! assert_eq!(plane.data.len(), plane.expected_len());
44//! # Ok::<(), openreadout_core::Error>(())
45//! ```
46//!
47//! Applications that accept any instrument file usually register every reader in an
48//! [`openreadout_core::Registry`] and let it detect the format; that is what the
49//! `openreadout` command-line tool does.
50//!
51//! # API stability
52//!
53//! The supported API is what this page documents. The parser modules are public only so that
54//! tests and fuzz targets can reach them: they are hidden from this documentation and may change
55//! in any release.
56#![forbid(unsafe_code)]
57#![warn(missing_docs)]
58
59mod assurance;
60#[doc(hidden)]
61pub mod dataset;
62#[doc(hidden)]
63pub mod tags;
64
65use std::path::Path;
66
67use openreadout_core::Result;
68use openreadout_core::cfb::CFB_MAGIC;
69use openreadout_core::model::{DetectConfidence, FormatDescriptor};
70use openreadout_core::reader::{Dataset, Detection, FormatReader, has_extension};
71use openreadout_core::source::Input;
72
73#[doc(hidden)]
74pub use dataset::*;
75
76/// Format id used on the command line and in JSON.
77pub const FORMAT_ID: &str = "zvi";
78
79/// The ZVI reader.
80#[derive(Debug, Default, Clone, Copy)]
81pub struct ZviReader;
82
83impl FormatReader for ZviReader {
84 fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
85 Some(&assurance::ZVI)
86 }
87
88 fn descriptor(&self) -> FormatDescriptor {
89 FormatDescriptor {
90 id: FORMAT_ID.into(),
91 name: "Zeiss AxioVision ZVI".into(),
92 vendor: "Carl Zeiss (AxioVision)".into(),
93 extensions: vec!["zvi".into()],
94 family: "microscopy".into(),
95 can_read: true,
96 can_write: false,
97 confidence: assurance::ZVI.confidence,
98 known_gaps: vec![
99 "Derived without a specification from 16 corpus files (12 depositors, 8 microscope stands, 2003-2025): 16-bit grey (pixel format 4) and 3 x 16-bit colour (format 8) are validated bit for bit; 8-bit grey and 3 x 8-bit colour are inferred (a note says so); other formats exit 6".into(),
100 "Time series (tag 2821), multi-position and mosaic files are handled by inferred index tags that no public file exercises (a note says so); the acquisition-setup folder (Image/RootFolder) is listed, not interpreted".into(),
101 "Scale units other than micrometres (code 76) are not interpreted; uncalibrated axes have no physical size".into(),
102 "Layers, shapes (annotations) and the document summary property sets are listed, not decoded".into(),
103 ],
104 }
105 }
106
107 fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
108 if !has_extension(path, &["zvi"]) {
109 return None;
110 }
111 // A file long enough to show the compound-file signature that does not is another kind
112 // of file (exit 3), not a damaged one.
113 if head.len() >= CFB_MAGIC.len() && !head.starts_with(&CFB_MAGIC) {
114 return None;
115 }
116 Some(if head.starts_with(&CFB_MAGIC) {
117 Detection {
118 format_id: FORMAT_ID,
119 confidence: DetectConfidence::Definite,
120 note: Some("OLE2 compound file with the .zvi extension".into()),
121 }
122 } else {
123 Detection {
124 format_id: FORMAT_ID,
125 confidence: DetectConfidence::ExtensionOnly,
126 note: Some("ZVI extension, but no compound-file signature".into()),
127 }
128 })
129 }
130
131 fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
132 Ok(Box::new(ZviDataset::open(path)?))
133 }
134
135 fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
136 Ok(Box::new(ZviDataset::open_input(input)?))
137 }
138
139 fn reads_any_source(&self) -> bool {
140 true
141 }
142}