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 theDTYPEtable (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,-1for ints,1.0forcalib, etc.). ObsPy parses only the 11 fields it needs to materialize aTrace(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
wfid9,chanid9,commid9,lddate18, plus an absent separator betweenjdateandendtime) are a best-fit derivation that parses the bundledtest_nnsa.wfdisccorrectly; alternative interpretations of the same line length exist. -
Numeric precision. Pisces declares
samprate,calibandcalperasFloat24(≈ f32). This crate parses every floating field asf64, 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 surfacingError::UnsupportedDatatyperather 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.
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.
- Wfdisc
Reader - Streaming iterator over the rows of a wfdisc descriptor file.
Enums§
- Clip
Flag - Clip indicator from the
clipcolumn. - Data
Type - 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
segtypecolumn.
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
JDateback to (year,month,day). - read_
samples_ at - Read
nsampsamples ofdatatypestarting at uncompressed byte offsetfofffrom a resolved waveform file. - read_
samples_ at_ with_ limit - Like
read_samples_atwith 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 aJDate.