Skip to main content

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}