Skip to main content

openreadout_oif/
lib.rs

1//! Clean-room reader for Olympus FluoView OIF and OIB data sets (FV1000/FV1200/FV10i).
2//!
3//! An OIF data set is a main `.oif` settings file (UTF-16 INI text) plus a `<name>.oif.files`
4//! folder of plane TIFFs, per-plane `.pty` property files, LUTs, ROIs and a thumbnail. An OIB
5//! file packs the same files into one OLE2 compound file (MS-CFB, read with the shared
6//! `openreadout-core::cfb` reader) with an `OibInfo.txt` stream mapping stream names to file
7//! names. Planes are decoded by the TIFF reader (`openreadout-tiff`).
8//!
9//! Derived from hex dumps of corpus files and from the documentation and source of `oiffile`
10//! (BSD-3-Clause, Christoph Gohlke); Bio-Formats is run only as a black-box oracle. Layout and
11//! vocabulary: `docs/formats/oif.md`. Provenance: `docs/provenance/oif.md`.
12//!
13//! # Example
14//!
15//! Every reader implements [`openreadout_core::FormatReader`]: `descriptor`
16//! says what it reads, `sniff` recognises a file from its first bytes, and `open` returns a
17//! [`openreadout_core::Dataset`] with a header-only `info()` summary and lazy data
18//! access.
19//!
20//! ```
21//! use openreadout_core::FormatReader;
22//! use openreadout_oif::{OibReader, OifReader};
23//!
24//! for format in [OibReader.descriptor(), OifReader.descriptor()] {
25//!     println!("{} ({}): .{}", format.name, format.family, format.extensions.join(", ."));
26//! }
27//! assert_eq!(OibReader.descriptor().id, openreadout_oif::OIB_FORMAT_ID);
28//! ```
29//!
30//! Reading a file:
31//!
32//! ```no_run
33//! use std::path::Path;
34//!
35//! use openreadout_core::{FormatReader, PlaneIndex};
36//! use openreadout_oif::OibReader;
37//!
38//! let mut dataset = OibReader.open(Path::new("cells.oib"))?;
39//! let info = dataset.info()?; // headers only
40//! for image in &info.images {
41//!     println!(
42//!         "image {}: {} x {} px, {} channel(s), {} plane(s)",
43//!         image.index, image.size_x, image.size_y, image.size_c, image.plane_count
44//!     );
45//! }
46//! // Pixels are read one plane at a time: image 0, channel 0, first Z slice, first time point.
47//! let plane = dataset.read_plane(0, PlaneIndex { c: 0, z: 0, t: 0 })?;
48//! assert_eq!(plane.data.len(), plane.expected_len());
49//! # Ok::<(), openreadout_core::Error>(())
50//! ```
51//!
52//! Applications that accept any instrument file usually register every reader in an
53//! [`openreadout_core::Registry`] and let it detect the format; that is what the
54//! `openreadout` command-line tool does.
55//!
56//! # API stability
57//!
58//! The supported API is what this page documents. The parser modules are public only so that
59//! tests and fuzz targets can reach them: they are hidden from this documentation and may change
60//! in any release.
61#![forbid(unsafe_code)]
62#![warn(missing_docs)]
63
64mod assurance;
65#[doc(hidden)]
66pub mod dataset;
67#[doc(hidden)]
68pub mod settings;
69#[doc(hidden)]
70pub mod store;
71
72use std::path::Path;
73
74use openreadout_core::Result;
75use openreadout_core::cfb::CFB_MAGIC;
76use openreadout_core::model::{DetectConfidence, FormatDescriptor};
77use openreadout_core::reader::{Dataset, Detection, FormatReader, has_extension};
78use openreadout_core::source::Input;
79
80#[doc(hidden)]
81pub use dataset::{FvDataset, FvImage, PlaneName, parse_plane_name};
82#[doc(hidden)]
83pub use settings::{Section, Settings};
84#[doc(hidden)]
85pub use store::{Member, MemberSource, Store, StoreKind};
86
87/// Format id of OIB (single compound file) data sets.
88pub const OIB_FORMAT_ID: &str = "oib";
89/// Format id of OIF (settings file plus `.oif.files` folder) data sets.
90pub const OIF_FORMAT_ID: &str = "oif";
91
92fn known_gaps() -> Vec<String> {
93    vec![
94        "Derived without a specification from 12 corpus data sets (FV1000/FV1200, FluoView 4.2): 16-bit grey planes, uncompressed or LZW; 8-bit and colour planes follow the TIFF reader but no corpus file has them".into(),
95        "Plane file names with axis letters other than C, Z, T and L become separate images (inferred, no corpus file)".into(),
96        "Line scans (XT) are exposed as planes whose height is the number of lines (Y is time); point scans and multi-area time lapse are not reinterpreted".into(),
97        "ROI (.roi) and LUT (.lut) files are listed, not decoded; channel colours are not reported".into(),
98        "Multi-page plane TIFFs are read from their first page only".into(),
99    ]
100}
101
102/// The OIB (compound file) reader.
103#[derive(Debug, Default, Clone, Copy)]
104pub struct OibReader;
105
106/// The OIF (settings file plus data folder) reader.
107#[derive(Debug, Default, Clone, Copy)]
108pub struct OifReader;
109
110impl FormatReader for OibReader {
111    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
112        Some(&assurance::OIB)
113    }
114
115    fn descriptor(&self) -> FormatDescriptor {
116        FormatDescriptor {
117            id: OIB_FORMAT_ID.into(),
118            name: "Olympus FluoView OIB".into(),
119            vendor: "Evident (Olympus)".into(),
120            extensions: vec!["oib".into()],
121            family: "microscopy".into(),
122            can_read: true,
123            can_write: false,
124            confidence: assurance::OIB.confidence,
125            known_gaps: known_gaps(),
126        }
127    }
128
129    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
130        if !has_extension(path, &["oib"]) {
131            return None;
132        }
133        // A file long enough to show the compound-file signature that does not is another kind
134        // of file (exit 3), not a damaged one.
135        if head.len() >= CFB_MAGIC.len() && !head.starts_with(&CFB_MAGIC) {
136            return None;
137        }
138        Some(if head.starts_with(&CFB_MAGIC) {
139            Detection {
140                format_id: OIB_FORMAT_ID,
141                confidence: DetectConfidence::Definite,
142                note: Some("OLE2 compound file with the .oib extension".into()),
143            }
144        } else {
145            Detection {
146                format_id: OIB_FORMAT_ID,
147                confidence: DetectConfidence::ExtensionOnly,
148                note: Some("OIB extension, but no compound-file signature".into()),
149            }
150        })
151    }
152
153    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
154        self.open_input(&Input::local(path))
155    }
156
157    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
158        Ok(Box::new(FvDataset::open_input(input, StoreKind::Oib)?))
159    }
160
161    fn reads_any_source(&self) -> bool {
162        true
163    }
164}
165
166/// Does this look like a FluoView settings file (UTF-16LE with a byte-order mark, then `[`)?
167pub fn looks_like_settings(head: &[u8]) -> bool {
168    head.starts_with(&[0xFF, 0xFE, b'[', 0])
169}
170
171impl FormatReader for OifReader {
172    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
173        Some(&assurance::OIF)
174    }
175
176    fn descriptor(&self) -> FormatDescriptor {
177        FormatDescriptor {
178            id: OIF_FORMAT_ID.into(),
179            name: "Olympus FluoView OIF".into(),
180            vendor: "Evident (Olympus)".into(),
181            extensions: vec!["oif".into()],
182            family: "microscopy".into(),
183            can_read: true,
184            can_write: false,
185            confidence: assurance::OIF.confidence,
186            known_gaps: known_gaps(),
187        }
188    }
189
190    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
191        if !has_extension(path, &["oif"]) {
192            return None;
193        }
194        Some(
195            if looks_like_settings(head) || head.first() == Some(&b'[') {
196                Detection {
197                    format_id: OIF_FORMAT_ID,
198                    confidence: DetectConfidence::Definite,
199                    note: Some(
200                        "FluoView settings file; planes are read from the .oif.files folder next to it"
201                            .into(),
202                    ),
203                }
204            } else {
205                Detection {
206                    format_id: OIF_FORMAT_ID,
207                    confidence: DetectConfidence::ExtensionOnly,
208                    note: Some("OIF extension, but not a settings text file".into()),
209                }
210            },
211        )
212    }
213
214    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
215        self.open_input(&Input::local(path))
216    }
217
218    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
219        Ok(Box::new(FvDataset::open_input(input, StoreKind::Oif)?))
220    }
221
222    fn reads_any_source(&self) -> bool {
223        true
224    }
225}