Skip to main content

openreadout_spectro/
lib.rs

1//! Clean-room readers for optical and vibrational spectroscopy files.
2//!
3//! - **Bruker OPUS** (`bruker-opus`, `.0`, `.1`, … numbered files): FT-IR/NIR/Raman spectra
4//!   (absorbance, transmittance, reflectance, single-channel sample and reference spectra,
5//!   interferograms, phases, 3D series) with the instrument, optics, acquisition and Fourier
6//!   transform parameters. Notes: `docs/formats/bruker-opus.md`.
7//! - **Thermo Fisher OMNIC** (`thermo-omnic`, `.spa` single spectra and `.spg` groups): spectra
8//!   with their acquisition header, title, timestamp and history. Notes:
9//!   `docs/formats/thermo-omnic.md`.
10//! - **Renishaw WiRE** (`renishaw-wdf`, `.wdf`): Raman spectra, line scans, depth and time
11//!   series and maps with their stage coordinates, laser wavelength, the property sets
12//!   (grating, exposure, objective, laser power) and the white-light image. Notes:
13//!   `docs/formats/renishaw-wdf.md`.
14//! - **PerkinElmer** (`perkinelmer-sp`, `.sp`): IR and UV-Vis spectra with instrument text.
15//!   Notes: `docs/formats/perkinelmer-sp.md`.
16//! - **JASCO Spectra Manager** (`jasco-jws`, `.jws`, `.jrs`): FT-IR, Raman, UV-Vis, circular
17//!   dichroism (CD, HT voltage, absorbance channels) and fluorescence spectra, from both the
18//!   compound-file and the flat container, with the instrument, sample and FT-IR acquisition
19//!   parameters. Notes: `docs/formats/jasco-jws.md`.
20//! - **Galactic / Thermo GRAMS SPC** (`galactic-spc`, `.spc`): single spectra and multifiles
21//!   (spectrum series and maps exported by GRAMS, OMNIC, WiRE, Spectragryph and others), float
22//!   or fixed-point values, with the log block's instrument settings. Notes:
23//!   `docs/formats/galactic-spc.md`.
24//! - **Shimadzu UVProbe** (`shimadzu-uvprobe`, `.spc` compound files from UV-Vis and UV-Vis-NIR
25//!   spectrophotometers): one trace per data set. Notes: `docs/formats/shimadzu-uvprobe.md`.
26//! - **Agilent (Varian) Cary UV-Vis** (`agilent-cary`, `.dsw` Scan, `.bsw` batch Scan, `.bsk`
27//!   Scanning Kinetics): absorbance spectra and baselines with their wavelengths, the
28//!   instrument, application, parameter list, method log and collection times. Notes:
29//!   `docs/formats/agilent-cary.md`.
30//! - **PerkinElmer Spotlight images** (`perkinelmer-fsm`, `.fsm`): FT-IR images as a spectrum
31//!   trace (one sweep per pixel) with stage positions and a map, with the instrument record.
32//!   Notes: `docs/formats/perkinelmer-fsm.md`.
33//! - **Agilent FT-IR imaging** (`agilent-fpa`, `.dat`/`.seq` with a `.bsp` header, mosaics
34//!   `.dms`/`.dmd`/`.drd` with a `.dmt` header): focal-plane-array hyperspectral images from
35//!   Cary 600 series microscopes (Resolutions Pro), as a spectrum trace (one sweep per pixel)
36//!   and a map with one channel per wavenumber, or interferograms on their optical-path-difference
37//!   axis, with the acquisition settings. Notes: `docs/formats/agilent-fpa.md`.
38//! - **WITec Project / WITec Data** (`witec-project`, `.wip`, `.wid`): confocal Raman
39//!   microscopy projects — single spectra, line scans, depth profiles and Raman maps with their
40//!   grating calibration (Raman shift, wavelength or energy axis), the images derived from them
41//!   (band sums, masks, peak positions), video images and each measurement's information text
42//!   (excitation, grating, integration time, objective). Notes: `docs/formats/witec-project.md`.
43//!
44//! Every spectrum set is a core trace: one sweep per spectrum, the y values as channel 0, and
45//! the x axis in `extra.axis` (`{quantity, unit, first, last, step, size}`: `wavenumber` in
46//! `1/cm`, `raman_shift` in `1/cm`, `wavelength` in `nm` or `µm`, `points`). An axis that is not
47//! evenly spaced (a grating spectrometer's calibration) is `{irregular: true, channel: 0}` and
48//! the trace then has two channels: the x values and the y values. Spectra on a map grid are
49//! also one image with one channel per spectral point, so `preview --channel N` draws the map
50//! at band N.
51//!
52//! # Example
53//!
54//! ```
55//! use openreadout_core::FormatReader;
56//! use openreadout_spectro::OpusReader;
57//!
58//! let format = OpusReader.descriptor();
59//! assert_eq!(format.id, openreadout_spectro::OPUS_FORMAT_ID);
60//! println!("{} ({})", format.name, format.family);
61//! ```
62//!
63//! Reading a file:
64//!
65//! ```no_run
66//! use std::path::Path;
67//!
68//! use openreadout_core::FormatReader;
69//! use openreadout_spectro::OpusReader;
70//!
71//! let mut dataset = OpusReader.open(Path::new("sample.0"))?;
72//! let info = dataset.info()?; // headers only
73//! let t = &info.traces[0];
74//! println!("{}: {} points, axis {}", t.name.as_deref().unwrap_or(""), t.sample_count, t.extra["axis"]);
75//! let spectrum = dataset.read_trace(0, 0, 0, u64::MAX)?;
76//! println!("first value {:?}", spectrum.channels[0].first());
77//! # Ok::<(), openreadout_core::Error>(())
78//! ```
79//!
80//! # API stability
81//!
82//! The supported API is what this page documents: the readers, their format ids and
83//! [`SpectroDataset`] (returned boxed by `open`).
84#![forbid(unsafe_code)]
85#![warn(missing_docs)]
86#![allow(clippy::many_single_char_names)] // byte-layout code: b (bytes), n, w, x, y as in the notes
87
88mod agilent;
89mod assurance;
90mod cary;
91mod common;
92mod fsm;
93mod jasco;
94mod omnic;
95mod omnic_map;
96mod omnic_srs;
97mod opus;
98mod pesp;
99mod pesp_ascii;
100mod spc;
101mod uvprobe;
102mod wdf;
103mod witec;
104
105use std::path::Path;
106
107use openreadout_core::Result;
108use openreadout_core::model::{DetectConfidence, FormatDescriptor};
109use openreadout_core::reader::{Dataset, Detection, FormatReader, has_extension};
110use openreadout_core::source::Input;
111
112pub use common::SpectroDataset;
113
114/// Format id of Bruker OPUS files.
115pub const OPUS_FORMAT_ID: &str = "bruker-opus";
116/// Format id of Thermo Fisher OMNIC `.spa`/`.spg` files.
117pub const OMNIC_FORMAT_ID: &str = "thermo-omnic";
118/// Format id of Renishaw WiRE `.wdf` files.
119pub const WDF_FORMAT_ID: &str = "renishaw-wdf";
120/// Format id of PerkinElmer `.sp` files.
121pub const PESP_FORMAT_ID: &str = "perkinelmer-sp";
122/// Format id of JASCO Spectra Manager `.jws`/`.jrs` files.
123pub const JWS_FORMAT_ID: &str = "jasco-jws";
124/// Format id of Galactic / Thermo GRAMS `.spc` files.
125pub const SPC_FORMAT_ID: &str = "galactic-spc";
126/// Format id of Agilent (Varian) Cary UV-Vis `.dsw`/`.bsw`/`.bsk` files.
127pub const CARY_FORMAT_ID: &str = "agilent-cary";
128/// Format id of PerkinElmer Spotlight `.fsm` images.
129pub const FSM_FORMAT_ID: &str = "perkinelmer-fsm";
130/// Format id of Agilent FT-IR imaging (focal-plane-array) files.
131pub const AGILENT_FPA_FORMAT_ID: &str = "agilent-fpa";
132/// Format id of WITec Project `.wip` and WITec Data `.wid` files.
133pub const WITEC_FORMAT_ID: &str = "witec-project";
134/// Format id of Shimadzu UVProbe `.spc` files.
135pub const UVPROBE_FORMAT_ID: &str = "shimadzu-uvprobe";
136
137/// The Bruker OPUS reader.
138#[derive(Debug, Default, Clone, Copy)]
139pub struct OpusReader;
140
141impl FormatReader for OpusReader {
142    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
143        Some(&assurance::BRUKER_OPUS)
144    }
145
146    fn descriptor(&self) -> FormatDescriptor {
147        FormatDescriptor {
148            id: OPUS_FORMAT_ID.into(),
149            name: "Bruker OPUS".into(),
150            vendor: "Bruker".into(),
151            extensions: vec!["0".into(), "1".into(), "2".into()],
152            family: "spectroscopy".into(),
153            can_read: true,
154            can_write: false,
155            confidence: assurance::BRUKER_OPUS.confidence,
156            known_gaps: vec![
157                "Any numbered extension (.0, .1, … .999) is an OPUS file when it starts with 0A 0A FE FE; the extensions listed are the common ones".into(),
158                "3D series blocks (rapid scan, time-resolved) follow brukeropus's layout; no public series file was available to validate them".into(),
159                "Report blocks (quant and search results), embedded bitmaps and blocks of unknown type are listed by `info --view structure`, not decoded".into(),
160                "Data blocks without a data-status block are listed, not decoded".into(),
161            ],
162        }
163    }
164
165    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
166        if head.starts_with(&opus::OPUS_MAGIC) {
167            return Some(Detection {
168                format_id: OPUS_FORMAT_ID,
169                confidence: DetectConfidence::Definite,
170                note: None,
171            });
172        }
173        let numbered = path.extension().and_then(|e| e.to_str()).is_some_and(|e| {
174            !e.is_empty() && e.len() <= 4 && e.bytes().all(|c| c.is_ascii_digit())
175        });
176        (numbered && !head.is_empty() && head.len() < 4).then_some(Detection {
177            format_id: OPUS_FORMAT_ID,
178            confidence: DetectConfidence::ExtensionOnly,
179            note: Some("numbered extension but the file is too short to be OPUS".into()),
180        })
181    }
182
183    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
184        self.open_input(&Input::local(path))
185    }
186
187    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
188        let (f, len) = common::open_source(input)?;
189        let parsed = opus::parse(&f, input.path(), len)?;
190        Ok(Box::new(SpectroDataset::new(
191            self.descriptor(),
192            input,
193            f,
194            len,
195            parsed,
196        )))
197    }
198
199    fn reads_any_source(&self) -> bool {
200        true
201    }
202}
203
204/// The Thermo Fisher OMNIC reader (`.spa`, `.spg`).
205#[derive(Debug, Default, Clone, Copy)]
206pub struct OmnicReader;
207
208impl FormatReader for OmnicReader {
209    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
210        Some(&assurance::THERMO_OMNIC)
211    }
212
213    fn descriptor(&self) -> FormatDescriptor {
214        FormatDescriptor {
215            id: OMNIC_FORMAT_ID.into(),
216            name: "Thermo Fisher OMNIC".into(),
217            vendor: "Thermo Fisher Scientific (Nicolet)".into(),
218            extensions: vec!["spa".into(), "spg".into(), "srs".into(), "map".into()],
219            family: "spectroscopy".into(),
220            can_read: true,
221            can_write: false,
222            confidence: assurance::THERMO_OMNIC.confidence,
223            known_gaps: vec![
224                "Series files (.srs: rapid scan, high-speed, GC-IR, TGA-IR) are read from their key table: the series spectra, their times and the backgrounds; the per-series profiles (Gram-Schmidt, chemigrams) and processing records are listed, not decoded; no licensed .srs file was available, so the series layout rests on held test files".into(),
225                "Map files (.map) are read as their spectra, the stage position of each (table `positions`) and the video image; there is no independent reader to check them against, and the value OMNIC stores with each map spectrum is not decoded".into(),
226                "Resolution and the instrument serial number come from the processing-history text (English or French OMNIC); files without that text have neither".into(),
227                "y-unit codes other than absorbance, transmittance, reflectance, log(1/R), single beam, Kubelka-Munk, volts, photoacoustic and Raman intensity are reported as `intensity`".into(),
228            ],
229        }
230    }
231
232    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
233        if head.starts_with(omnic::OMNIC_MAGIC) || head.starts_with(omnic::OMNIC_SERIES_MAGIC) {
234            return Some(Detection {
235                format_id: OMNIC_FORMAT_ID,
236                confidence: DetectConfidence::Definite,
237                note: None,
238            });
239        }
240        // A longer file without the signature is another kind of file (exit 3), not a damaged
241        // OMNIC file.
242        (has_extension(path, &["spa", "spg", "srs", "map"])
243            && head.len() < omnic::OMNIC_MAGIC.len())
244        .then_some(Detection {
245            format_id: OMNIC_FORMAT_ID,
246            confidence: DetectConfidence::ExtensionOnly,
247            note: Some("OMNIC extension but the file is too short to be OMNIC".into()),
248        })
249    }
250
251    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
252        self.open_input(&Input::local(path))
253    }
254
255    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
256        let (f, len) = common::open_source(input)?;
257        let parsed = omnic::parse(&f, input.path(), len)?;
258        Ok(Box::new(SpectroDataset::new(
259            self.descriptor(),
260            input,
261            f,
262            len,
263            parsed,
264        )))
265    }
266
267    fn reads_any_source(&self) -> bool {
268        true
269    }
270}
271
272/// The Renishaw WiRE reader (`.wdf`).
273#[derive(Debug, Default, Clone, Copy)]
274pub struct WdfReader;
275
276impl FormatReader for WdfReader {
277    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
278        Some(&assurance::RENISHAW_WDF)
279    }
280
281    fn descriptor(&self) -> FormatDescriptor {
282        FormatDescriptor {
283            id: WDF_FORMAT_ID.into(),
284            name: "Renishaw WiRE".into(),
285            vendor: "Renishaw".into(),
286            extensions: vec!["wdf".into()],
287            family: "spectroscopy".into(),
288            can_read: true,
289            can_write: false,
290            confidence: assurance::RENISHAW_WDF.confidence,
291            known_gaps: vec![
292                "x-list and y-unit codes are named only where the corpus confirms them (Raman shift, counts); other codes are reported as numbers with an `x` axis".into(),
293                "Property sets are decoded to a tree; keys WiRE does not name in the file appear as `#<number>` and only those whose meaning the corpus shows are normalized (objective, laser name, serial numbers)".into(),
294                "Map pixels are placed from the stage coordinates on the WMAP grid; maps without coordinates fall back to storage order".into(),
295                "Line scans and depth or time series are traces with a positions table, not images".into(),
296                "Pre-WiRE-3 files, processed data blocks (baseline, cosmic-ray removal results) and embedded Z-stacks are not decoded".into(),
297            ],
298        }
299    }
300
301    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
302        if head.starts_with(wdf::WDF_MAGIC) {
303            return Some(Detection {
304                format_id: WDF_FORMAT_ID,
305                confidence: DetectConfidence::Definite,
306                note: None,
307            });
308        }
309        (has_extension(path, &["wdf"]) && head.len() < wdf::WDF_MAGIC.len()).then_some(Detection {
310            format_id: WDF_FORMAT_ID,
311            confidence: DetectConfidence::ExtensionOnly,
312            note: Some("WiRE extension but the file does not start with WDF1".into()),
313        })
314    }
315
316    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
317        self.open_input(&Input::local(path))
318    }
319
320    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
321        let (f, len) = common::open_source(input)?;
322        let parsed = wdf::parse(&f, input.path(), len)?;
323        Ok(Box::new(SpectroDataset::new(
324            self.descriptor(),
325            input,
326            f,
327            len,
328            parsed,
329        )))
330    }
331
332    fn reads_any_source(&self) -> bool {
333        true
334    }
335}
336
337/// The PerkinElmer `.sp` reader.
338#[derive(Debug, Default, Clone, Copy)]
339pub struct PeSpReader;
340
341impl FormatReader for PeSpReader {
342    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
343        Some(&assurance::PERKINELMER_SP)
344    }
345
346    fn descriptor(&self) -> FormatDescriptor {
347        FormatDescriptor {
348            id: PESP_FORMAT_ID.into(),
349            name: "PerkinElmer Spectrum (.sp)".into(),
350            vendor: "PerkinElmer".into(),
351            extensions: vec!["sp".into()],
352            family: "spectroscopy".into(),
353            can_read: true,
354            can_write: false,
355            confidence: assurance::PERKINELMER_SP.confidence,
356            known_gaps: vec![
357                "One spectrum per file (2D constant-interval data sets); Spotlight image files (.fsm) are read by the perkinelmer-fsm reader".into(),
358                "Instrument settings are named from their values in the corpus (scans, resolution, detector, source, beamsplitter, apodization, laser wavenumber); other settings are in the vendor tree by member id".into(),
359                "UV-Vis (.sp from Lambda instruments, x in nm) follows the same layout by inference; no public UV-Vis .sp file was available".into(),
360                "Text .sp files (`PE … ASCII PEDS`, e.g. from an LS55): only the x and y pairs and the technique code are read; the other header lines are kept unnamed in the vendor tree".into(),
361            ],
362        }
363    }
364
365    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
366        if head.starts_with(pesp::PESP_MAGIC) && !fsm::is_image_description(head) {
367            return Some(Detection {
368                format_id: PESP_FORMAT_ID,
369                confidence: DetectConfidence::Definite,
370                note: None,
371            });
372        }
373        if pesp_ascii::is_ascii_sp(head) {
374            return Some(Detection {
375                format_id: PESP_FORMAT_ID,
376                confidence: DetectConfidence::Definite,
377                note: Some("PerkinElmer .sp saved as text (PEDS)".into()),
378            });
379        }
380        (has_extension(path, &["sp"]) && (head.len() < 4 || head.starts_with(b"PE"))).then_some(
381            Detection {
382                format_id: PESP_FORMAT_ID,
383                confidence: DetectConfidence::ExtensionOnly,
384                note: Some("PerkinElmer extension but the file does not start with PEPE".into()),
385            },
386        )
387    }
388
389    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
390        self.open_input(&Input::local(path))
391    }
392
393    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
394        let (f, len) = common::open_source(input)?;
395        let head = common::read_at(&f, input.path(), 0, len.min(256), len)?;
396        if !head.starts_with(pesp::PESP_MAGIC) && pesp_ascii::is_ascii_sp(&head) {
397            let opened = pesp_ascii::parse(&f, input.path(), len)?;
398            let n = opened.values.len() as u64;
399            let src = openreadout_core::source::MemSource::new("#DATA", opened.values);
400            return Ok(Box::new(
401                SpectroDataset::new(self.descriptor(), input, f, len, opened.parsed)
402                    .with_values_source(
403                        openreadout_core::source::SourceFile::new(std::sync::Arc::new(src)),
404                        n,
405                    ),
406            ));
407        }
408        let parsed = pesp::parse(&f, input.path(), len)?;
409        Ok(Box::new(SpectroDataset::new(
410            self.descriptor(),
411            input,
412            f,
413            len,
414            parsed,
415        )))
416    }
417
418    fn reads_any_source(&self) -> bool {
419        true
420    }
421}
422
423/// The JASCO Spectra Manager reader (`.jws`, `.jrs`).
424#[derive(Debug, Default, Clone, Copy)]
425pub struct JwsReader;
426
427impl FormatReader for JwsReader {
428    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
429        Some(&assurance::JASCO_JWS)
430    }
431
432    fn descriptor(&self) -> FormatDescriptor {
433        FormatDescriptor {
434            id: JWS_FORMAT_ID.into(),
435            name: "JASCO Spectra Manager (.jws)".into(),
436            vendor: "JASCO".into(),
437            extensions: vec!["jws".into(), "jrs".into()],
438            family: "spectroscopy".into(),
439            can_read: true,
440            can_write: false,
441            confidence: assurance::JASCO_JWS.confidence,
442            known_gaps: vec![
443                "Validated on FT/IR-4600/4700, NRS-5100 Raman, V-630/V-730 UV-Vis, J-1500 circular dichroism (1-3 channels) and FP-8300 fluorescence files; interval/kinetics files (`.jwb`) and channel or axis codes not seen are refused or returned unnamed with a finding".into(),
444                "Time-course files carry their x axis as time without a unit (the unit is not in a field that has been validated)".into(),
445                "Acquisition parameters are named for FT-IR (module 9) only; the other instruments' parameter records are kept raw in the vendor tree".into(),
446                "Text fields of flat files are decoded as UTF-8 or Latin-1; Japanese (Shift-JIS) titles may be garbled".into(),
447            ],
448        }
449    }
450
451    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
452        if head.starts_with(jasco::FLAT_MAGIC) {
453            return Some(Detection {
454                format_id: JWS_FORMAT_ID,
455                confidence: DetectConfidence::Definite,
456                note: None,
457            });
458        }
459        (has_extension(path, &["jws", "jrs"])
460            && head.starts_with(&openreadout_core::cfb::CFB_MAGIC))
461        .then_some(Detection {
462            format_id: JWS_FORMAT_ID,
463            confidence: DetectConfidence::Likely,
464            note: None,
465        })
466    }
467
468    fn sniff_input(&self, head: &[u8], input: &Input) -> Option<Detection> {
469        if head.starts_with(&openreadout_core::cfb::CFB_MAGIC) && jasco::is_compound_jws(input) {
470            return Some(Detection {
471                format_id: JWS_FORMAT_ID,
472                confidence: DetectConfidence::Definite,
473                note: None,
474            });
475        }
476        self.sniff(head, input.path())
477    }
478
479    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
480        self.open_input(&Input::local(path))
481    }
482
483    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
484        let (f, len) = common::open_source(input)?;
485        let opened = jasco::parse(&f, input.path(), len)?;
486        let ds = SpectroDataset::new(self.descriptor(), input, f, len, opened.parsed);
487        Ok(Box::new(match opened.values {
488            Some(v) => {
489                let n = v.len() as u64;
490                let src = openreadout_core::source::MemSource::new("Y-Data", v);
491                ds.with_values_source(
492                    openreadout_core::source::SourceFile::new(std::sync::Arc::new(src)),
493                    n,
494                )
495            }
496            None => ds,
497        }))
498    }
499
500    fn reads_any_source(&self) -> bool {
501        true
502    }
503}
504
505/// The Galactic / Thermo GRAMS `.spc` reader.
506#[derive(Debug, Default, Clone, Copy)]
507pub struct SpcReader;
508
509impl FormatReader for SpcReader {
510    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
511        Some(&assurance::GALACTIC_SPC)
512    }
513
514    fn descriptor(&self) -> FormatDescriptor {
515        FormatDescriptor {
516            id: SPC_FORMAT_ID.into(),
517            name: "Galactic / Thermo GRAMS SPC (.spc)".into(),
518            vendor: "Thermo Fisher Scientific (Galactic Industries) GRAMS".into(),
519            extensions: vec!["spc".into()],
520            family: "spectroscopy".into(),
521            can_read: true,
522            can_write: false,
523            confidence: assurance::GALACTIC_SPC.confidence,
524            known_gaps: vec![
525                "Big-endian (0x4C) files, per-subfile x arrays (TXYXYS, mass spectra) and old-format (0x4D) multifiles are refused".into(),
526                "16-bit fixed-point values follow the documented rule but no development file has them".into(),
527                "Multifile maps are returned as spectrum series with a subfile table (z, W); the map grid is not rebuilt".into(),
528                "Other programs' .spc files (Bruker EPR, Becker & Hickl, EDAX) are not Galactic SPC and are not read by this reader; Shimadzu UVProbe .spc files are read by shimadzu-uvprobe".into(),
529            ],
530        }
531    }
532
533    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
534        // The SPC header has no signature (only a version byte), so only `.spc` files are
535        // claimed: other files whose bytes happen to fit (zips, plate-reader exports) are not.
536        if !has_extension(path, &["spc"]) {
537            return None;
538        }
539        if spc::looks_like_spc(head) {
540            return Some(Detection {
541                format_id: SPC_FORMAT_ID,
542                confidence: DetectConfidence::Definite,
543                note: None,
544            });
545        }
546        (has_extension(path, &["spc"]) && head.get(1) == Some(&0x4C)).then_some(Detection {
547            format_id: SPC_FORMAT_ID,
548            confidence: DetectConfidence::Likely,
549            note: Some("big-endian Galactic SPC (refused on open)".into()),
550        })
551    }
552
553    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
554        self.open_input(&Input::local(path))
555    }
556
557    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
558        let (f, len) = common::open_source(input)?;
559        let parsed = spc::parse(&f, input.path(), len)?;
560        Ok(Box::new(SpectroDataset::new(
561            self.descriptor(),
562            input,
563            f,
564            len,
565            parsed,
566        )))
567    }
568
569    fn reads_any_source(&self) -> bool {
570        true
571    }
572}
573
574/// The WITec Project / WITec Data reader (`.wip`, `.wid`).
575#[derive(Debug, Default, Clone, Copy)]
576pub struct WitecReader;
577
578impl FormatReader for WitecReader {
579    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
580        Some(&assurance::WITEC_PROJECT)
581    }
582
583    fn descriptor(&self) -> FormatDescriptor {
584        FormatDescriptor {
585            id: WITEC_FORMAT_ID.into(),
586            name: "WITec Project / WITec Data".into(),
587            vendor: "WITec (Oxford Instruments)".into(),
588            extensions: vec!["wip".into(), "wid".into()],
589            family: "spectroscopy".into(),
590            can_read: true,
591            can_write: false,
592            confidence: assurance::WITEC_PROJECT.confidence,
593            known_gaps: vec![
594                "Format versions 0-7 (WITec Control 1.6 to WITec Suite SIX); spectral calibrations of the grating and polynomial kinds are validated, linear and lookup-table x calibrations follow the published format description without a development file".into(),
595                "Filter, cursor, colour-profile and mask-definition records (analysis settings) are listed, not decoded; the images they produced are read".into(),
596                "Acquisition settings come from each measurement's information text (English WITec software); the version-7 Suite SIX parameter records are kept in the vendor tree only".into(),
597                "The acquisition time is local time (the file holds no time zone)".into(),
598            ],
599        }
600    }
601
602    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
603        if witec::looks_like_witec(head) {
604            return Some(Detection {
605                format_id: WITEC_FORMAT_ID,
606                confidence: DetectConfidence::Definite,
607                note: None,
608            });
609        }
610        (has_extension(path, &["wip", "wid"]) && (head.len() < 8 || head.starts_with(b"WIT_")))
611            .then_some(Detection {
612                format_id: WITEC_FORMAT_ID,
613                confidence: DetectConfidence::ExtensionOnly,
614                note: Some("WITec extension but the file does not start with a WIT_ magic".into()),
615            })
616    }
617
618    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
619        self.open_input(&Input::local(path))
620    }
621
622    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
623        let (f, len) = common::open_source(input)?;
624        let parsed = witec::parse(&f, input.path(), len)?;
625        Ok(Box::new(SpectroDataset::new(
626            self.descriptor(),
627            input,
628            f,
629            len,
630            parsed,
631        )))
632    }
633
634    fn reads_any_source(&self) -> bool {
635        true
636    }
637}
638
639/// The Agilent FT-IR imaging reader (`.dat`, `.seq`, `.dms`, `.dmd`, `.drd` data files; `.bsp`,
640/// `.dmt` headers).
641#[derive(Debug, Default, Clone, Copy)]
642pub struct AgilentFpaReader;
643
644impl FormatReader for AgilentFpaReader {
645    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
646        Some(&assurance::AGILENT_FPA)
647    }
648
649    fn descriptor(&self) -> FormatDescriptor {
650        FormatDescriptor {
651            id: AGILENT_FPA_FORMAT_ID.into(),
652            name: "Agilent FT-IR imaging (Resolutions Pro)".into(),
653            vendor: "Agilent".into(),
654            extensions: vec![
655                "dat".into(),
656                "seq".into(),
657                "dms".into(),
658                "dmd".into(),
659                "drd".into(),
660                "bsp".into(),
661                "dmt".into(),
662            ],
663            family: "spectroscopy".into(),
664            can_read: true,
665            can_write: false,
666            confidence: assurance::AGILENT_FPA.confidence,
667            known_gaps: vec![
668                "A mosaic is read from its whole-image .dms file (or one tile at a time); tiles are not assembled when the .dms is missing".into(),
669                "Rows run top to bottom: the files store them bottom to top (inferred from how a mosaic's tiles are stacked in its .dms)".into(),
670                "The pixel size is the detector pixel size times the aggregation, read from the header; stage positions are not in the files".into(),
671                "Settings are read from the header's text settings (English Resolutions Pro); the selected-pixel spectrum stored in the header is not returned".into(),
672            ],
673        }
674    }
675
676    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
677        if has_extension(path, &agilent::DATA_EXTENSIONS) && agilent::looks_like_data(head) {
678            return Some(Detection {
679                format_id: AGILENT_FPA_FORMAT_ID,
680                confidence: DetectConfidence::Definite,
681                note: None,
682            });
683        }
684        None
685    }
686
687    fn sniff_input(&self, head: &[u8], input: &Input) -> Option<Detection> {
688        if has_extension(input.path(), &agilent::HEADER_EXTENSIONS)
689            && agilent::is_header(head, input)
690        {
691            return Some(Detection {
692                format_id: AGILENT_FPA_FORMAT_ID,
693                confidence: DetectConfidence::Definite,
694                note: None,
695            });
696        }
697        self.sniff(head, input.path())
698    }
699
700    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
701        self.open_input(&Input::local(path))
702    }
703
704    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
705        let data = agilent::resolve(input)?;
706        let (f, len) = common::open_source(&data)?;
707        let parsed = agilent::parse(&f, &data, len)?;
708        Ok(Box::new(SpectroDataset::new(
709            self.descriptor(),
710            &data,
711            f,
712            len,
713            parsed,
714        )))
715    }
716
717    fn reads_any_source(&self) -> bool {
718        true
719    }
720}
721
722/// The PerkinElmer Spotlight image reader (`.fsm`).
723#[derive(Debug, Default, Clone, Copy)]
724pub struct FsmReader;
725
726impl FormatReader for FsmReader {
727    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
728        Some(&assurance::PERKINELMER_FSM)
729    }
730
731    fn descriptor(&self) -> FormatDescriptor {
732        FormatDescriptor {
733            id: FSM_FORMAT_ID.into(),
734            name: "PerkinElmer Spotlight image (.fsm)".into(),
735            vendor: "PerkinElmer".into(),
736            extensions: vec!["fsm".into()],
737            family: "spectroscopy".into(),
738            can_read: true,
739            can_write: false,
740            confidence: assurance::PERKINELMER_FSM.confidence,
741            known_gaps: vec![
742                "Image rows are in acquisition order (stage y increasing by one step per row); which way up Spectrum IMAGE draws them is not in the file".into(),
743                "Only the 4-D constant-interval layout (one float32 spectrum per pixel block) has been seen".into(),
744                "Instrument settings are named as in the .sp reader (the same member ids); other settings are in the vendor tree".into(),
745            ],
746        }
747    }
748
749    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
750        if head.starts_with(pesp::PESP_MAGIC) && fsm::is_image_description(head) {
751            return Some(Detection {
752                format_id: FSM_FORMAT_ID,
753                confidence: DetectConfidence::Definite,
754                note: None,
755            });
756        }
757        (has_extension(path, &["fsm"]) && (head.len() < 4 || head.starts_with(pesp::PESP_MAGIC)))
758            .then_some(Detection {
759            format_id: FSM_FORMAT_ID,
760            confidence: DetectConfidence::ExtensionOnly,
761            note: Some("Spotlight extension but the file does not start with PEPE and a 4D data-set description".into()),
762        })
763    }
764
765    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
766        self.open_input(&Input::local(path))
767    }
768
769    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
770        let (f, len) = common::open_source(input)?;
771        let parsed = fsm::parse(&f, input.path(), len)?;
772        Ok(Box::new(SpectroDataset::new(
773            self.descriptor(),
774            input,
775            f,
776            len,
777            parsed,
778        )))
779    }
780
781    fn reads_any_source(&self) -> bool {
782        true
783    }
784}
785
786/// The Agilent (Varian) Cary UV-Vis reader (`.dsw`, `.bsw`, `.bsk`).
787#[derive(Debug, Default, Clone, Copy)]
788pub struct CaryReader;
789
790impl FormatReader for CaryReader {
791    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
792        Some(&assurance::AGILENT_CARY)
793    }
794
795    fn descriptor(&self) -> FormatDescriptor {
796        FormatDescriptor {
797            id: CARY_FORMAT_ID.into(),
798            name: "Agilent Cary UV-Vis (.dsw, .bsw, .bsk)".into(),
799            vendor: "Agilent (Varian)".into(),
800            extensions: vec!["dsw".into(), "bsw".into(), "bsk".into(), "csw".into()],
801            family: "spectroscopy".into(),
802            can_read: true,
803            can_write: false,
804            confidence: assurance::AGILENT_CARY.confidence,
805            known_gaps: vec![
806                "Validated against the Cary software's CSV exports on Cary 4000 Scan 3.00 files (absorbance over wavelength); Cary 60 files of Scan and Scanning Kinetics 5.0 are read the same way but have no export to check them against".into(),
807                "Only the spectrum and baseline stores are decoded; graph, report, database and baseline-info stores are listed by `info --view structure`".into(),
808                "Y modes other than absorbance and X modes other than nanometers have no corpus file: their spectra are returned with a finding".into(),
809                "Collection times are a local clock (no time zone is stored), read month/day/year as every corpus file writes them".into(),
810            ],
811        }
812    }
813
814    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
815        if head.starts_with(cary::MAGIC) {
816            return Some(Detection {
817                format_id: CARY_FORMAT_ID,
818                confidence: DetectConfidence::Definite,
819                note: None,
820            });
821        }
822        (has_extension(path, &["dsw", "bsw", "bsk", "csw"]) && head.len() < cary::MAGIC.len())
823            .then_some(Detection {
824                format_id: CARY_FORMAT_ID,
825                confidence: DetectConfidence::ExtensionOnly,
826                note: Some("Cary extension but the file is too short to hold its header".into()),
827            })
828    }
829
830    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
831        self.open_input(&Input::local(path))
832    }
833
834    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
835        let (f, len) = common::open_source(input)?;
836        let opened = cary::parse(&f, input.path(), len)?;
837        let n = opened.values.len() as u64;
838        let src = openreadout_core::source::MemSource::new("spectra", opened.values);
839        Ok(Box::new(
840            SpectroDataset::new(self.descriptor(), input, f, len, opened.parsed)
841                .with_values_source(
842                    openreadout_core::source::SourceFile::new(std::sync::Arc::new(src)),
843                    n,
844                ),
845        ))
846    }
847
848    fn reads_any_source(&self) -> bool {
849        true
850    }
851}
852
853/// The Shimadzu UVProbe `.spc` reader (compound files; Galactic SPC shares the extension).
854#[derive(Debug, Default, Clone, Copy)]
855pub struct UvProbeReader;
856
857impl FormatReader for UvProbeReader {
858    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
859        Some(&assurance::SHIMADZU_UVPROBE)
860    }
861
862    fn descriptor(&self) -> FormatDescriptor {
863        FormatDescriptor {
864            id: UVPROBE_FORMAT_ID.into(),
865            name: "Shimadzu UVProbe (.spc)".into(),
866            vendor: "Shimadzu UVProbe".into(),
867            extensions: vec!["spc".into()],
868            family: "spectroscopy".into(),
869            can_read: true,
870            can_write: false,
871            confidence: assurance::SHIMADZU_UVPROBE.confidence,
872            known_gaps: vec![
873                "Validated on UV-3600 Plus files (UVProbe 2.43 and 2.71, absorbance and reflectance scans) against the software's text exports; transmittance, photometric and kinetics files have no development file, and value codes not seen are returned unnamed".into(),
874                "Files with several spectra per data set (`.2` arrays) read the first only".into(),
875                "Text in a non-UTF-8 code page (GBK on Chinese-language PCs) is shown as Latin-1; the method pages are kept as text, not named".into(),
876            ],
877        }
878    }
879
880    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
881        (has_extension(path, &["spc"]) && head.starts_with(&openreadout_core::cfb::CFB_MAGIC))
882            .then_some(Detection {
883                format_id: UVPROBE_FORMAT_ID,
884                confidence: DetectConfidence::Likely,
885                note: Some("compound file with the .spc extension".into()),
886            })
887    }
888
889    fn sniff_input(&self, head: &[u8], input: &Input) -> Option<Detection> {
890        if head.starts_with(&openreadout_core::cfb::CFB_MAGIC) && uvprobe::is_uvprobe(input) {
891            return Some(Detection {
892                format_id: UVPROBE_FORMAT_ID,
893                confidence: DetectConfidence::Definite,
894                note: None,
895            });
896        }
897        self.sniff(head, input.path())
898    }
899
900    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
901        self.open_input(&Input::local(path))
902    }
903
904    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
905        let (f, len) = common::open_source(input)?;
906        let opened = uvprobe::parse(&f, input.path())?;
907        let n = opened.values.len() as u64;
908        let src = openreadout_core::source::MemSource::new("Y Data", opened.values);
909        Ok(Box::new(
910            SpectroDataset::new(self.descriptor(), input, f, len, opened.parsed)
911                .with_values_source(
912                    openreadout_core::source::SourceFile::new(std::sync::Arc::new(src)),
913                    n,
914                ),
915        ))
916    }
917
918    fn reads_any_source(&self) -> bool {
919        true
920    }
921}