Skip to main content

Crate wfdisc

Crate wfdisc 

Source
Expand description

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

use wfdisc::WfdiscReader;

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,
    );
}

§API mirrors mseed / miniseed

Like the mseed and 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) for the table schema (column widths, default values).
  • ObsPy (obspy.io.css.core) 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

CodeDescriptionBytes/sample
s4big-endian signed 32-bit integer4
s2big-endian signed 16-bit integer2
s3big-endian signed 24-bit integer3
i4little-endian signed 32-bit integer4
i2little-endian signed 16-bit integer2
t4big-endian IEEE-754 32-bit float4
t8big-endian IEEE-754 64-bit float8
f4little-endian IEEE-754 32-bit float4
f8little-endian IEEE-754 64-bit float8

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.

Structs§

JDate
A Julian date in the CSS 3.0 form YYYYDDD (year × 1000 + 1-based day-of-year, 1..=366).
Trace
A descriptor row paired with its decoded samples.
Wfdisc
One parsed row of a wfdisc descriptor file.
WfdiscReader
Streaming iterator over the rows of a wfdisc descriptor file.

Enums§

ClipFlag
Clip indicator from the clip column.
DataType
Two-character datatype code carried in column 14 of a wfdisc row.
Error
All errors produced by this crate.
Samples
Decoded samples for one trace, typed by encoding.
Schema
Field layout variant for a wfdisc descriptor file.
SegType
Structural channel category from the segtype column.

Constants§

DEFAULT_MAX_SAMPLE_BYTES
Default cap on sample payload bytes (bps * nsamp) and gzip skip offsets.

Functions§

jdate_from_epoch
Convert Unix epoch seconds (UTC) to a JDate.
jdate_to_ymd
Convert a JDate back to (year, month, day).
read_samples_at
Read nsamp samples of datatype starting at uncompressed byte offset foff from a resolved waveform file.
read_samples_at_with_limit
Like read_samples_at with a caller-supplied byte cap on the sample payload and gzip skip offset.
ymd_hms_to_epoch
Convert (year, month, day, hour, min, sec) to Unix epoch seconds.
ymd_to_jdate
Convert (year, month, day) to a JDate.

Type Aliases§

Result
Convenience Result alias parameterised over Error.