wfdisc 0.1.1

Reader for CSS 3.0 / NNSA KB Core wfdisc seismological waveform descriptor files. Cross-validated against ObsPy.
Documentation

wfdisc

crates.io docs.rs license

A Rust reader for CSS 3.0 and NNSA KB Core wfdisc files: fixed-width catalog rows that point at binary seismic waveform samples.

The crate provides a streaming WfdiscReader, parsed Wfdisc rows, and a Samples enum for decoded native binary sample data. Fixed-width offsets follow ObsPy/Pisces conventions, with lenient recovery for common real-world exports.

Quick start

use wfdisc::WfdiscReader;

fn main() -> wfdisc::Result<()> {
    let reader = WfdiscReader::open("path/to/file.wfdisc")?;
    for row in reader {
        let row = row?;
        let trace = row.read_trace_relative_to("path/to/data/dir")?;
        println!(
            "{}.{}  {} samples @ {} Hz  ({})  start={}",
            trace.descriptor.sta,
            trace.descriptor.chan,
            trace.samples.len(),
            trace.descriptor.samprate,
            trace.descriptor.datatype,
            trace.descriptor.time,
        );
    }
    Ok(())
}

A working CLI dumper lives in examples/dump.rs:

cargo run --example dump -- tests/data/test_css.wfdisc

Supported datatype codes

Code Encoding Bytes/sample Decoded variant
s4 big-endian signed 32-bit integer 4 Samples::I32
s2 big-endian signed 16-bit integer 2 Samples::I16
s3 big-endian signed 24-bit integer 3 Samples::I32*
i4 little-endian signed 32-bit integer 4 Samples::I32
i2 little-endian signed 16-bit integer 2 Samples::I16
t4 big-endian IEEE-754 32-bit float 4 Samples::F32
t8 big-endian IEEE-754 64-bit float 8 Samples::F64
f4 little-endian IEEE-754 32-bit float 4 Samples::F32
f8 little-endian IEEE-754 64-bit float 8 Samples::F64

* s3 samples are sign-extended into i32 because Rust has no i24.

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.

Behavior notes

  • CSS 3.0 rows are 283 chars; NNSA KB Core rows are 287 chars. The reader auto-detects the first non-empty row and applies that schema to later rows.
  • Lenient mode is on by default: non-canonical rows can be recovered from 20 whitespace-separated fields, or 21 fields when lddate contains a space. Use .strict() for fixed-width-only parsing.
  • read_samples() tries dir/dfile, dir/dfile.gz, then base/dfile and base/dfile.gz. Use read_samples_strict() to disable the basename fallback.
  • read_samples() is intentionally unsandboxed and honours historical CSS path values. Use read_samples_sandboxed() for untrusted rows.
  • Sample payloads and gzip skips are capped at 256 MiB by default; plain-file seeks are not capped.
  • Integer columns accept exact integers and exact .0+ suffixes such as 4800.0; fractional values, non-finite floats, and exponent notation are rejected.

Features

  • gzip (default): enables fallback to <dfile>.gz when the bare waveform file is absent. Disable default features if you do not need gzip support or want to avoid the flate2 dependency.

Test data

The tests/data/ directory bundles the ObsPy CSS test fixtures unchanged (see tests/data/README.obspy.txt). They cover:

  • both schemas (CSS 3.0 and NNSA KB Core),
  • both byte orders (s4 big-endian and i4 little-endian),
  • the gzip fallback path, and
  • error paths (missing waveform file, unsupported datatype).

The integration suite cross-checks decoded samples against two independent reference dumps of the same fixtures:

  • 201101311155.10.ascii.gz — produced by the css2ascii.c tool that ships with the ObsPy fixtures (validates the byte-level s4 decoder).
  • *.wfdisc.obspy.json — captured once by running ObsPy 1.5.0 over the bundled CSS and NNSA fixtures (tools/capture_obspy.py) and committed as snapshots. These validate start time, sampling rate, calib, calper, sample count, first/last samples, min/max, and sum. No Python is required at test-time; rerun the script only when the fixtures or contract change.

License

Dual-licensed under either of:

at your option.