# wfdisc
[](https://crates.io/crates/wfdisc)
[](https://docs.rs/wfdisc)
[](#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
```rust,no_run
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`](examples/dump.rs):
```sh
cargo run --example dump -- tests/data/test_css.wfdisc
```
## Supported datatype codes
| `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:
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))
at your option.