feat(seismo_lab): Inspector tab — annotated hex reader for Series-3 binaries

New top-level "Inspector" tab: open any Series-3 waveform binary and read it as
a colour-coded hex dump driven by binary_annotate. Each region is labelled with
its offset range and size (header / STRT / per-channel sample records / footer),
and everything the decoder can't account for is painted UNKNOWN (red) so gaps
stand out — the point being to comb for undecoded data (e.g. a stored FFT/
spectral block). A summary shows total size, region count, and % unknown.

Read-only reader/translator; Series-3 only for now (Series-4 later). The GUI
needs tkinter + a display (not available in the dev venv); the annotator core it
calls is unit-tested headless.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YDXjZCr4RqT2U3QvMDhgzf

minimateplus/binary_annotate.py

@@ -0,0 +1,75 @@
+"""Structural annotation of a Series-3 Blastware waveform binary.
+
+Pure, no I/O: takes the raw file bytes and returns a flat, gap-free tiling of
+labelled :class:`Span` regions for a hex viewer to paint.  Every byte is
+covered — anything the decoder can't account for becomes an ``unknown`` span,
+so undecoded regions (e.g. a stored spectral/FFT block, if one exists) stand
+out instead of hiding.
+
+File layout (see ``blastware_file.py``):  ``[header][21B STRT][body][26B footer]``.
+The body is the record chain walked by :func:`waveform_codec.walk_records`.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List
+
+from .waveform_codec import walk_records
+
+_STRT_LEN = 21
+_FOOTER_LEN = 26
+
+
+@dataclass
+class Span:
+    start: int          # inclusive byte offset
+    end: int            # exclusive byte offset
+    label: str          # human-readable description
+    kind: str           # 'header' | 'strt' | 'sample' | 'footer' | 'unknown'
+
+
+def _tile(known: List[Span], total: int) -> List[Span]:
+    """Sort *known* spans and fill every gap with an ``unknown`` span, so the
+    result is a contiguous, non-overlapping tiling of ``[0, total)``.  Overlaps
+    are resolved by clamping to the running position (first writer wins)."""
+    out: List[Span] = []
+    pos = 0
+    for s in sorted(known, key=lambda x: (x.start, x.end)):
+        if s.end <= pos:
+            continue                       # fully behind — dropped overlap
+        start = max(s.start, pos)
+        if start > pos:
+            out.append(Span(pos, start, "unknown", "unknown"))
+        out.append(s if start == s.start else Span(start, s.end, s.label, s.kind))
+        pos = s.end
+    if pos < total:
+        out.append(Span(pos, total, "unknown", "unknown"))
+    return out
+
+
+def annotate_blastware_binary(raw: bytes) -> List[Span]:
+    """Annotate a Series-3 waveform binary into a gap-free list of spans."""
+    total = len(raw)
+    strt_pos = raw.find(b"STRT")
+    if strt_pos < 0:
+        return [Span(0, total, "unrecognized — no STRT record", "unknown")]
+
+    known: List[Span] = []
+    if strt_pos > 0:
+        known.append(Span(0, strt_pos, "File header", "header"))
+    known.append(Span(strt_pos, strt_pos + _STRT_LEN, "STRT record", "strt"))
+
+    body_start = strt_pos + _STRT_LEN
+    footer_start = total - _FOOTER_LEN
+    if footer_start >= body_start:
+        known.append(Span(footer_start, total, "File footer", "footer"))
+    else:
+        footer_start = total          # file too short for a footer
+
+    body = raw[body_start:footer_start]
+    for rec in walk_records(body):
+        hi, lo = rec["mode"]
+        label = f"{rec['channel']} record (seg {rec['segment_index']}, mode {hi:02x} {lo:02x})"
+        known.append(Span(body_start + rec["offset"], body_start + rec["end"], label, "sample"))
+
+    return _tile(known, total)

seismo_lab.py

@@ -54,6 +54,7 @@ from s3_analyzer import (  # noqa: E402
     write_claude_export,
 )
 from frame_db import FrameDB  # noqa: E402
+from minimateplus.binary_annotate import annotate_blastware_binary  # noqa: E402
 
 # ── colour palette ────────────────────────────────────────────────────────────
 BG       = "#1e1e1e"
@@ -2675,6 +2676,95 @@ class DownloadPanel(tk.Frame):
         self._on_capture_ready(bw_path, s3_path, label)
 
 
+# ─────────────────────────────────────────────────────────────────────────────
+# Inspector panel — annotated hex view of a Series-3 binary
+# ─────────────────────────────────────────────────────────────────────────────
+
+class InspectorPanel(tk.Frame):
+    """Load any Series-3 waveform binary and read it as an annotated hex dump.
+
+    Regions the decoder understands (header, STRT, per-channel sample records,
+    footer) are labelled and colour-coded; everything the decoder cannot account
+    for is flagged UNKNOWN, so undecoded bytes stand out for hand-inspection.
+    """
+
+    _KIND_COLOR = {
+        "header":  ACCENT,
+        "strt":    YELLOW,
+        "sample":  COL_S3,
+        "footer":  FG_DIM,
+        "unknown": RED,
+    }
+
+    def __init__(self, parent: tk.Widget, initialdir=None, **kw) -> None:
+        super().__init__(parent, bg=BG, **kw)
+        self._path = None
+        self._initialdir = initialdir
+        self._build()
+
+    def _build(self) -> None:
+        bar = tk.Frame(self, bg=BG2)
+        bar.pack(side=tk.TOP, fill=tk.X)
+        tk.Button(bar, text="Open binary…", command=self._open, bg=BG3, fg=FG,
+                  relief=tk.FLAT, font=MONO, activebackground=ACCENT).pack(side=tk.LEFT, padx=6, pady=6)
+        self._path_var = tk.StringVar(value="(no file loaded)")
+        tk.Label(bar, textvariable=self._path_var, bg=BG2, fg=FG_DIM, font=MONO).pack(side=tk.LEFT, padx=6)
+        self._summary_var = tk.StringVar(value="")
+        tk.Label(bar, textvariable=self._summary_var, bg=BG2, fg=FG, font=MONO).pack(side=tk.RIGHT, padx=10)
+
+        legend = tk.Frame(self, bg=BG2)
+        legend.pack(side=tk.TOP, fill=tk.X)
+        tk.Label(legend, text="legend:", bg=BG2, fg=FG_DIM, font=MONO).pack(side=tk.LEFT, padx=(8, 2))
+        for kind, color in self._KIND_COLOR.items():
+            tk.Label(legend, text=f"■ {kind}", bg=BG2, fg=color, font=MONO).pack(side=tk.LEFT, padx=5, pady=2)
+
+        self._text = scrolledtext.ScrolledText(
+            self, bg=BG, fg=FG, insertbackground=FG, font=MONO, wrap=tk.NONE, borderwidth=0)
+        self._text.pack(side=tk.TOP, fill=tk.BOTH, expand=True)
+        for kind, color in self._KIND_COLOR.items():
+            self._text.tag_configure(kind, foreground=color)
+        self._text.tag_configure("label", foreground="#ffffff", font=("Consolas", 9, "bold"))
+        self._text.tag_configure("dim", foreground=FG_DIM)
+        self._text.configure(state=tk.DISABLED)
+
+    def _open(self) -> None:
+        p = filedialog.askopenfilename(title="Open a Series-3 binary", initialdir=self._initialdir)
+        if p:
+            self.load(Path(p))
+
+    def load(self, path: Path) -> None:
+        try:
+            raw = path.read_bytes()
+            spans = annotate_blastware_binary(raw)
+        except Exception as e:  # noqa: BLE001 — surface any read/annotate failure to the user
+            messagebox.showerror("Inspector", f"Failed to read/annotate:\n{path}\n\n{e}")
+            return
+        self._path = path
+        self._path_var.set(str(path))
+        self._render(raw, spans)
+
+    def _render(self, raw: bytes, spans) -> None:
+        t = self._text
+        t.configure(state=tk.NORMAL)
+        t.delete("1.0", tk.END)
+        unknown = sum(s.end - s.start for s in spans if s.kind == "unknown")
+        pct = 100 * unknown / max(1, len(raw))
+        self._summary_var.set(f"{len(raw)} B · {len(spans)} regions · {pct:.1f}% unknown")
+        for s in spans:
+            t.insert(tk.END, f"\n── {s.label}  [0x{s.start:04x}:0x{s.end:04x}]  {s.end - s.start} B ──\n", ("label",))
+            self._insert_hex(t, raw, s.start, s.end, s.kind)
+        t.configure(state=tk.DISABLED)
+
+    def _insert_hex(self, t: tk.Text, raw: bytes, start: int, end: int, kind: str) -> None:
+        for off in range(start, end, 16):
+            row = raw[off:min(off + 16, end)]
+            hx = " ".join(f"{b:02x}" for b in row).ljust(16 * 3 - 1)
+            txt = "".join(chr(b) if 32 <= b < 127 else "." for b in row)
+            t.insert(tk.END, f"  0x{off:04x}  ", ("dim",))
+            t.insert(tk.END, hx, (kind,))
+            t.insert(tk.END, f"  {txt}\n", ("dim",))
+
+
 # ─────────────────────────────────────────────────────────────────────────────
 # Main application window
 # ─────────────────────────────────────────────────────────────────────────────
@@ -2730,6 +2820,9 @@ class SeismoLab(tk.Tk):
         )
         nb.add(self._download_panel, text="  Download  ")
 
+        self._inspector_panel = InspectorPanel(nb)
+        nb.add(self._inspector_panel, text="  Inspector  ")
+
         self._nb = nb
         self.protocol("WM_DELETE_WINDOW", self._on_close)
 

sfm/report_pdf.py

@@ -777,6 +777,19 @@ def _draw_waveform_subplot(fig, gridspec_cell, rd: ReportData) -> None:
     dt_s = (rd.dt_ms or (1000.0 / sr)) / 1000.0
     t0_s = (rd.t0_ms if rd.t0_ms is not None else 0.0) / 1000.0
 
+    # Shared geo scale across Long/Vert/Tran (matches the event modal + BW's
+    # single amp/div): all three geo lanes use ONE Y scale = the max |sample|
+    # across them (padded, floored), so relative amplitudes stay honest instead
+    # of each lane auto-zooming to its own peak.  Mic keeps its own (psi) scale.
+    GEO_FLOOR_INS = 0.05
+    _geo_amax = 0.0
+    for _gch in ("Long", "Vert", "Tran"):
+        for _x in (rd.channels.get(_gch) or []):
+            _a = abs(_x)
+            if _a > _geo_amax:
+                _geo_amax = _a
+    geo_shared = max(_geo_amax * 1.10, GEO_FLOOR_INS)
+
     last_idx = len(order) - 1
     for i, ch in enumerate(order):
         ax = fig.add_subplot(inner[i])
@@ -786,10 +799,10 @@ def _draw_waveform_subplot(fig, gridspec_cell, rd: ReportData) -> None:
         if values:
             color = _channel_axis_color(ch)
             ax.plot(times, values, color=color, linewidth=0.5)
-            # Symmetric y-axis for geo; zero-anchored for mic.
+            # Geo: one shared symmetric scale (honest relative amplitudes).
+            # Mic: symmetric on its own psi scale (different unit).
             if ch != "MicL":
-                amax = max((abs(v) for v in values), default=0.001)
+                ax.set_ylim(-geo_shared, geo_shared)
-                ax.set_ylim(-amax * 1.10, amax * 1.10)
             else:
                 amax = max((abs(v) for v in values), default=0.001)
                 ax.set_ylim(-amax * 1.10, amax * 1.10)
@@ -824,13 +837,9 @@ def _draw_waveform_subplot(fig, gridspec_cell, rd: ReportData) -> None:
     # and find peak geo amplitude for the geo amp/div setting.
     total_s = times[-1] - times[0] if values else 0
     div_s = total_s / 10 if total_s > 0 else 0
-    geo_amp_div = "—"
+    # Footer div value reflects the SHARED geo scale (so it's correct for all
-    for ch in ("Tran", "Vert", "Long"):
+    # three lanes, not just whichever one happened to be checked first).
-        v = rd.channels.get(ch) or []
+    geo_amp_div = f"{(geo_shared * 2) / 10:.3f}" if _geo_amax > 0 else "—"
-        if v:
-            amax = max(abs(x) for x in v)
-            geo_amp_div = f"{(amax * 1.1 * 2) / 10:.3f}"
-            break
     fig.text(
         0.11, 0.030,
         f"Time(Seconds) {div_s:.2f} sec/div   Amplitude Geo: {geo_amp_div} in/s/div   Mic: 0.001 psi(L)/div",

tests/test_binary_annotate.py

@@ -0,0 +1,50 @@
+"""Structural annotation of a Series-3 Blastware binary (for the seismo_lab
+Binary Inspector). The annotator maps byte ranges to labelled spans; anything
+the decoder can't account for is a first-class ``unknown`` span, so the whole
+file is tiled and the gaps (candidate FFT/spectral data) are visible.
+"""
+from pathlib import Path
+
+from minimateplus.binary_annotate import annotate_blastware_binary, Span
+
+# A known-good full-3-channel Series-3 waveform binary (the V70 cracking fixture).
+FIXTURE = Path(__file__).parent / "fixtures" / "5-11-26" / "M529LL1L.V70"
+
+
+def _raw() -> bytes:
+    return FIXTURE.read_bytes()
+
+
+def test_spans_tile_the_whole_file():
+    raw = _raw()
+    spans = annotate_blastware_binary(raw)
+    assert spans, "expected at least one span"
+    assert spans[0].start == 0
+    assert spans[-1].end == len(raw)
+    for a, b in zip(spans, spans[1:]):
+        assert a.end == b.start, f"gap/overlap between {a!r} and {b!r}"
+    for s in spans:
+        assert s.start < s.end, f"empty/negative span {s!r}"
+
+
+def test_strt_record_is_located():
+    raw = _raw()
+    spans = annotate_blastware_binary(raw)
+    strt = [s for s in spans if s.kind == "strt"]
+    assert strt, "expected a STRT region"
+    assert raw[strt[0].start : strt[0].start + 4] == b"STRT"
+
+
+def test_geo_sample_records_annotated():
+    raw = _raw()
+    spans = annotate_blastware_binary(raw)
+    chans = {s.label.split()[0] for s in spans if s.kind == "sample"}
+    # V70 is a full three-geo-channel event.
+    assert {"Tran", "Vert", "Long"} <= chans, f"expected geo records, got {chans}"
+
+
+def test_footer_is_last():
+    raw = _raw()
+    spans = annotate_blastware_binary(raw)
+    assert spans[-1].kind == "footer"
+    assert spans[-1].end - spans[-1].start == 26

tests/test_report_pdf_geo_scale.py

@@ -0,0 +1,61 @@
+"""The event-report PDF must draw the three geo channels on ONE shared Y scale
+(max |sample| across Long/Vert/Tran, floored), not each trace auto-zoomed to its
+own peak — so relative amplitudes are honest and a small channel doesn't fill its
+lane looking as big as a large one.  Mirrors the event-modal waveform behaviour.
+"""
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+import pytest
+
+from sfm.report_pdf import ReportData, _draw_waveform_subplot
+
+
+def _draw(channels):
+    rd = ReportData(
+        channels=channels,
+        sample_rate_sps=1024,
+        dt_ms=1000.0 / 1024,
+        t0_ms=0.0,
+    )
+    fig = plt.figure()
+    cell = fig.add_gridspec(1, 1)[0, 0]
+    _draw_waveform_subplot(fig, cell, rd)
+    by_label = {ax.get_ylabel(): ax for ax in fig.axes}
+    try:
+        yield_ = {k: by_label[k].get_ylim() for k in ("Long", "Vert", "Tran", "MicL")}
+    finally:
+        plt.close(fig)
+    return yield_
+
+
+def test_geo_traces_share_one_y_scale():
+    # Tran is the biggest geo channel (0.35); Long 0.10, Vert 0.02.
+    ylims = _draw({
+        "Long": [0.10, -0.10, 0.0],
+        "Vert": [0.02, -0.02, 0.0],
+        "Tran": [0.35, -0.35, 0.0],
+        "MicL": [0.0005, -0.0005, 0.0],
+    })
+    # Shared scale = max(0.35 * 1.10, floor 0.05) = 0.385, symmetric.
+    expected = pytest.approx(0.385, rel=1e-6)
+    for ch in ("Long", "Vert", "Tran"):
+        lo, hi = ylims[ch]
+        assert hi == expected, f"{ch} top ylim {hi} != shared 0.385"
+        assert lo == pytest.approx(-0.385, rel=1e-6), f"{ch} bottom ylim {lo}"
+    # All three geo lanes identical.
+    assert ylims["Long"] == ylims["Vert"] == ylims["Tran"]
+    # Mic keeps its own (much smaller) scale — not lumped into the geo max.
+    assert ylims["MicL"][1] < 0.01
+
+
+def test_geo_shared_scale_has_floor():
+    # A tiny event (all geo well under the floor) clamps to the 0.05 floor.
+    ylims = _draw({
+        "Long": [0.008, -0.008, 0.0],
+        "Vert": [0.006, -0.006, 0.0],
+        "Tran": [0.010, -0.010, 0.0],
+        "MicL": [0.0001, -0.0001, 0.0],
+    })
+    for ch in ("Long", "Vert", "Tran"):
+        assert ylims[ch][1] == pytest.approx(0.05, rel=1e-6), f"{ch} not floored"