SRAS Scan Binary Format — Version 4

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

File Layout

[Global Header      — 43 bytes]
[Angle Table        — n_angles × 4 bytes  (float32 per angle)]
[Row Table          — n_rows   × 4 bytes  (float32 per row)]
[Preamble Blocks    — n_channels × (uint16 length + UTF-8 WFMOutpre string)]
[Background Block   — uint32 n_bg_samples + n_bg_samples × int8 bytes]
[Waveform Data      — n_angles × n_rows × n_channels × n_frames × samples_per_frame × bps bytes]

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

Global Header (42 bytes)

Offset	Size	Type	Field	Description
0	4	`4s`	`magic`	Always `SRAS` (0x53 0x52 0x41 0x53)
4	1	`uint8`	`version`	Format version — `4`
5	2	`uint16`	`n_angles`	Number of GR rotation angles
7	2	`uint16`	`n_rows`	Number of Y rows per angle
9	4	`float32`	`x_start_mm`	X scan start position in mm
13	4	`float32`	`x_delta_mm`	X scan width in mm
17	4	`float32`	`velocity_mm_s`	Stage scan velocity in mm/s
21	4	`float32`	`laser_freq_hz`	Laser repetition rate in Hz
25	4	`uint32`	`n_frames`	A-scans per row (= FastFrame count per channel)
29	4	`uint32`	`samples_per_frame`	Time samples per waveform
33	8	`float64`	`sample_rate_hz`	Oscilloscope sample rate in Hz (e.g. 6.25e9)
41	1	`uint8`	`bytes_per_sample`	Bytes per ADC sample: `1` = int8, `2` = int16
42	1	`uint8`	`n_channels`	Number of channels recorded (currently `3`)

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

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]

Row Table

Immediately after the angle table: n_rows big-endian float32 values, one per Y row (mm).

y_mm[0], y_mm[1], …, y_mm[n_rows - 1]

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

Immediately after the background block. Data is stored in angle-major, row-minor order. Within each row, channels are interleaved in ascending channel-index order, with each channel's FastFrame data written in frame order.

for angle in 0 … n_angles-1:
  for row in 0 … n_rows-1:
    for channel in [CH1, CH3, CH4]:          # 3 channels, fixed order
      for frame in 0 … n_frames-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:

n_angles × n_rows × 3 × n_frames × 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 check file_size >= header + angle_table + row_table + data before reshaping.

Spatial Mapping

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

x_k = x_start_mm + k * (velocity_mm_s / laser_freq_hz)

Python Read Example

import struct, numpy as np
from pathlib import Path

HDR_FMT  = ">4sBHHffffIIdBB"
HDR_SIZE = struct.calcsize(HDR_FMT)   # 43 bytes

def read_sras(path):
    with open(path, "rb") as f:
        hdr = struct.unpack(HDR_FMT, f.read(HDR_SIZE))
        magic, ver, n_angles, n_rows, xs, xd, vel, freq, nf, spf, sr, bps, n_ch = hdr
        assert magic == b"SRAS" and ver == 4, "Not a v4 SRAS file"

        angles      = np.frombuffer(f.read(n_angles * 4), dtype=">f4")
        y_positions = np.frombuffer(f.read(n_rows * 4),   dtype=">f4")

        # Preamble blocks (one per channel)
        preambles = []
        for _ in range(n_ch):
            (plen,) = struct.unpack(">H", f.read(2))
            preambles.append(f.read(plen).decode("utf-8"))

        # Background waveform block (v4+)
        (n_bg,) = struct.unpack(">I", f.read(4))
        background = np.frombuffer(f.read(n_bg), dtype=np.int8)

        dtype = np.int8 if bps == 1 else ">i2"
        data = np.frombuffer(f.read(), dtype=dtype).reshape(
            n_angles, n_rows, n_ch, nf, spf
        )

    return {
        "angles_deg":     angles,
        "y_positions_mm": y_positions,
        "x_start_mm":     xs,
        "x_delta_mm":     xd,
        "velocity_mm_s":  vel,
        "laser_freq_hz":  freq,
        "sample_rate_hz": sr,
        "n_channels":     n_ch,      # 3: CH1, CH3, CH4 (see Acquisition Settings)
        "preambles":      preambles, # WFMOutpre strings, same order as n_channels
        "background":     background,# shape: (n_bg_samples,) — CH1 noise reference
        # shape: (n_angles, n_rows, n_channels, n_frames, samples_per_frame)
        "data":           data,
    }

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.

7.6 KiB Raw Blame History Unescape Escape