SRAS File Format Specification

Format family: .sras
Byte order: Big-endian (network byte order) throughout, unless noted.
Version history: v2 (baseline), v3 (scope calibration), v4 (background waveform), v5 (precomputed images + guaranteed frame count).

Table of Contents

1. Overview
2. Type notation
3. Version history
4. File structure
   • Fixed header (all versions)
   • Angle table (all versions)
   • Row position table (all versions)
   • Channel preambles (v3+)
   • Background waveform (v4+)
   • Waveform data (all versions)
   • PREC section (v5)
5. Derived quantities
6. ADC calibration
7. Waveform data layout detail
8. Size reference
9. Compatibility notes

Overview

An SRAS file stores the raw RF waveforms captured during a Surface-acoustic-wave Resonance And Spectroscopy (SRAS) scan, along with the scan geometry and scope calibration metadata needed to interpret them.

A scan consists of one or more angles (rotation positions of the sample), each containing a 2-D raster of rows × frames. At every pixel, n_channels waveforms of samples_per_frame ADC counts are stored. Channel order is fixed:

Type notation

Version history

v2 note: Version 1 is not defined; version 2 is the lowest observed in the field.

File structure

┌─────────────────────────────────────────────┐
│  1. Fixed header                  (43 bytes) │  all versions
├─────────────────────────────────────────────┤
│  2. Angle table          (n_angles × 4 bytes)│  all versions
├─────────────────────────────────────────────┤
│  3. Row position table     (n_rows × 4 bytes)│  all versions
├─────────────────────────────────────────────┤
│  4. Channel preambles           (variable)   │  v3+
├─────────────────────────────────────────────┤
│  5. Background waveform         (variable)   │  v4+
├─────────────────────────────────────────────┤
│  6. Waveform data               (variable)   │  all versions
├─────────────────────────────────────────────┤
│  7. PREC section                (variable)   │  v5 only
└─────────────────────────────────────────────┘

1. Fixed header (43 bytes, all versions)

2. Angle table (all versions)

Immediately follows the fixed header.

n_angles × f32   — scan angle in degrees

Each entry is a big-endian f32 giving the sample rotation angle in degrees at which that angle index was acquired.

3. Row position table (all versions)

Immediately follows the angle table.

n_rows × f32   — Y position of each row, in millimetres

4. Channel preambles (v3+)

One entry per channel, in channel-index order (CH1 first).

for each channel:
    u16          preamble_length   — byte count of the UTF-8 string that follows
    utf8[N]      preamble          — Tektronix WFMOutpre string

The preamble is the oscilloscope's WFMOutpre response string. Readers extract the following keys (case-insensitive, space-separated value):

v2 fallback: when preambles are absent, readers use:

• YMULT = 1.5625 mV count⁻¹ (50 mV/div, 8 div, 8-bit ADC)
• YOFF = −87.04 ADC counts (scope position = −2.72 div)
• YZERO = 0 mV

5. Background waveform (v4+)

u32          n_bg_samples   — number of i8 ADC samples that follow
i8[n_bg]     background     — one representative CH1 background shot

The background waveform has the same samples_per_frame length as a normal CH1 waveform. It is subtracted from each CH1 waveform before FFT processing when background subtraction is enabled. When n_bg_samples == 0 the section is present but empty.

6. Waveform data (all versions)

Begins immediately after the fixed header (v2), preambles (v3), or background waveform (v4+). The waveform data is a flat, contiguous array with the following logical shape, stored in row-major (C) order:

waveform_data[n_angles][n_rows][n_channels][n_frames][samples_per_frame]

Each element is a signed ADC count of size bytes_per_sample:

• bytes_per_sample == 1 → i8
• bytes_per_sample == 2 → i16 big-endian

Total byte count:

waveform_bytes = n_angles × n_rows × n_channels × n_frames × samples_per_frame × bytes_per_sample

Index semantics

Frame-count determination

• v5: use n_frames_hdr directly; do not use file-size arithmetic.
• v2–v4: n_frames = floor((file_bytes_after_header_sections) / (bytes_per_sample × n_angles × n_rows × n_channels × samples_per_frame)). Any remainder bytes are a partial trailing row and are discarded.

7. PREC section (v5)

The PREC section is appended immediately after the waveform data and is present if and only if version == 5 and the file size exceeds waveform_end_offset.

waveform_end_offset = data_offset + waveform_bytes

where data_offset is the file offset of the first waveform byte (the byte immediately after the background waveform, or after the angle/row tables for v2 files).

PREC header (8 bytes)

Flags byte

PREC angle entries

Repeated n_stored times, in arbitrary angle-index order:

