scanengine-3/scan_format.md

SRAS Scan Binary Format — Versions 6 and 10

Each .sras file contains one complete scan: all GR rotation angles and all Y rows. Files are named {prefix}.sras.

Two versions share this layout byte for byte — only the version field differs, and with it what the file means:

Version	Meaning	Rows per angle
6	A full scan.	Whatever the ROI needs.
10	A middle-row SAW quality check ({prefix}-sawcheck.sras).	Exactly 1.

See SAW Quality Check (v10) below.

Starting in v6, each angle only scans the bounding box of the nominal ROI rotated by that specific angle — not the worst case across all angles — so x_start, x_delta (and therefore n_frames, the points/row count) and n_rows all vary per angle. A 0°/180° scan of a wide, short ROI needs far fewer rows than a 45° scan of the same ROI, and the file format reflects that instead of forcing every angle to the largest bounding box.

---

File Layout

[Global Header           — 49 bytes]
[Angle Table             — n_angles × 4 bytes  (float32 per angle, degrees)]
[Per-Angle Geometry Table— n_angles × 14 bytes (x_start f32, x_delta f32, n_frames u32, n_rows u16)]
[Row Table (ragged)      — sum(n_rows) × 4 bytes (float32 per row, angle-major)]
[Preamble Blocks         — n_channels × (uint16 length + UTF-8 WFMOutpre string)]
[Background Block        — uint32 n_bg_samples + n_bg_samples × int8 bytes]
[Waveform Data (ragged)  — per angle: n_rows[a] × n_channels × n_frames[a] × samples_per_frame × bps bytes]

