wfdisc 0.1.1

Reader for CSS 3.0 / NNSA KB Core wfdisc seismological waveform descriptor files. Cross-validated against ObsPy.
Documentation
//! `wfdisc` — a Rust reader for **CSS 3.0** and **NNSA KB Core** *wfdisc*
//! waveform descriptor files used in seismology.
//!
//! A *wfdisc* file is a fixed-width text catalog: each line points at a
//! contiguous slice of binary samples in a separate `.w` data file. The text
//! row holds station, channel, start time, sample count, sampling rate,
//! datatype code, file path, and byte offset. This crate parses those rows
//! and decodes the binary samples they reference.
//!
//! ## Quick start
//!
//! ```no_run
//! use wfdisc::WfdiscReader;
//!
//! # fn main() -> wfdisc::Result<()> {
//! let reader = WfdiscReader::open("test_css.wfdisc")?;
//! for row in reader {
//!     let row = row?;
//!     let trace = row.read_trace_relative_to("/path/to/data/dir")?;
//!     println!(
//!         "{}.{}  {} samples @ {} Hz  ({})",
//!         trace.descriptor.sta,
//!         trace.descriptor.chan,
//!         trace.samples.len(),
//!         trace.descriptor.samprate,
//!         trace.descriptor.datatype,
//!     );
//! }
//! # Ok(())
//! # }
//! ```
//!
//! ## API mirrors `mseed` / `miniseed`
//!
//! Like the [`mseed`](https://docs.rs/mseed) and
//! [`miniseed`](https://docs.rs/miniseed) crates for miniSEED, this crate
//! exposes a streaming reader that yields owned descriptor records, plus a
//! [`Samples`] enum that mirrors miniseed's `Data` (one variant per native
//! datatype). Errors are surfaced through a single [`Error`] type and the
//! [`Result`] alias.
//!
//! ## Reference implementations
//!
//! Field widths and parsing positions follow:
//!
//! - **Pisces** ([`pisces.schema.css3`](https://github.com/LANL-Seismoacoustics/pisces))
//!   for the table schema (column widths, default values).
//! - **ObsPy** ([`obspy.io.css.core`](https://github.com/obspy/obspy/blob/master/obspy/io/css/core.py))
//!   for the literal byte offsets used to slice each line and the `DTYPE`
//!   table (datatype code → sample dtype + endianness).
//!
//! ## Schema sources — and where they disagree
//!
//! Pisces and ObsPy do not fully agree on the wfdisc schema, and this
//! crate is best understood as a **union** of the two rather than a
//! faithful port of either. Specifically:
//!
//! - **Scope.** Pisces models wfdisc as a full SQL table — all 20
//!   columns with declared SQL types and defaults (`-` for strings,
//!   `-1` for ints, `1.0` for `calib`, etc.). ObsPy parses only the
//!   **11 fields** it needs to materialize a `Trace` (`sta`, `chan`,
//!   `time`, `nsamp`, `samprate`, `calib`, `calper`, `datatype`, `dir`,
//!   `dfile`, `foff`). The other 9 fields (`wfid`, `chanid`, `jdate`,
//!   `endtime`, `instype`, `segtype`, `clip`, `commid`, `lddate`) have
//!   their **positions derived from Pisces field widths plus probing
//!   the real ObsPy test fixtures**, not directly attested by ObsPy.
//!
//! - **NNSA KB Core layout.** Pisces ships a separate schema module
//!   with widened columns; ObsPy keeps a parallel reader with
//!   hardcoded offsets. The two do not fully reconstruct each other.
//!   The NNSA positions in this crate (notably `wfid` 9, `chanid` 9,
//!   `commid` 9, `lddate` 18, plus an absent separator between
//!   `jdate` and `endtime`) are a **best-fit derivation that parses
//!   the bundled `test_nnsa.wfdisc` correctly**; alternative
//!   interpretations of the same line length exist.
//!
//! - **Numeric precision.** Pisces declares `samprate`, `calib` and
//!   `calper` as `Float24` (≈ f32). This crate parses every floating
//!   field as `f64`, matching ObsPy. That silently discards Pisces'
//!   declared 32-bit precision; it is the right choice for a reader
//!   but is technically a divergence from the Pisces table model.
//!
//! - **Datatype coverage.** Neither reference decodes the rare CSS
//!   compressed encodings (`e1`, `g2`, `cd`, `sc`); ObsPy issue #2387
//!   tracks the gap. This crate matches that gap by surfacing
//!   [`Error::UnsupportedDatatype`] rather than silently failing.
//!
//! - **Known ObsPy edge cases.** ObsPy issue #1290 reports
//!   substring-indexing problems in `obspy.io.css.core`. This crate
//!   uses ObsPy's published offsets without auditing for that bug —
//!   if you encounter a row that parses wrong, please file an issue.
//!
//! ## Supported datatype codes
//!
//! | Code | Description                          | Bytes/sample |
//! |------|--------------------------------------|--------------|
//! | `s4` | big-endian signed 32-bit integer     | 4            |
//! | `s2` | big-endian signed 16-bit integer     | 2            |
//! | `s3` | big-endian signed 24-bit integer     | 3            |
//! | `i4` | little-endian signed 32-bit integer  | 4            |
//! | `i2` | little-endian signed 16-bit integer  | 2            |
//! | `t4` | big-endian IEEE-754 32-bit float     | 4            |
//! | `t8` | big-endian IEEE-754 64-bit float     | 8            |
//! | `f4` | little-endian IEEE-754 32-bit float  | 4            |
//! | `f8` | little-endian IEEE-754 64-bit float  | 8            |
//!
//! ASCII-encoded variants (`a0`, `a#`, `b0`, `b#`, `c0`, `c#`) and the rare
//! CSS compressed encodings (`e1`, `g2`, `cd`, `sc`) are recognised by the
//! parser but reading their samples returns
//! [`Error::UnsupportedDatatype`].
//!
//! ## Lenient sample-file resolution (default)
//!
//! [`Wfdisc::read_samples`] tries `dir/dfile` first, then `dir/dfile.gz`,
//! then **falls back to `base/dfile`** (and `base/dfile.gz`) — handy for
//! real-world archives where wfdiscs bake in an absolute `dir`
//! (`/data/archive/`) but the `.mwf` is colocated with the
//! `.wfdisc` on disk. Use [`Wfdisc::read_samples_strict`] to disable
//! the basename fallback.
//!
//! ## Lenient mode for real-world wfdiscs (default)
//!
//! Real-world Oracle-spooled wfdiscs and third-party converters
//! frequently emit lines that drift from the canonical 283 / 287
//! widths: shortened 32-char `dir`, Oracle `DD-MON-YY` or epoch-seconds
//! `lddate`, single-space delimiters with no right-alignment padding,
//! or trailing pad spaces stripped. The reader is **lenient by
//! default**: lines whose length does not match a canonical schema are
//! recovered via whitespace tokenization ([`Schema::Loose`]), and lines
//! with fewer than 20 tokens (Oracle prompts, banners) are silently
//! skipped. Call [`WfdiscReader::strict`] for byte-exact CSS 3.0 / NNSA
//! KB Core compliance.

#![deny(missing_debug_implementations)]
#![warn(missing_docs)]

mod datatype;
mod error;
mod reader;
mod samples;
mod time;
mod wfdisc;

pub use datatype::DataType;
pub use error::{Error, Result};

/// Default cap on sample payload bytes (`bps * nsamp`) and gzip skip offsets.
pub const DEFAULT_MAX_SAMPLE_BYTES: usize = 256 * 1024 * 1024;
pub use reader::{Schema, WfdiscReader};
pub use samples::Samples;
pub use time::{JDate, jdate_from_epoch, jdate_to_ymd, ymd_hms_to_epoch, ymd_to_jdate};
pub use wfdisc::{
    ClipFlag, SegType, Trace, Wfdisc, read_samples_at, read_samples_at_with_limit,
};