Per-angle background capture: v7/v11 .sras layout

A multi-angle scan runs for hours, but every angle was referenced against
one background captured before the first row of the first angle. That
reference has drifted by the last angle, and comparing angles — the whole
point of a multi-angle scan — was comparing each one against a noise floor
measured at whichever angle came first.

Every angle now captures its own. Before each angle's rows, the operator is
prompted to switch the Genesis laser off, the engine averages a fresh CH1
record, and the operator switches it back on. The data block therefore reads
[background][scan][background][scan] …, one pair per angle.

Format v7 (scan) and v11 (SAW check) carry the background inside the data
block, one length-prefixed block ahead of each angle's rows; the single
block that sat between the preambles and the data is gone. Per-angle offsets
now come from a walk of the data block at parse time rather than arithmetic
over the geometry table, and an angle whose background is not fully on disk
is the frontier — nothing of it was written yet.

v6/v10 files still read: SrasFile hands their one background to every angle,
so readers never branch on the version. Nothing writes them, and a resume
refuses them, since a re-acquired angle writes a block the old layout has no
room for. A resumed v7 angle rewrites its background in place, and the
engine checks the new block fits the room the file has before writing it —
anything else would shift every row behind it.

Two fixes made along the way:

  * QtScanController never accepted file_version, so every scan launched
    from the app raised TypeError at construction.
  * angle_status() left its cursor parked at the frontier, so every angle
    past it reported the frontier's own data_offset — which handed a resumed
    scan the same write position for several angles. Two recorded offsets in
    tests/golden/sras_expected.json are corrected accordingly.

The v6 goldens stay as parser fixtures; the writer is now locked against
bytes the test lays out from scan_format.md itself.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Thomas Ales
2026-09-04 12:44:25 -05:00
parent 83744c3337
commit aa06fa1460
21 changed files with 823 additions and 241 deletions
+11 -7
View File
@@ -2,7 +2,7 @@
"""
SAW Check Viewer — every angle's frequency on one graph.
Opens a v10 middle-row SAW check (written by the main app's "SAW Quality
Opens a middle-row SAW check (written by the main app's "SAW Quality
Check") and plots the peak SAW frequency along each angle's row, all angles
on the same axes. ``core.saw_check`` explains why that answers an alignment
question: every angle's middle row crosses the same ROI centre, so the angles
@@ -17,7 +17,7 @@ Two readings share the window:
* the summary — each angle's median with ±1σ, plotted against angle, plus
the same numbers per angle in a table.
A full v6 scan opens too: the same middle row is pulled out of it, so a scan
A full scan opens too: the same middle row is pulled out of it, so a scan
can be re-examined with the check's own read-out after the fact.
"""
@@ -91,14 +91,17 @@ class LoadedCheck:
def __init__(self, path: Path):
self.sras = SrasFile(path)
self.calib = ChannelCalibration.from_preambles(self.sras.preambles)
bg = np.frombuffer(self.sras.background, dtype=np.int8)
self.background = bg.astype(np.float32) if len(bg) else None
# Each angle carries its own background (v7/v11); the read-out pulls
# the right one per angle, so the viewer only needs to know whether
# there is anything to subtract at all.
self.has_background = any(self.sras.background_array(ai) is not None
for ai in range(self.sras.header.n_angles))
self.traces = []
self.summary = None
def describe(self) -> str:
h = self.sras.header
kind = ("v10 SAW check" if self.sras.is_saw_check
kind = (f"v{self.sras.version} SAW check" if self.sras.is_saw_check
else f"v{self.sras.version} scan — middle row of each angle")
return (f"{self.sras.path.name}\n{kind}\n"
f"{h.n_angles} angle(s) · {h.samples_per_frame} samples/frame · "
@@ -468,10 +471,11 @@ class SawCheckWindow(QMainWindow):
self._check = check
self.setWindowTitle(f"SAW Check Viewer — {path.name}")
self.lbl_file.setText(check.describe())
self.chk_bg_sub.setEnabled(check.has_background)
if not check.sras.is_saw_check:
self.lbl_status.setText(
"Not a v10 check — reading the middle row of each angle "
"Not a SAW check file — reading the middle row of each angle "
"out of this scan instead.")
else:
self.lbl_status.setText("")
@@ -504,7 +508,7 @@ class SawCheckWindow(QMainWindow):
gated = self.chk_gate.isChecked()
kwargs = dict(
dc_threshold_mv=self.spin_threshold_mv.value(),
background=check.background if self.chk_bg_sub.isChecked() else None,
subtract_background=self.chk_bg_sub.isChecked(),
gate_start_ns=self.spin_gate_start.value() if gated else None,
gate_end_ns=self.spin_gate_end.value() if gated else None,
calib=check.calib,