original program
This commit is contained in:
Thomas Ales
+210
@@ -0,0 +1,210 @@
|
||||
# SRAS Scan Binary Format — Version 6
|
||||
|
||||
Each `.sras` file contains **one complete scan**: all GR rotation angles and all
|
||||
Y rows. Files are named `{prefix}.sras`.
|
||||
|
||||
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` |
|
||||
| 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, 0–180).
|
||||
|
||||
```
|
||||
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 sc3_aui_app.py)
|
||||
|
||||
| Parameter | Value |
|
||||
|-----------------------|------------------------------|
|
||||
| Oscilloscope trigger | CH2, rising edge, 1.24 V |
|
||||
| Trigger offset | 0 % (trigger at left edge) |
|
||||
| Sample rate | 6.25 GS/s (160 ps/sample) |
|
||||
| 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 |
|
||||
| Acquisition mode | FastFrame, Normal trigger |
|
||||
|
||||
---
|
||||
|
||||
## 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). |
|
||||
|
||||
Reference in New Issue
Block a user