for each stored angle:
    u16                   angle_idx      — index into the angle table (0-based)
    f32[n_rows×n_frames]  peak_freq_mhz  — CH1 FFT peak frequency, MHz, row-major
    f32[n_rows×n_frames]  dc4_mv         — CH4 waveform mean, mV, row-major
    f32[n_rows×n_frames]  dc3_mv         — CH3 waveform mean, mV, row-major

All image arrays are f32 big-endian, stored in row-major order: element [r][f] is at offset (r × n_frames + f) × 4 bytes within the array.

peak_freq_mhz is computed without any DC-threshold masking (i.e. the FFT is run on every pixel unconditionally). Readers apply the dc4_mv threshold at display time:

pixel is valid  ⟺  dc4_mv[r][f]  ≥  threshold_mv
display_value   =   peak_freq_mhz[r][f]  if valid, else 0

dc4_mv / dc3_mv are the mean of all ADC samples in the respective channel waveform, converted to millivolts using the channel calibration:

dc_mv = (adc_mean − YOFF) × YMULT + YZERO

When readers must bypass the PREC fast path

Readers must fall back to real-time FFT computation (ignoring stored peak_freq_mhz) when any of the following are true:

• Time-domain gating is active (zeroing samples outside a time window changes peak frequency).
• Zero-padding (n_fft ≠ samples_per_frame) is requested (changes bin spacing).
• The reader's background-subtraction setting does not match flags.bg_sub_applied.

Derived quantities

pixel_pitch_mm  = velocity_mm_s / laser_freq_hz

x_axis_mm[f]    = x_start_mm + f × pixel_pitch_mm          (f = 0 … n_frames−1)

time_axis_ns[s] = s / sample_rate_hz × 1e9                 (s = 0 … spf−1)

freq_axis_mhz[k] = k × sample_rate_hz / (n_fft × 1e6)      (k = 0 … n_fft/2)
                   where n_fft = samples_per_frame unless zero-padding is active

velocity_ms[r][f] = peak_freq_mhz[r][f] × grating_um       (grating_um user-supplied)

ADC calibration

Convert raw ADC counts to millivolts:

voltage_mv = (adc_count − YOFF) × YMULT_mv + YZERO_mv

Invert (mV → ADC count):

adc_count = (voltage_mv − YZERO_mv) / YMULT_mv + YOFF

where YMULT_mv is YMULT in mV count⁻¹ (= scope YMULT in V count⁻¹ × 1000).

Waveform data layout detail

For a scan with n_angles=2, n_rows=3, n_channels=3, n_frames=4, spf=5 the layout is:

angle 0
  row 0
    CH1: [s0 s1 s2 s3 s4] [s0 s1 s2 s3 s4] [s0 s1 s2 s3 s4] [s0 s1 s2 s3 s4]
          frame 0           frame 1           frame 2           frame 3
    CH3: …(same layout)…
    CH4: …(same layout)…
  row 1
    …
  row 2
    …
angle 1
  …

The flat byte offset of sample s of frame f, channel c, row r, angle a is:

offset = data_offset
       + (a × n_rows × n_channels × n_frames × spf
         + r × n_channels × n_frames × spf
         + c × n_frames × spf
         + f × spf
         + s)
       × bytes_per_sample

Size reference

Approximate sizes for representative scans (bytes_per_sample = 1, n_channels = 3).

PREC section size formula:

prec_bytes = 8  +  n_stored × (2 + 3 × n_rows × n_frames × 4)

Compatibility notes

Reading v5 files with a v4 reader

A v4 reader that only accepts versions {2, 3, 4} will reject a v5 file with an "unsupported version" error. This is intentional: a v4 reader would derive n_frames from the file size, incorrectly including the PREC bytes in the sample count, producing a silently wrong reshape.

Producing v5 files

v5 files are produced by the SRAS viewer's "Pre-process and Save as v5" action. The procedure is:

1. Copy the source file (any version) verbatim.
2. Set version = 5 at byte offset 4.
3. Set n_frames_hdr at byte offset 25 to the actual acquired frame count.
4. Truncate the copy to data_offset + waveform_bytes (removes any pre-existing stale PREC tail).
5. Compute peak_freq_mhz, dc4_mv, and dc3_mv for every angle using chunked FFT.
6. Append the PREC section.

Partially-written PREC sections

If n_stored < n_angles (e.g. pre-processing was interrupted), the file is still valid. Readers use stored images for the angles present in the PREC section and fall back to real-time FFT for the remainder. Readers must check angle_idx bounds on each entry and stop parsing on an out-of-range value.