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](https://img.shields.io/crates/v/wfdisc.svg)](https://crates.io/crates/wfdisc)
[![docs.rs](https://docs.rs/wfdisc/badge.svg)](https://docs.rs/wfdisc)
[![license](https://img.shields.io/crates/l/wfdisc.svg)](#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

| 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:

- Apache License, Version 2.0 ([LICENSE-APACHE]LICENSE-APACHE)
- MIT license ([LICENSE-MIT]LICENSE-MIT)

at your option.