1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
//! `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
//!
//! ```no_run
//! use wfdisc::WfdiscReader;
//!
//! # fn main() -> wfdisc::Result<()> {
//! 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,
//! );
//! }
//! # Ok(())
//! # }
//! ```
//!
//! ## API mirrors `mseed` / `miniseed`
//!
//! Like the [`mseed`](https://docs.rs/mseed) and
//! [`miniseed`](https://docs.rs/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`](https://github.com/LANL-Seismoacoustics/pisces))
//! for the table schema (column widths, default values).
//! - **ObsPy** ([`obspy.io.css.core`](https://github.com/obspy/obspy/blob/master/obspy/io/css/core.py))
//! for the literal byte offsets used to slice each line and the `DTYPE`
//! table (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,
//! `-1` for ints, `1.0` for `calib`, etc.). ObsPy parses only the
//! **11 fields** it needs to materialize a `Trace` (`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 `wfid` 9, `chanid` 9,
//! `commid` 9, `lddate` 18, plus an absent separator between
//! `jdate` and `endtime`) are a **best-fit derivation that parses
//! the bundled `test_nnsa.wfdisc` correctly**; alternative
//! interpretations of the same line length exist.
//!
//! - **Numeric precision.** Pisces declares `samprate`, `calib` and
//! `calper` as `Float24` (≈ f32). This crate parses every floating
//! field as `f64`, 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 surfacing
//! [`Error::UnsupportedDatatype`] rather 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.
pub use DataType;
pub use ;
/// Default cap on sample payload bytes (`bps * nsamp`) and gzip skip offsets.
pub const DEFAULT_MAX_SAMPLE_BYTES: usize = 256 * 1024 * 1024;
pub use ;
pub use Samples;
pub use ;
pub use ;