Skip to main content

openreadout_dcimg/
lib.rs

1//! Clean-room reader for Hamamatsu DCIMG camera streams (ORCA-Flash, ORCA-Fusion).
2//!
3//! A DCIMG file is one camera stream: a file header, a session header with the frame geometry,
4//! the frames, and each frame's camera counter and time stamp — in tables after the last frame
5//! (format version 7) or in a trailer after every frame (version 0x1000000). Frames are exposed
6//! as the time points of one image. Some cameras overwrite the first pixels of one sensor row
7//! in every frame and store their real values separately; the reader puts them back.
8//!
9//! Derived from hex dumps of corpus files and the documentation of the `dcimg` Python package
10//! (MIT, Giacomo Mazzamuto); Bio-Formats is run only as a black-box oracle. Layout and
11//! vocabulary: `docs/formats/dcimg.md`. Provenance: `docs/provenance/dcimg.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_dcimg::DcimgReader;
23//!
24//! let format = DcimgReader.descriptor();
25//! assert_eq!(format.id, openreadout_dcimg::FORMAT_ID);
26//! println!("{} ({}): .{}", format.name, format.family, format.extensions.join(", ."));
27//! ```
28//!
29//! Reading a file:
30//!
31//! ```no_run
32//! use std::path::Path;
33//!
34//! use openreadout_core::{FormatReader, PlaneIndex};
35//! use openreadout_dcimg::DcimgReader;
36//!
37//! let mut dataset = DcimgReader.open(Path::new("stream.dcimg"))?;
38//! let info = dataset.info()?; // headers only
39//! let image = &info.images[0];
40//! println!("{} x {} px, {} frames", image.size_x, image.size_y, image.size_t);
41//! // Frames are time points: read the third one.
42//! let plane = dataset.read_plane(0, PlaneIndex { c: 0, z: 0, t: 2 })?;
43//! assert_eq!(plane.data.len(), plane.expected_len());
44//! // Camera frame counters and time stamps, one record per frame.
45//! let (total, records) = dataset.frames(0, Some(10))?;
46//! println!("{total} frames; first: {}", records[0]);
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 dataset;
65#[doc(hidden)]
66pub mod layout;
67
68use std::path::Path;
69
70use openreadout_core::Result;
71use openreadout_core::model::{DetectConfidence, FormatDescriptor};
72use openreadout_core::reader::{Dataset, Detection, FormatReader};
73
74#[doc(hidden)]
75pub use dataset::DcimgDataset;
76#[doc(hidden)]
77pub use layout::{
78    CameraText, DCIMG_MAGIC, DcimgLayout, FrameLayout, FrameStamp, Problem, StoredPixels,
79    VERSION_FRAMED, VERSION_PACKED, looks_like_dcimg,
80};
81
82/// Format id used on the command line and in JSON.
83pub const FORMAT_ID: &str = "dcimg";
84
85/// The DCIMG reader.
86#[derive(Debug, Default, Clone, Copy)]
87pub struct DcimgReader;
88
89impl FormatReader for DcimgReader {
90    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
91        Some(&assurance::DCIMG)
92    }
93
94    fn descriptor(&self) -> FormatDescriptor {
95        FormatDescriptor {
96            id: FORMAT_ID.into(),
97            name: "Hamamatsu DCIMG".into(),
98            vendor: "Hamamatsu Photonics".into(),
99            extensions: vec!["dcimg".into()],
100            family: "microscopy".into(),
101            can_read: true,
102            can_write: false,
103            confidence: assurance::DCIMG.confidence,
104            known_gaps: vec![
105                "Derived without a specification from 15 corpus files (versions 7 and 0x1000000; ORCA-Flash4.0 and ORCA-Fusion; 16-bit); 8-bit frames are inferred".into(),
106                "Each file is one image: Bio-Formats groups sibling files named `<stem>_NNN_NNN.dcimg` into a Z stack, this reader does not (nothing in the file says the siblings belong together)".into(),
107                "Planes are returned in stored row order; Bio-Formats returns them bottom row first".into(),
108                "Only the first session of a file is read (no corpus file has more than one)".into(),
109                "No physical pixel size: the file records none".into(),
110            ],
111        }
112    }
113
114    fn sniff(&self, head: &[u8], _path: &Path) -> Option<Detection> {
115        looks_like_dcimg(head).then_some(Detection {
116            format_id: FORMAT_ID,
117            confidence: DetectConfidence::Definite,
118            note: None,
119        })
120    }
121
122    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
123        Ok(Box::new(DcimgDataset::open(path)?))
124    }
125
126    fn open_input(&self, input: &openreadout_core::source::Input) -> Result<Box<dyn Dataset>> {
127        Ok(Box::new(DcimgDataset::open_input(input)?))
128    }
129
130    fn reads_any_source(&self) -> bool {
131        true
132    }
133}