All multi-byte integers and floats use big-endian byte order (> in Python's struct module).

---

Global Header (49 bytes)

Offset	Size	Type	Field	Description
0	4	4s	magic	Always SRAS (0x53 0x52 0x41 0x53)
4	1	uint8	version	Format version — 6 (scan) or 10 (SAW check)
5	2	uint16	n_angles	Number of GR rotation angles
7	4	float32	x_start_nominal	Nominal (pre-rotation) X scan start, mm
11	4	float32	y_start_nominal	Nominal (pre-rotation) Y scan start, mm
15	4	float32	x_delta_nominal	Nominal (pre-rotation) X scan width, mm
19	4	float32	y_delta_nominal	Nominal (pre-rotation) Y scan height, mm
23	4	float32	row_spacing_mm	Y spacing between rows, mm
27	4	float32	velocity_mm_s	Stage scan velocity in mm/s
31	4	float32	laser_freq_hz	Laser repetition rate in Hz
35	4	uint32	samples_per_frame	Time samples per waveform
39	8	float64	sample_rate_hz	Oscilloscope sample rate in Hz (e.g. 6.25e9)
47	1	uint8	bytes_per_sample	Bytes per ADC sample: 1 = int8, 2 = int16
48	1	uint8	n_channels	Number of channels recorded (currently 3)

Total header size: 49 bytes — verified: struct.calcsize(">4sBHfffffffIdBB") == 49.

The *_nominal fields describe the ROI as originally entered on the New Scan page (XS/YS/XD/YD), before per-angle bounding-box expansion. They are for reference/reconstruction only — the actual per-angle scan geometry used for acquisition is in the Per-Angle Geometry Table below.

---

Angle Table

Immediately after the header: n_angles big-endian float32 values, one per GR angle (degrees, signed; magnitude 0–180, sign gives physical rotation direction — negative for the current CW-rotating GR stage).

angle[0], angle[1], …, angle[n_angles - 1]

---

Per-Angle Geometry Table

Immediately after the angle table: n_angles fixed-size records, one per angle (same order as the angle table), each 14 bytes:

Size	Type	Field	Description
4	float32	x_start	X scan start for this angle's bounding box, mm
4	float32	x_delta	X scan width for this angle's bounding box, mm
4	uint32	n_frames	A-scans per row for this angle (FastFrame count)
2	uint16	n_rows	Number of Y rows scanned for this angle

Format string per record: ">ffIH".

---

Row Table (ragged)

Immediately after the per-angle geometry table: for each angle in order, that angle's n_rows big-endian float32 Y positions (mm), concatenated with no padding between angles.

# angle 0's rows, then angle 1's rows, …
y_mm[0][0], …, y_mm[0][n_rows[0]-1], y_mm[1][0], …, y_mm[n_angles-1][n_rows[-1]-1]

Row-table boundaries for angle a are derived from the per-angle geometry table: sum(n_rows[0:a]) gives the starting index into the flattened array.

---

Preamble Blocks

Immediately after the row table: n_channels length-prefixed UTF-8 strings, one per channel in SCAN_CHANNELS order (CH1, CH3, CH4). Each block is:

uint16  length   — byte length of the following UTF-8 string
bytes   preamble — WFMOutpre response string from the oscilloscope

The preamble captures per-channel scaling constants (YMULT, YOFF, YZERO) needed to convert raw ADC values to volts.

---

Background Block

Immediately after the preamble blocks: a single CH1 waveform captured with the Helios (generation) laser enabled and the Genesis (detection) laser disabled. This provides a noise/background reference for subtraction during post-processing.

uint32  n_bg_samples   — number of samples in the background waveform
int8[]  bg_data        — raw ADC samples (same encoding as waveform data)

n_bg_samples equals samples_per_frame under normal acquisition settings.

---

Waveform Data (ragged)

Immediately after the background block. Data is stored in angle-major, row-minor order, but unlike earlier versions each angle contributes a different number of rows (n_rows[a]) and a different number of frames per row (n_frames[a]), both taken from that angle's Per-Angle Geometry Table entry. Within each row, channels are interleaved in ascending channel-index order, with each channel's FastFrame data written in frame order.

for angle a in 0 … n_angles-1:
  for row in 0 … n_rows[a]-1:
    for channel in [CH1, CH3, CH4]:          # 3 channels, fixed order
      for frame in 0 … n_frames[a]-1:
        samples[0 … samples_per_frame-1]     # bps bytes each

Each sample is a raw signed ADC value. With bytes_per_sample = 1 this is int8 (−128 … +127). With bytes_per_sample = 2 this is big-endian int16.

Total data size:

sum over angles a of: n_rows[a] × 3 × n_frames[a] × samples_per_frame × bytes_per_sample

Incomplete files: If a scan is aborted the file is closed immediately and the data block will be shorter than the expected size. Readers should reconstruct the expected per-angle byte offsets from the Per-Angle Geometry Table and check file_size against the running total before reshaping — a fixed (n_angles, n_rows, ...) reshape (as in pre-v6 readers) will not work since row/frame counts are no longer uniform across angles.

---

Spatial Mapping

The k-th waveform (frame) in a row corresponds to the k-th laser pulse that hit the sample. For a row belonging to angle a, the physical X position of that pulse is:

x_k = x_start[a] + k * (velocity_mm_s / laser_freq_hz)

using that angle's x_start from the Per-Angle Geometry Table (not x_start_nominal).

---

Acquisition Settings (fixed by core/scope_sras.py)

Parameter	Value
Setup trigger	CH2, rising edge, 0.500 V (TRIG_LEVEL_V)
Scan trigger	Logic AND, CH2 HIGH ∧ CH3 HIGH, 0.500 V
Horizontal position	30 (HORizontal:POSition)
Sample rate	6.25 GS/s (160 ps/sample)
Transfer format	DATa:ENCdg RIBinary, DATa:WIDth 1
Channels recorded	CH1, CH3, CH4
Stage X velocity	100 mm/s
Stage X acceleration	1500 mm/s²
Stage X trigger out	Logic-high at max velocity (TRIGOUT_MAXV)
Acquisition mode	FastFrame, Normal trigger

None of these are stored in the file, so they do not affect byte layout — but they do set where the acoustic packet lands inside each frame. Read them from core/scope_sras.py; earlier revisions of this table drifted from the code.

---

Acquisition Paths

Two acquisition strategies write byte-identical files; the choice is a runtime flag (ScanEngine(burst_mode=…), exposed as a checkbox in the app) and is not recorded in the file.

	Per-row (default)	Burst
FastFrame acquisitions	one per row	one per floor(max_frames / n_frames) rows
Curve transfers	one per channel per row	one per channel per burst
Stage X trigger out	armed for the whole scan	armed per acquiring pass, dropped for the flyback

Burst mode runs a single acquisition across several rows, so the return move must not trigger: the trigger output is dropped before each flyback and re-armed for each acquiring pass. Row boundaries inside the burst come from ACQuire:NUMFRAMESACQuired? sampled after each pass — the burst itself carries no row markers. See core/scope_burst.py.

Row packing

The format has no per-row length field, so a row that over- or under-triggers cannot be written as it arrived — that would shift every later row. Two policies are selectable (ScanEngine(strict_rows=…), a checkbox in the app), and the choice is not recorded in the file:

	Pad (default)	Strict
Short row	zero-padded to n_frames, warned	scan stops
Long row	trailing frames dropped, warned	scan stops

Pad keeps a scan running through an occasional mis-trigger, at the cost that the affected row is indistinguishable from a good one afterwards — nothing in the file records that it was padded. Strict is for data runs where that ambiguity is worse than a failed scan: it aborts before writing the row, so the file always ends on a whole-row boundary.

---

SAW Quality Check (v10)

A full multi-angle scan takes hours, and a rig whose angles disagree produces all of them before anyone finds out. The SAW quality check acquires one row per angle — the row-wise middle of the ROI — and writes it as a v10 file. The cost is one row-time per angle instead of n_rows of them.

Nothing about the byte layout changes. A v10 file is a v6 file in which every angle's Per-Angle Geometry Table entry declares n_rows = 1, and its Row Table holds that angle's single middle Y position. Every v6 reader that works from the geometry table (rather than assuming a uniform shape) reads a v10 file unchanged.

The version byte earns its keep because the two are otherwise indistinguishable: a v6 scan aborted after its first row is not a check, even though both hold one row per angle. A reader that guessed from the row count would treat a failed scan as a deliberate measurement.

Why the middle row in particular: core/scan_geometry.py centres every angle's rotated bounding box on the same nominal ROI centre, so each angle's middle row crosses that one point on the sample. All the angles therefore measure the same material, and a spread in their SAW frequencies is a property of the rig — which is what makes it an alignment check. saw_check_viewer.py plots every angle's frequency on one graph for exactly that comparison.

Writers must honour the one-row rule; core.sras_format.create_scan_file refuses a v10 write for any plan that breaks it. Producing the plan is core.saw_check.middle_row_plan(plan), and n_rows // 2 is the middle-row rule (the upper of the two central rows when the count is even).

---

Version History

Version	Change
1	One file per row; header included angle_idx, row_idx, angle_deg, y_mm.
2	One file per scan; global header with n_angles/n_rows; separate angle and row tables; three channels (CH1, CH3, CH4) per row.
3	Added preamble blocks (WFMOutpre strings) after the row table, one length-prefixed UTF-8 block per channel.
4	Added background waveform block (CH1, Helios ON / Genesis OFF) after the preamble blocks; stored as uint32 sample count followed by raw int8 ADC bytes.
5	(skipped)
6	Each angle now scans only the bounding box of the nominal ROI rotated by that angle instead of the AABB-expanded worst case across all angles. Header no longer carries a single global x_start/x_delta/n_rows — replaced with *_nominal reference fields plus a new Per-Angle Geometry Table (x_start, x_delta, n_frames, n_rows per angle) and a ragged Row Table / Waveform Data block sized per angle. Not compatible with v4 readers (e.g. sras_viewer.py, which has not yet been updated for v6).
7–9	(skipped)
10	Middle-row SAW quality check. Byte layout identical to v6, with every angle declaring exactly one row — the row-wise middle of the ROI. A v6 reader that derives its shape from the Per-Angle Geometry Table reads these unchanged; the version byte exists so a check is not confused with a scan aborted after its first row. Written by the main app's SAW Quality Check, read by saw_check_viewer.py.