wfdisc
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 WfdiscReader;
A working CLI dumper lives in examples/dump.rs:
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
lddatecontains a space. Use.strict()for fixed-width-only parsing. read_samples()triesdir/dfile,dir/dfile.gz, thenbase/dfileandbase/dfile.gz. Useread_samples_strict()to disable the basename fallback.read_samples()is intentionally unsandboxed and honours historical CSS path values. Useread_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 as4800.0; fractional values, non-finite floats, and exponent notation are rejected.
Features
gzip(default): enables fallback to<dfile>.gzwhen the bare waveform file is absent. Disable default features if you do not need gzip support or want to avoid theflate2dependency.
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 (
s4big-endian andi4little-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 thecss2ascii.ctool that ships with the ObsPy fixtures (validates the byte-levels4decoder).*.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:
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT license (LICENSE-MIT)
at your option.