Skip to main content

openreadout_tiff/
lib.rs

1//! Clean-room reader for the TIFF family.
2//!
3//! Container: TIFF 6.0 and BigTIFF (open specifications). Conventions detected from tags,
4//! in priority order: OME-TIFF (OME-XML in `ImageDescription`, multi-file sets, `BinaryOnly`
5//! and `*.companion.ome`), Zeiss LSM, MetaMorph STK, Aperio SVS, Hamamatsu NDPI, PerkinElmer
6//! QPTIFF, MetaMorph MetaSeries, ImageJ hyperstacks, Micro-Manager, and plain TIFF; Nikon
7//! NIS-Elements TIFF exports are grouped with their sibling files. A MetaMorph `.nd` file opens
8//! the multi-stage, multi-wavelength time series of TIFF/STK files it names.
9//!
10//! Layout and vocabulary: `docs/formats/tiff.md`. Provenance: `docs/provenance/tiff.md`.
11//!
12//! # Example
13//!
14//! Every reader implements [`openreadout_core::FormatReader`]: `descriptor`
15//! says what it reads, `sniff` recognises a file from its first bytes, and `open` returns a
16//! [`openreadout_core::Dataset`] with a header-only `info()` summary and lazy data
17//! access.
18//!
19//! ```
20//! use openreadout_core::FormatReader;
21//! use openreadout_tiff::TiffReader;
22//!
23//! let format = TiffReader.descriptor();
24//! assert_eq!(format.id, openreadout_tiff::FORMAT_ID);
25//! println!("{} ({}): .{}", format.name, format.family, format.extensions.join(", ."));
26//! ```
27//!
28//! Reading a file:
29//!
30//! ```no_run
31//! use std::path::Path;
32//!
33//! use openreadout_core::{FormatReader, PlaneIndex};
34//! use openreadout_tiff::TiffReader;
35//!
36//! let mut dataset = TiffReader.open(Path::new("stack.ome.tiff"))?;
37//! let info = dataset.info()?; // headers only: fast even on multi-gigabyte files
38//! for image in &info.images {
39//!     println!(
40//!         "image {}: {} x {} px, {} channel(s), {} plane(s)",
41//!         image.index, image.size_x, image.size_y, image.size_c, image.plane_count
42//!     );
43//! }
44//! // Pixels are read one plane at a time: image 0, channel 0, first Z slice, first time point.
45//! let plane = dataset.read_plane(0, PlaneIndex { c: 0, z: 0, t: 0 })?;
46//! assert_eq!(plane.data.len(), plane.expected_len());
47//! # Ok::<(), openreadout_core::Error>(())
48//! ```
49//!
50//! Applications that accept any instrument file usually register every reader in an
51//! [`openreadout_core::Registry`] and let it detect the format; that is what the
52//! `openreadout` command-line tool does.
53//!
54//! # API stability
55//!
56//! The supported API is what this page documents. The parser modules are public only so that
57//! tests and fuzz targets can reach them: they are hidden from this documentation and may change
58//! in any release.
59#![forbid(unsafe_code)]
60#![warn(missing_docs)]
61
62mod assurance;
63#[doc(hidden)]
64pub mod bif;
65mod check;
66mod chunk_codecs;
67#[doc(hidden)]
68pub mod container;
69#[doc(hidden)]
70pub mod dataset;
71#[doc(hidden)]
72pub mod decode;
73#[doc(hidden)]
74pub mod eer;
75mod files;
76mod flavors;
77mod imagej;
78mod imagers;
79mod incucyte;
80mod jpeg2000;
81mod lsm;
82mod mdgel;
83#[doc(hidden)]
84pub mod metamorph;
85mod nd;
86mod ndpi;
87#[doc(hidden)]
88pub mod ndpis;
89#[doc(hidden)]
90pub mod nis;
91#[doc(hidden)]
92pub mod ome;
93#[doc(hidden)]
94pub mod philips;
95#[doc(hidden)]
96pub mod scn;
97mod tags;
98
99use std::io::Read;
100use std::path::Path;
101
102use openreadout_core::model::{DetectConfidence, FormatDescriptor};
103use openreadout_core::reader::{Dataset, Detection, FormatReader, has_extension};
104use openreadout_core::source::{Fs, Input};
105use openreadout_core::{Error, Result};
106
107#[doc(hidden)]
108pub use container::{
109    BIGTIFF_MAGIC, ByteOrder, ByteSource, Field, FieldValue, Ifd, StructureProblem, TIFF_MAGIC,
110    TiffFile, TiffHeader, looks_like_tiff,
111};
112#[doc(hidden)]
113pub use dataset::{Flavor, TiffDataset};
114#[doc(hidden)]
115pub use decode::{MAX_PLANE_BYTES, PageLayout, SampleSelect, compression_name, read_page};
116#[doc(hidden)]
117pub use metamorph::{MetaSeriesPlane, NdFile, StkInfo, parse_metaseries, parse_nd, parse_stk};
118#[doc(hidden)]
119pub use nis::{NisPage, SequenceAxis, SequenceName, parse_nis, parse_sequence_name};
120#[doc(hidden)]
121pub use ome::{
122    OmeAnnotation, OmeBinaryOnly, OmeChannel, OmeDetector, OmeDocument, OmeImage, OmeInstrument,
123    OmeObjective, OmePixels, OmePlane, OmeTiffData, parse as parse_ome_xml,
124};
125
126/// Format id used on the command line and in JSON.
127pub const FORMAT_ID: &str = "tiff";
128
129/// Extensions of the TIFF family (lowercase, without the dot).
130pub const EXTENSIONS: [&str; 16] = [
131    "tif", "tiff", "ome.tif", "ome.tiff", "svs", "ndpi", "ndpis", "lsm", "qptiff", "btf", "stk",
132    "nd", "eer", "scn", "bif", "gel",
133];
134
135/// The TIFF-family reader.
136#[derive(Debug, Default, Clone, Copy)]
137pub struct TiffReader;
138
139pub(crate) fn is_companion_path(path: &Path) -> bool {
140    path.file_name()
141        .and_then(|n| n.to_str())
142        .is_some_and(|n| n.to_ascii_lowercase().ends_with(".companion.ome"))
143}
144
145pub(crate) fn file_starts_like_tiff(fs: &Fs, path: &Path) -> Result<bool> {
146    let mut f = fs.open(path).map_err(|e| Error::io(path, e))?;
147    let mut head = [0u8; 4];
148    let n = f.read(&mut head).map_err(|e| Error::io(path, e))?;
149    Ok(n == 4 && looks_like_tiff(&head))
150}
151
152/// A MetaMorph `.nd` series file: the `.nd` extension and the `"NDInfoFile"` key first.
153pub(crate) fn is_nd_path(fs: &Fs, path: &Path) -> bool {
154    has_extension(path, &["nd"])
155        && fs
156            .open(path)
157            .and_then(|mut f| {
158                let mut head = [0u8; 16];
159                let n = f.read(&mut head)?;
160                Ok(looks_like_nd(&head[..n]))
161            })
162            .unwrap_or(false)
163}
164
165/// A Hamamatsu NDPI set: a text file whose first line is the set header.
166fn is_ndpis(fs: &Fs, path: &Path) -> bool {
167    fs.open(path)
168        .and_then(|mut f| {
169            let mut head = [0u8; 64];
170            let n = f.read(&mut head)?;
171            Ok(ndpis::looks_like_ndpis(&head[..n]))
172        })
173        .unwrap_or(false)
174}
175
176fn looks_like_nd(head: &[u8]) -> bool {
177    let head = head.strip_prefix(b"\xef\xbb\xbf").unwrap_or(head);
178    head.starts_with(b"\"NDInfoFile\"")
179}
180
181fn looks_like_ome_xml(head: &[u8]) -> bool {
182    let s = String::from_utf8_lossy(&head[..head.len().min(4096)]);
183    let s = s.trim_start_matches('\u{feff}').trim_start();
184    s.starts_with('<') && (s.contains("<OME ") || s.contains("<OME>") || s.contains(":OME "))
185}
186
187impl FormatReader for TiffReader {
188    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
189        Some(&assurance::TIFF)
190    }
191
192    fn descriptor(&self) -> FormatDescriptor {
193        FormatDescriptor {
194            id: FORMAT_ID.into(),
195            name: "TIFF family (TIFF, BigTIFF, OME-TIFF, ImageJ, SVS, NDPI, LSM, QPTIFF, Leica SCN, Ventana BIF, Micro-Manager, MetaMorph STK/.nd, Thermo Fisher EER)".into(),
196            vendor: "open standard (TIFF 6.0 / OME); Leica Aperio, Hamamatsu, Zeiss, PerkinElmer, Molecular Devices MetaMorph, Thermo Fisher (Falcon EER) conventions".into(),
197            extensions: EXTENSIONS.iter().map(|s| (*s).to_string()).collect(),
198            family: "microscopy".into(),
199            can_read: true,
200            // `export --format ome-tiff` writes OME-TIFF (openreadout-ometiff).
201            can_write: true,
202            confidence: assurance::TIFF.confidence,
203            known_gaps: vec![
204                "Old-style JPEG (6) is decoded only in its tables form (not lossless, not a single JPEGInterchangeFormat stream); LERC tiles exit 6 in default builds (the opt-in `lerc` feature decodes them with lerc-rs, which panics on some malformed input; SECURITY.md). JPEG 2000 tiles (Aperio 33003/33005, 34712) are decoded, irreversible (9/7) ones within 1 grey level of OpenJPEG (the reconstruction is not bit-exact)".into(),
205                "Packed 1-31-bit, half and 24-bit float and complex-integer samples are decoded only uncompressed or with LZW, deflate, PackBits or zstd (not inside JPEG, JPEG 2000, WebP, JPEG XL or LERC chunks)".into(),
206                "Ventana BIF: tiles are returned on their stored grid; the overlaps recorded in EncodeInfo/TileJointInfo are reported, not stitched (such files are partially decoded for --strict); volumetric BIF (ImageDepth > 1) exits 6".into(),
207                "EER (Falcon electron-event movies): frames are decoded to counts on the sensor grid; the sub-pixel (super-resolution) positions of events are not used, the gain reference is not applied, and the TIFF Orientation is reported, not applied".into(),
208                "Planes larger than 4 GiB (whole-slide level 0) are read by region (`--region`), not whole; NDPI level 0 is read by its JPEG restart intervals (baseline JPEG only)".into(),
209                "NDPI files larger than 4 GiB (offset high bytes in tag 65324) and LSM files larger than 4 GiB (wrapped strip offsets) are not supported".into(),
210                "OME Modulo annotations (FLIM/lambda/angle sub-dimensions along C/Z/T) are reported in images[].extra.modulo with the sub-dimension's size and labels; planes keep the stored C/Z/T indices (the sub-dimension varies fastest within its parent axis)".into(),
211                "Micro-Manager multi-file datasets without OME-XML and other TIFF dialects fall back to plain-TIFF behaviour (pages as Z)".into(),
212                "MetaMorph STK: only uncompressed stacks; `.nd` series: file names are built from the .nd keys (`_w<i><name>_s<j>_t<k>`), stage positions become separate images, no time increment is derived from the member files".into(),
213                "Nikon NIS-Elements TIFF exports: files are grouped by the `xy`/`c` tokens of their names (validated on one public export; `t`/`z` tokens inferred); the LV and XML metadata blocks (objective, channel names, text information) are not decoded; the pixel size tag's meaning is inferred".into(),
214                "Palette (indexed-colour) pages return the stored indices; photometric WhiteIsZero pages return stored values (not inverted)".into(),
215                "JPEG: YCbCr stored as separate sample planes (PlanarConfiguration 2, e.g. Bio-Formats 8.x from planar input) and three-component streams in grey/palette/CMYK pages are refused (exit 6) rather than decoded to wrong colours; chroma upsampling differs from libjpeg-turbo by up to 3 counts".into(),
216            ],
217        }
218    }
219
220    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
221        if looks_like_tiff(head) {
222            return Some(Detection {
223                format_id: FORMAT_ID,
224                confidence: DetectConfidence::Definite,
225                note: None,
226            });
227        }
228        if has_extension(path, &["nd"]) && looks_like_nd(head) {
229            return Some(Detection {
230                format_id: FORMAT_ID,
231                confidence: DetectConfidence::Definite,
232                note: Some(
233                    "MetaMorph .nd series file (the TIFF/STK files it names are read as one data set)"
234                        .into(),
235                ),
236            });
237        }
238        if ndpis::looks_like_ndpis(head) {
239            return Some(Detection {
240                format_id: FORMAT_ID,
241                confidence: DetectConfidence::Definite,
242                note: Some(
243                    "Hamamatsu NDPI set (the NDPI files it lists are read as the channels of one image)"
244                        .into(),
245                ),
246            });
247        }
248        if (is_companion_path(path) || has_extension(path, &["ome", "xml"]))
249            && looks_like_ome_xml(head)
250        {
251            return Some(Detection {
252                format_id: FORMAT_ID,
253                confidence: DetectConfidence::Definite,
254                note: Some("OME-XML companion file of a multi-file OME-TIFF set".into()),
255            });
256        }
257        None
258    }
259
260    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
261        self.open_input(&Input::local(path))
262    }
263
264    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
265        if is_ndpis(input.fs(), input.path()) {
266            return Ok(Box::new(ndpis::NdpisDataset::open(input)?));
267        }
268        Ok(Box::new(TiffDataset::open(input)?))
269    }
270
271    fn reads_any_source(&self) -> bool {
272        true
273    }
274}