Compare commits
26 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Thomas Ales
|
3989c2a1b8 | ||
|
Thomas Ales
|
eecb0e3a82 | ||
|
Thomas Ales
|
8154c57066 | ||
|
Thomas Ales
|
f0f622b9ab | ||
|
Thomas Ales
|
26a34f7436 | ||
|
Thomas Ales
|
00a7afade0 | ||
|
Thomas Ales
|
e80717d5c5 | ||
|
Thomas Ales
|
9a9a2557d6 | ||
|
Thomas Ales
|
11ff3b62e2 | ||
|
Thomas Ales
|
007089dd48 | ||
|
Thomas Ales
|
dc513e3fd0 | ||
|
Thomas Ales
|
d5028db445 | ||
 tka
|
b0bfe6e8c6 | ||
|
Thomas Ales
|
bbb075ff34 | ||
|
Thomas Ales
|
52e91d46fd | ||
|
Thomas Ales
|
8312668c02 | ||
|
Thomas Ales
|
ca0c736c28 | ||
|
Thomas Ales
|
3c835f4592 | ||
|
Thomas Ales
|
013c7739a1 | ||
|
Thomas Ales
|
9a7cc396e7 | ||
|
Thomas Ales
|
55a4c5e42f | ||
|
Thomas Ales
|
95c273dce5 | ||
|
Thomas Ales
|
ed0eba4bae | ||
|
Thomas Ales
|
a5770491d5 | ||
|
Thomas Ales
|
f745efe7e0 | ||
|
Thomas Ales
|
158f60d2a7 |
@@ -1,2 +1,9 @@
|
||||
__pycache__/
|
||||
.venv/
|
||||
.DS_Store
|
||||
.pytest_cache/
|
||||
*.png
|
||||
*.sras
|
||||
baseline*.txt
|
||||
after*.txt
|
||||
sras_viewer.egg-info/
|
||||
|
||||
@@ -1,761 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>SRAS File Format Specification</title>
|
||||
<style>
|
||||
/* From extension vscode.github */
|
||||
/*---------------------------------------------------------------------------------------------
|
||||
* Copyright (c) Microsoft Corporation. All rights reserved.
|
||||
* Licensed under the MIT License. See License.txt in the project root for license information.
|
||||
*--------------------------------------------------------------------------------------------*/
|
||||
|
||||
.vscode-dark img[src$=\#gh-light-mode-only],
|
||||
.vscode-light img[src$=\#gh-dark-mode-only],
|
||||
.vscode-high-contrast:not(.vscode-high-contrast-light) img[src$=\#gh-light-mode-only],
|
||||
.vscode-high-contrast-light img[src$=\#gh-dark-mode-only] {
|
||||
display: none;
|
||||
}
|
||||
|
||||
</style>
|
||||
|
||||
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/Microsoft/vscode/extensions/markdown-language-features/media/markdown.css">
|
||||
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/Microsoft/vscode/extensions/markdown-language-features/media/highlight.css">
|
||||
<style>
|
||||
body {
|
||||
font-family: -apple-system, BlinkMacSystemFont, 'Segoe WPC', 'Segoe UI', system-ui, 'Ubuntu', 'Droid Sans', sans-serif;
|
||||
font-size: 14px;
|
||||
line-height: 1.6;
|
||||
}
|
||||
</style>
|
||||
<style>
|
||||
.task-list-item {
|
||||
list-style-type: none;
|
||||
}
|
||||
|
||||
.task-list-item-checkbox {
|
||||
margin-left: -20px;
|
||||
vertical-align: middle;
|
||||
pointer-events: none;
|
||||
}
|
||||
</style>
|
||||
<style>
|
||||
:root {
|
||||
--color-note: #0969da;
|
||||
--color-tip: #1a7f37;
|
||||
--color-warning: #9a6700;
|
||||
--color-severe: #bc4c00;
|
||||
--color-caution: #d1242f;
|
||||
--color-important: #8250df;
|
||||
}
|
||||
|
||||
</style>
|
||||
<style>
|
||||
@media (prefers-color-scheme: dark) {
|
||||
:root {
|
||||
--color-note: #2f81f7;
|
||||
--color-tip: #3fb950;
|
||||
--color-warning: #d29922;
|
||||
--color-severe: #db6d28;
|
||||
--color-caution: #f85149;
|
||||
--color-important: #a371f7;
|
||||
}
|
||||
}
|
||||
|
||||
</style>
|
||||
<style>
|
||||
.markdown-alert {
|
||||
padding: 0.5rem 1rem;
|
||||
margin-bottom: 16px;
|
||||
color: inherit;
|
||||
border-left: .25em solid #888;
|
||||
}
|
||||
|
||||
.markdown-alert>:first-child {
|
||||
margin-top: 0
|
||||
}
|
||||
|
||||
.markdown-alert>:last-child {
|
||||
margin-bottom: 0
|
||||
}
|
||||
|
||||
.markdown-alert .markdown-alert-title {
|
||||
display: flex;
|
||||
font-weight: 500;
|
||||
align-items: center;
|
||||
line-height: 1
|
||||
}
|
||||
|
||||
.markdown-alert .markdown-alert-title .octicon {
|
||||
margin-right: 0.5rem;
|
||||
display: inline-block;
|
||||
overflow: visible !important;
|
||||
vertical-align: text-bottom;
|
||||
fill: currentColor;
|
||||
}
|
||||
|
||||
.markdown-alert.markdown-alert-note {
|
||||
border-left-color: var(--color-note);
|
||||
}
|
||||
|
||||
.markdown-alert.markdown-alert-note .markdown-alert-title {
|
||||
color: var(--color-note);
|
||||
}
|
||||
|
||||
.markdown-alert.markdown-alert-important {
|
||||
border-left-color: var(--color-important);
|
||||
}
|
||||
|
||||
.markdown-alert.markdown-alert-important .markdown-alert-title {
|
||||
color: var(--color-important);
|
||||
}
|
||||
|
||||
.markdown-alert.markdown-alert-warning {
|
||||
border-left-color: var(--color-warning);
|
||||
}
|
||||
|
||||
.markdown-alert.markdown-alert-warning .markdown-alert-title {
|
||||
color: var(--color-warning);
|
||||
}
|
||||
|
||||
.markdown-alert.markdown-alert-tip {
|
||||
border-left-color: var(--color-tip);
|
||||
}
|
||||
|
||||
.markdown-alert.markdown-alert-tip .markdown-alert-title {
|
||||
color: var(--color-tip);
|
||||
}
|
||||
|
||||
.markdown-alert.markdown-alert-caution {
|
||||
border-left-color: var(--color-caution);
|
||||
}
|
||||
|
||||
.markdown-alert.markdown-alert-caution .markdown-alert-title {
|
||||
color: var(--color-caution);
|
||||
}
|
||||
|
||||
</style>
|
||||
|
||||
</head>
|
||||
<body class="vscode-body vscode-light">
|
||||
<h1 id="sras-file-format-specification">SRAS File Format Specification</h1>
|
||||
<p><strong>Format family:</strong> <code>.sras</code><br>
|
||||
<strong>Byte order:</strong> Big-endian (network byte order) throughout, unless noted.<br>
|
||||
<strong>Version history:</strong> v2 (baseline), v3 (scope calibration), v4 (background waveform), v5 (precomputed images + guaranteed frame count).</p>
|
||||
<hr>
|
||||
<h2 id="table-of-contents">Table of Contents</h2>
|
||||
<ol>
|
||||
<li><a href="#overview">Overview</a></li>
|
||||
<li><a href="#type-notation">Type notation</a></li>
|
||||
<li><a href="#version-history">Version history</a></li>
|
||||
<li><a href="#file-structure">File structure</a>
|
||||
<ul>
|
||||
<li><a href="#1-fixed-header-43-bytes-all-versions">Fixed header (all versions)</a></li>
|
||||
<li><a href="#2-angle-table-all-versions">Angle table (all versions)</a></li>
|
||||
<li><a href="#3-row-position-table-all-versions">Row position table (all versions)</a></li>
|
||||
<li><a href="#4-channel-preambles-v3">Channel preambles (v3+)</a></li>
|
||||
<li><a href="#5-background-waveform-v4">Background waveform (v4+)</a></li>
|
||||
<li><a href="#6-waveform-data-all-versions">Waveform data (all versions)</a></li>
|
||||
<li><a href="#7-prec-section-v5">PREC section (v5)</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#derived-quantities">Derived quantities</a></li>
|
||||
<li><a href="#adc-calibration">ADC calibration</a></li>
|
||||
<li><a href="#waveform-data-layout-detail">Waveform data layout detail</a></li>
|
||||
<li><a href="#size-reference">Size reference</a></li>
|
||||
<li><a href="#compatibility-notes">Compatibility notes</a></li>
|
||||
</ol>
|
||||
<hr>
|
||||
<h2 id="overview">Overview</h2>
|
||||
<p>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.</p>
|
||||
<p>A scan consists of one or more <strong>angles</strong> (rotation positions of the sample), each containing a 2-D raster of <strong>rows</strong> × <strong>frames</strong>. At every pixel, <code>n_channels</code> waveforms of <code>samples_per_frame</code> ADC counts are stored. Channel order is fixed:</p>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Index</th>
|
||||
<th>Hardware channel</th>
|
||||
<th>Signal</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>0</td>
|
||||
<td>CH1</td>
|
||||
<td>RF acoustic packet (AC-coupled)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>1</td>
|
||||
<td>CH3</td>
|
||||
<td>Bias A — DC mean used for masking</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>2</td>
|
||||
<td>CH4</td>
|
||||
<td>Bias B — DC mean used for masking</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<hr>
|
||||
<h2 id="type-notation">Type notation</h2>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Symbol</th>
|
||||
<th>C type</th>
|
||||
<th>Size</th>
|
||||
<th>Notes</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>u8</code></td>
|
||||
<td><code>uint8_t</code></td>
|
||||
<td>1 byte</td>
|
||||
<td>unsigned</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>u16</code></td>
|
||||
<td><code>uint16_t</code></td>
|
||||
<td>2 bytes</td>
|
||||
<td>big-endian</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>u32</code></td>
|
||||
<td><code>uint32_t</code></td>
|
||||
<td>4 bytes</td>
|
||||
<td>big-endian</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>i8</code></td>
|
||||
<td><code>int8_t</code></td>
|
||||
<td>1 byte</td>
|
||||
<td>signed, used for ADC samples when <code>bytes_per_sample == 1</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>i16</code></td>
|
||||
<td><code>int16_t</code></td>
|
||||
<td>2 bytes</td>
|
||||
<td>big-endian signed, used when <code>bytes_per_sample == 2</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>f32</code></td>
|
||||
<td><code>float</code></td>
|
||||
<td>4 bytes</td>
|
||||
<td>big-endian IEEE 754 single</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>f64</code></td>
|
||||
<td><code>double</code></td>
|
||||
<td>8 bytes</td>
|
||||
<td>big-endian IEEE 754 double</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>char[N]</code></td>
|
||||
<td>—</td>
|
||||
<td>N bytes</td>
|
||||
<td>raw bytes, no null terminator unless noted</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>utf8[N]</code></td>
|
||||
<td>—</td>
|
||||
<td>N bytes</td>
|
||||
<td>UTF-8 string, length-prefixed (see preamble section)</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<hr>
|
||||
<h2 id="version-history">Version history</h2>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Version</th>
|
||||
<th>Added</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>2</td>
|
||||
<td>Baseline: fixed header, angle table, row table, raw waveform data. No scope calibration (fallback constants used by readers).</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>3</td>
|
||||
<td>Per-channel Tektronix WFMOutpre preamble strings carrying YMULT / YOFF / YZERO calibration.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>4</td>
|
||||
<td>Background waveform section: one CH1 reference shot subtracted from each CH1 frame before FFT.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>5</td>
|
||||
<td><strong>(this document)</strong> Version byte incremented to 5. <code>n_frames_hdr</code> is now the <em>actual</em> acquired frame count (authoritative). PREC section appended after waveform data with precomputed FFT-peak and DC images for instant re-display.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<blockquote>
|
||||
<p><strong>v2 note:</strong> Version 1 is not defined; version 2 is the lowest observed in the field.</p>
|
||||
</blockquote>
|
||||
<hr>
|
||||
<h2 id="file-structure">File structure</h2>
|
||||
<pre><code>┌─────────────────────────────────────────────┐
|
||||
│ 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
|
||||
└─────────────────────────────────────────────┘
|
||||
</code></pre>
|
||||
<hr>
|
||||
<h3 id="1-fixed-header-43-bytes-all-versions">1. Fixed header (43 bytes, all versions)</h3>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Offset</th>
|
||||
<th>Size</th>
|
||||
<th>Type</th>
|
||||
<th>Field</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>0</td>
|
||||
<td>4</td>
|
||||
<td><code>char[4]</code></td>
|
||||
<td><code>magic</code></td>
|
||||
<td><code>SRAS</code> (ASCII, no null terminator). Reject file if this does not match.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>4</td>
|
||||
<td>1</td>
|
||||
<td><code>u8</code></td>
|
||||
<td><code>version</code></td>
|
||||
<td>Format version. This document describes version <strong>5</strong>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>5</td>
|
||||
<td>2</td>
|
||||
<td><code>u16</code></td>
|
||||
<td><code>n_angles</code></td>
|
||||
<td>Number of scan angles (rotation positions). ≥ 1.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>7</td>
|
||||
<td>2</td>
|
||||
<td><code>u16</code></td>
|
||||
<td><code>n_rows</code></td>
|
||||
<td>Number of scan rows (Y positions). ≥ 1.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>9</td>
|
||||
<td>4</td>
|
||||
<td><code>f32</code></td>
|
||||
<td><code>x_start_mm</code></td>
|
||||
<td>X position of the first frame in the first row, in millimetres.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>13</td>
|
||||
<td>4</td>
|
||||
<td><code>f32</code></td>
|
||||
<td><code>x_delta_mm</code></td>
|
||||
<td>Pre-computed pixel pitch in mm (<code>velocity_mm_s / laser_freq_hz</code>). Provided for convenience; readers should prefer the derived value.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>17</td>
|
||||
<td>4</td>
|
||||
<td><code>f32</code></td>
|
||||
<td><code>velocity_mm_s</code></td>
|
||||
<td>Scanner stage velocity, mm s⁻¹. Used together with <code>laser_freq_hz</code> to compute pixel pitch.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>21</td>
|
||||
<td>4</td>
|
||||
<td><code>f32</code></td>
|
||||
<td><code>laser_freq_hz</code></td>
|
||||
<td>Laser repetition rate, Hz.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>25</td>
|
||||
<td>4</td>
|
||||
<td><code>u32</code></td>
|
||||
<td><code>n_frames_hdr</code></td>
|
||||
<td><strong>v2–v4:</strong> the <em>configured</em> frame count written before acquisition; may exceed actual frames acquired (use file-size arithmetic to obtain the true count). <strong>v5:</strong> the <em>actual</em> acquired frame count — authoritative; readers must not re-derive it from file size.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>29</td>
|
||||
<td>4</td>
|
||||
<td><code>u32</code></td>
|
||||
<td><code>samples_per_frame</code></td>
|
||||
<td>ADC samples per waveform (<code>spf</code>).</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>33</td>
|
||||
<td>8</td>
|
||||
<td><code>f64</code></td>
|
||||
<td><code>sample_rate_hz</code></td>
|
||||
<td>Oscilloscope sample rate, Hz (e.g. 5 × 10⁹ for 5 GS/s).</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>41</td>
|
||||
<td>1</td>
|
||||
<td><code>u8</code></td>
|
||||
<td><code>bytes_per_sample</code></td>
|
||||
<td>ADC word size: <code>1</code> → <code>i8</code>, <code>2</code> → <code>i16</code> (big-endian).</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>42</td>
|
||||
<td>1</td>
|
||||
<td><code>u8</code></td>
|
||||
<td><code>n_channels</code></td>
|
||||
<td>Number of channels per frame. Currently always <code>3</code>.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<hr>
|
||||
<h3 id="2-angle-table-all-versions">2. Angle table (all versions)</h3>
|
||||
<p>Immediately follows the fixed header.</p>
|
||||
<pre><code>n_angles × f32 — scan angle in degrees
|
||||
</code></pre>
|
||||
<p>Each entry is a big-endian <code>f32</code> giving the sample rotation angle in degrees at which that angle index was acquired.</p>
|
||||
<hr>
|
||||
<h3 id="3-row-position-table-all-versions">3. Row position table (all versions)</h3>
|
||||
<p>Immediately follows the angle table.</p>
|
||||
<pre><code>n_rows × f32 — Y position of each row, in millimetres
|
||||
</code></pre>
|
||||
<hr>
|
||||
<h3 id="4-channel-preambles-v3">4. Channel preambles (v3+)</h3>
|
||||
<p>One entry per channel, in channel-index order (CH1 first).</p>
|
||||
<pre><code>for each channel:
|
||||
u16 preamble_length — byte count of the UTF-8 string that follows
|
||||
utf8[N] preamble — Tektronix WFMOutpre string
|
||||
</code></pre>
|
||||
<p>The preamble is the oscilloscope's <code>WFMOutpre</code> response string. Readers extract the following keys (case-insensitive, space-separated value):</p>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Key</th>
|
||||
<th>Stored unit</th>
|
||||
<th>Conversion to mV</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>YMULT</code></td>
|
||||
<td>V count⁻¹</td>
|
||||
<td>multiply by 1000</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>YOFF</code></td>
|
||||
<td>ADC counts</td>
|
||||
<td>used directly</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>YZERO</code></td>
|
||||
<td>V</td>
|
||||
<td>multiply by 1000</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p><strong>v2 fallback:</strong> when preambles are absent, readers use:</p>
|
||||
<ul>
|
||||
<li><code>YMULT</code> = 1.5625 mV count⁻¹ (50 mV/div, 8 div, 8-bit ADC)</li>
|
||||
<li><code>YOFF</code> = −87.04 ADC counts (scope position = −2.72 div)</li>
|
||||
<li><code>YZERO</code> = 0 mV</li>
|
||||
</ul>
|
||||
<hr>
|
||||
<h3 id="5-background-waveform-v4">5. Background waveform (v4+)</h3>
|
||||
<pre><code>u32 n_bg_samples — number of i8 ADC samples that follow
|
||||
i8[n_bg] background — one representative CH1 background shot
|
||||
</code></pre>
|
||||
<p>The background waveform has the same <code>samples_per_frame</code> length as a normal CH1 waveform. It is subtracted from each CH1 waveform before FFT processing when background subtraction is enabled. When <code>n_bg_samples == 0</code> the section is present but empty.</p>
|
||||
<hr>
|
||||
<h3 id="6-waveform-data-all-versions">6. Waveform data (all versions)</h3>
|
||||
<p>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:</p>
|
||||
<pre><code>waveform_data[n_angles][n_rows][n_channels][n_frames][samples_per_frame]
|
||||
</code></pre>
|
||||
<p>Each element is a signed ADC count of size <code>bytes_per_sample</code>:</p>
|
||||
<ul>
|
||||
<li><code>bytes_per_sample == 1</code> → <code>i8</code></li>
|
||||
<li><code>bytes_per_sample == 2</code> → <code>i16</code> big-endian</li>
|
||||
</ul>
|
||||
<p><strong>Total byte count:</strong></p>
|
||||
<pre><code>waveform_bytes = n_angles × n_rows × n_channels × n_frames × samples_per_frame × bytes_per_sample
|
||||
</code></pre>
|
||||
<h4 id="index-semantics">Index semantics</h4>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Dimension</th>
|
||||
<th>Range</th>
|
||||
<th>Meaning</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>[a]</code></td>
|
||||
<td>0 … n_angles−1</td>
|
||||
<td>Scan angle (rotation position)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>[r]</code></td>
|
||||
<td>0 … n_rows−1</td>
|
||||
<td>Row (Y position); row 0 is the first acquired</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>[c]</code></td>
|
||||
<td>0 … n_channels−1</td>
|
||||
<td>Channel (0=CH1 RF, 1=CH3 Bias A, 2=CH4 Bias B)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>[f]</code></td>
|
||||
<td>0 … n_frames−1</td>
|
||||
<td>Frame (X position) within the row</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>[s]</code></td>
|
||||
<td>0 … spf−1</td>
|
||||
<td>Sample index within the waveform</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h4 id="frame-count-determination">Frame-count determination</h4>
|
||||
<ul>
|
||||
<li><strong>v5:</strong> use <code>n_frames_hdr</code> directly; do not use file-size arithmetic.</li>
|
||||
<li><strong>v2–v4:</strong> <code>n_frames = floor((file_bytes_after_header_sections) / (bytes_per_sample × n_angles × n_rows × n_channels × samples_per_frame))</code>. Any remainder bytes are a partial trailing row and are discarded.</li>
|
||||
</ul>
|
||||
<hr>
|
||||
<h3 id="7-prec-section-v5">7. PREC section (v5)</h3>
|
||||
<p>The PREC section is appended immediately after the waveform data and is present if and only if <code>version == 5</code> and the file size exceeds <code>waveform_end_offset</code>.</p>
|
||||
<pre><code>waveform_end_offset = data_offset + waveform_bytes
|
||||
</code></pre>
|
||||
<p>where <code>data_offset</code> 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).</p>
|
||||
<h4 id="prec-header-8-bytes">PREC header (8 bytes)</h4>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Offset (relative)</th>
|
||||
<th>Size</th>
|
||||
<th>Type</th>
|
||||
<th>Field</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>0</td>
|
||||
<td>4</td>
|
||||
<td><code>char[4]</code></td>
|
||||
<td><code>prec_magic</code></td>
|
||||
<td><code>PREC</code> (ASCII). Absent or wrong magic → ignore section.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>4</td>
|
||||
<td>1</td>
|
||||
<td><code>u8</code></td>
|
||||
<td><code>prec_version</code></td>
|
||||
<td>PREC format version. Currently <code>1</code>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>5</td>
|
||||
<td>1</td>
|
||||
<td><code>u8</code></td>
|
||||
<td><code>flags</code></td>
|
||||
<td>Bitmask (see below).</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>6</td>
|
||||
<td>2</td>
|
||||
<td><code>u16</code></td>
|
||||
<td><code>n_stored</code></td>
|
||||
<td>Number of angle entries that follow. 0 ≤ <code>n_stored</code> ≤ <code>n_angles</code>.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h5 id="flags-byte">Flags byte</h5>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Bit</th>
|
||||
<th>Mask</th>
|
||||
<th>Meaning when set</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>0</td>
|
||||
<td><code>0x01</code></td>
|
||||
<td><code>bg_sub_applied</code> — background waveform was subtracted from CH1 before the FFT when these images were computed.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>1–7</td>
|
||||
<td>—</td>
|
||||
<td>Reserved, must be zero on write; readers must ignore.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h4 id="prec-angle-entries">PREC angle entries</h4>
|
||||
<p>Repeated <code>n_stored</code> times, in arbitrary angle-index order:</p>
|
||||
<pre><code>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
|
||||
</code></pre>
|
||||
<p>All image arrays are <code>f32</code> big-endian, stored in row-major order: element <code>[r][f]</code> is at offset <code>(r × n_frames + f) × 4</code> bytes within the array.</p>
|
||||
<p><strong><code>peak_freq_mhz</code></strong> is computed without any DC-threshold masking (i.e. the FFT is run on every pixel unconditionally). Readers apply the <code>dc4_mv</code> threshold at display time:</p>
|
||||
<pre><code>pixel is valid ⟺ dc4_mv[r][f] ≥ threshold_mv
|
||||
display_value = peak_freq_mhz[r][f] if valid, else 0
|
||||
</code></pre>
|
||||
<p><strong><code>dc4_mv</code> / <code>dc3_mv</code></strong> are the mean of all ADC samples in the respective channel waveform, converted to millivolts using the channel calibration:</p>
|
||||
<pre><code>dc_mv = (adc_mean − YOFF) × YMULT + YZERO
|
||||
</code></pre>
|
||||
<h4 id="when-readers-must-bypass-the-prec-fast-path">When readers must bypass the PREC fast path</h4>
|
||||
<p>Readers must fall back to real-time FFT computation (ignoring stored <code>peak_freq_mhz</code>) when any of the following are true:</p>
|
||||
<ul>
|
||||
<li>Time-domain gating is active (zeroing samples outside a time window changes peak frequency).</li>
|
||||
<li>Zero-padding (<code>n_fft ≠ samples_per_frame</code>) is requested (changes bin spacing).</li>
|
||||
<li>The reader's background-subtraction setting does not match <code>flags.bg_sub_applied</code>.</li>
|
||||
</ul>
|
||||
<hr>
|
||||
<h2 id="derived-quantities">Derived quantities</h2>
|
||||
<pre><code>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)
|
||||
</code></pre>
|
||||
<hr>
|
||||
<h2 id="adc-calibration">ADC calibration</h2>
|
||||
<p>Convert raw ADC counts to millivolts:</p>
|
||||
<pre><code>voltage_mv = (adc_count − YOFF) × YMULT_mv + YZERO_mv
|
||||
</code></pre>
|
||||
<p>Invert (mV → ADC count):</p>
|
||||
<pre><code>adc_count = (voltage_mv − YZERO_mv) / YMULT_mv + YOFF
|
||||
</code></pre>
|
||||
<p>where <code>YMULT_mv</code> is YMULT in mV count⁻¹ (= scope YMULT in V count⁻¹ × 1000).</p>
|
||||
<hr>
|
||||
<h2 id="waveform-data-layout-detail">Waveform data layout detail</h2>
|
||||
<p>For a scan with <code>n_angles=2</code>, <code>n_rows=3</code>, <code>n_channels=3</code>, <code>n_frames=4</code>, <code>spf=5</code> the layout is:</p>
|
||||
<pre><code>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
|
||||
…
|
||||
</code></pre>
|
||||
<p>The flat byte offset of sample <code>s</code> of frame <code>f</code>, channel <code>c</code>, row <code>r</code>, angle <code>a</code> is:</p>
|
||||
<pre><code>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
|
||||
</code></pre>
|
||||
<hr>
|
||||
<h2 id="size-reference">Size reference</h2>
|
||||
<p>Approximate sizes for representative scans (<code>bytes_per_sample = 1</code>, <code>n_channels = 3</code>).</p>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>n_angles</th>
|
||||
<th>n_rows</th>
|
||||
<th>n_frames</th>
|
||||
<th>spf</th>
|
||||
<th>Waveform data</th>
|
||||
<th>PREC section</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>1</td>
|
||||
<td>500</td>
|
||||
<td>500</td>
|
||||
<td>400</td>
|
||||
<td>300 MB</td>
|
||||
<td>12 MB</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>4</td>
|
||||
<td>500</td>
|
||||
<td>500</td>
|
||||
<td>400</td>
|
||||
<td>1.2 GB</td>
|
||||
<td>48 MB</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>1</td>
|
||||
<td>2000</td>
|
||||
<td>2000</td>
|
||||
<td>400</td>
|
||||
<td>4.8 GB</td>
|
||||
<td>48 MB</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>4</td>
|
||||
<td>2000</td>
|
||||
<td>2000</td>
|
||||
<td>400</td>
|
||||
<td>19.2 GB</td>
|
||||
<td>192 MB</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>8</td>
|
||||
<td>2000</td>
|
||||
<td>2000</td>
|
||||
<td>400</td>
|
||||
<td>38.4 GB</td>
|
||||
<td>384 MB</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>16</td>
|
||||
<td>2000</td>
|
||||
<td>2000</td>
|
||||
<td>400</td>
|
||||
<td>76.8 GB</td>
|
||||
<td>768 MB</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p><strong>PREC section size formula:</strong></p>
|
||||
<pre><code>prec_bytes = 8 + n_stored × (2 + 3 × n_rows × n_frames × 4)
|
||||
</code></pre>
|
||||
<hr>
|
||||
<h2 id="compatibility-notes">Compatibility notes</h2>
|
||||
<h3 id="reading-v5-files-with-a-v4-reader">Reading v5 files with a v4 reader</h3>
|
||||
<p>A v4 reader that only accepts versions <code>{2, 3, 4}</code> will reject a v5 file with an "unsupported version" error. This is intentional: a v4 reader would derive <code>n_frames</code> from the file size, incorrectly including the PREC bytes in the sample count, producing a silently wrong reshape.</p>
|
||||
<h3 id="producing-v5-files">Producing v5 files</h3>
|
||||
<p>v5 files are produced by the SRAS viewer's <strong>"Pre-process and Save as v5"</strong> action. The procedure is:</p>
|
||||
<ol>
|
||||
<li>Copy the source file (any version) verbatim.</li>
|
||||
<li>Set <code>version = 5</code> at byte offset 4.</li>
|
||||
<li>Set <code>n_frames_hdr</code> at byte offset 25 to the actual acquired frame count.</li>
|
||||
<li>Truncate the copy to <code>data_offset + waveform_bytes</code> (removes any pre-existing stale PREC tail).</li>
|
||||
<li>Compute <code>peak_freq_mhz</code>, <code>dc4_mv</code>, and <code>dc3_mv</code> for every angle using chunked FFT.</li>
|
||||
<li>Append the PREC section.</li>
|
||||
</ol>
|
||||
<h3 id="partially-written-prec-sections">Partially-written PREC sections</h3>
|
||||
<p>If <code>n_stored < n_angles</code> (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 <code>angle_idx</code> bounds on each entry and stop parsing on an out-of-range value.</p>
|
||||
|
||||
|
||||
|
||||
</body>
|
||||
</html>
|
||||
-379
@@ -1,379 +0,0 @@
|
||||
# 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](#overview)
|
||||
2. [Type notation](#type-notation)
|
||||
3. [Version history](#version-history)
|
||||
4. [File structure](#file-structure)
|
||||
- [Fixed header (all versions)](#1-fixed-header-43-bytes-all-versions)
|
||||
- [Angle table (all versions)](#2-angle-table-all-versions)
|
||||
- [Row position table (all versions)](#3-row-position-table-all-versions)
|
||||
- [Channel preambles (v3+)](#4-channel-preambles-v3)
|
||||
- [Background waveform (v4+)](#5-background-waveform-v4)
|
||||
- [Waveform data (all versions)](#6-waveform-data-all-versions)
|
||||
- [PREC section (v5)](#7-prec-section-v5)
|
||||
5. [Derived quantities](#derived-quantities)
|
||||
6. [ADC calibration](#adc-calibration)
|
||||
7. [Waveform data layout detail](#waveform-data-layout-detail)
|
||||
8. [Size reference](#size-reference)
|
||||
9. [Compatibility notes](#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:
|
||||
|
||||
| Index | Hardware channel | Signal |
|
||||
|-------|-----------------|--------|
|
||||
| 0 | CH1 | RF acoustic packet (AC-coupled) |
|
||||
| 1 | CH3 | Bias A — DC mean used for masking |
|
||||
| 2 | CH4 | Bias B — DC mean used for masking |
|
||||
|
||||
---
|
||||
|
||||
## Type notation
|
||||
|
||||
| Symbol | C type | Size | Notes |
|
||||
|--------|--------|------|-------|
|
||||
| `u8` | `uint8_t` | 1 byte | unsigned |
|
||||
| `u16` | `uint16_t` | 2 bytes | big-endian |
|
||||
| `u32` | `uint32_t` | 4 bytes | big-endian |
|
||||
| `i8` | `int8_t` | 1 byte | signed, used for ADC samples when `bytes_per_sample == 1` |
|
||||
| `i16` | `int16_t` | 2 bytes | big-endian signed, used when `bytes_per_sample == 2` |
|
||||
| `f32` | `float` | 4 bytes | big-endian IEEE 754 single |
|
||||
| `f64` | `double` | 8 bytes | big-endian IEEE 754 double |
|
||||
| `char[N]` | — | N bytes | raw bytes, no null terminator unless noted |
|
||||
| `utf8[N]` | — | N bytes | UTF-8 string, length-prefixed (see preamble section) |
|
||||
|
||||
---
|
||||
|
||||
## Version history
|
||||
|
||||
| Version | Added |
|
||||
|---------|-------|
|
||||
| 2 | Baseline: fixed header, angle table, row table, raw waveform data. No scope calibration (fallback constants used by readers). |
|
||||
| 3 | Per-channel Tektronix WFMOutpre preamble strings carrying YMULT / YOFF / YZERO calibration. |
|
||||
| 4 | Background waveform section: one CH1 reference shot subtracted from each CH1 frame before FFT. |
|
||||
| 5 | **(this document)** Version byte incremented to 5. `n_frames_hdr` is now the *actual* acquired frame count (authoritative). PREC section appended after waveform data with precomputed FFT-peak and DC images for instant re-display. |
|
||||
|
||||
> **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)
|
||||
|
||||
| Offset | Size | Type | Field | Description |
|
||||
|--------|------|------|-------|-------------|
|
||||
| 0 | 4 | `char[4]` | `magic` | `SRAS` (ASCII, no null terminator). Reject file if this does not match. |
|
||||
| 4 | 1 | `u8` | `version` | Format version. This document describes version **5**. |
|
||||
| 5 | 2 | `u16` | `n_angles` | Number of scan angles (rotation positions). ≥ 1. |
|
||||
| 7 | 2 | `u16` | `n_rows` | Number of scan rows (Y positions). ≥ 1. |
|
||||
| 9 | 4 | `f32` | `x_start_mm` | X position of the first frame in the first row, in millimetres. |
|
||||
| 13 | 4 | `f32` | `x_delta_mm` | Pre-computed pixel pitch in mm (`velocity_mm_s / laser_freq_hz`). Provided for convenience; readers should prefer the derived value. |
|
||||
| 17 | 4 | `f32` | `velocity_mm_s` | Scanner stage velocity, mm s⁻¹. Used together with `laser_freq_hz` to compute pixel pitch. |
|
||||
| 21 | 4 | `f32` | `laser_freq_hz` | Laser repetition rate, Hz. |
|
||||
| 25 | 4 | `u32` | `n_frames_hdr` | **v2–v4:** the *configured* frame count written before acquisition; may exceed actual frames acquired (use file-size arithmetic to obtain the true count). **v5:** the *actual* acquired frame count — authoritative; readers must not re-derive it from file size. |
|
||||
| 29 | 4 | `u32` | `samples_per_frame` | ADC samples per waveform (`spf`). |
|
||||
| 33 | 8 | `f64` | `sample_rate_hz` | Oscilloscope sample rate, Hz (e.g. 5 × 10⁹ for 5 GS/s). |
|
||||
| 41 | 1 | `u8` | `bytes_per_sample` | ADC word size: `1` → `i8`, `2` → `i16` (big-endian). |
|
||||
| 42 | 1 | `u8` | `n_channels` | Number of channels per frame. Currently always `3`. |
|
||||
|
||||
---
|
||||
|
||||
### 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):
|
||||
|
||||
| Key | Stored unit | Conversion to mV |
|
||||
|-----|-------------|-----------------|
|
||||
| `YMULT` | V count⁻¹ | multiply by 1000 |
|
||||
| `YOFF` | ADC counts | used directly |
|
||||
| `YZERO` | V | multiply by 1000 |
|
||||
|
||||
**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
|
||||
|
||||
| Dimension | Range | Meaning |
|
||||
|-----------|-------|---------|
|
||||
| `[a]` | 0 … n_angles−1 | Scan angle (rotation position) |
|
||||
| `[r]` | 0 … n_rows−1 | Row (Y position); row 0 is the first acquired |
|
||||
| `[c]` | 0 … n_channels−1 | Channel (0=CH1 RF, 1=CH3 Bias A, 2=CH4 Bias B) |
|
||||
| `[f]` | 0 … n_frames−1 | Frame (X position) within the row |
|
||||
| `[s]` | 0 … spf−1 | Sample index within the waveform |
|
||||
|
||||
#### 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)
|
||||
|
||||
| Offset (relative) | Size | Type | Field | Description |
|
||||
|-------------------|------|------|-------|-------------|
|
||||
| 0 | 4 | `char[4]` | `prec_magic` | `PREC` (ASCII). Absent or wrong magic → ignore section. |
|
||||
| 4 | 1 | `u8` | `prec_version` | PREC format version. Currently `1`. |
|
||||
| 5 | 1 | `u8` | `flags` | Bitmask (see below). |
|
||||
| 6 | 2 | `u16` | `n_stored` | Number of angle entries that follow. 0 ≤ `n_stored` ≤ `n_angles`. |
|
||||
|
||||
##### Flags byte
|
||||
|
||||
| Bit | Mask | Meaning when set |
|
||||
|-----|------|-----------------|
|
||||
| 0 | `0x01` | `bg_sub_applied` — background waveform was subtracted from CH1 before the FFT when these images were computed. |
|
||||
| 1–7 | — | Reserved, must be zero on write; readers must ignore. |
|
||||
|
||||
#### 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`).
|
||||
|
||||
| n_angles | n_rows | n_frames | spf | Waveform data | PREC section |
|
||||
|----------|--------|----------|-----|---------------|-------------|
|
||||
| 1 | 500 | 500 | 400 | 300 MB | 12 MB |
|
||||
| 4 | 500 | 500 | 400 | 1.2 GB | 48 MB |
|
||||
| 1 | 2000 | 2000 | 400 | 4.8 GB | 48 MB |
|
||||
| 4 | 2000 | 2000 | 400 | 19.2 GB | 192 MB |
|
||||
| 8 | 2000 | 2000 | 400 | 38.4 GB | 384 MB |
|
||||
| 16 | 2000 | 2000 | 400 | 76.8 GB | 768 MB |
|
||||
|
||||
**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.
|
||||
+199
@@ -0,0 +1,199 @@
|
||||
# sras-viewer design notes
|
||||
|
||||
Rationale that outgrew code comments. Each section is referenced by a short
|
||||
pointer comment at the relevant definition, so the code stays scannable and
|
||||
the reasoning stays findable.
|
||||
|
||||
## Memory budget and row chunking (`sras_compute.py`)
|
||||
|
||||
DC images are computed over row chunks so the float32 working buffers for one
|
||||
chunk stay under a memory budget. A fixed row count (the original design)
|
||||
works fine for small legacy scans but is catastrophic for a v6 scan with a
|
||||
large per-angle frame/sample count — e.g. a 7500-frame × 2500-sample angle
|
||||
needs ~2.4 GB for a single 32-row chunk.
|
||||
|
||||
With chunks running concurrently the budget has to cover *all* live chunks at
|
||||
once. On a large scan `chunk_rows` is already clamped to its floor of one row
|
||||
(one row alone is ~75 MB of float32 at 7507×2500), so shrinking the per-chunk
|
||||
size cannot buy more concurrency — the worker count must be derived from the
|
||||
budget instead: `_plan_chunks` picks the worker count *first* and sizes the
|
||||
chunk to it. Sizing the chunk first is the trap: a single chunk would always
|
||||
consume the whole budget and leave room for exactly one worker, precisely on
|
||||
the large scans that need concurrency most.
|
||||
|
||||
The 1024 MB default (`SRAS_MEM_BUDGET_MB`) is the measured knee on a 16-core
|
||||
machine against a 7507-frame × 2500-sample angle: 512 MB left ~20% of the
|
||||
speedup on the table, and 1536+ MB cost ~0.4 GB more resident memory for no
|
||||
further gain.
|
||||
|
||||
A caller that itself runs several computations concurrently (angle-level
|
||||
parallelism, `plan_angle_level`) must pass *both* `max_workers=1` and its
|
||||
share of the budget. Capping the workers alone is not enough: the chunk would
|
||||
still be sized against the whole budget, and N concurrent callers would each
|
||||
allocate all of it.
|
||||
|
||||
## FFT peak search: block-parallel zoom refinement (`sras_compute.py`)
|
||||
|
||||
The displayed RF value per pixel is the argmax of the zero-padded power
|
||||
spectrum of that pixel's CH1 waveform. At the pad factor of 40 needed for
|
||||
mapping resolution, materialising padded spectra is hopeless: ~9 GB per scan
|
||||
row, which is what used to collapse the old row-chunk planner to one worker
|
||||
and make synthesis single-threaded.
|
||||
|
||||
`_peak_bins_zoom` never materialises the padded spectrum:
|
||||
|
||||
1. a coarse rfft at `next_fast_len(2*spf)` — 2× oversampled, so the padded
|
||||
power spectrum (a trig polynomial of degree spf−1) cannot hide its global
|
||||
max between coarse samples;
|
||||
2. every coarse bin within `_ZOOM_CAND_RATIO` (0.7) of its row's coarse max
|
||||
becomes a refinement candidate. Quarter-natural-bin scalloping at the 2×
|
||||
grid can understate a peak's power by at most ~19%, so 0.7 keeps a wide
|
||||
margin. The DC-adjacent window is always refined too: the coarse DC bin
|
||||
is zeroed for suppression, which would otherwise blind the scan to fine
|
||||
bins closer to DC than the first coarse sample (where the leakage skirt
|
||||
of an un-subtracted offset peaks);
|
||||
3. each candidate window (±`_ZOOM_HALFWIDTH` = 0.75 coarse spacings; every
|
||||
fine bin lies within 0.5 spacings of its nearest coarse bin) is evaluated
|
||||
on the exact `n_fft` grid by one small complex gemm, with np.argmax's
|
||||
lowest-bin tie-break preserved across windows.
|
||||
|
||||
The selected bin is bit-identical to the full padded argmax — enforced by
|
||||
`tests/test_compute.py::test_zoom_identity`, a fuzz test over adversarial
|
||||
spectra, and the golden-hash harness (`tools/check_equivalence.py`), whose
|
||||
baseline was captured on the old full-padded path.
|
||||
|
||||
Work fans out over a persistent thread pool in `_FFT_BLOCK` = 512-waveform
|
||||
tasks: smaller blocks serialise on GIL-held numpy dispatch, larger ones lose
|
||||
cache residency and task granularity (measured on a 16-core machine, where
|
||||
this path runs ~35× faster than the old serial padded transform at pad 40).
|
||||
pyFFTW runs through per-thread `builders` plans (FFTW_MEASURE, wisdom
|
||||
persisted under `~/.cache/sras-viewer/`), and `threadpoolctl` clamps BLAS to
|
||||
one thread under the pool so the refinement gemm cannot oversubscribe.
|
||||
`compute_rf_image(exact=True)` (or `SRAS_FFT_EXACT=1`) keeps the reference
|
||||
full-padded path for audits.
|
||||
|
||||
## Row-averaged FFT: same-row, distance-weighted SNR cleanup (`sras_compute.py`)
|
||||
|
||||
`compute_rf_image`'s `row_avg_n` parameter averages each pixel's CH1
|
||||
waveform with its up-to-n same-row neighbors before the FFT peak search, to
|
||||
improve SNR on noisy scans. Never crosses rows: pixel pitch is strongly
|
||||
anisotropic and varies by scan (5 µm × 50 µm on a typical scan, but as
|
||||
stretched as 5 µm × 1 mm on others), so a physically meaningful "neighbor"
|
||||
set can't be a fixed-shape 2-D window — but the X pitch *within one row* is
|
||||
a single file-wide constant (`SrasFile.pixel_x_mm`), so restricting to the
|
||||
row axis sidesteps the anisotropy question entirely rather than solving it
|
||||
with an elliptical or physically-scaled 2-D kernel.
|
||||
|
||||
`_row_average_weights` is a Gaussian in pixel-index distance, not physical
|
||||
mm distance — deliberately: within one row those are the same function up
|
||||
to a fixed scale factor (`pixel_x_mm` is constant along a row), so the
|
||||
kernel itself needs no pitch at all. `pixel_x_mm` is used for real exactly
|
||||
once, in the GUI's options dialog, to show the window's physical width —
|
||||
not in the kernel math, where it would only ever cancel out.
|
||||
|
||||
`_row_average_waveforms` is a masked/renormalized convolution (two
|
||||
`correlate1d` calls, numerator and denominator, divided) rather than a
|
||||
single fixed-normalized convolution, because a masked neighbor must
|
||||
contribute *zero weight*, not a zero-amplitude sample at full weight — the
|
||||
latter would bias every average near a masked run or a row's own edge
|
||||
toward zero. The same two-correlation trick handles row-edge truncation for
|
||||
free: `mode="constant", cval=0.0` zero-pads both the numerator and the
|
||||
denominator beyond a row's own ends, so the output renormalizes by whatever
|
||||
weight sum actually landed inside the row, no separate edge case.
|
||||
|
||||
Background subtraction stays exactly where it already was (subtracted once
|
||||
from the fully-assembled `waves` buffer) rather than being threaded into the
|
||||
per-neighbor gather. This is exact, not an approximation: because
|
||||
`_row_average_waveforms`'s denominator is always the *actual* sum of
|
||||
included, valid weights (never a fixed total), `Σwᵢ·(rawᵢ−bg) / Σwᵢ`
|
||||
distributes to `avg − bg·(Σwᵢ/Σwᵢ) = avg − bg` regardless of which or how
|
||||
many neighbors were included — subtracting background from the averaged
|
||||
waveform is identical to subtracting it from every neighbor first, for any
|
||||
window, at any row edge, with any number of masked-out neighbors.
|
||||
|
||||
No cross-row halo is needed: `compute_rf_image`'s chunk loop already splits
|
||||
on rows only, and `read_row` already reads one row's complete
|
||||
`(n_frames, spf)` slice at a time — averaging happens entirely inside that
|
||||
one row's own frame axis, so a chunk boundary (which falls between rows)
|
||||
can never truncate a window. Only a row's own start/end can, and that's the
|
||||
same edge case the masked convolution already handles.
|
||||
|
||||
The averaging step doubles the live per-row scratch memory (a full-width
|
||||
`(n_frames, spf)` buffer on top of the existing compacted `waves` buffer),
|
||||
so `compute_rf_image` halves its byte budget when `row_avg_n > 0` before
|
||||
`_plan_fft_rows`/the exact-path sizing runs — see "Memory budget and row
|
||||
chunking" above. On the largest real scans `_plan_chunks` is already
|
||||
clamped to its floor of one row regardless, so this costs no concurrency
|
||||
where it matters most; it mainly protects moderate-sized scans from an
|
||||
unexpected regression.
|
||||
|
||||
Persistence: `cached_rf_image` (the extracted fast-path check) requires
|
||||
`sras.precomputed_row_avg_n == row_avg_n` exactly, so a raw request can
|
||||
never be silently served a row-averaged cache or vice versa, and a request
|
||||
at one window size can never be served a cache at another — see
|
||||
`scan_format.md`'s Cache Tail / CACH tail version history sections for the
|
||||
on-disk `row_avg_n` field this depends on.
|
||||
|
||||
## Angle alignment coordinate frames (`sras_compute.py`)
|
||||
|
||||
Alignment puts every angle's images onto one shared, zero-padded pixel grid
|
||||
using a rigid transform only — rotation + translation, never scale.
|
||||
|
||||
Angle 0 (the reference) is the sole coordinate authority: it is the only
|
||||
angle whose stage XY (`x_start_mm` / `y_positions_mm`) is ever read, and the
|
||||
shared canvas is literally an extension of angle 0's own pixel grid, so the
|
||||
aligned view carries angle 0's real X/Y axes. Every *other* angle is placed
|
||||
purely by content — its rotation and translation come from cross-correlating
|
||||
its CH4 image against angle 0's (`register_angle_to_reference`) — and its own
|
||||
stage XY is deliberately never consulted. That is not an oversight: the
|
||||
rotation stage moves the sample relative to the scan window, so where a
|
||||
window sat in stage coordinates says nothing about where the sample is, and
|
||||
an earlier design that pivoted each angle on a signal-weighted centroid of
|
||||
its own window put every angle on a ~20 mm circle around the optical center
|
||||
instead of stacking them into one shape.
|
||||
|
||||
Only two coordinate frames exist:
|
||||
|
||||
* **local mm** — one angle's own physical frame: origin at the *center of its
|
||||
own pixel array*, x along +column, y along +row, scaled by that angle's own
|
||||
pitches. Carries no stage position whatsoever.
|
||||
* **ref mm** — the reference angle's local mm. A registration result
|
||||
`(rotation_deg, shift_mm)` is exactly the rigid map from an angle's local
|
||||
mm to ref mm: `q = R(rotation_deg) @ l + shift_mm`. Stage coordinates
|
||||
re-enter once, at the very end, when the canvas origin is converted to
|
||||
angle 0's stage mm (`AlignmentResult.canvas_origin_mm`).
|
||||
|
||||
Rotation is done in mm, never on raw pixel indices: the x pitch
|
||||
(`SrasFile.pixel_x_mm`, 5 µm on a real scan) and the y/row pitch (50 µm)
|
||||
differ by 10×, so rotating the raw index grid would shear the image — an
|
||||
unwanted anisotropic scale. Registration runs on a resampled *isotropic* grid
|
||||
for the same reason, and every affine maps shared-grid index → mm → undo
|
||||
rotation/shift → that angle's own local mm → that angle's own raw index,
|
||||
matching the output→input convention `scipy.ndimage.affine_transform` wants.
|
||||
|
||||
## Manual-alignment sidecar (`sras_compute.py`)
|
||||
|
||||
`<name>.sras.align.json` lives next to the scan file. The code lives in
|
||||
`sras_compute`, not `sras_format`: `sras_format` is scoped to the versioned
|
||||
binary .sras spec itself (see `scan_format.md`), while a manual alignment is
|
||||
a viewer-computed *derived* artifact, analogous in kind to `AlignmentResult`
|
||||
— so it belongs with the alignment math it serialises. json + pathlib are
|
||||
stdlib, so this adds no dependency to a module whose load-bearing constraint
|
||||
is staying free of Qt/matplotlib for cheap multiprocessing-child imports.
|
||||
|
||||
### Schema history
|
||||
|
||||
The stored `rotation_deg`/`shift_mm` are meaningless without the frame they
|
||||
were measured in, so `_SIDECAR_SCHEMA_VERSION` is bumped whenever that frame
|
||||
changes. Each bump makes older files describe a different (and, for the bugs
|
||||
each bump fixed, actively wrong) transform than the same numbers would today;
|
||||
loading one unchanged would silently reproduce the very "scans show up
|
||||
everywhere" symptom the bump fixed — so older sidecars are treated as absent
|
||||
rather than migrated.
|
||||
|
||||
* **1 → 2** — pivot moved from the scan-window bbox center to a
|
||||
content-derived centroid, and the rotation sign convention was corrected.
|
||||
* **2 → 3** — the content centroid was abandoned entirely: rotation is now
|
||||
about each angle's own array center, mapped onto the reference's array
|
||||
center, with `shift_mm` in the reference's local mm frame. No angle but the
|
||||
reference contributes stage coordinates any more.
|
||||
@@ -0,0 +1,40 @@
|
||||
[build-system]
|
||||
requires = ["setuptools>=68"]
|
||||
build-backend = "setuptools.build_meta"
|
||||
|
||||
[project]
|
||||
name = "sras-viewer"
|
||||
version = "0.1.0"
|
||||
description = "Viewer and processing tools for SRAS .sras scan files"
|
||||
requires-python = ">=3.12"
|
||||
dependencies = [
|
||||
"PyQt6==6.10.2",
|
||||
"numpy==2.4.1",
|
||||
"matplotlib==3.10.8",
|
||||
"scipy==1.18.0",
|
||||
# Angle alignment only: masked FFT phase correlation (skimage.registration).
|
||||
"scikit-image==0.26.0",
|
||||
# Faster rfft backend; the viewer falls back to scipy.fft without it.
|
||||
"pyFFTW==0.15.1",
|
||||
# Clamps BLAS threading under the FFT worker pool.
|
||||
"threadpoolctl==3.6.0",
|
||||
]
|
||||
|
||||
[project.optional-dependencies]
|
||||
dev = ["pytest"]
|
||||
|
||||
[project.scripts]
|
||||
sras-viewer = "sras_viewer.main_window:main"
|
||||
|
||||
[tool.setuptools]
|
||||
py-modules = [
|
||||
"sras_format",
|
||||
"sras_compute",
|
||||
"sras_workers",
|
||||
"sras_average",
|
||||
"sras_edit_scans",
|
||||
]
|
||||
packages = ["sras_viewer"]
|
||||
|
||||
[tool.pytest.ini_options]
|
||||
testpaths = ["tests"]
|
||||
+148
-2
@@ -1,4 +1,4 @@
|
||||
# SRAS Scan Binary Format — Version 6
|
||||
# SRAS Scan Binary Format — Version 6 / 7
|
||||
|
||||
Each `.sras` file contains **one complete scan**: all GR rotation angles and all
|
||||
Y rows. Files are named `{prefix}.sras`.
|
||||
@@ -10,6 +10,14 @@ rotated by that specific angle** — not the worst case across all angles — so
|
||||
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.
|
||||
|
||||
v7 is byte-identical to v6 (same header, angle table, geometry table, row
|
||||
table, preamble blocks, background block, waveform data) plus an optional
|
||||
trailing **Cache Tail** holding precomputed per-angle DC and/or FFT images
|
||||
(see [Cache Tail (v7)](#cache-tail-v7) below) — only the header's `version`
|
||||
field and the presence of that trailing section differ. Scans come off the
|
||||
scope as v6; `sras_viewer.py`'s "Convert" menu batch actions convert a file
|
||||
to v7 **in place** the first time either cache block is computed and stored.
|
||||
|
||||
---
|
||||
|
||||
## File Layout
|
||||
@@ -22,6 +30,7 @@ instead of forcing every angle to the largest bounding box.
|
||||
[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]
|
||||
[Cache Tail (optional) — "CACH" + DC block (optional) + FFT block (optional); v7 only]
|
||||
```
|
||||
|
||||
All multi-byte integers and floats use **big-endian** byte order
|
||||
@@ -182,6 +191,142 @@ using that angle's `x_start` from the Per-Angle Geometry Table (not
|
||||
|
||||
---
|
||||
|
||||
## Cache Tail (v7)
|
||||
|
||||
Present iff `version == 7` and `file_size > cache_offset`, where:
|
||||
|
||||
```
|
||||
cache_offset = data_offset + Σ over angles a of:
|
||||
n_rows[a] × n_channels × n_frames[a] × samples_per_frame × bytes_per_sample
|
||||
```
|
||||
|
||||
i.e. exactly `data_offset + waveform_bytes` — the same "Total data size"
|
||||
formula as Waveform Data above. This offset is derivable from the header and
|
||||
Per-Angle Geometry Table alone and does **not** depend on which cache
|
||||
block(s) are present, so a writer can always seek straight there without
|
||||
reading or touching any waveform byte before it.
|
||||
|
||||
Unlike the (removed) v5 `PREC` section, which stored one omnibus per-angle
|
||||
entry (FFT + both DC channels together) in a dense, uniform-geometry array,
|
||||
the v7 Cache Tail splits DC and FFT into two **independent** sub-blocks —
|
||||
each sized per-angle from the Per-Angle Geometry Table, each independently
|
||||
present, and each independently updatable in any order, any number of
|
||||
times, without disturbing the other. This matches `sras_viewer.py`'s
|
||||
"Convert" menu, which exposes DC and FFT store as two separate batch
|
||||
actions.
|
||||
|
||||
### CACH outer header (6 bytes, `">4sBB"`)
|
||||
|
||||
| Offset | Size | Type | Field | Description |
|
||||
|--------|------|------|-------|-------------|
|
||||
| 0 | 4 | `char[4]` | `cach_magic` | `CACH` (ASCII). Missing/wrong magic → treat file as having no cache. |
|
||||
| 4 | 1 | `u8` | `cach_version` | Cache format version. Currently `2`; readers also accept `1` (a `1` tail predates row-averaged FFT caching — see the `SFFT` block below and [CACH tail version history](#cach-tail-version-history)). Any other value → treat the file as uncached (unlike v5's `PREC` section, which read but never validated its version byte). |
|
||||
| 5 | 1 | `u8` | `block_flags` | Bit 0 = DC block (`SDCB`) follows. Bit 1 = FFT block (`SFFT`) follows, immediately after the DC block if both are present. Bits 2–7 reserved, must be zero on write. |
|
||||
|
||||
### DC block `SDCB` (present iff `block_flags & 0x01`)
|
||||
|
||||
7-byte block header, format `">4sBH"`:
|
||||
|
||||
| Offset (rel) | Size | Type | Field | Description |
|
||||
|--------------|------|------|-------|-------------|
|
||||
| 0 | 4 | `char[4]` | `magic` | `SDCB` |
|
||||
| 4 | 1 | `u8` | `reserved` | `0`, reserved for future use |
|
||||
| 5 | 2 | `u16` | `n_stored` | Number of angle entries that follow, `0 ≤ n_stored ≤ n_angles` |
|
||||
|
||||
followed by `n_stored` entries, each:
|
||||
|
||||
```
|
||||
u16 angle_idx — index into the angle table (0-based)
|
||||
f32[n_rows[angle_idx] × n_frames[angle_idx]] dc3_mv — CH3 waveform mean, mV, row-major
|
||||
f32[n_rows[angle_idx] × n_frames[angle_idx]] dc4_mv — CH4 waveform mean, mV, row-major
|
||||
```
|
||||
|
||||
Entries may appear in any order and need not be contiguous from angle 0 —
|
||||
this supports storing (or re-storing) a subset of angles, or an
|
||||
interrupted batch run leaving only some angles cached. Readers bounds-check
|
||||
`angle_idx < n_angles` on each entry and stop parsing on an out-of-range
|
||||
value, same as v5's `PREC` section.
|
||||
|
||||
### FFT block `SFFT` (present iff `block_flags & 0x02`)
|
||||
|
||||
Block header layout depends on `cach_version`:
|
||||
|
||||
- **`cach_version` 1**: 7 bytes, format `">4sBH"` — magic, flags, n_stored.
|
||||
- **`cach_version` 2**: 8 bytes, format `">4sBHB"` — magic, flags, n_stored,
|
||||
`row_avg_n`. Always written by current code; a `cach_version` 1 tail (no
|
||||
trailing byte) is still read, with `row_avg_n` taken as `0` for every
|
||||
entry it stores.
|
||||
|
||||
| Offset (rel) | Size | Type | Field | Description |
|
||||
|--------------|------|------|-------|-------------|
|
||||
| 0 | 4 | `char[4]` | `magic` | `SFFT` |
|
||||
| 4 | 1 | `u8` | `flags` | Bit 0 = `bg_sub_applied` — background waveform was subtracted from CH1 before the FFT when these images were computed. Bit 1 = `row_averaged` — `peak_freq_mhz` came from same-row, distance-weighted averaged CH1 waveforms rather than raw per-pixel ones; `row_avg_n` (below) is the neighbor half-width used. Bits 2–7 reserved. |
|
||||
| 5 | 2 | `u16` | `n_stored` | Number of angle entries that follow |
|
||||
| 7 | 1 | `u8` | `row_avg_n` | *`cach_version` 2 only.* Same-row neighbor half-width, in pixels, that `peak_freq_mhz` was averaged over before its FFT; `0` = raw (unaveraged). Meaningful only when `flags` bit 1 is set — a `cach_version` 1 tail has no such byte and is always `row_avg_n = 0`. |
|
||||
|
||||
followed by `n_stored` entries, each:
|
||||
|
||||
```
|
||||
u16 angle_idx — index into the angle table (0-based)
|
||||
f32[n_rows[angle_idx] × n_frames[angle_idx]] peak_freq_mhz — CH1 FFT peak frequency, MHz, row-major
|
||||
```
|
||||
|
||||
**`peak_freq_mhz`** for a raw store (`row_avg_n == 0`) is computed without
|
||||
any DC-threshold masking (i.e. the FFT is run on every pixel
|
||||
unconditionally, same as v5's `PREC` convention). Readers apply the DC4
|
||||
threshold at display time:
|
||||
|
||||
```
|
||||
pixel is valid ⟺ dc4_mv[r][f] ≥ threshold_mv
|
||||
display_value = peak_freq_mhz[r][f] if valid, else 0
|
||||
```
|
||||
|
||||
using the DC4 image from the DC block if that angle is also cached there,
|
||||
else computed on demand.
|
||||
|
||||
For a row-averaged store (`row_avg_n > 0`), the DC4 threshold is applied
|
||||
*during* the store — a pixel below threshold is left at `0` and never
|
||||
contributes to any neighbor's average — since neighbor validity can't be
|
||||
deferred to display time the way plain masking can. The threshold value
|
||||
itself is not recorded, only that averaging happened and at what window
|
||||
size. Readers still apply their own live DC4 threshold at display time
|
||||
exactly as for a raw store, using whatever mask they currently have.
|
||||
|
||||
Readers must fall back to real-time FFT computation (ignoring stored
|
||||
`peak_freq_mhz`) under the same conditions as v5's PREC fast path: time-domain
|
||||
gating is active, zero-padding (`n_fft ≠ samples_per_frame`) is requested,
|
||||
the reader's background-subtraction setting doesn't match
|
||||
`flags.bg_sub_applied`, or the reader's requested `row_avg_n` doesn't match
|
||||
the stored value exactly — a raw request must never be served a
|
||||
row-averaged store, or vice versa, and a request at one window size must
|
||||
never be served a store at another.
|
||||
|
||||
### In-place write ordering
|
||||
|
||||
A writer updating a file's Cache Tail must write the payload (CACH header +
|
||||
whichever block(s) are present) **before** flipping the header's `version`
|
||||
byte to `7`, and `truncate()` the file to the new payload's end immediately
|
||||
after writing it. If the process is interrupted between the payload write
|
||||
and the version-byte flip, the file is still valid v6 — v6 parsing only
|
||||
bounds-checks each angle's `offset + nbytes ≤ file_size`, it never asserts
|
||||
exactly how many bytes follow the last angle's waveform block — so the
|
||||
interrupted write leaves harmless trailing bytes rather than a corrupt file,
|
||||
and the next successful write overwrites them via the same deterministic
|
||||
`cache_offset`.
|
||||
|
||||
### CACH tail version history
|
||||
|
||||
Distinct from the outer `.sras` file `version` byte (top of this document),
|
||||
which has stayed `7` since the Cache Tail was introduced — this is the inner
|
||||
`cach_version` byte inside the `CACH` header itself.
|
||||
|
||||
| cach_version | Change |
|
||||
|--------------|--------|
|
||||
| 1 | Initial Cache Tail: `SDCB` (DC) and `SFFT` (FFT, 7-byte header) blocks. |
|
||||
| 2 | `SFFT` header grows one byte, `row_avg_n` — the same-row neighbor half-width the stored `peak_freq_mhz` was averaged over before its FFT, `0` = raw. Readers still accept a `cach_version` 1 tail, treated as `row_avg_n = 0` for every angle it stores, so files cached before this change keep working without a recompute. |
|
||||
|
||||
---
|
||||
|
||||
## Acquisition Settings (fixed by sc3_aui_app.py)
|
||||
|
||||
| Parameter | Value |
|
||||
@@ -206,5 +351,6 @@ using that angle's `x_start` from the Per-Angle Geometry Table (not
|
||||
| 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 pre-v6 readers** that assume uniform geometry. `sras_viewer.py` reads v6 natively (per-angle `n_rows`/`n_frames`/`x_start`); the "Pre-process and Save as v5" fast-path export is not offered for v6 files since the flat v5 layout cannot represent per-angle geometry. |
|
||||
| 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 pre-v6 readers** that assume uniform geometry. `sras_viewer.py` reads v6 natively (per-angle `n_rows`/`n_frames`/`x_start`). |
|
||||
| 7 | Adds an optional trailing **Cache Tail** (`CACH` section, see [Cache Tail (v7)](#cache-tail-v7)) after the ragged waveform data, holding independently-present, independently-updatable per-angle DC (`SDCB`: dc3_mv + dc4_mv) and FFT (`SFFT`: peak_freq_mhz) blocks, so previously-computed images redisplay instantly instead of being recomputed. Header / angle table / geometry table / row table / preamble blocks / background block / waveform data are byte-identical to v6 — only the version byte and the optional Cache Tail differ. Scans still come off the scope as v6; `sras_viewer.py`'s "Convert" menu ("Batch Compute DC and Store" / "Batch Compute FFT and Store") converts a file to v7 **in place** on first use, or updates an existing v7 file's cache blocks, without rewriting any waveform bytes. Supersedes the removed "Pre-process and Save as v5" workflow, which was never available for v6 sources since the flat v5 `PREC` layout can't represent per-angle geometry. |
|
||||
|
||||
|
||||
+71
-146
@@ -15,18 +15,17 @@ Options:
|
||||
Default: include a partial average for the last group.
|
||||
"""
|
||||
|
||||
import sys
|
||||
import struct
|
||||
import argparse
|
||||
import numpy as np
|
||||
import shutil
|
||||
import struct
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Header format — must match sras_viewer.py exactly
|
||||
# ---------------------------------------------------------------------------
|
||||
import numpy as np
|
||||
|
||||
HDR_FMT = ">4sBHHffffIIdBB"
|
||||
HDR_SIZE = struct.calcsize(HDR_FMT) # 43 bytes
|
||||
from sras_format import HDR_FMT, HDR_SIZE, SrasFile
|
||||
|
||||
_SUPPORTED = (2, 3, 4)
|
||||
|
||||
|
||||
def parse_args():
|
||||
@@ -42,143 +41,68 @@ def parse_args():
|
||||
return p.parse_args()
|
||||
|
||||
|
||||
def read_sras(path: Path):
|
||||
"""Read all sections of a .sras file and return them as a dict."""
|
||||
with open(path, "rb") as f:
|
||||
header_bytes = f.read(HDR_SIZE)
|
||||
fields = struct.unpack(HDR_FMT, header_bytes)
|
||||
|
||||
(magic, ver, n_angles, n_rows, x_start, x_delta, vel, freq,
|
||||
n_frames_hdr, spf, sr, bps, n_ch) = fields
|
||||
|
||||
if magic != b"SRAS":
|
||||
raise ValueError(f"Not a .sras file (bad magic: {magic!r})")
|
||||
if ver not in (2, 3, 4):
|
||||
raise ValueError(f"Unsupported .sras version: {ver}")
|
||||
|
||||
with open(path, "rb") as f:
|
||||
def read_header_sections(sras: SrasFile) -> bytes:
|
||||
"""The raw bytes between the header and the waveform data (angle table,
|
||||
row table, preambles, background), copied through verbatim so nothing is
|
||||
lost in a re-encode."""
|
||||
with open(sras.path, "rb") as f:
|
||||
f.seek(HDR_SIZE)
|
||||
|
||||
angles = f.read(n_angles * 4) # big-endian float32 array, raw bytes
|
||||
y_pos = f.read(n_rows * 4) # big-endian float32 array, raw bytes
|
||||
|
||||
preambles = [] # list of raw bytes (length-prefixed strings)
|
||||
if ver >= 3:
|
||||
for _ in range(n_ch):
|
||||
(length,) = struct.unpack(">H", f.read(2))
|
||||
preambles.append(f.read(length))
|
||||
|
||||
background = b"" # raw bytes for the v4 background block
|
||||
if ver >= 4:
|
||||
(n_bg,) = struct.unpack(">I", f.read(4))
|
||||
background = f.read(n_bg)
|
||||
|
||||
raw = f.read() # all waveform data
|
||||
|
||||
# -----------------------------------------------------------------------
|
||||
# Determine actual frame count from file size (the header value can be
|
||||
# wrong — the viewer does the same correction)
|
||||
# -----------------------------------------------------------------------
|
||||
total_samples = len(raw) // bps
|
||||
samples_per_pixel = n_ch * spf # samples in one (angle, row, frame) cell
|
||||
samples_per_full = n_angles * n_rows * samples_per_pixel
|
||||
|
||||
actual_n_frames = total_samples // (n_angles * n_rows * samples_per_pixel)
|
||||
good_bytes = actual_n_frames * samples_per_full * bps
|
||||
|
||||
# Decode waveform data
|
||||
dtype = np.int8 if bps == 1 else ">i2"
|
||||
data = np.frombuffer(raw[:good_bytes], dtype=dtype)
|
||||
data = data.reshape(n_angles, n_rows, n_ch, actual_n_frames, spf)
|
||||
# Work in int16 (safe intermediate for both int8 and int16 inputs)
|
||||
data = data.astype(np.int16)
|
||||
|
||||
return {
|
||||
"ver": ver, "n_angles": n_angles, "n_rows": n_rows,
|
||||
"x_start": x_start, "x_delta": x_delta, "vel": vel, "freq": freq,
|
||||
"n_frames_hdr": n_frames_hdr, "spf": spf, "sr": sr,
|
||||
"bps": bps, "n_ch": n_ch,
|
||||
"angles_raw": angles, "y_pos_raw": y_pos,
|
||||
"preambles": preambles, "background": background,
|
||||
"data": data, # shape: (n_angles, n_rows, n_ch, n_frames, spf), int16
|
||||
}
|
||||
return f.read(sras.data_offset - HDR_SIZE)
|
||||
|
||||
|
||||
def average_frames(data: np.ndarray, n: int, discard_remainder: bool) -> np.ndarray:
|
||||
"""Average every N frames along axis 3.
|
||||
def average_rows(block: np.ndarray, n: int, discard_remainder: bool) -> np.ndarray:
|
||||
"""Average every N frames of one angle's (n_rows, n_ch, n_frames, spf)
|
||||
block. Returns int16 of shape (n_rows, n_ch, n_out, spf).
|
||||
|
||||
data shape: (n_angles, n_rows, n_ch, n_frames, spf)
|
||||
Returns array of shape (n_angles, n_rows, n_ch, n_out, spf).
|
||||
Averaging is done in float32 and rounded on cast, matching numpy's mean
|
||||
followed by an int16 cast in the original implementation.
|
||||
"""
|
||||
n_frames = data.shape[3]
|
||||
|
||||
n_frames = block.shape[2]
|
||||
n_full = n_frames // n
|
||||
remainder = n_frames % n
|
||||
|
||||
# Average full groups using reshape-trick (no Python loop)
|
||||
if n_full > 0:
|
||||
full = data[:, :, :, :n_full * n, :] # trim to full groups
|
||||
full = full.reshape(data.shape[0], data.shape[1], data.shape[2],
|
||||
n_full, n, data.shape[4]) # (..., n_out, n, spf)
|
||||
averaged = full.mean(axis=4).astype(np.int16) # (..., n_out, spf)
|
||||
else:
|
||||
averaged = np.empty((*data.shape[:3], 0, data.shape[4]), dtype=np.int16)
|
||||
parts = []
|
||||
if n_full:
|
||||
full = block[:, :, :n_full * n, :].astype(np.float32)
|
||||
full = full.reshape(block.shape[0], block.shape[1], n_full, n, block.shape[3])
|
||||
parts.append(full.mean(axis=3).astype(np.int16))
|
||||
if remainder and not discard_remainder:
|
||||
tail = block[:, :, n_full * n:, :].astype(np.float32)
|
||||
parts.append(tail.mean(axis=2, keepdims=True).astype(np.int16))
|
||||
|
||||
if remainder > 0 and not discard_remainder:
|
||||
tail = data[:, :, :, n_full * n:, :] # shape (..., remainder, spf)
|
||||
tail_avg = tail.mean(axis=3, keepdims=True).astype(np.int16)
|
||||
averaged = np.concatenate([averaged, tail_avg], axis=3)
|
||||
|
||||
return averaged
|
||||
if not parts:
|
||||
return np.empty((*block.shape[:2], 0, block.shape[3]), dtype=np.int16)
|
||||
return parts[0] if len(parts) == 1 else np.concatenate(parts, axis=2)
|
||||
|
||||
|
||||
def write_sras(path: Path, src: dict, data_out: np.ndarray):
|
||||
"""Write a new .sras file with the averaged waveform data."""
|
||||
ver = src["ver"]
|
||||
bps = src["bps"]
|
||||
n_out = data_out.shape[3]
|
||||
def write_averaged(out_path: Path, sras: SrasFile, mid_sections: bytes,
|
||||
n: int, discard_remainder: bool) -> int:
|
||||
"""Stream each angle through the averager, writing as we go so peak RAM
|
||||
stays at one angle's block rather than the whole file."""
|
||||
bps = sras.bytes_per_sample
|
||||
n_frames_in = int(sras.n_frames[0])
|
||||
n_out = n_frames_in // n
|
||||
if n_frames_in % n and not discard_remainder:
|
||||
n_out += 1
|
||||
|
||||
# Pack header — update only n_frames_hdr; everything else stays the same
|
||||
header = struct.pack(
|
||||
HDR_FMT,
|
||||
b"SRAS",
|
||||
ver,
|
||||
src["n_angles"],
|
||||
src["n_rows"],
|
||||
src["x_start"],
|
||||
src["x_delta"],
|
||||
src["vel"],
|
||||
src["freq"],
|
||||
HDR_FMT, b"SRAS", sras.version, sras.n_angles, int(sras.n_rows[0]),
|
||||
float(sras.x_start_mm[0]), float(sras.x_delta_mm),
|
||||
sras.velocity_mm_s, sras.laser_freq_hz,
|
||||
n_out, # updated frame count
|
||||
src["spf"],
|
||||
src["sr"],
|
||||
bps,
|
||||
src["n_ch"],
|
||||
sras.samples_per_frame, sras.sample_rate_hz, bps, sras.n_channels,
|
||||
)
|
||||
|
||||
# Encode waveform data back to original dtype
|
||||
if bps == 1:
|
||||
raw_out = np.clip(data_out, -128, 127).astype(np.int8).tobytes()
|
||||
else:
|
||||
# big-endian int16
|
||||
raw_out = data_out.astype(">i2").tobytes()
|
||||
|
||||
with open(path, "wb") as f:
|
||||
with open(out_path, "wb") as f:
|
||||
f.write(header)
|
||||
f.write(src["angles_raw"])
|
||||
f.write(src["y_pos_raw"])
|
||||
|
||||
if ver >= 3:
|
||||
for preamble_bytes in src["preambles"]:
|
||||
f.write(struct.pack(">H", len(preamble_bytes)))
|
||||
f.write(preamble_bytes)
|
||||
|
||||
if ver >= 4:
|
||||
bg = src["background"]
|
||||
f.write(struct.pack(">I", len(bg)))
|
||||
f.write(bg)
|
||||
|
||||
f.write(raw_out)
|
||||
f.write(mid_sections)
|
||||
for a in range(sras.n_angles):
|
||||
averaged = average_rows(sras.data[a], n, discard_remainder)
|
||||
if bps == 1:
|
||||
f.write(np.clip(averaged, -128, 127).astype(np.int8).tobytes())
|
||||
else:
|
||||
f.write(averaged.astype(">i2").tobytes())
|
||||
return n_out
|
||||
|
||||
|
||||
def main():
|
||||
@@ -194,26 +118,29 @@ def main():
|
||||
if not in_path.exists():
|
||||
print(f"Error: input file not found: {in_path}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
if out_path.resolve() == in_path.resolve():
|
||||
print("Error: output path must differ from input path.", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
print(f"Reading {in_path} ...", flush=True)
|
||||
src = read_sras(in_path)
|
||||
sras = SrasFile(str(in_path))
|
||||
if sras.version not in _SUPPORTED:
|
||||
print(f"Error: unsupported .sras version: {sras.version} "
|
||||
f"(this tool handles v{'/v'.join(map(str, _SUPPORTED))})",
|
||||
file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
n_frames_in = src["data"].shape[3]
|
||||
print(f" Version : v{src['ver']}")
|
||||
print(f" Angles : {src['n_angles']}")
|
||||
print(f" Rows : {src['n_rows']}")
|
||||
n_frames_in = int(sras.n_frames[0])
|
||||
print(f" Version : v{sras.version}")
|
||||
print(f" Angles : {sras.n_angles}")
|
||||
print(f" Rows : {int(sras.n_rows[0])}")
|
||||
print(f" Frames (actual): {n_frames_in}")
|
||||
print(f" Channels : {src['n_ch']}")
|
||||
print(f" Samples/frame : {src['spf']}")
|
||||
print(f" Bytes/sample : {src['bps']}")
|
||||
print(f" Channels : {sras.n_channels}")
|
||||
print(f" Samples/frame : {sras.samples_per_frame}")
|
||||
print(f" Bytes/sample : {sras.bytes_per_sample}")
|
||||
|
||||
if args.n == 1:
|
||||
print("--n 1: no averaging needed; copying file as-is.")
|
||||
import shutil
|
||||
shutil.copy2(in_path, out_path)
|
||||
print(f"Wrote {out_path}")
|
||||
return
|
||||
@@ -223,27 +150,25 @@ def main():
|
||||
"The entire dataset will be averaged into a single frame.")
|
||||
|
||||
print(f"\nAveraging every {args.n} frames ...", flush=True)
|
||||
data_out = average_frames(src["data"], args.n, args.discard_remainder)
|
||||
n_frames_out = data_out.shape[3]
|
||||
print(f"\nWriting {out_path} ...", flush=True)
|
||||
mid_sections = read_header_sections(sras)
|
||||
n_frames_out = write_averaged(out_path, sras, mid_sections,
|
||||
args.n, args.discard_remainder)
|
||||
|
||||
n_full = n_frames_in // args.n
|
||||
remainder = n_frames_in % args.n
|
||||
if remainder and not args.discard_remainder:
|
||||
status = f"({n_full} full groups + 1 partial group of {remainder})"
|
||||
elif remainder and args.discard_remainder:
|
||||
elif remainder:
|
||||
status = f"({n_full} full groups, {remainder} trailing frames discarded)"
|
||||
else:
|
||||
status = f"({n_full} full groups)"
|
||||
|
||||
print(f" {n_frames_in} frames -> {n_frames_out} frames {status}")
|
||||
|
||||
print(f"\nWriting {out_path} ...", flush=True)
|
||||
write_sras(out_path, src, data_out)
|
||||
|
||||
in_mb = in_path.stat().st_size / 1024**2
|
||||
out_mb = out_path.stat().st_size / 1024**2
|
||||
print(f" Input size : {in_mb:.1f} MB")
|
||||
print(f" Output size: {out_mb:.1f} MB ({out_mb/in_mb*100:.1f}% of input)")
|
||||
print(f" Output size: {out_mb:.1f} MB ({out_mb / in_mb * 100:.1f}% of input)")
|
||||
print("Done.")
|
||||
|
||||
|
||||
|
||||
+1756
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,219 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
sras_edit_scans.py — Remove one or more angle scans from a .sras file.
|
||||
|
||||
A .sras file holds one or more "angles" (rotation positions); the viewer
|
||||
cross-correlates each non-reference angle against the reference to align
|
||||
them. If one angle's acquisition went wrong (stage glitch, bad trigger,
|
||||
laser dropout, ...) it throws off that alignment for the whole file. This
|
||||
tool drops the bad angle(s) and renumbers the rest, writing a new .sras file
|
||||
with everything else — waveform samples, calibration preambles, background
|
||||
waveform, row/geometry tables — carried over byte-for-byte.
|
||||
|
||||
Handles v2-v7. Any precomputed FFT/DC cache (v5 PREC tail, v7 CACH tail) is
|
||||
dropped on write, since it's indexed by angle and would be stale/misaligned
|
||||
after renumbering; the viewer just recomputes it next time the file opens.
|
||||
|
||||
Usage:
|
||||
python sras_edit_scans.py input.sras --list
|
||||
python sras_edit_scans.py input.sras output.sras --drop 2,5
|
||||
python sras_edit_scans.py input.sras output.sras --keep 0,1,3,4,6
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import struct
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
from sras_format import GEO_FMT_V6, HDR_FMT, HDR_FMT_V6, HDR_SIZE, SrasFile
|
||||
|
||||
_LEGACY_VERSIONS = (2, 3, 4, 5)
|
||||
_V6_VERSIONS = (6, 7)
|
||||
|
||||
|
||||
def _die(msg: str):
|
||||
print(f"Error: {msg}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
def parse_args():
|
||||
p = argparse.ArgumentParser(
|
||||
description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
|
||||
p.add_argument("input", help="Input .sras file")
|
||||
p.add_argument("output", nargs="?", help="Output .sras file (omit with --list)")
|
||||
p.add_argument("--list", action="store_true",
|
||||
help="Print each angle's index/degrees/geometry and exit")
|
||||
g = p.add_mutually_exclusive_group()
|
||||
g.add_argument("--drop", metavar="I,J,...",
|
||||
help="Comma-separated angle indices to remove")
|
||||
g.add_argument("--keep", metavar="I,J,...",
|
||||
help="Comma-separated angle indices to keep (all others dropped)")
|
||||
return p.parse_args()
|
||||
|
||||
|
||||
def _parse_index_list(s: str, n_angles: int) -> set[int]:
|
||||
out = set()
|
||||
for piece in s.split(","):
|
||||
piece = piece.strip()
|
||||
if not piece:
|
||||
continue
|
||||
i = int(piece)
|
||||
if not (0 <= i < n_angles):
|
||||
raise ValueError(f"angle index {i} out of range [0, {n_angles - 1}]")
|
||||
out.add(i)
|
||||
return out
|
||||
|
||||
|
||||
def print_listing(sras: SrasFile):
|
||||
print(f"\n{'idx':>4} {'angle_deg':>10} {'x_start_mm':>11} {'rows':>6} {'frames':>7}")
|
||||
for a in range(sras.n_angles):
|
||||
print(f"{a:>4} {sras.angles_deg[a]:>10.4f} {sras.x_start_mm[a]:>11.4f} "
|
||||
f"{int(sras.n_rows[a]):>6} {int(sras.n_frames[a]):>7}")
|
||||
|
||||
|
||||
def _copy_range(fin, fout, offset: int, nbytes: int, chunk: int = 64 * 1024 * 1024):
|
||||
"""Stream *nbytes* raw bytes from *fin* at *offset* into *fout*, without
|
||||
ever holding more than one chunk in memory (waveform blocks can be
|
||||
hundreds of MB to low GB each)."""
|
||||
fin.seek(offset)
|
||||
remaining = nbytes
|
||||
while remaining:
|
||||
buf = fin.read(min(chunk, remaining))
|
||||
if not buf:
|
||||
raise IOError("unexpected EOF while copying waveform data")
|
||||
fout.write(buf)
|
||||
remaining -= len(buf)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Legacy (v2-v5): uniform geometry across angles, one flat waveform block
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def _write_legacy(sras: SrasFile, keep: list[int], out_path: Path):
|
||||
n_rows = int(sras.n_rows[0])
|
||||
n_frames = int(sras.n_frames[0]) # uniform across angles for v2-v5
|
||||
n_ch = sras.n_channels
|
||||
spf = sras.samples_per_frame
|
||||
bps = sras.bytes_per_sample
|
||||
|
||||
header = struct.pack(
|
||||
HDR_FMT, b"SRAS", sras.version, len(keep), n_rows,
|
||||
float(sras.x_start_mm[0]), float(sras.x_delta_mm),
|
||||
sras.velocity_mm_s, sras.laser_freq_hz,
|
||||
n_frames, spf, sras.sample_rate_hz, bps, n_ch,
|
||||
)
|
||||
|
||||
# Row table + preambles + background sit right after the angle table and
|
||||
# don't vary per angle — copy that whole span through unmodified.
|
||||
angle_table_size = sras.n_angles * 4
|
||||
with open(sras.path, "rb") as f:
|
||||
f.seek(HDR_SIZE + angle_table_size)
|
||||
shared_mid = f.read(sras.data_offset - (HDR_SIZE + angle_table_size))
|
||||
|
||||
angle_bytes = n_rows * n_ch * n_frames * spf * bps
|
||||
|
||||
with open(sras.path, "rb") as fin, open(out_path, "wb") as fout:
|
||||
fout.write(header)
|
||||
fout.write(sras.angles_deg[keep].astype(">f4").tobytes())
|
||||
fout.write(shared_mid)
|
||||
for a in keep:
|
||||
_copy_range(fin, fout, sras.data_offset + a * angle_bytes, angle_bytes)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# v6/v7: per-angle geometry, ragged waveform blocks
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def _write_v6(sras: SrasFile, keep: list[int], out_path: Path):
|
||||
header = struct.pack(
|
||||
HDR_FMT_V6, b"SRAS", sras.version, len(keep),
|
||||
sras.x_start_nominal_mm, sras.y_start_nominal_mm,
|
||||
sras.x_delta_nominal_mm, sras.y_delta_nominal_mm,
|
||||
sras.row_spacing_mm, sras.velocity_mm_s, sras.laser_freq_hz,
|
||||
sras.samples_per_frame, sras.sample_rate_hz,
|
||||
sras.bytes_per_sample, sras.n_channels,
|
||||
)
|
||||
|
||||
blocks = {a: (offset, nbytes) for a, offset, nbytes in sras.iter_angle_blocks()}
|
||||
with open(sras.path, "rb") as fin, open(out_path, "wb") as fout:
|
||||
fout.write(header)
|
||||
fout.write(sras.angles_deg[keep].astype(">f4").tobytes())
|
||||
for i in keep:
|
||||
fout.write(struct.pack(
|
||||
GEO_FMT_V6, float(sras.x_start_mm[i]),
|
||||
float(sras.x_delta_mm_per_angle[i]),
|
||||
int(sras.n_frames[i]), int(sras.n_rows[i])))
|
||||
for i in keep:
|
||||
fout.write(sras.y_pos_per_angle[i].astype(">f4").tobytes())
|
||||
fout.write(sras.preambles_raw)
|
||||
fout.write(sras.background_raw)
|
||||
for i in keep:
|
||||
offset, nbytes = blocks[i]
|
||||
_copy_range(fin, fout, offset, nbytes)
|
||||
|
||||
|
||||
def main():
|
||||
args = parse_args()
|
||||
in_path = Path(args.input)
|
||||
if not in_path.exists():
|
||||
_die(f"input file not found: {in_path}")
|
||||
|
||||
print(f"Reading {in_path} ...", flush=True)
|
||||
try:
|
||||
sras = SrasFile(str(in_path))
|
||||
except ValueError as e:
|
||||
_die(str(e))
|
||||
|
||||
if sras.version not in (*_LEGACY_VERSIONS, *_V6_VERSIONS):
|
||||
_die(f"unsupported .sras version: {sras.version}")
|
||||
|
||||
aborted_note = " (scan aborted; trailing angle(s) already excluded)" if sras.scan_aborted else ""
|
||||
print(f" Version : v{sras.version}", flush=True)
|
||||
print(f" Angles : {sras.n_angles}{aborted_note}", flush=True)
|
||||
|
||||
if args.list:
|
||||
print_listing(sras)
|
||||
return
|
||||
|
||||
if not args.output:
|
||||
_die("output path required unless --list is given.")
|
||||
if not (args.drop or args.keep):
|
||||
_die("specify --drop or --keep (see --list for indices).")
|
||||
|
||||
out_path = Path(args.output)
|
||||
if out_path.resolve() == in_path.resolve():
|
||||
_die("output path must differ from input path.")
|
||||
|
||||
try:
|
||||
if args.drop:
|
||||
drop = _parse_index_list(args.drop, sras.n_angles)
|
||||
keep = [a for a in range(sras.n_angles) if a not in drop]
|
||||
else:
|
||||
keep = sorted(_parse_index_list(args.keep, sras.n_angles))
|
||||
except ValueError as e:
|
||||
_die(str(e))
|
||||
|
||||
if not keep:
|
||||
_die("at least one angle must remain.")
|
||||
|
||||
dropped = [a for a in range(sras.n_angles) if a not in keep]
|
||||
print(f"\nDropping angle(s): {dropped}")
|
||||
print(f"Keeping angle(s) : {keep} ({len(keep)} of {sras.n_angles})")
|
||||
print(f"\nWriting {out_path} ...", flush=True)
|
||||
|
||||
if sras.version in _LEGACY_VERSIONS:
|
||||
_write_legacy(sras, keep, out_path)
|
||||
else:
|
||||
_write_v6(sras, keep, out_path)
|
||||
|
||||
in_mb = in_path.stat().st_size / 1024**2
|
||||
out_mb = out_path.stat().st_size / 1024**2
|
||||
print(f" Input size : {in_mb:.1f} MB")
|
||||
print(f" Output size: {out_mb:.1f} MB")
|
||||
print("Done.")
|
||||
print("Note: any precomputed FFT/DC cache was dropped (it's indexed by "
|
||||
"angle); the viewer will recompute it next time this file opens.")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
+691
@@ -0,0 +1,691 @@
|
||||
#!/usr/bin/env python3
|
||||
"""SRAS binary scan file format — parsing and writing.
|
||||
|
||||
Reads v2–v7 .sras files. Depends only on numpy + struct, so compute workers
|
||||
(including multiprocessing children) can import it without pulling in Qt or
|
||||
matplotlib. See scan_format.md for the full v6/v7 spec.
|
||||
|
||||
Channel semantics (fixed by sc3_aui_app.py acquisition settings):
|
||||
CH1 — RF Acoustic Packet (AC-coupled, 100 mV/div): FFT → peak frequency
|
||||
CH3 — Bias A (DC-coupled, 50 mV/div): waveform mean
|
||||
CH4 — Bias B (DC-coupled, 50 mV/div): waveform mean
|
||||
|
||||
Frame-count correction: the scanner writes the *configured* frame count in the
|
||||
header before acquisition, but the scope may acquire fewer frames. The actual
|
||||
count is computed from the file size and used for the reshape so channels are
|
||||
correctly aligned.
|
||||
|
||||
Scan geometry: v6/v7 files scan a different bounding box per angle (x_start,
|
||||
x_delta, n_frames, n_rows all vary by angle), so geometry is exposed per-angle
|
||||
via SrasFile.n_rows / n_frames / x_start_mm arrays and the x_axis_mm() /
|
||||
y_positions_mm() methods. v2–v5 files have uniform geometry across angles, so
|
||||
those arrays simply repeat the same value n_angles times.
|
||||
|
||||
v7 files are v6 files with an optional trailing cache section holding
|
||||
precomputed per-angle DC and/or FFT images, so display never has to recompute
|
||||
them after the "Convert" menu's batch actions have stored them once.
|
||||
"""
|
||||
|
||||
import os
|
||||
import re
|
||||
import struct
|
||||
from pathlib import Path
|
||||
|
||||
import numpy as np
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Format constants
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
# v2–v5: fixed header, uniform geometry across angles (43 bytes)
|
||||
HDR_FMT = ">4sBHHffffIIdBB"
|
||||
HDR_SIZE = struct.calcsize(HDR_FMT)
|
||||
|
||||
# v6/v7: fixed header, per-angle geometry in a separate table (49 bytes)
|
||||
HDR_FMT_V6 = ">4sBHfffffffIdBB"
|
||||
HDR_SIZE_V6 = struct.calcsize(HDR_FMT_V6)
|
||||
|
||||
# v6/v7: per-angle geometry record (x_start, x_delta, n_frames, n_rows)
|
||||
GEO_FMT_V6 = ">ffIH"
|
||||
GEO_SIZE_V6 = struct.calcsize(GEO_FMT_V6)
|
||||
|
||||
# v5 precomputed-image tail
|
||||
PREC_MAGIC = b"PREC"
|
||||
PREC_FLAG_BG_SUB = 0x01
|
||||
|
||||
# v7 cache tail. v7 is byte-identical to v6 (the version byte is the only
|
||||
# header difference) plus this optional trailing section. Sub-block sizes are
|
||||
# per-angle (n_rows[a] * n_frames[a]), taken from the Per-Angle Geometry Table
|
||||
# already parsed for v6 — no new geometry fields are needed.
|
||||
CACH_MAGIC = b"CACH"
|
||||
CACH_HDR_FMT = ">4sBB" # magic, cach_version, block_flags
|
||||
CACH_HDR_SIZE = struct.calcsize(CACH_HDR_FMT)
|
||||
CACH_VERSION = 2 # written on every fresh write
|
||||
CACH_VERSIONS_READABLE = (1, 2) # accepted on read — see
|
||||
# _read_sfft_block: a v1 tail
|
||||
# predates row-averaged FFT
|
||||
# caching and reads as row_avg_n=0
|
||||
CACH_FLAG_DC = 0x01
|
||||
CACH_FLAG_FFT = 0x02
|
||||
|
||||
SDCB_MAGIC = b"SDCB"
|
||||
SDCB_HDR_FMT = ">4sBH" # magic, reserved, n_stored
|
||||
SDCB_HDR_SIZE = struct.calcsize(SDCB_HDR_FMT)
|
||||
|
||||
SFFT_MAGIC = b"SFFT"
|
||||
SFFT_HDR_FMT_V1 = ">4sBH" # magic, flags, n_stored (cach_version 1)
|
||||
SFFT_HDR_FMT = ">4sBHB" # + row_avg_n (cach_version 2)
|
||||
SFFT_HDR_SIZE_V1 = struct.calcsize(SFFT_HDR_FMT_V1)
|
||||
SFFT_HDR_SIZE = struct.calcsize(SFFT_HDR_FMT)
|
||||
SFFT_FLAG_BG_SUB = 0x01
|
||||
SFFT_FLAG_ROW_AVG = 0x02 # peak_freq_mhz came from same-row,
|
||||
# distance-weighted averaged CH1
|
||||
# waveforms, not raw per-pixel ones;
|
||||
# row_avg_n is the neighbor half-width
|
||||
# (pixels) used. Bits 2-7 reserved.
|
||||
|
||||
# Fixed channel indices into the .sras data array (CH1=RF, CH3/CH4=Bias DC)
|
||||
CH1_IDX, CH3_IDX, CH4_IDX = 0, 1, 2
|
||||
CH_NAMES = ["CH1", "CH3", "CH4", "VEL"]
|
||||
|
||||
# Fallback scope calibration used only when reading v2 files without embedded
|
||||
# preambles. v3+ files carry the WFMOutpre string so these are not used.
|
||||
# 50 mV/div, 8 div full-scale, int8 ADC, position = -2.72 div
|
||||
# ymult = 50 mV × 8 / 256 = 1.5625 mV/count
|
||||
# yoff = position × (256/8) = -2.72 × 32 = -87.04 (ADC count for 0 V)
|
||||
_FALLBACK_YMULT_MV = 1.5625 # mV per ADC count
|
||||
_FALLBACK_YOFF_ADC = -87.04 # ADC count that represents 0 V
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Calibration
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def _parse_preamble(preamble: str) -> dict[str, float]:
|
||||
"""Extract YMULT, YOFF, YZERO from a Tektronix WFMOutpre string.
|
||||
|
||||
Returns a dict with float values for whichever keys are present.
|
||||
YMULT is left in V/count as the scope reports it.
|
||||
"""
|
||||
result = {}
|
||||
for key in ("YMULT", "YOFF", "YZERO"):
|
||||
m = re.search(rf'\b{key}\s+([-+]?\d*\.?\d+(?:[Ee][+-]?\d+)?)', preamble)
|
||||
if m:
|
||||
result[key] = float(m.group(1))
|
||||
return result
|
||||
|
||||
|
||||
def mv_to_adc(mv: float, ymult_mv: float = _FALLBACK_YMULT_MV,
|
||||
yoff_adc: float = _FALLBACK_YOFF_ADC,
|
||||
yzero_mv: float = 0.0) -> float:
|
||||
return (mv - yzero_mv) / ymult_mv + yoff_adc
|
||||
|
||||
|
||||
def adc_to_mv(adc, ymult_mv: float = _FALLBACK_YMULT_MV,
|
||||
yoff_adc: float = _FALLBACK_YOFF_ADC,
|
||||
yzero_mv: float = 0.0):
|
||||
return (adc - yoff_adc) * ymult_mv + yzero_mv
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Binary read helpers
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def _read_struct(f, fmt: str) -> tuple:
|
||||
return struct.unpack(fmt, f.read(struct.calcsize(fmt)))
|
||||
|
||||
|
||||
def _read_preambles(f, n_ch: int) -> list[str]:
|
||||
"""n_ch length-prefixed UTF-8 WFMOutpre strings."""
|
||||
out = []
|
||||
for _ in range(n_ch):
|
||||
(length,) = _read_struct(f, ">H")
|
||||
out.append(f.read(length).decode("utf-8"))
|
||||
return out
|
||||
|
||||
|
||||
def _read_background(f) -> np.ndarray:
|
||||
"""uint32 sample count followed by that many int8 samples."""
|
||||
(n_bg,) = _read_struct(f, ">I")
|
||||
return np.frombuffer(f.read(n_bg), dtype=np.int8).astype(np.float32)
|
||||
|
||||
|
||||
def _read_f32_image(f, shape: tuple[int, int]) -> np.ndarray:
|
||||
"""One big-endian float32 image, converted to native float32.
|
||||
|
||||
The conversion matters: np.frombuffer hands back a read-only big-endian
|
||||
view, and these arrays flow straight into the display caches and every
|
||||
downstream arithmetic op.
|
||||
"""
|
||||
n_bytes = shape[0] * shape[1] * 4
|
||||
return np.frombuffer(f.read(n_bytes), dtype=">f4").reshape(shape).astype(np.float32)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# File parser
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class SrasFile:
|
||||
"""Parsed in-memory representation of a v2–v7 .sras file.
|
||||
|
||||
Scan geometry (rows, frames, x_start) is exposed per-angle via the
|
||||
``n_rows`` / ``n_frames`` / ``x_start_mm`` arrays and the ``x_axis_mm()``
|
||||
/ ``y_positions_mm()`` methods, since v6/v7 files scan a different
|
||||
bounding box per angle. v2–v5 files have uniform geometry, so these
|
||||
arrays just repeat the same value ``n_angles`` times. Waveform data is
|
||||
likewise exposed as ``data[angle_idx]``, an array of shape
|
||||
``(n_rows[a], n_channels, n_frames[a], samples_per_frame)``.
|
||||
|
||||
Precomputed images (v5's PREC tail or v7's CACH tail) are exposed as
|
||||
``precomputed_dc3_mv`` / ``precomputed_dc4_mv`` / ``precomputed_freq_mhz``,
|
||||
always as ragged per-angle lists (``list[np.ndarray | None]``, one entry
|
||||
per angle, ``None`` where that angle was never stored) regardless of
|
||||
source version.
|
||||
"""
|
||||
|
||||
def __init__(self, path: str):
|
||||
self.path = Path(path)
|
||||
self._parse()
|
||||
|
||||
def _parse(self):
|
||||
with open(self.path, "rb") as f:
|
||||
magic = f.read(4)
|
||||
if magic != b"SRAS":
|
||||
raise ValueError(f"Bad magic bytes: {magic!r}")
|
||||
(version,) = struct.unpack(">B", f.read(1))
|
||||
|
||||
self.version = version
|
||||
if version in (2, 3, 4, 5):
|
||||
self._parse_legacy()
|
||||
elif version in (6, 7):
|
||||
self._parse_v6()
|
||||
else:
|
||||
raise ValueError(f"Unsupported version: {version}")
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Calibration
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def _set_calibration(self, preambles: list[str] | None, n_ch: int):
|
||||
"""Populate the per-channel ymult/yoff/yzero lists from preamble
|
||||
strings, falling back to the hardcoded scope constants for v2 files
|
||||
that carry no preambles."""
|
||||
if preambles is None:
|
||||
self.preambles = None
|
||||
self.ch_ymult_mv = [_FALLBACK_YMULT_MV] * n_ch
|
||||
self.ch_yoff_adc = [_FALLBACK_YOFF_ADC] * n_ch
|
||||
self.ch_yzero_mv = [0.0] * n_ch
|
||||
return
|
||||
|
||||
self.preambles = preambles
|
||||
self.ch_ymult_mv, self.ch_yoff_adc, self.ch_yzero_mv = [], [], []
|
||||
for p in preambles:
|
||||
cal = _parse_preamble(p)
|
||||
# The scope reports YMULT and YZERO in volts; store both as mV.
|
||||
self.ch_ymult_mv.append(cal.get("YMULT", _FALLBACK_YMULT_MV / 1000) * 1000)
|
||||
self.ch_yoff_adc.append(cal.get("YOFF", _FALLBACK_YOFF_ADC))
|
||||
self.ch_yzero_mv.append(cal.get("YZERO", 0.0) * 1000)
|
||||
|
||||
def cal(self, ch_idx: int) -> tuple[float, float, float]:
|
||||
"""(ymult_mv, yoff_adc, yzero_mv) for one channel — splat straight
|
||||
into adc_to_mv / mv_to_adc."""
|
||||
return (self.ch_ymult_mv[ch_idx], self.ch_yoff_adc[ch_idx],
|
||||
self.ch_yzero_mv[ch_idx])
|
||||
|
||||
def _init_precomputed(self, n_angles: int):
|
||||
self.precomputed_freq_mhz: list[np.ndarray | None] = [None] * n_angles
|
||||
self.precomputed_dc4_mv: list[np.ndarray | None] = [None] * n_angles
|
||||
self.precomputed_dc3_mv: list[np.ndarray | None] = [None] * n_angles
|
||||
self.precomputed_bg_sub: bool = False
|
||||
self.precomputed_row_avg_n: int = 0
|
||||
|
||||
def cached_dc_mv(self, angle_idx: int, ch_idx: int) -> np.ndarray | None:
|
||||
"""A stored DC image (already in mV) for (angle, channel), or None."""
|
||||
store = self.precomputed_dc3_mv if ch_idx == CH3_IDX else self.precomputed_dc4_mv
|
||||
return store[angle_idx] if angle_idx < len(store) else None
|
||||
|
||||
def image_shape(self, angle_idx: int) -> tuple[int, int]:
|
||||
return int(self.n_rows[angle_idx]), int(self.n_frames[angle_idx])
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# v2–v5 parsing (uniform geometry, flat waveform block)
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def _parse_legacy(self):
|
||||
with open(self.path, "rb") as f:
|
||||
(magic, ver, n_angles, n_rows, x_start, x_delta, vel, freq,
|
||||
n_frames_hdr, spf, sr, bps, n_ch) = _read_struct(f, HDR_FMT)
|
||||
|
||||
self.n_angles = n_angles
|
||||
self.velocity_mm_s = float(vel)
|
||||
self.laser_freq_hz = float(freq)
|
||||
self.n_frames_header = n_frames_hdr # configured count (may be wrong)
|
||||
self.samples_per_frame = spf
|
||||
self.sample_rate_hz = float(sr)
|
||||
self.bytes_per_sample = bps
|
||||
self.n_channels = n_ch
|
||||
|
||||
self._init_precomputed(n_angles)
|
||||
self.scan_aborted = False
|
||||
self.n_angles_declared = n_angles
|
||||
|
||||
angles = np.frombuffer(f.read(n_angles * 4), dtype=">f4").astype(np.float32)
|
||||
y_pos = np.frombuffer(f.read(n_rows * 4), dtype=">f4").astype(np.float32)
|
||||
|
||||
self._set_calibration(_read_preambles(f, n_ch) if ver >= 3 else None, n_ch)
|
||||
self.background = _read_background(f) if ver >= 4 else None
|
||||
|
||||
# Record where raw waveform data begins; np.memmap maps from here.
|
||||
data_offset = f.tell()
|
||||
|
||||
# ---- Determine actual frame count from file size ---------------
|
||||
# For v4 and earlier the header n_frames may be the *configured*
|
||||
# count before acquisition; the actual count is derived from the
|
||||
# bytes on disk. For v5 files a PREC tail follows the waveform
|
||||
# data, so we must not include those extra bytes in the frame count.
|
||||
file_size = self.path.stat().st_size
|
||||
samples_per_row_per_ch = n_ch * spf
|
||||
available_bytes = file_size - data_offset
|
||||
|
||||
if ver == 5:
|
||||
actual_n_frames = n_frames_hdr
|
||||
remainder = 0
|
||||
else:
|
||||
total_samples = available_bytes // bps
|
||||
per_frame = n_angles * n_rows * samples_per_row_per_ch
|
||||
actual_n_frames = total_samples // per_frame
|
||||
remainder = total_samples % per_frame
|
||||
|
||||
self.frame_count_mismatch = (actual_n_frames != n_frames_hdr)
|
||||
self.n_frames_remainder = remainder
|
||||
|
||||
# ---- Memory-map the waveform data (zero RAM cost) --------------
|
||||
# Instead of f.read() → astype() (which peaks at 2× file size),
|
||||
# memmap lets the OS page only the bytes that are actually touched.
|
||||
data5d = np.memmap(
|
||||
str(self.path),
|
||||
dtype=np.int8 if bps == 1 else ">i2",
|
||||
mode="r",
|
||||
offset=data_offset,
|
||||
shape=(n_angles, n_rows, n_ch, actual_n_frames, spf),
|
||||
)
|
||||
# Expose as a list of per-angle views so downstream code shares one
|
||||
# indexing convention with v6: sras.data[a][row, ch, frame, sample]
|
||||
self.data = [data5d[a] for a in range(n_angles)]
|
||||
|
||||
# Uniform per-angle geometry, repeated so callers don't need to
|
||||
# special-case legacy vs. v6 files.
|
||||
self.n_rows = np.full(n_angles, n_rows, dtype=np.int64)
|
||||
self.n_frames = np.full(n_angles, actual_n_frames, dtype=np.int64)
|
||||
self.x_start_mm = np.full(n_angles, float(x_start), dtype=np.float64)
|
||||
self.x_delta_mm = float(x_delta) # reference only; kept for re-encode
|
||||
self._y_pos_per_angle = [y_pos] * n_angles
|
||||
self.angles_deg = angles
|
||||
self._data_offset = data_offset
|
||||
|
||||
if ver >= 5:
|
||||
waveform_bytes = actual_n_frames * n_angles * n_rows * n_ch * spf * bps
|
||||
prec_offset = data_offset + waveform_bytes
|
||||
if file_size > prec_offset:
|
||||
self._parse_prec_section(prec_offset)
|
||||
|
||||
def _parse_prec_section(self, offset: int):
|
||||
"""Parse the v5 PREC tail that holds precomputed images.
|
||||
|
||||
Stored per-angle as (freq, dc4, dc3), each a full-image float32
|
||||
block prefixed by its uint16 angle index.
|
||||
"""
|
||||
with open(self.path, "rb") as f:
|
||||
f.seek(offset)
|
||||
header_raw = f.read(6) # magic(4) + fmt_ver(1) + flags(1)
|
||||
if len(header_raw) < 6 or header_raw[:4] != PREC_MAGIC:
|
||||
return
|
||||
self.precomputed_bg_sub = bool(header_raw[5] & PREC_FLAG_BG_SUB)
|
||||
|
||||
(n_stored,) = _read_struct(f, ">H")
|
||||
for _ in range(n_stored):
|
||||
(aidx,) = _read_struct(f, ">H")
|
||||
if aidx >= self.n_angles:
|
||||
break
|
||||
shape = self.image_shape(aidx)
|
||||
self.precomputed_freq_mhz[aidx] = _read_f32_image(f, shape)
|
||||
self.precomputed_dc4_mv[aidx] = _read_f32_image(f, shape)
|
||||
self.precomputed_dc3_mv[aidx] = _read_f32_image(f, shape)
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# v6/v7 parsing (per-angle geometry, ragged waveform blocks)
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def _parse_v6(self):
|
||||
with open(self.path, "rb") as f:
|
||||
(magic, ver, n_angles, x_start_nom, y_start_nom, x_delta_nom,
|
||||
y_delta_nom, row_spacing, vel, freq, spf, sr, bps,
|
||||
n_ch) = _read_struct(f, HDR_FMT_V6)
|
||||
|
||||
n_angles_declared = n_angles
|
||||
|
||||
self.velocity_mm_s = float(vel)
|
||||
self.laser_freq_hz = float(freq)
|
||||
self.samples_per_frame = spf
|
||||
self.sample_rate_hz = float(sr)
|
||||
self.bytes_per_sample = bps
|
||||
self.n_channels = n_ch
|
||||
|
||||
# Reference-only fields: the ROI as entered before per-angle
|
||||
# bounding-box expansion. Actual per-angle geometry used for
|
||||
# rendering comes from the Per-Angle Geometry Table below.
|
||||
self.x_start_nominal_mm = float(x_start_nom)
|
||||
self.y_start_nominal_mm = float(y_start_nom)
|
||||
self.x_delta_nominal_mm = float(x_delta_nom)
|
||||
self.y_delta_nominal_mm = float(y_delta_nom)
|
||||
self.row_spacing_mm = float(row_spacing)
|
||||
|
||||
self.n_frames_header = None
|
||||
self.frame_count_mismatch = False
|
||||
self.n_frames_remainder = 0
|
||||
|
||||
angles = np.frombuffer(f.read(n_angles * 4), dtype=">f4").astype(np.float32)
|
||||
|
||||
x_start = np.empty(n_angles, dtype=np.float64)
|
||||
x_delta = np.empty(n_angles, dtype=np.float64)
|
||||
n_frames = np.empty(n_angles, dtype=np.int64)
|
||||
n_rows = np.empty(n_angles, dtype=np.int64)
|
||||
for a in range(n_angles):
|
||||
xs, xd, nf, nr = _read_struct(f, GEO_FMT_V6)
|
||||
x_start[a], x_delta[a], n_frames[a], n_rows[a] = xs, xd, nf, nr
|
||||
|
||||
y_pos_per_angle = [
|
||||
np.frombuffer(f.read(int(n_rows[a]) * 4), dtype=">f4").astype(np.float32)
|
||||
for a in range(n_angles)
|
||||
]
|
||||
|
||||
# Verbatim on-disk spans of the preamble and background sections,
|
||||
# kept so file-rewriting tools (sras_edit_scans) can carry them
|
||||
# over byte-for-byte without re-parsing.
|
||||
span_start = f.tell()
|
||||
self._set_calibration(_read_preambles(f, n_ch), n_ch)
|
||||
span_end = f.tell()
|
||||
f.seek(span_start)
|
||||
self.preambles_raw = f.read(span_end - span_start)
|
||||
|
||||
span_start = span_end
|
||||
self.background = _read_background(f)
|
||||
span_end = f.tell()
|
||||
f.seek(span_start)
|
||||
self.background_raw = f.read(span_end - span_start)
|
||||
|
||||
data_offset = span_end
|
||||
|
||||
self._data_offset = data_offset
|
||||
|
||||
# ---- Memory-map each angle's ragged waveform block -------------
|
||||
# v6 gives each angle its own row/frame count, so waveform data is
|
||||
# no longer one uniform (n_angles, n_rows, ...) block — each angle's
|
||||
# block sits at a different offset with its own shape. An aborted
|
||||
# scan truncates the file mid-angle; per the format spec we keep
|
||||
# whatever complete angles are present rather than refusing to open
|
||||
# the file.
|
||||
file_size = self.path.stat().st_size
|
||||
waveform_dtype = np.int8 if bps == 1 else ">i2"
|
||||
|
||||
data = []
|
||||
offset = data_offset
|
||||
for a in range(n_angles):
|
||||
nr, nf = int(n_rows[a]), int(n_frames[a])
|
||||
nbytes = nr * n_ch * nf * spf * bps
|
||||
if offset + nbytes > file_size:
|
||||
break
|
||||
data.append(np.memmap(
|
||||
str(self.path), dtype=waveform_dtype, mode="r",
|
||||
offset=offset, shape=(nr, n_ch, nf, spf),
|
||||
))
|
||||
offset += nbytes
|
||||
|
||||
n_complete = len(data)
|
||||
if n_complete == 0:
|
||||
raise ValueError(
|
||||
"v6 file has no complete angle blocks — scan was aborted "
|
||||
"before the first angle finished.")
|
||||
|
||||
self.data = data
|
||||
self.n_angles = n_complete
|
||||
self.n_angles_declared = n_angles_declared
|
||||
self.scan_aborted = n_complete < n_angles_declared
|
||||
self.angles_deg = angles[:n_complete]
|
||||
self.x_start_mm = x_start[:n_complete]
|
||||
self.x_delta_mm_per_angle = x_delta[:n_complete]
|
||||
self.n_frames = n_frames[:n_complete]
|
||||
self.n_rows = n_rows[:n_complete]
|
||||
self._y_pos_per_angle = y_pos_per_angle[:n_complete]
|
||||
|
||||
self._init_precomputed(n_complete)
|
||||
if self.version == 7 and offset < file_size:
|
||||
self._parse_cach_section(offset)
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Byte-layout accessors (public: used by file-rewriting tools)
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
@property
|
||||
def data_offset(self) -> int:
|
||||
"""File offset where the waveform data begins (headers end)."""
|
||||
return self._data_offset
|
||||
|
||||
@property
|
||||
def y_pos_per_angle(self) -> list[np.ndarray]:
|
||||
"""Per-angle Y row positions (mm). The list and its arrays are the
|
||||
live parsed state — tools that reproject may replace entries."""
|
||||
return self._y_pos_per_angle
|
||||
|
||||
@y_pos_per_angle.setter
|
||||
def y_pos_per_angle(self, value: list[np.ndarray]):
|
||||
self._y_pos_per_angle = value
|
||||
|
||||
def iter_angle_blocks(self):
|
||||
"""Yields (angle_idx, byte_offset, byte_count) for each complete
|
||||
angle's waveform block. Works for every version: legacy files have
|
||||
uniform per-angle geometry, so the same walk applies."""
|
||||
offset = self._data_offset
|
||||
for a in range(self.n_angles):
|
||||
nbytes = (int(self.n_rows[a]) * self.n_channels
|
||||
* int(self.n_frames[a]) * self.samples_per_frame
|
||||
* self.bytes_per_sample)
|
||||
yield a, offset, nbytes
|
||||
offset += nbytes
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# v7 cache tail (CACH section: precomputed DC / FFT images)
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def _cache_tail_offset(self) -> int:
|
||||
"""Deterministic file offset where the CACH tail starts (or would
|
||||
start), derived purely from the header + Per-Angle Geometry Table —
|
||||
independent of whether a cache tail is actually present. Used by
|
||||
both the parser and the in-place writer."""
|
||||
end = self._data_offset
|
||||
for _, offset, nbytes in self.iter_angle_blocks():
|
||||
end = offset + nbytes
|
||||
return end
|
||||
|
||||
def _read_cache_block(self, f, hdr_fmt: str, magic: bytes,
|
||||
stores: list[list]) -> int | None:
|
||||
"""Read one CACH sub-block header, then its per-angle image entries
|
||||
into *stores* (one list per image the block stores per angle).
|
||||
|
||||
Returns the header's flags byte, or None if the block is malformed.
|
||||
"""
|
||||
raw = f.read(struct.calcsize(hdr_fmt))
|
||||
if len(raw) < struct.calcsize(hdr_fmt):
|
||||
return None
|
||||
block_magic, flags, n_stored = struct.unpack(hdr_fmt, raw)
|
||||
if block_magic != magic:
|
||||
return None
|
||||
for _ in range(n_stored):
|
||||
(angle_idx,) = _read_struct(f, ">H")
|
||||
if angle_idx >= self.n_angles:
|
||||
break
|
||||
shape = self.image_shape(angle_idx)
|
||||
for store in stores:
|
||||
store[angle_idx] = _read_f32_image(f, shape)
|
||||
return flags
|
||||
|
||||
def _read_sfft_block(self, f, cach_version: int) -> tuple[int, int] | None:
|
||||
"""Read the SFFT block header — its layout depends on cach_version,
|
||||
since v2 appended a trailing row_avg_n byte — then n_stored per-angle
|
||||
peak_freq_mhz entries (unchanged across versions).
|
||||
|
||||
Returns (flags, row_avg_n), or None if the block is malformed.
|
||||
row_avg_n is always 0 for a v1 tail, which predates row-averaged FFT
|
||||
caching entirely.
|
||||
"""
|
||||
hdr_fmt = SFFT_HDR_FMT_V1 if cach_version == 1 else SFFT_HDR_FMT
|
||||
raw = f.read(struct.calcsize(hdr_fmt))
|
||||
if len(raw) < struct.calcsize(hdr_fmt):
|
||||
return None
|
||||
if cach_version == 1:
|
||||
magic, flags, n_stored = struct.unpack(hdr_fmt, raw)
|
||||
row_avg_n = 0
|
||||
else:
|
||||
magic, flags, n_stored, row_avg_n = struct.unpack(hdr_fmt, raw)
|
||||
if magic != SFFT_MAGIC:
|
||||
return None
|
||||
for _ in range(n_stored):
|
||||
(angle_idx,) = _read_struct(f, ">H")
|
||||
if angle_idx >= self.n_angles:
|
||||
break
|
||||
self.precomputed_freq_mhz[angle_idx] = _read_f32_image(
|
||||
f, self.image_shape(angle_idx))
|
||||
return flags, row_avg_n
|
||||
|
||||
def _parse_cach_section(self, offset: int):
|
||||
"""Parse the v7 CACH tail that holds precomputed DC/FFT images."""
|
||||
with open(self.path, "rb") as f:
|
||||
f.seek(offset)
|
||||
header_raw = f.read(CACH_HDR_SIZE)
|
||||
if len(header_raw) < CACH_HDR_SIZE:
|
||||
return
|
||||
magic, cach_version, block_flags = struct.unpack(CACH_HDR_FMT, header_raw)
|
||||
if magic != CACH_MAGIC or cach_version not in CACH_VERSIONS_READABLE:
|
||||
return
|
||||
|
||||
if block_flags & CACH_FLAG_DC:
|
||||
if self._read_cache_block(
|
||||
f, SDCB_HDR_FMT, SDCB_MAGIC,
|
||||
[self.precomputed_dc3_mv, self.precomputed_dc4_mv]) is None:
|
||||
return
|
||||
|
||||
if block_flags & CACH_FLAG_FFT:
|
||||
result = self._read_sfft_block(f, cach_version)
|
||||
if result is None:
|
||||
return
|
||||
flags, row_avg_n = result
|
||||
self.precomputed_bg_sub = bool(flags & SFFT_FLAG_BG_SUB)
|
||||
self.precomputed_row_avg_n = row_avg_n if (flags & SFFT_FLAG_ROW_AVG) else 0
|
||||
|
||||
def write_v7_cache(self, *,
|
||||
new_dc3_mv: list[np.ndarray | None] | None = None,
|
||||
new_dc4_mv: list[np.ndarray | None] | None = None,
|
||||
new_freq_mhz: list[np.ndarray | None] | None = None,
|
||||
new_bg_sub: bool | None = None,
|
||||
new_row_avg_n: int | None = None):
|
||||
"""Store computed DC and/or FFT images into this file's CACH tail,
|
||||
in place, converting a v6 source to v7 (or updating an existing v7
|
||||
file). Only the block(s) passed in are recomputed; whichever block
|
||||
isn't passed is carried forward unchanged from whatever this
|
||||
``SrasFile`` already has in memory (from parsing, or a prior write
|
||||
in this same session) — its bytes are never re-read from disk.
|
||||
|
||||
*new_row_avg_n* is the same-row neighbor half-width (pixels) the
|
||||
passed *new_freq_mhz* was averaged over before its FFT, 0 for a raw
|
||||
(unaveraged) compute — carried forward like *new_bg_sub* when None.
|
||||
It describes the whole stored FFT block, not per-angle, mirroring
|
||||
how bg-sub has never been tracked per-angle either.
|
||||
|
||||
The waveform data itself is never touched: the cache tail always
|
||||
starts at ``_cache_tail_offset()``, a fixed offset derived from the
|
||||
header and geometry table alone.
|
||||
"""
|
||||
if self.version not in (6, 7):
|
||||
raise ValueError(
|
||||
f"write_v7_cache only supports v6/v7 source files, got v{self.version}")
|
||||
|
||||
final_dc3 = new_dc3_mv if new_dc3_mv is not None else self.precomputed_dc3_mv
|
||||
final_dc4 = new_dc4_mv if new_dc4_mv is not None else self.precomputed_dc4_mv
|
||||
final_freq = new_freq_mhz if new_freq_mhz is not None else self.precomputed_freq_mhz
|
||||
final_bg_sub = new_bg_sub if new_bg_sub is not None else self.precomputed_bg_sub
|
||||
final_row_avg_n = (new_row_avg_n if new_row_avg_n is not None
|
||||
else self.precomputed_row_avg_n)
|
||||
if not (0 <= final_row_avg_n <= 255):
|
||||
raise ValueError(f"row_avg_n must fit in a byte (0-255), got {final_row_avg_n}")
|
||||
|
||||
dc_entries = [a for a in range(self.n_angles) if final_dc3[a] is not None]
|
||||
fft_entries = [a for a in range(self.n_angles) if final_freq[a] is not None]
|
||||
|
||||
block_flags = ((CACH_FLAG_DC if dc_entries else 0)
|
||||
| (CACH_FLAG_FFT if fft_entries else 0))
|
||||
|
||||
payload = bytearray()
|
||||
payload += struct.pack(CACH_HDR_FMT, CACH_MAGIC, CACH_VERSION, block_flags)
|
||||
|
||||
if dc_entries:
|
||||
payload += struct.pack(SDCB_HDR_FMT, SDCB_MAGIC, 0, len(dc_entries))
|
||||
for a in dc_entries:
|
||||
payload += struct.pack(">H", a)
|
||||
payload += final_dc3[a].astype(">f4").tobytes()
|
||||
payload += final_dc4[a].astype(">f4").tobytes()
|
||||
|
||||
if fft_entries:
|
||||
fft_flags = SFFT_FLAG_BG_SUB if final_bg_sub else 0
|
||||
fft_flags |= SFFT_FLAG_ROW_AVG if final_row_avg_n else 0
|
||||
payload += struct.pack(SFFT_HDR_FMT, SFFT_MAGIC, fft_flags,
|
||||
len(fft_entries), final_row_avg_n)
|
||||
for a in fft_entries:
|
||||
payload += struct.pack(">H", a)
|
||||
payload += final_freq[a].astype(">f4").tobytes()
|
||||
|
||||
with open(self.path, "r+b") as f:
|
||||
f.seek(self._cache_tail_offset())
|
||||
f.write(payload)
|
||||
f.truncate()
|
||||
f.flush()
|
||||
os.fsync(f.fileno())
|
||||
# Version-byte flip last: if the process dies before this point,
|
||||
# the file is still readable as plain v6 (v6 parsing only
|
||||
# bounds-checks per-angle offset+nbytes <= file_size, it never
|
||||
# asserts exactly how many bytes follow the last angle) — so an
|
||||
# interrupted write can never corrupt the file, only leave
|
||||
# harmless trailing bytes that the next successful write
|
||||
# overwrites via this same deterministic cache offset.
|
||||
f.seek(4)
|
||||
f.write(struct.pack("B", 7))
|
||||
f.flush()
|
||||
os.fsync(f.fileno())
|
||||
|
||||
self.version = 7
|
||||
self.precomputed_dc3_mv = final_dc3
|
||||
self.precomputed_dc4_mv = final_dc4
|
||||
self.precomputed_freq_mhz = final_freq
|
||||
self.precomputed_bg_sub = final_bg_sub
|
||||
self.precomputed_row_avg_n = final_row_avg_n
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Axes helpers
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
@property
|
||||
def pixel_x_mm(self) -> float:
|
||||
return self.velocity_mm_s / self.laser_freq_hz
|
||||
|
||||
def x_axis_mm(self, angle_idx: int) -> np.ndarray:
|
||||
n = int(self.n_frames[angle_idx])
|
||||
return self.x_start_mm[angle_idx] + np.arange(n) * self.pixel_x_mm
|
||||
|
||||
def y_positions_mm(self, angle_idx: int) -> np.ndarray:
|
||||
return self._y_pos_per_angle[angle_idx]
|
||||
|
||||
def time_axis_ns(self) -> np.ndarray:
|
||||
return np.arange(self.samples_per_frame) / self.sample_rate_hz * 1e9
|
||||
|
||||
def freq_axis_mhz(self, n_fft: int | None = None) -> np.ndarray:
|
||||
n = n_fft if n_fft is not None else self.samples_per_frame
|
||||
return np.fft.rfftfreq(n, d=1.0 / self.sample_rate_hz) / 1e6
|
||||
-2352
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,26 @@
|
||||
"""
|
||||
SRAS Scan File Viewer
|
||||
PyQt6 application for visualizing channel data from .sras binary scan files.
|
||||
|
||||
Channel semantics (fixed by sc3_aui_app.py acquisition settings):
|
||||
CH1 — RF Acoustic Packet (AC-coupled, 100 mV/div): FFT → peak frequency
|
||||
CH3 — Bias A (DC-coupled, 50 mV/div): waveform mean
|
||||
CH4 — Bias B (DC-coupled, 50 mV/div): waveform mean
|
||||
|
||||
RF images are masked: pixels where CH4_dc < dc_threshold show 0.
|
||||
|
||||
File parsing lives in sras_format, image/alignment math in sras_compute, and
|
||||
background workers in sras_workers — none of which import Qt or matplotlib,
|
||||
so multiprocessing children can load them cheaply.
|
||||
"""
|
||||
|
||||
import faulthandler
|
||||
|
||||
faulthandler.enable() # print a native stack trace on SIGSEGV/SIGABRT/etc.
|
||||
|
||||
from .canvases import ImageCanvas, RoiQuad, WaveformCanvas # noqa: E402,F401
|
||||
from .common import CH_LABELS, CMAPS, VELOCITY_MODE_IDX # noqa: E402,F401
|
||||
from .dialogs import ( # noqa: E402,F401
|
||||
FftOptionsDialog, ManualAlignmentDialog, RowAverageFftOptionsDialog,
|
||||
)
|
||||
from .main_window import SrasViewerWindow, main # noqa: E402,F401
|
||||
@@ -0,0 +1,4 @@
|
||||
from .main_window import main
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,542 @@
|
||||
"""Matplotlib canvases and the ROI primitive."""
|
||||
|
||||
import numpy as np
|
||||
from matplotlib.backends.backend_qtagg import FigureCanvasQTAgg
|
||||
from matplotlib.figure import Figure
|
||||
from matplotlib.patches import Polygon
|
||||
from matplotlib.path import Path as MplPath
|
||||
from PyQt6.QtCore import Qt, pyqtSignal
|
||||
from PyQt6.QtGui import QKeyEvent
|
||||
from PyQt6.QtWidgets import QSizePolicy
|
||||
|
||||
from sras_format import CH1_IDX, CH3_IDX, CH4_IDX, CH_NAMES, SrasFile, adc_to_mv
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# ROI (free quadrilateral in data coordinates)
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class RoiQuad:
|
||||
"""Free quadrilateral defined in data coordinates (mm).
|
||||
|
||||
Stored as 4 corner points (shape (4, 2)) in CCW order: BL, BR, TR, TL.
|
||||
Each corner can be positioned independently, allowing skewed /
|
||||
non-orthogonal regions of interest. Because it lives in scan/data
|
||||
coords it persists unchanged when the displayed channel/mode switches.
|
||||
"""
|
||||
|
||||
def __init__(self, pts: np.ndarray):
|
||||
"""pts : array-like, shape (4, 2)."""
|
||||
self._pts = np.asarray(pts, dtype=np.float64).reshape(4, 2).copy()
|
||||
|
||||
@classmethod
|
||||
def from_bbox(cls, x0: float, y0: float, x1: float, y1: float) -> "RoiQuad":
|
||||
"""Create an axis-aligned rectangle from two opposite corners."""
|
||||
lx, rx = min(x0, x1), max(x0, x1)
|
||||
by, ty = min(y0, y1), max(y0, y1)
|
||||
return cls(np.array([[lx, by], [rx, by], [rx, ty], [lx, ty]]))
|
||||
|
||||
def copy(self) -> "RoiQuad":
|
||||
return RoiQuad(self._pts.copy())
|
||||
|
||||
def corners(self) -> np.ndarray:
|
||||
"""World-coord corners, shape (4, 2), CCW: BL, BR, TR, TL."""
|
||||
return self._pts.copy()
|
||||
|
||||
def centroid(self) -> np.ndarray:
|
||||
return self._pts.mean(axis=0)
|
||||
|
||||
def bbox_size(self) -> np.ndarray:
|
||||
"""Width and height of the axis-aligned bounding box, shape (2,)."""
|
||||
return self._pts.max(axis=0) - self._pts.min(axis=0)
|
||||
|
||||
def contains(self, x: float, y: float) -> bool:
|
||||
return bool(MplPath(self._pts).contains_point((x, y)))
|
||||
|
||||
def mask_for_grid(self, x_axis: np.ndarray,
|
||||
y_axis: np.ndarray) -> np.ndarray:
|
||||
"""Boolean mask (n_rows, n_frames) of pixels whose centres lie
|
||||
inside the quadrilateral.
|
||||
|
||||
Only the quad's axis-aligned bounding box is tested — meshgrid and
|
||||
contains_points over the *whole* grid would be tens of millions of
|
||||
point-in-polygon tests (and hundreds of MB of float64 temporaries)
|
||||
on a large scan, on every ROI edit.
|
||||
"""
|
||||
x = np.asarray(x_axis, dtype=np.float64)
|
||||
y = np.asarray(y_axis, dtype=np.float64)
|
||||
mask = np.zeros((y.size, x.size), dtype=bool)
|
||||
|
||||
(x0, y0), (x1, y1) = self._pts.min(axis=0), self._pts.max(axis=0)
|
||||
cols = np.nonzero((x >= x0) & (x <= x1))[0]
|
||||
rows = np.nonzero((y >= y0) & (y <= y1))[0]
|
||||
if cols.size == 0 or rows.size == 0:
|
||||
return mask
|
||||
|
||||
c0, c1 = int(cols[0]), int(cols[-1]) + 1
|
||||
r0, r1 = int(rows[0]), int(rows[-1]) + 1
|
||||
X, Y = np.meshgrid(x[c0:c1], y[r0:r1])
|
||||
inside = MplPath(self._pts).contains_points(
|
||||
np.column_stack([X.ravel(), Y.ravel()]))
|
||||
mask[r0:r1, c0:c1] = inside.reshape(X.shape)
|
||||
return mask
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Matplotlib canvases
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class ImageCanvas(FigureCanvasQTAgg):
|
||||
pixel_clicked = pyqtSignal(int, int) # row_idx, frame_idx
|
||||
roi_changed = pyqtSignal() # ROI created / edited / cleared
|
||||
draw_mode_changed = pyqtSignal(bool) # "draw new ROI" arm toggled
|
||||
|
||||
# Interaction state values
|
||||
_IDLE = "idle"
|
||||
_DRAW_NEW = "draw_new"
|
||||
_MOVE = "move"
|
||||
_DRAG_CORNER = "drag_corner"
|
||||
|
||||
# Hit tolerance (display pixels) for handles.
|
||||
_HANDLE_PX = 12
|
||||
_CLICK_THRESH_PX = 4 # releases within this of press count as a click
|
||||
|
||||
def __init__(self, parent=None):
|
||||
fig = Figure(figsize=(7, 5), tight_layout=True)
|
||||
self.ax = fig.add_subplot(111)
|
||||
super().__init__(fig)
|
||||
self.setParent(parent)
|
||||
self.setSizePolicy(QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Expanding)
|
||||
self._extent = None
|
||||
self._img_shape = None
|
||||
|
||||
# ROI state
|
||||
self._roi: RoiQuad | None = None
|
||||
self._roi_artists: list = []
|
||||
self._state = self._IDLE
|
||||
self._draw_mode = False
|
||||
|
||||
# Per-interaction snapshots / anchors
|
||||
self._press_xy: tuple[float, float] | None = None
|
||||
self._press_pixel: tuple[float, float] | None = None
|
||||
self._press_button = None
|
||||
self._snapshot: RoiQuad | None = None
|
||||
self._drag_corner_idx: int = -1
|
||||
self._move_anchor = None # press-point in world coords
|
||||
self._draw_previous: RoiQuad | None = None
|
||||
|
||||
self.mpl_connect("button_press_event", self._on_press)
|
||||
self.mpl_connect("motion_notify_event", self._on_motion)
|
||||
self.mpl_connect("button_release_event", self._on_release)
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Public API
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def show_image(self, img: np.ndarray, extent: list[float], cmap: str,
|
||||
vmin: float, vmax: float, xlabel: str, ylabel: str, title: str,
|
||||
colorbar_label: str = ""):
|
||||
self.figure.clf()
|
||||
self.ax = self.figure.add_subplot(111)
|
||||
# Patches and lines are destroyed by figure.clf(); drop stale refs.
|
||||
self._roi_artists = []
|
||||
|
||||
self._extent = extent
|
||||
self._img_shape = img.shape
|
||||
|
||||
im = self.ax.imshow(
|
||||
img, aspect="auto", origin="upper",
|
||||
extent=extent, cmap=cmap, vmin=vmin, vmax=vmax,
|
||||
interpolation="nearest",
|
||||
)
|
||||
cb = self.figure.colorbar(im, ax=self.ax, fraction=0.046, pad=0.04)
|
||||
if colorbar_label:
|
||||
cb.set_label(colorbar_label)
|
||||
|
||||
self.ax.set_xlabel(xlabel)
|
||||
self.ax.set_ylabel(ylabel)
|
||||
self.ax.set_title(title)
|
||||
|
||||
# Re-draw the ROI (if any) on top of the fresh image so it persists
|
||||
# unchanged across mode / angle / channel switches.
|
||||
self._draw_roi()
|
||||
self.draw()
|
||||
|
||||
def get_roi(self) -> RoiQuad | None:
|
||||
return self._roi
|
||||
|
||||
def set_roi(self, roi: RoiQuad | None):
|
||||
self._roi = roi.copy() if roi is not None else None
|
||||
self._draw_roi()
|
||||
self.draw_idle()
|
||||
self.roi_changed.emit()
|
||||
|
||||
def clear_roi(self):
|
||||
self._roi = None
|
||||
self._remove_roi_artists()
|
||||
self.draw_idle()
|
||||
self.roi_changed.emit()
|
||||
|
||||
def start_drawing(self):
|
||||
"""Arm the next click+drag on the image to create a new ROI,
|
||||
replacing any existing one."""
|
||||
self._draw_mode = True
|
||||
self.setCursor(Qt.CursorShape.CrossCursor)
|
||||
self.draw_mode_changed.emit(True)
|
||||
|
||||
def cancel_drawing(self):
|
||||
if self._draw_mode:
|
||||
self._draw_mode = False
|
||||
self.setCursor(Qt.CursorShape.ArrowCursor)
|
||||
self.draw_mode_changed.emit(False)
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Rendering
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def _remove_roi_artists(self):
|
||||
for a in self._roi_artists:
|
||||
try:
|
||||
a.remove()
|
||||
except (ValueError, AttributeError, NotImplementedError):
|
||||
pass
|
||||
self._roi_artists = []
|
||||
|
||||
def _draw_roi(self):
|
||||
self._remove_roi_artists()
|
||||
if self._roi is None or self.ax is None:
|
||||
return
|
||||
corners = self._roi.corners()
|
||||
|
||||
# Filled quad, then a sharp unfilled edge for visibility over bright
|
||||
# images, then draggable corner handles.
|
||||
for kwargs in (
|
||||
dict(fill=True, facecolor="#ffd93a", edgecolor="#e53935",
|
||||
alpha=0.22, linewidth=2.0, zorder=10),
|
||||
dict(fill=False, edgecolor="#e53935", linewidth=1.8, zorder=11),
|
||||
):
|
||||
patch = Polygon(corners, closed=True, **kwargs)
|
||||
self.ax.add_patch(patch)
|
||||
self._roi_artists.append(patch)
|
||||
|
||||
self._roi_artists.append(self.ax.scatter(
|
||||
corners[:, 0], corners[:, 1], s=60, c="white",
|
||||
edgecolors="#e53935", linewidths=1.6, zorder=13))
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Hit testing (display pixels for handles, data coords for "inside")
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def _hit_test(self, event) -> tuple[str, int | None] | None:
|
||||
if self._roi is None or self.ax is None:
|
||||
return None
|
||||
if event.x is None or event.y is None:
|
||||
return None
|
||||
corners_disp = self.ax.transData.transform(self._roi.corners())
|
||||
click = np.array([event.x, event.y])
|
||||
|
||||
for i in range(4):
|
||||
if np.hypot(*(corners_disp[i] - click)) <= self._HANDLE_PX:
|
||||
return ("corner", i)
|
||||
|
||||
if event.xdata is not None and event.ydata is not None:
|
||||
if self._roi.contains(event.xdata, event.ydata):
|
||||
return ("inside", None)
|
||||
return None
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Mouse event handlers
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def _on_press(self, event):
|
||||
if event.inaxes is not self.ax or self._extent is None:
|
||||
return
|
||||
if event.button != 1: # only left mouse button
|
||||
return
|
||||
# If the matplotlib toolbar is in pan / zoom mode, let it handle
|
||||
# the interaction instead of starting a ROI manipulation.
|
||||
tb = getattr(self, "toolbar", None)
|
||||
if tb is not None and getattr(tb, "mode", ""):
|
||||
return
|
||||
|
||||
self._press_xy = (event.xdata, event.ydata)
|
||||
self._press_pixel = (event.x, event.y)
|
||||
self._press_button = event.button
|
||||
|
||||
if self._draw_mode:
|
||||
self._draw_previous = self._roi.copy() if self._roi else None
|
||||
self._roi = RoiQuad.from_bbox(event.xdata, event.ydata,
|
||||
event.xdata, event.ydata)
|
||||
self._state = self._DRAW_NEW
|
||||
self._draw_roi()
|
||||
self.draw_idle()
|
||||
return
|
||||
|
||||
hit = self._hit_test(event)
|
||||
if hit is None:
|
||||
self._state = self._IDLE
|
||||
return
|
||||
|
||||
kind, idx = hit
|
||||
self._snapshot = self._roi.copy()
|
||||
if kind == "corner":
|
||||
self._state = self._DRAG_CORNER
|
||||
self._drag_corner_idx = idx
|
||||
else:
|
||||
self._state = self._MOVE
|
||||
self._move_anchor = (event.xdata, event.ydata)
|
||||
|
||||
def _on_motion(self, event):
|
||||
if self._state == self._IDLE:
|
||||
return
|
||||
if event.xdata is None or event.ydata is None:
|
||||
return
|
||||
if event.inaxes is not self.ax:
|
||||
return
|
||||
|
||||
if self._state == self._DRAW_NEW:
|
||||
x0, y0 = self._press_xy
|
||||
self._roi = RoiQuad.from_bbox(x0, y0, event.xdata, event.ydata)
|
||||
elif self._state == self._MOVE:
|
||||
delta = np.array([event.xdata - self._move_anchor[0],
|
||||
event.ydata - self._move_anchor[1]])
|
||||
self._roi._pts = self._snapshot.corners() + delta
|
||||
elif self._state == self._DRAG_CORNER:
|
||||
self._roi._pts[self._drag_corner_idx] = [event.xdata, event.ydata]
|
||||
|
||||
self._draw_roi()
|
||||
self.draw_idle()
|
||||
|
||||
def _on_release(self, event):
|
||||
if event.button != 1 and self._press_button != 1:
|
||||
return
|
||||
prev_state = self._state
|
||||
self._state = self._IDLE
|
||||
try:
|
||||
if prev_state == self._DRAW_NEW:
|
||||
self._finish_draw()
|
||||
elif prev_state in (self._MOVE, self._DRAG_CORNER):
|
||||
self._draw_roi()
|
||||
self.draw_idle()
|
||||
self.roi_changed.emit()
|
||||
else:
|
||||
self._maybe_emit_pixel_click(event)
|
||||
finally:
|
||||
self._press_xy = self._press_pixel = None
|
||||
self._press_button = None
|
||||
|
||||
def _finish_draw(self):
|
||||
"""Commit (or reject) a freshly-dragged quad."""
|
||||
if self._extent is not None:
|
||||
x0, x1, y_bot, y_top = self._extent
|
||||
min_w = abs(x1 - x0) * 0.01 # minimum: 1% of each axis range
|
||||
min_h = abs(y_bot - y_top) * 0.01
|
||||
else:
|
||||
min_w = min_h = 1e-6
|
||||
|
||||
if self._roi is None:
|
||||
too_small = True
|
||||
else:
|
||||
bbox = self._roi.bbox_size()
|
||||
too_small = bbox[0] < min_w or bbox[1] < min_h
|
||||
if too_small:
|
||||
self._roi = self._draw_previous
|
||||
|
||||
self._draw_previous = None
|
||||
self.cancel_drawing()
|
||||
self._draw_roi()
|
||||
self.draw_idle()
|
||||
self.roi_changed.emit()
|
||||
|
||||
def _maybe_emit_pixel_click(self, event):
|
||||
"""A release close enough to its press counts as a pixel click."""
|
||||
if (self._press_pixel is None or event.x is None or event.y is None
|
||||
or self._extent is None or event.inaxes is not self.ax
|
||||
or event.xdata is None):
|
||||
return
|
||||
dx_px = event.x - self._press_pixel[0]
|
||||
dy_px = event.y - self._press_pixel[1]
|
||||
if dx_px * dx_px + dy_px * dy_px > self._CLICK_THRESH_PX ** 2:
|
||||
return
|
||||
|
||||
x0, x1, y_bot, y_top = self._extent
|
||||
n_rows, n_frames = self._img_shape
|
||||
col = int((event.xdata - x0) / (x1 - x0) * n_frames)
|
||||
row = int((event.ydata - y_top) / (y_bot - y_top) * n_rows)
|
||||
self.pixel_clicked.emit(max(0, min(row, n_rows - 1)),
|
||||
max(0, min(col, n_frames - 1)))
|
||||
|
||||
|
||||
class WaveformCanvas(FigureCanvasQTAgg):
|
||||
def __init__(self, parent=None):
|
||||
fig = Figure(figsize=(8, 3), tight_layout=True)
|
||||
self.ax_wave = fig.add_subplot(121)
|
||||
self.ax_right = fig.add_subplot(122)
|
||||
super().__init__(fig)
|
||||
self.setParent(parent)
|
||||
self.setSizePolicy(QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Expanding)
|
||||
|
||||
def show_rf_waveform(self, sras: SrasFile, angle_idx: int,
|
||||
row_idx: int, frame_idx: int,
|
||||
apply_bg_sub: bool = True):
|
||||
"""CH1 RF: time-domain + FFT spectrum.
|
||||
|
||||
If apply_bg_sub is True and sras.background is not None, the background
|
||||
waveform is overlaid on the time-domain plot and the FFT is computed
|
||||
on the subtracted signal. The unsubtracted FFT is also shown faintly
|
||||
for comparison.
|
||||
"""
|
||||
data = sras.data[angle_idx]
|
||||
waveform = data[row_idx, CH1_IDX, frame_idx, :].astype(np.float32)
|
||||
t_ns = sras.time_axis_ns()
|
||||
f_mhz = sras.freq_axis_mhz()
|
||||
dc3_val = data[row_idx, CH3_IDX, frame_idx, :].astype(np.float32).mean()
|
||||
dc4_val = data[row_idx, CH4_IDX, frame_idx, :].astype(np.float32).mean()
|
||||
|
||||
bg = sras.background if (apply_bg_sub and sras.background is not None) else None
|
||||
waveform_plot = waveform - bg if bg is not None else waveform
|
||||
|
||||
self.ax_wave.cla()
|
||||
self.ax_right.cla()
|
||||
|
||||
if bg is not None:
|
||||
self.ax_wave.plot(t_ns, waveform, linewidth=0.5, color="#aaaaaa",
|
||||
label="raw", zorder=1)
|
||||
self.ax_wave.plot(t_ns, bg, linewidth=0.5, color="#e07030",
|
||||
linestyle="--", label="background", zorder=2)
|
||||
self.ax_wave.plot(t_ns, waveform_plot, linewidth=0.7, color="#4488cc",
|
||||
label="subtracted", zorder=3)
|
||||
self.ax_wave.legend(fontsize=7, loc="upper right")
|
||||
else:
|
||||
self.ax_wave.plot(t_ns, waveform, linewidth=0.7, color="#4488cc")
|
||||
|
||||
self.ax_wave.set_xlabel("Time (ns)")
|
||||
self.ax_wave.set_ylabel("ADC counts")
|
||||
bg_tag = " [bg sub]" if bg is not None else ""
|
||||
dc3_mv = adc_to_mv(dc3_val, *sras.cal(CH3_IDX))
|
||||
dc4_mv = adc_to_mv(dc4_val, *sras.cal(CH4_IDX))
|
||||
self.ax_wave.set_title(
|
||||
f"CH1 RF row={row_idx} frame={frame_idx}{bg_tag}\n"
|
||||
f"CH3={dc3_val:.1f} CH4={dc4_val:.1f} "
|
||||
f"({dc3_mv:.2f} / {dc4_mv:.2f} mV)",
|
||||
fontsize=8,
|
||||
)
|
||||
|
||||
# FFT of the (possibly subtracted) waveform
|
||||
power_sub = np.abs(np.fft.rfft(waveform_plot)) ** 2
|
||||
power_sub[0] = 0.0
|
||||
peak_mhz = f_mhz[int(np.argmax(power_sub))]
|
||||
|
||||
if bg is not None:
|
||||
# Also show the unsubtracted FFT for reference
|
||||
power_raw = np.abs(np.fft.rfft(waveform)) ** 2
|
||||
power_raw[0] = 0.0
|
||||
self.ax_right.plot(f_mhz, power_raw, linewidth=0.5, color="#aaaaaa",
|
||||
label="raw FFT", zorder=1)
|
||||
|
||||
self.ax_right.plot(f_mhz, power_sub, linewidth=0.7, color="#4488cc",
|
||||
label="subtracted FFT" if bg is not None else None, zorder=2)
|
||||
self.ax_right.axvline(peak_mhz, color="tomato", linestyle="--",
|
||||
linewidth=1.2, label=f"peak = {peak_mhz:.1f} MHz")
|
||||
self.ax_right.set_xlabel("Frequency (MHz)")
|
||||
self.ax_right.set_ylabel("Power (arb.)")
|
||||
self.ax_right.set_title("FFT Power Spectrum")
|
||||
self.ax_right.set_xlim(0, 500)
|
||||
self.ax_right.legend(fontsize=8)
|
||||
|
||||
self.draw()
|
||||
|
||||
def show_dc_waveform(self, sras: SrasFile, angle_idx: int, ch_idx: int,
|
||||
row_idx: int, frame_idx: int):
|
||||
"""CH3 or CH4 DC: time-domain + mean annotation."""
|
||||
waveform = sras.data[angle_idx][row_idx, ch_idx, frame_idx, :].astype(np.float32)
|
||||
mean_val = float(waveform.mean())
|
||||
mean_mv = adc_to_mv(mean_val, *sras.cal(ch_idx))
|
||||
|
||||
self.ax_wave.cla()
|
||||
self.ax_right.cla()
|
||||
|
||||
self.ax_wave.plot(sras.time_axis_ns(), waveform, linewidth=0.7, color="#4488cc")
|
||||
self.ax_wave.axhline(mean_val, color="tomato", linestyle="--",
|
||||
linewidth=1.2, label=f"mean = {mean_val:.2f} ADC")
|
||||
self.ax_wave.set_xlabel("Time (ns)")
|
||||
self.ax_wave.set_ylabel("ADC counts")
|
||||
self.ax_wave.set_title(
|
||||
f"{CH_NAMES[ch_idx]} DC row={row_idx} frame={frame_idx}")
|
||||
self.ax_wave.legend(fontsize=8)
|
||||
|
||||
self.ax_right.text(
|
||||
0.5, 0.5,
|
||||
f"DC mode\n\nmean = {mean_val:.3f} ADC\n = {mean_mv:.3f} mV",
|
||||
ha="center", va="center",
|
||||
transform=self.ax_right.transAxes, fontsize=11,
|
||||
)
|
||||
self.ax_right.set_axis_off()
|
||||
|
||||
self.draw()
|
||||
|
||||
|
||||
class ManualAlignOverlayCanvas(FigureCanvasQTAgg):
|
||||
"""Renders ManualAlignmentDialog's multi-angle mask overlay and turns
|
||||
keyboard input into translate/rotate nudge requests for whichever angle
|
||||
the dialog currently has active.
|
||||
|
||||
A pure input+render widget — it holds no alignment state and never
|
||||
touches SrasFile itself; ManualAlignmentDialog owns all of that and
|
||||
decides, from these signals, whether a cheap single-layer refresh or a
|
||||
full preview-canvas rebuild is needed.
|
||||
|
||||
FigureCanvasQTAgg is a real QWidget, so keyPressEvent works like on any
|
||||
other widget, but Qt only ever delivers key events to whichever widget
|
||||
currently has focus — StrongFocus, plus grabbing focus on click and once
|
||||
right after the dialog is shown, are both required or arrow keys
|
||||
silently do nothing.
|
||||
|
||||
Rotate keys are letters (Q/E), not punctuation (comma/period or
|
||||
brackets): Shift+letter still reports the same Qt.Key on every platform,
|
||||
whereas Shift+comma/bracket can report a different virtual key
|
||||
(Key_Less / Key_BraceLeft) depending on platform and keyboard layout —
|
||||
which would silently break the "Shift = coarse step" modifier for
|
||||
rotation specifically. Arrow keys have no such hazard.
|
||||
"""
|
||||
nudge_translate = pyqtSignal(int, int, bool) # dir_x, dir_y in {-1,0,1}; coarse
|
||||
nudge_rotate = pyqtSignal(int, bool) # dir in {-1,1} (CCW/CW); coarse
|
||||
|
||||
_TRANSLATE_KEYS = {
|
||||
Qt.Key.Key_Left: (-1, 0),
|
||||
Qt.Key.Key_Right: (1, 0),
|
||||
Qt.Key.Key_Up: (0, -1),
|
||||
Qt.Key.Key_Down: (0, 1),
|
||||
}
|
||||
_ROTATE_KEYS = {Qt.Key.Key_Q: 1, Qt.Key.Key_E: -1} # CCW, CW
|
||||
|
||||
def __init__(self, parent=None):
|
||||
fig = Figure(figsize=(6, 6), tight_layout=True)
|
||||
self.ax = fig.add_subplot(111)
|
||||
super().__init__(fig)
|
||||
self.setParent(parent)
|
||||
self.setFocusPolicy(Qt.FocusPolicy.StrongFocus)
|
||||
self.setSizePolicy(QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Expanding)
|
||||
self.mpl_connect("button_press_event", lambda _e: self.setFocus())
|
||||
|
||||
def show_overlay(self, rgba: np.ndarray, extent: list[float], title: str):
|
||||
self.figure.clf()
|
||||
self.ax = self.figure.add_subplot(111)
|
||||
self.ax.imshow(rgba, extent=extent, origin="upper", aspect="auto")
|
||||
self.ax.set_xlabel("X (mm)")
|
||||
self.ax.set_ylabel("Y (mm)")
|
||||
self.ax.set_title(title)
|
||||
self.draw_idle() # coalesces rapid redraws — matters for key-repeat.
|
||||
|
||||
def keyPressEvent(self, event: QKeyEvent):
|
||||
key = event.key()
|
||||
coarse = bool(event.modifiers() & Qt.KeyboardModifier.ShiftModifier)
|
||||
if key in self._TRANSLATE_KEYS:
|
||||
dx, dy = self._TRANSLATE_KEYS[key]
|
||||
self.nudge_translate.emit(dx, dy, coarse)
|
||||
event.accept()
|
||||
elif key in self._ROTATE_KEYS:
|
||||
self.nudge_rotate.emit(self._ROTATE_KEYS[key], coarse)
|
||||
event.accept()
|
||||
else:
|
||||
super().keyPressEvent(event)
|
||||
|
||||
@@ -0,0 +1,151 @@
|
||||
"""Shared constants and small layout helpers for the viewer widgets."""
|
||||
|
||||
from PyQt6.QtCore import Qt
|
||||
from PyQt6.QtWidgets import (
|
||||
QDoubleSpinBox, QFormLayout, QFrame, QGroupBox, QLabel, QScrollArea,
|
||||
QSizePolicy, QVBoxLayout, QWidget,
|
||||
)
|
||||
|
||||
from sras_format import CH1_IDX, CH3_IDX, CH4_IDX
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Display constants
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
CH_LABELS = [
|
||||
"CH1 — RF (FFT peak freq)",
|
||||
"CH3 — Bias A (DC mean)",
|
||||
"CH4 — Bias B (DC mean)",
|
||||
"CH1 — Velocity (SRAS)",
|
||||
]
|
||||
|
||||
# Combo index for the derived velocity mode (uses CH1_IDX data)
|
||||
VELOCITY_MODE_IDX = 3
|
||||
# All modes that operate on CH1 waveforms
|
||||
CH1_DERIVED_MODES = (CH1_IDX, VELOCITY_MODE_IDX)
|
||||
|
||||
CMAPS = ["gray", "viridis", "plasma", "inferno", "hot", "jet", "RdBu_r", "seismic"]
|
||||
|
||||
# (mode_str, status-bar unit, colorbar label) per channel index
|
||||
_CHANNEL_DISPLAY = {
|
||||
CH1_IDX: ("RF", "Peak frequency (MHz)", "MHz"),
|
||||
CH3_IDX: ("DC", "DC mean (mV)", "mV"),
|
||||
CH4_IDX: ("DC", "DC mean (mV)", "mV"),
|
||||
VELOCITY_MODE_IDX: ("Velocity", "Velocity (m/s)", "m/s"),
|
||||
}
|
||||
|
||||
_CSS_HINT = "font-size: 11px; color: #aaa;"
|
||||
_CSS_INFO = "font-size: 11px;"
|
||||
_CSS_MUTED = "color: #888; font-size: 11px;"
|
||||
_CSS_WARN = "color: #e07000; font-size: 11px;"
|
||||
_CSS_BUSY = "color: #4a90d9; font-size: 11px;"
|
||||
|
||||
# Side-panel column widths (the scroll areas that hold the controls).
|
||||
_LEFT_PANEL_W = 288
|
||||
_RIGHT_PANEL_W = 272
|
||||
|
||||
# Minimum width for a spin box so its value + suffix are never clipped.
|
||||
_SPIN_MIN_W = 96
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Small layout helpers
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class Jobs:
|
||||
"""Keys for SrasViewerWindow's background-job registry (_run_worker /
|
||||
_job_running) and its progress dialogs — one place instead of string
|
||||
literals scattered across window and dialogs."""
|
||||
LOAD = "load"
|
||||
COMPUTE = "compute"
|
||||
DC_PRECOMPUTE = "dc_precompute"
|
||||
BATCH = "batch"
|
||||
ALIGN = "align"
|
||||
MANUAL_ALIGN_MASKS = "manual_align_masks"
|
||||
MANUAL_ALIGN_CORRELATE = "manual_align_correlate"
|
||||
|
||||
|
||||
def _make_dspin(lo: float, hi: float, decimals: int, *, suffix: str = "",
|
||||
value: float | None = None, step: float | None = None) -> QDoubleSpinBox:
|
||||
"""A QDoubleSpinBox with the panel-standard construction."""
|
||||
spin = QDoubleSpinBox()
|
||||
spin.setRange(lo, hi)
|
||||
spin.setDecimals(decimals)
|
||||
if suffix:
|
||||
spin.setSuffix(suffix)
|
||||
if step is not None:
|
||||
spin.setSingleStep(step)
|
||||
if value is not None:
|
||||
spin.setValue(value)
|
||||
spin.setMinimumWidth(_SPIN_MIN_W)
|
||||
return spin
|
||||
|
||||
|
||||
def _axes_extent(x_axis, y_axis, dx: float, dy: float) -> list[float]:
|
||||
"""Matplotlib imshow extent with half-pixel margins, Y flipped so row 0
|
||||
renders at the top."""
|
||||
return [x_axis[0] - dx / 2, x_axis[-1] + dx / 2,
|
||||
y_axis[-1] + dy / 2, y_axis[0] - dy / 2]
|
||||
|
||||
|
||||
def _wrap_label(text: str = "", css: str | None = None) -> QLabel:
|
||||
"""A word-wrapped QLabel that reports its *wrapped* height to the layout.
|
||||
|
||||
A plain word-wrapped QLabel advertises a single-line minimum height, so in a
|
||||
fixed-width column the layout happily shrinks it and the extra lines get
|
||||
clipped. Enabling height-for-width makes the box layout ask for the real
|
||||
height at the column's width instead.
|
||||
"""
|
||||
lbl = QLabel(text)
|
||||
lbl.setWordWrap(True)
|
||||
sp = lbl.sizePolicy()
|
||||
sp.setVerticalPolicy(QSizePolicy.Policy.Minimum)
|
||||
sp.setHeightForWidth(True)
|
||||
lbl.setSizePolicy(sp)
|
||||
if css:
|
||||
lbl.setStyleSheet(css)
|
||||
return lbl
|
||||
|
||||
|
||||
def _group(title: str) -> tuple[QGroupBox, QVBoxLayout]:
|
||||
"""A group box with consistent, non-cramped internal margins."""
|
||||
grp = QGroupBox(title)
|
||||
lay = QVBoxLayout(grp)
|
||||
lay.setContentsMargins(10, 8, 10, 10)
|
||||
lay.setSpacing(6)
|
||||
return grp, lay
|
||||
|
||||
|
||||
def _form() -> QFormLayout:
|
||||
"""A label/field form layout for a narrow side panel."""
|
||||
form = QFormLayout()
|
||||
form.setContentsMargins(0, 0, 0, 0)
|
||||
form.setHorizontalSpacing(8)
|
||||
form.setVerticalSpacing(6)
|
||||
form.setLabelAlignment(Qt.AlignmentFlag.AlignRight
|
||||
| Qt.AlignmentFlag.AlignVCenter)
|
||||
form.setFormAlignment(Qt.AlignmentFlag.AlignLeft | Qt.AlignmentFlag.AlignTop)
|
||||
form.setFieldGrowthPolicy(
|
||||
QFormLayout.FieldGrowthPolicy.AllNonFixedFieldsGrow)
|
||||
form.setRowWrapPolicy(QFormLayout.RowWrapPolicy.DontWrapRows)
|
||||
return form
|
||||
|
||||
|
||||
def _scroll_panel(inner: QWidget, width: int) -> QScrollArea:
|
||||
"""Put a side panel in a fixed-width scroll area.
|
||||
|
||||
Without this the panels are sized by the window: a short window squeezes the
|
||||
controls past their minimum heights, which is what makes text overlap the
|
||||
widget below it. Scrolling keeps every control at its natural size.
|
||||
"""
|
||||
area = QScrollArea()
|
||||
area.setWidget(inner)
|
||||
area.setWidgetResizable(True)
|
||||
area.setFrameShape(QFrame.Shape.NoFrame)
|
||||
area.setHorizontalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAlwaysOff)
|
||||
area.setVerticalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAsNeeded)
|
||||
area.setFixedWidth(width)
|
||||
area.viewport().setAutoFillBackground(False)
|
||||
inner.setAutoFillBackground(False)
|
||||
return area
|
||||
|
||||
@@ -0,0 +1,837 @@
|
||||
"""FFT Options and Manual Alignment dialogs."""
|
||||
|
||||
from typing import TYPE_CHECKING
|
||||
|
||||
import matplotlib as mpl
|
||||
import numpy as np
|
||||
from matplotlib.backends.backend_qtagg import NavigationToolbar2QT
|
||||
from PyQt6.QtCore import QSignalBlocker, pyqtSignal
|
||||
from PyQt6.QtWidgets import (
|
||||
QButtonGroup, QComboBox, QDialog, QDialogButtonBox, QGroupBox,
|
||||
QHBoxLayout, QLabel, QMessageBox, QPushButton, QRadioButton, QSpinBox,
|
||||
QVBoxLayout, QWidget,
|
||||
)
|
||||
|
||||
import sras_compute as compute
|
||||
from sras_compute import (
|
||||
PYFFTW_AVAILABLE, ManualAngleParams, build_manual_alignment,
|
||||
delete_manual_alignment, save_manual_alignment,
|
||||
)
|
||||
from sras_format import SrasFile
|
||||
from sras_workers import Ch4MaskWorker, CrossCorrelateWorker
|
||||
|
||||
from .canvases import ManualAlignOverlayCanvas
|
||||
from .common import (
|
||||
_CSS_HINT, _CSS_MUTED, _CSS_WARN, Jobs, _axes_extent, _form, _group, _make_dspin,
|
||||
_scroll_panel, _wrap_label,
|
||||
)
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from .main_window import SrasViewerWindow
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# FFT Options dialog
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class FftOptionsDialog(QDialog):
|
||||
"""Configure FFT backend and zero-padding.
|
||||
|
||||
Changes take effect only when the user clicks Apply. Cancel discards
|
||||
all pending edits. The live 'frequency resolution' label updates as
|
||||
the user adjusts the pad factor so they can see the trade-off before
|
||||
committing.
|
||||
"""
|
||||
|
||||
def __init__(self, parent=None, *,
|
||||
current_backend: str,
|
||||
current_pad_factor: int,
|
||||
samples_per_frame: int | None,
|
||||
sample_rate_hz: float | None,
|
||||
grating_um: float):
|
||||
super().__init__(parent)
|
||||
self.setWindowTitle("FFT Options")
|
||||
self.setModal(True)
|
||||
self.setMinimumWidth(380)
|
||||
|
||||
self._samples_per_frame = samples_per_frame
|
||||
self._sample_rate_hz = sample_rate_hz
|
||||
self._grating_um = grating_um
|
||||
|
||||
layout = QVBoxLayout(self)
|
||||
|
||||
# ---- Backend ---------------------------------------------------
|
||||
grp_backend = QGroupBox("FFT Backend")
|
||||
bl = QVBoxLayout(grp_backend)
|
||||
|
||||
self._btn_scipy = QRadioButton("SciPy FFT (pocketfft) (always available)")
|
||||
self._btn_pyfftw = QRadioButton(
|
||||
"pyFFTW (faster for large arrays)" if PYFFTW_AVAILABLE
|
||||
else "pyFFTW (not installed — run: pip install pyfftw)")
|
||||
self._btn_pyfftw.setEnabled(PYFFTW_AVAILABLE)
|
||||
|
||||
self._backend_group = QButtonGroup(self)
|
||||
self._backend_group.addButton(self._btn_scipy, id=0)
|
||||
self._backend_group.addButton(self._btn_pyfftw, id=1)
|
||||
|
||||
if current_backend == "pyfftw" and PYFFTW_AVAILABLE:
|
||||
self._btn_pyfftw.setChecked(True)
|
||||
else:
|
||||
self._btn_scipy.setChecked(True)
|
||||
|
||||
bl.addWidget(self._btn_scipy)
|
||||
bl.addWidget(self._btn_pyfftw)
|
||||
layout.addWidget(grp_backend)
|
||||
|
||||
# ---- Zero-padding ----------------------------------------------
|
||||
grp_zp = QGroupBox("Zero-Padding")
|
||||
zl = QVBoxLayout(grp_zp)
|
||||
|
||||
pad_row = QHBoxLayout()
|
||||
pad_row.addWidget(QLabel("Pad factor:"))
|
||||
self._spin_pad = QSpinBox()
|
||||
self._spin_pad.setRange(1, 256)
|
||||
self._spin_pad.setValue(max(1, current_pad_factor))
|
||||
self._spin_pad.setToolTip(
|
||||
"Multiply the waveform length by this factor via zero-padding\n"
|
||||
"before computing the FFT.\n"
|
||||
"1 = no padding (natural length).\n"
|
||||
"Powers of 2 (2, 4, 8 …) give the best performance."
|
||||
)
|
||||
self._spin_pad.valueChanged.connect(self._update_info)
|
||||
pad_row.addWidget(self._spin_pad)
|
||||
zl.addLayout(pad_row)
|
||||
|
||||
self._lbl_nfft = QLabel()
|
||||
self._lbl_freq_res = QLabel()
|
||||
self._lbl_vel_res = QLabel()
|
||||
for lbl in (self._lbl_nfft, self._lbl_freq_res, self._lbl_vel_res):
|
||||
lbl.setStyleSheet(_CSS_HINT)
|
||||
zl.addWidget(lbl)
|
||||
|
||||
layout.addWidget(grp_zp)
|
||||
|
||||
# ---- Buttons ---------------------------------------------------
|
||||
buttons = QDialogButtonBox()
|
||||
buttons.addButton("Apply", QDialogButtonBox.ButtonRole.AcceptRole
|
||||
).clicked.connect(self.accept)
|
||||
buttons.addButton("Cancel", QDialogButtonBox.ButtonRole.RejectRole
|
||||
).clicked.connect(self.reject)
|
||||
layout.addWidget(buttons)
|
||||
|
||||
self._update_info()
|
||||
|
||||
def _update_info(self):
|
||||
spf = self._samples_per_frame
|
||||
sr = self._sample_rate_hz
|
||||
pad = self._spin_pad.value()
|
||||
|
||||
if spf is None or sr is None:
|
||||
self._lbl_nfft.setText("Load a file to preview FFT parameters.")
|
||||
self._lbl_freq_res.setText("")
|
||||
self._lbl_vel_res.setText("")
|
||||
return
|
||||
|
||||
n_fft = spf * pad
|
||||
freq_res_hz = sr / n_fft
|
||||
freq_res_mhz = freq_res_hz / 1e6
|
||||
# v (m/s) = freq (MHz) × grating (µm)
|
||||
vel_res_ms = freq_res_mhz * self._grating_um
|
||||
|
||||
self._lbl_nfft.setText(f"FFT points: {spf} × {pad} = {n_fft:,}")
|
||||
self._lbl_freq_res.setText(
|
||||
f"Frequency bin: {freq_res_mhz:.4f} MHz ({freq_res_hz / 1e3:.2f} kHz)")
|
||||
self._lbl_vel_res.setText(
|
||||
f"Velocity bin: {vel_res_ms:.3f} m/s "
|
||||
f"(at grating = {self._grating_um:.2f} µm)")
|
||||
|
||||
def get_backend(self) -> str:
|
||||
return "pyfftw" if self._btn_pyfftw.isChecked() and PYFFTW_AVAILABLE else "scipy"
|
||||
|
||||
def get_pad_factor(self) -> int:
|
||||
return max(1, self._spin_pad.value())
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Row-Averaged FFT Options dialog
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class RowAverageFftOptionsDialog(QDialog):
|
||||
"""Configure the same-row, distance-weighted neighbor averaging applied
|
||||
to each pixel's CH1 waveform before 'Batch Compute Row-Averaged FFT and
|
||||
Store' re-runs the FFT peak search — a same-row SNR cleanup pass, never
|
||||
mixing across rows/Y (see sras_compute._row_average_waveforms).
|
||||
|
||||
Unlike the plain FFT batch action (which stores unmasked and defers
|
||||
masking to display time), the DC threshold here is required up front:
|
||||
it decides which same-row neighbors are eligible to contribute to a
|
||||
pixel's average, so it can't be deferred.
|
||||
|
||||
Changes take effect only when the user clicks Apply. Cancel discards
|
||||
all pending edits.
|
||||
"""
|
||||
|
||||
def __init__(self, parent=None, *,
|
||||
current_n: int,
|
||||
current_threshold_mv: float,
|
||||
pixel_x_mm: float | None):
|
||||
super().__init__(parent)
|
||||
self.setWindowTitle("Row-Averaged FFT Options")
|
||||
self.setModal(True)
|
||||
self.setMinimumWidth(380)
|
||||
|
||||
self._pixel_x_mm = pixel_x_mm
|
||||
|
||||
layout = QVBoxLayout(self)
|
||||
|
||||
# ---- Neighbor window ---------------------------------------------
|
||||
grp_window = QGroupBox("Same-Row Neighbor Window")
|
||||
wl = QVBoxLayout(grp_window)
|
||||
|
||||
n_row = QHBoxLayout()
|
||||
n_row.addWidget(QLabel("Neighbor half-width (n):"))
|
||||
self._spin_n = QSpinBox()
|
||||
self._spin_n.setRange(1, 50)
|
||||
self._spin_n.setValue(max(1, current_n))
|
||||
self._spin_n.setToolTip(
|
||||
"Each pixel's CH1 waveform is averaged with up to n same-row\n"
|
||||
"neighbors on each side, distance-weighted (Gaussian) and\n"
|
||||
"counting only neighbors that already pass the DC threshold\n"
|
||||
"below. Never mixes across rows/Y.")
|
||||
self._spin_n.valueChanged.connect(self._update_info)
|
||||
n_row.addWidget(self._spin_n)
|
||||
wl.addLayout(n_row)
|
||||
|
||||
self._lbl_width = QLabel()
|
||||
self._lbl_width.setStyleSheet(_CSS_HINT)
|
||||
wl.addWidget(self._lbl_width)
|
||||
|
||||
layout.addWidget(grp_window)
|
||||
|
||||
# ---- DC threshold ------------------------------------------------
|
||||
grp_thr = QGroupBox("Neighbor Validity")
|
||||
tl = QVBoxLayout(grp_thr)
|
||||
thr_row = QHBoxLayout()
|
||||
thr_row.addWidget(QLabel("DC threshold:"))
|
||||
self._spin_threshold = _make_dspin(-500.0, 500.0, 3, suffix=" mV",
|
||||
value=current_threshold_mv, step=0.025)
|
||||
self._spin_threshold.setToolTip(
|
||||
"A same-row neighbor only contributes to a pixel's average if\n"
|
||||
"its own CH4 signal is at or above this threshold -- the same\n"
|
||||
"test used for RF mask display. A pixel below threshold stays\n"
|
||||
"masked, exactly as today; it is never rescued by its neighbors.")
|
||||
thr_row.addWidget(self._spin_threshold)
|
||||
tl.addLayout(thr_row)
|
||||
layout.addWidget(grp_thr)
|
||||
|
||||
# ---- Buttons -----------------------------------------------------
|
||||
buttons = QDialogButtonBox()
|
||||
buttons.addButton("Apply", QDialogButtonBox.ButtonRole.AcceptRole
|
||||
).clicked.connect(self.accept)
|
||||
buttons.addButton("Cancel", QDialogButtonBox.ButtonRole.RejectRole
|
||||
).clicked.connect(self.reject)
|
||||
layout.addWidget(buttons)
|
||||
|
||||
self._update_info()
|
||||
|
||||
def _update_info(self):
|
||||
n = self._spin_n.value()
|
||||
if self._pixel_x_mm is None:
|
||||
self._lbl_width.setText("Load a file to preview the window's physical width.")
|
||||
return
|
||||
width_um = 2 * n * self._pixel_x_mm * 1e3
|
||||
self._lbl_width.setText(
|
||||
f"Window: ±{n} px = {width_um:.2f} µm full width "
|
||||
f"(pixel pitch {self._pixel_x_mm * 1e3:.3g} µm)")
|
||||
|
||||
def get_half_width(self) -> int:
|
||||
return self._spin_n.value()
|
||||
|
||||
def get_threshold_mv(self) -> float:
|
||||
return self._spin_threshold.value()
|
||||
|
||||
|
||||
|
||||
class ManualAlignmentDialog(QDialog):
|
||||
"""Non-modal manual angle-alignment editor (Fusion -> Manual Alignment...).
|
||||
|
||||
Shows every angle's binarized CH4 (Bias B) mask overlaid in a distinct
|
||||
color at partial opacity on one shared canvas, so translation/rotation
|
||||
misalignment is visible by eye. Reference angle (always index 0) is
|
||||
ground truth and never moves; every other angle is aligned to it. The
|
||||
user picks an "active" angle and nudges its rotation+translation with
|
||||
the keyboard; Auto Cross-Correlate finds every non-reference angle's
|
||||
rotation *and* translation by registering its image against the
|
||||
reference's (see compute.register_angle_to_reference) — meant to get every
|
||||
angle stacked on top of each other so keyboard nudging only has to make
|
||||
small corrections, not find an alignment from scratch; Auto De-rotate is
|
||||
the weaker fallback that just seeds rotation from the stage's reported
|
||||
angle, leaving translation alone. Save writes a JSON sidecar next to the
|
||||
.sras file and hands a freshly-built, full-resolution AlignmentResult back
|
||||
to the main window — the exact same object shape compute_angle_alignment
|
||||
produces, so every existing Aligned-View code path (apply_alignment,
|
||||
_aligned_canvas_axes, the pixel-inspector inverse-transform) works
|
||||
completely unmodified.
|
||||
|
||||
Non-modal by design (shown via .show(), never .exec() or setModal(True))
|
||||
so the user can still interact with the main window. Talks back to
|
||||
SrasViewerWindow two ways: it reuses parent._run_worker/_jobs directly
|
||||
for its background mask-fetch and cross-correlate steps, so the main
|
||||
window's existing shutdown/lifecycle plumbing covers both for free, and
|
||||
it emits alignment_saved / alignment_cleared signals for the two moments
|
||||
that should actually mutate the main window's persistent state —
|
||||
everything else (nudging, Auto De-rotate, Auto Cross-Correlate, threshold
|
||||
edits) stays purely local to this dialog until Save.
|
||||
"""
|
||||
|
||||
alignment_saved = pyqtSignal(object, str) # AlignmentResult, sidecar path (str)
|
||||
alignment_cleared = pyqtSignal()
|
||||
|
||||
_PREVIEW_MARGIN_FRAC = 0.15
|
||||
_BASE_ALPHA = 0.42
|
||||
_ACTIVE_ALPHA = 0.75
|
||||
_MAX_PREVIEW_DIM = 1024
|
||||
|
||||
# (label, sources passed to compute.register_angle_to_reference). "Both"
|
||||
# registers on each and keeps whichever scores higher per angle, which
|
||||
# costs roughly double but removes the failure mode where the single
|
||||
# chosen source is the one that happens to be uninformative for one angle.
|
||||
_CORRELATE_SOURCES = (
|
||||
("Both, keep best (recommended)", ("signal", "mask")),
|
||||
("Raw signal", ("signal",)),
|
||||
("Thresholded mask", ("mask",)),
|
||||
)
|
||||
|
||||
def __init__(self, parent: "SrasViewerWindow", sras: SrasFile, *,
|
||||
ref_angle_idx: int, dc_threshold_mv: float,
|
||||
seed_per_angle: dict[int, ManualAngleParams] | None,
|
||||
cached_dc4_mv: dict[int, np.ndarray]):
|
||||
super().__init__(parent)
|
||||
self._parent = parent
|
||||
self._sras = sras
|
||||
self._ref_angle_idx = ref_angle_idx
|
||||
self._downsample = (1, 1) # (rows, cols) block-mean factors
|
||||
self._dc4_mv: dict[int, np.ndarray] = {}
|
||||
self._masks_small: dict[int, np.ndarray] = {}
|
||||
self._preview_layers: dict[int, np.ndarray] = {}
|
||||
self._preview_origin_mm = (0.0, 0.0)
|
||||
self._preview_shape = (1, 1)
|
||||
self._preview_pitch_mm = (1.0, 1.0)
|
||||
self._masks_ready = False
|
||||
self._fit_notes: dict[int, tuple[float, str]] = {}
|
||||
self._derotate_sign_flipped = False
|
||||
|
||||
self.setWindowTitle(f"Manual Alignment — {sras.path.name}")
|
||||
self.resize(1150, 760)
|
||||
|
||||
self._seed_initial_params(seed_per_angle)
|
||||
n = sras.n_angles
|
||||
cmap = mpl.colormaps["tab10"] if n <= 10 else mpl.colormaps["tab20"]
|
||||
self._angle_colors = {a: cmap(a % cmap.N)[:3] for a in range(n)}
|
||||
self._active_angle = 1 if ref_angle_idx == 0 and n > 1 else 0
|
||||
|
||||
self._build_ui(dc_threshold_mv)
|
||||
self._set_controls_enabled(False) # re-enabled once masks are ready
|
||||
self._start_mask_prep(cached_dc4_mv)
|
||||
|
||||
def showEvent(self, event):
|
||||
super().showEvent(event)
|
||||
self.canvas.setFocus()
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Construction
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def _seed_initial_params(self, seed_per_angle: dict[int, ManualAngleParams] | None):
|
||||
seed = seed_per_angle or {}
|
||||
self._angle_params: dict[int, ManualAngleParams] = {
|
||||
a: (ManualAngleParams(seed[a].rotation_deg, seed[a].shift_mm)
|
||||
if a in seed else ManualAngleParams())
|
||||
for a in range(self._sras.n_angles)
|
||||
}
|
||||
self._angle_params[self._ref_angle_idx] = ManualAngleParams()
|
||||
|
||||
def _build_ui(self, dc_threshold_mv: float):
|
||||
root = QHBoxLayout(self)
|
||||
|
||||
self.canvas = ManualAlignOverlayCanvas()
|
||||
left = QWidget()
|
||||
left_l = QVBoxLayout(left)
|
||||
left_l.setContentsMargins(0, 0, 0, 0)
|
||||
left_l.setSpacing(4)
|
||||
left_l.addWidget(NavigationToolbar2QT(self.canvas, left))
|
||||
left_l.addWidget(self.canvas)
|
||||
root.addWidget(left, stretch=1)
|
||||
|
||||
panel = QWidget()
|
||||
panel_l = QVBoxLayout(panel)
|
||||
panel_l.setContentsMargins(0, 0, 0, 0)
|
||||
panel_l.setSpacing(8)
|
||||
panel_l.addWidget(self._build_angle_group())
|
||||
panel_l.addWidget(self._build_adjust_group())
|
||||
panel_l.addWidget(self._build_step_group())
|
||||
panel_l.addWidget(self._build_threshold_group(dc_threshold_mv))
|
||||
panel_l.addWidget(self._build_correlate_group())
|
||||
panel_l.addWidget(self._build_actions_group())
|
||||
self.lbl_status = _wrap_label("", _CSS_MUTED)
|
||||
panel_l.addWidget(self.lbl_status)
|
||||
panel_l.addStretch()
|
||||
|
||||
root.addWidget(_scroll_panel(panel, 320))
|
||||
self._connect_controls()
|
||||
|
||||
def _build_angle_group(self) -> QWidget:
|
||||
grp_angle, al = _group("Active Angle")
|
||||
self.combo_active_angle = QComboBox()
|
||||
for a in range(self._sras.n_angles):
|
||||
label = f"Angle {a} ({self._sras.angles_deg[a]:.1f}°)"
|
||||
if a == self._ref_angle_idx:
|
||||
label += " [reference]"
|
||||
self.combo_active_angle.addItem(label)
|
||||
al.addWidget(self.combo_active_angle)
|
||||
self.lbl_active_note = _wrap_label("", _CSS_WARN)
|
||||
al.addWidget(self.lbl_active_note)
|
||||
return grp_angle
|
||||
|
||||
def _build_adjust_group(self) -> QWidget:
|
||||
self.grp_manual_adjust, mform_box = _group("Manual Adjustment")
|
||||
mform = _form()
|
||||
self.spin_active_rotation_deg = _make_dspin(-3600.0, 3600.0, 3, suffix=" °")
|
||||
mform.addRow("Rotation:", self.spin_active_rotation_deg)
|
||||
|
||||
self.spin_active_shift_x_mm = _make_dspin(-1e5, 1e5, 4, suffix=" mm")
|
||||
mform.addRow("Shift X:", self.spin_active_shift_x_mm)
|
||||
|
||||
self.spin_active_shift_y_mm = _make_dspin(-1e5, 1e5, 4, suffix=" mm")
|
||||
mform.addRow("Shift Y:", self.spin_active_shift_y_mm)
|
||||
mform_box.addLayout(mform)
|
||||
return self.grp_manual_adjust
|
||||
|
||||
def _build_step_group(self) -> QWidget:
|
||||
self.grp_step_sizes, sl = _group("Nudge Step Sizes")
|
||||
sform = _form()
|
||||
self.spin_step_translate_mm = _make_dspin(0.0001, 1000.0, 4,
|
||||
suffix=" mm", value=0.01)
|
||||
sform.addRow("Translate step:", self.spin_step_translate_mm)
|
||||
|
||||
self.spin_step_rotate_deg = _make_dspin(0.001, 90.0, 3,
|
||||
suffix=" °", value=0.1)
|
||||
sform.addRow("Rotate step:", self.spin_step_rotate_deg)
|
||||
|
||||
self.spin_step_multiplier = _make_dspin(1.0, 1000.0, 1, value=10.0)
|
||||
sform.addRow("Coarse × (Shift):", self.spin_step_multiplier)
|
||||
sl.addLayout(sform)
|
||||
sl.addWidget(_wrap_label(
|
||||
"Arrow keys nudge X/Y translation; Q/E nudge rotation (CCW/CW). "
|
||||
"Hold Shift for the coarse step. Click the image once so it has "
|
||||
"keyboard focus.", _CSS_HINT))
|
||||
return self.grp_step_sizes
|
||||
|
||||
def _build_threshold_group(self, dc_threshold_mv: float) -> QWidget:
|
||||
self.grp_mask_threshold, tl = _group("Mask Threshold")
|
||||
tform = _form()
|
||||
self.spin_mask_threshold_mv = _make_dspin(-500.0, 500.0, 3,
|
||||
suffix=" mV", value=dc_threshold_mv)
|
||||
tform.addRow("DC threshold:", self.spin_mask_threshold_mv)
|
||||
tl.addLayout(tform)
|
||||
return self.grp_mask_threshold
|
||||
|
||||
def _build_correlate_group(self) -> QWidget:
|
||||
self.grp_correlate, cl = _group("Cross-Correlate (FFT)")
|
||||
cform = _form()
|
||||
self.combo_correlate_source = QComboBox()
|
||||
for label, sources in self._CORRELATE_SOURCES:
|
||||
self.combo_correlate_source.addItem(label, sources)
|
||||
cform.addRow("Correlate on:", self.combo_correlate_source)
|
||||
|
||||
self.spin_correlate_search_deg = _make_dspin(0.0, 180.0, 1, suffix=" °",
|
||||
value=6.0, step=1.0)
|
||||
cform.addRow("Rotation search (±):", self.spin_correlate_search_deg)
|
||||
cl.addLayout(cform)
|
||||
self.btn_auto_correlate = QPushButton("Auto Cross-Correlate (vs Reference)")
|
||||
cl.addWidget(self.btn_auto_correlate)
|
||||
cl.addWidget(_wrap_label(
|
||||
"Finds each non-reference angle's rotation *and* translation by "
|
||||
"cross-correlating its image against the reference's — the stage's "
|
||||
"reported angle is only the starting point of the search, and both "
|
||||
"of its signs are tried. Run this first, then nudge only for small "
|
||||
"corrections.", _CSS_HINT))
|
||||
return self.grp_correlate
|
||||
|
||||
def _build_actions_group(self) -> QWidget:
|
||||
grp_actions, acl = _group("Actions")
|
||||
self.btn_auto_derotate = QPushButton("Auto De-rotate (use known angles)")
|
||||
self.btn_save = QPushButton("Save Alignment")
|
||||
self.btn_clear = QPushButton("Clear Alignment…")
|
||||
self.btn_close = QPushButton("Close")
|
||||
for btn in (self.btn_auto_derotate, self.btn_save, self.btn_clear, self.btn_close):
|
||||
acl.addWidget(btn)
|
||||
return grp_actions
|
||||
|
||||
def _connect_controls(self):
|
||||
self.combo_active_angle.currentIndexChanged.connect(self._on_active_angle_changed)
|
||||
self.spin_active_rotation_deg.editingFinished.connect(self._on_rotation_spin_edited)
|
||||
self.spin_active_shift_x_mm.editingFinished.connect(self._on_shift_spin_edited)
|
||||
self.spin_active_shift_y_mm.editingFinished.connect(self._on_shift_spin_edited)
|
||||
self.spin_mask_threshold_mv.editingFinished.connect(self._on_mask_threshold_edited)
|
||||
self.btn_auto_derotate.clicked.connect(self._on_auto_derotate)
|
||||
self.btn_auto_correlate.clicked.connect(self._on_auto_correlate)
|
||||
self.btn_save.clicked.connect(self._on_save)
|
||||
self.btn_clear.clicked.connect(self._on_clear)
|
||||
self.btn_close.clicked.connect(self.close)
|
||||
self.canvas.nudge_translate.connect(self._on_nudge_translate)
|
||||
self.canvas.nudge_rotate.connect(self._on_nudge_rotate)
|
||||
|
||||
with QSignalBlocker(self.combo_active_angle):
|
||||
self.combo_active_angle.setCurrentIndex(self._active_angle)
|
||||
self._on_active_angle_changed(self._active_angle)
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Mask preparation (initial CH4 fetch + threshold + downsample)
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def _start_mask_prep(self, cached_dc4_mv: dict[int, np.ndarray]):
|
||||
self._dc4_mv = dict(cached_dc4_mv)
|
||||
missing = [a for a in range(self._sras.n_angles) if a not in self._dc4_mv]
|
||||
if not missing:
|
||||
self._finish_mask_prep()
|
||||
return
|
||||
self.lbl_status.setText(f"Preparing masks: 0/{len(missing)} angle(s) needed…")
|
||||
started = self._parent._run_worker(
|
||||
Jobs.MANUAL_ALIGN_MASKS, Ch4MaskWorker(self._sras, missing),
|
||||
connect=(
|
||||
("angle_done", self._on_mask_angle_done),
|
||||
("error", lambda msg: self.lbl_status.setText(f"Mask prep error: {msg}")),
|
||||
),
|
||||
on_done=self._finish_mask_prep)
|
||||
if not started:
|
||||
self.lbl_status.setText(
|
||||
"Could not start mask preparation (busy) — close and reopen.")
|
||||
|
||||
def _on_mask_angle_done(self, angle_idx: int, dc4_mv: np.ndarray):
|
||||
self._dc4_mv[angle_idx] = dc4_mv
|
||||
self.lbl_status.setText(
|
||||
f"Preparing masks: {len(self._dc4_mv)}/{self._sras.n_angles} ready…")
|
||||
|
||||
def _finish_mask_prep(self):
|
||||
if len(self._dc4_mv) < self._sras.n_angles:
|
||||
return # a mask-worker error left some angles unfetched
|
||||
# Rows and columns get their own factor. A real scan is ~7500 frames
|
||||
# wide but only ~750 rows tall, so one shared factor sized for the
|
||||
# frames would throw away 8x more row detail than the preview needs and
|
||||
# leave the overlay too coarse in y to judge alignment by eye.
|
||||
max_rows = max(img.shape[0] for img in self._dc4_mv.values())
|
||||
max_cols = max(img.shape[1] for img in self._dc4_mv.values())
|
||||
self._downsample = (
|
||||
max(1, int(np.ceil(max_rows / self._MAX_PREVIEW_DIM))),
|
||||
max(1, int(np.ceil(max_cols / self._MAX_PREVIEW_DIM))))
|
||||
self._recompute_masks_small()
|
||||
self._rebuild_preview_canvas()
|
||||
self._set_controls_enabled(True)
|
||||
self.lbl_status.setText("Ready.")
|
||||
|
||||
def _recompute_masks_small(self):
|
||||
"""Threshold + downsample every angle's already-in-memory full-res
|
||||
CH4 mV image. Cheap (a compare + block-mean), so this re-runs in
|
||||
full whenever the mask-threshold spin box changes — no re-fetch.
|
||||
Purely for the overlay's visuals: no alignment geometry depends on this
|
||||
threshold, only which pixels the overlay paints."""
|
||||
threshold = self.spin_mask_threshold_mv.value()
|
||||
fy, fx = self._downsample
|
||||
self._masks_small = {
|
||||
a: compute.block_mean_2d((img >= threshold).astype(np.float32), fy, fx)
|
||||
for a, img in self._dc4_mv.items()
|
||||
}
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Preview canvas: full rebuild vs. incremental single-layer refresh
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def _rebuild_preview_canvas(self):
|
||||
"""Full geometry rebuild: recomputes the shared preview canvas's
|
||||
origin/shape (rotation can grow the union bbox — translation alone
|
||||
cannot, per the padding baked in via _PREVIEW_MARGIN_FRAC) and every
|
||||
angle's reprojected mask layer. Triggered by: dialog open,
|
||||
mask-threshold change, Auto De-rotate, a rotation nudge/edit of the
|
||||
active angle. NOT triggered by a translation-only nudge — see
|
||||
_refresh_active_preview_layer."""
|
||||
dx_ref, dy_ref = compute.pixel_pitch_mm(self._sras, self._ref_angle_idx)
|
||||
fy, fx = self._downsample
|
||||
pitch = (dx_ref * fx, dy_ref * fy)
|
||||
origin, shape = compute.canvas_for_params(
|
||||
self._sras, self._ref_angle_idx, pitch, self._angle_params,
|
||||
margin_frac=self._PREVIEW_MARGIN_FRAC, snap=False)
|
||||
self._preview_origin_mm, self._preview_shape = origin, shape
|
||||
self._preview_pitch_mm = pitch
|
||||
self._preview_layers = {
|
||||
a: self._reproject(a) for a in range(self._sras.n_angles)
|
||||
}
|
||||
self._redraw_overlay()
|
||||
|
||||
def _reproject(self, angle_idx: int) -> np.ndarray:
|
||||
"""One angle's downsampled mask on the current preview canvas.
|
||||
src_downsample must match _masks_small's block-mean factors, or the
|
||||
layer lands magnified and offset instead of where the alignment
|
||||
actually puts it."""
|
||||
p = self._angle_params[angle_idx]
|
||||
return compute.reproject_mask(
|
||||
self._sras, angle_idx, self._ref_angle_idx,
|
||||
self._masks_small[angle_idx], p.rotation_deg, p.shift_mm,
|
||||
self._preview_pitch_mm, self._preview_origin_mm, self._preview_shape,
|
||||
src_downsample=self._downsample)
|
||||
|
||||
def _refresh_active_preview_layer(self):
|
||||
"""Cheap path for a translation-only nudge/edit of the active angle:
|
||||
reproject just that one angle's downsampled mask onto the *existing*
|
||||
preview canvas — every other angle's cached layer is untouched."""
|
||||
self._preview_layers[self._active_angle] = self._reproject(self._active_angle)
|
||||
self._redraw_overlay()
|
||||
|
||||
def _redraw_overlay(self):
|
||||
"""Alpha-composite every angle's colored mask layer into one RGBA
|
||||
image ("all thresholds overlaid with varying opacity"). Each angle
|
||||
keeps a fixed, distinct color regardless of which is active; the
|
||||
active angle is drawn last (on top) at a visibly higher alpha so
|
||||
it's easy to track while nudging."""
|
||||
if not self._preview_layers:
|
||||
return # mask prep hasn't finished yet — nothing to draw
|
||||
n_rows, n_cols = self._preview_shape
|
||||
rgba = np.zeros((n_rows, n_cols, 4), dtype=np.float32)
|
||||
order = sorted(range(self._sras.n_angles), key=lambda a: a == self._active_angle)
|
||||
for a in order:
|
||||
layer = self._preview_layers.get(a)
|
||||
if layer is None:
|
||||
continue
|
||||
alpha = self._ACTIVE_ALPHA if a == self._active_angle else self._BASE_ALPHA
|
||||
color = self._angle_colors[a]
|
||||
fg_a = layer * alpha
|
||||
for c in range(3):
|
||||
rgba[..., c] = color[c] * fg_a + rgba[..., c] * rgba[..., 3] * (1 - fg_a)
|
||||
rgba[..., 3] = fg_a + rgba[..., 3] * (1 - fg_a)
|
||||
|
||||
x0, y0 = self._preview_origin_mm
|
||||
dx, dy = self._preview_pitch_mm
|
||||
x_axis = x0 + np.arange(n_cols) * dx
|
||||
y_axis = y0 + np.arange(n_rows) * dy
|
||||
extent = _axes_extent(x_axis, y_axis, dx, dy)
|
||||
title = (f"Angle {self._active_angle} active "
|
||||
f"({self._sras.angles_deg[self._active_angle]:.1f}°)")
|
||||
self.canvas.show_overlay(rgba, extent, title)
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Angle selection / nudge / edit handlers
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def _on_active_angle_changed(self, angle_idx: int):
|
||||
self._active_angle = angle_idx
|
||||
is_ref = angle_idx == self._ref_angle_idx
|
||||
self.grp_manual_adjust.setEnabled(self._masks_ready and not is_ref)
|
||||
self.lbl_active_note.setText(
|
||||
"Reference angle — defines the shared origin, not adjustable." if is_ref else "")
|
||||
self._sync_active_spinboxes()
|
||||
self._redraw_overlay()
|
||||
|
||||
def _sync_active_spinboxes(self):
|
||||
p = self._angle_params[self._active_angle]
|
||||
for spin, val in ((self.spin_active_rotation_deg, p.rotation_deg),
|
||||
(self.spin_active_shift_x_mm, p.shift_mm[0]),
|
||||
(self.spin_active_shift_y_mm, p.shift_mm[1])):
|
||||
with QSignalBlocker(spin):
|
||||
spin.setValue(val)
|
||||
|
||||
def _on_nudge_translate(self, dir_x: int, dir_y: int, coarse: bool):
|
||||
if not self._masks_ready or self._active_angle == self._ref_angle_idx:
|
||||
return
|
||||
step = self.spin_step_translate_mm.value()
|
||||
if coarse:
|
||||
step *= self.spin_step_multiplier.value()
|
||||
p = self._angle_params[self._active_angle]
|
||||
p.shift_mm = (p.shift_mm[0] + dir_x * step, p.shift_mm[1] + dir_y * step)
|
||||
self._sync_active_spinboxes()
|
||||
self._refresh_active_preview_layer()
|
||||
|
||||
def _on_nudge_rotate(self, direction: int, coarse: bool):
|
||||
if not self._masks_ready or self._active_angle == self._ref_angle_idx:
|
||||
return
|
||||
step = self.spin_step_rotate_deg.value()
|
||||
if coarse:
|
||||
step *= self.spin_step_multiplier.value()
|
||||
self._angle_params[self._active_angle].rotation_deg += direction * step
|
||||
self._sync_active_spinboxes()
|
||||
self._rebuild_preview_canvas()
|
||||
|
||||
def _on_rotation_spin_edited(self):
|
||||
if self._active_angle == self._ref_angle_idx:
|
||||
return
|
||||
self._angle_params[self._active_angle].rotation_deg = self.spin_active_rotation_deg.value()
|
||||
self._rebuild_preview_canvas()
|
||||
|
||||
def _on_shift_spin_edited(self):
|
||||
if self._active_angle == self._ref_angle_idx:
|
||||
return
|
||||
p = self._angle_params[self._active_angle]
|
||||
p.shift_mm = (self.spin_active_shift_x_mm.value(), self.spin_active_shift_y_mm.value())
|
||||
self._refresh_active_preview_layer()
|
||||
|
||||
def _on_mask_threshold_edited(self):
|
||||
if not self._masks_ready:
|
||||
return
|
||||
self._recompute_masks_small()
|
||||
self._rebuild_preview_canvas()
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Actions
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def _on_auto_derotate(self):
|
||||
"""Seed every angle's rotation from the stage's reported angle.
|
||||
|
||||
A starting point for nudging by eye, not an alignment: the stage's
|
||||
sign convention relative to this module's is not knowable from the
|
||||
file, so the sign that lines the scans up is whichever of the two looks
|
||||
right in the overlay. Auto Cross-Correlate decides that from the images
|
||||
instead, and is the button to reach for first.
|
||||
"""
|
||||
sign = -1.0 if self._derotate_sign_flipped else 1.0
|
||||
self._derotate_sign_flipped = not self._derotate_sign_flipped
|
||||
n_changed = 0
|
||||
for a in range(self._sras.n_angles):
|
||||
if a == self._ref_angle_idx:
|
||||
continue
|
||||
self._angle_params[a].rotation_deg = sign * compute.nominal_delta_deg(
|
||||
self._sras, a, self._ref_angle_idx)
|
||||
n_changed += 1
|
||||
self._sync_active_spinboxes()
|
||||
self._rebuild_preview_canvas()
|
||||
self.lbl_status.setText(
|
||||
f"Rotation set to the stage angle ({'−' if sign < 0 else '+'}delta) "
|
||||
f"for {n_changed} angle(s); translation untouched. Click again to "
|
||||
"try the opposite sign.")
|
||||
|
||||
def _on_auto_correlate(self):
|
||||
if not self._masks_ready:
|
||||
return
|
||||
angles = [a for a in range(self._sras.n_angles) if a != self._ref_angle_idx]
|
||||
if not angles:
|
||||
return
|
||||
worker = CrossCorrelateWorker(
|
||||
self._sras, self._ref_angle_idx, angles, self._dc4_mv,
|
||||
sources=self.combo_correlate_source.currentData(),
|
||||
dc_threshold_mv=self.spin_mask_threshold_mv.value(),
|
||||
search_deg=self.spin_correlate_search_deg.value())
|
||||
self._correlate_done_count = 0
|
||||
self._correlate_total = len(angles)
|
||||
self._fit_notes = {}
|
||||
self._set_controls_enabled(False)
|
||||
self.lbl_status.setText(f"Cross-correlating: 0/{self._correlate_total} angle(s)…")
|
||||
started = self._parent._run_worker(
|
||||
Jobs.MANUAL_ALIGN_CORRELATE, worker,
|
||||
connect=(
|
||||
("angle_done", self._on_correlate_angle_done),
|
||||
("error", self._on_correlate_error),
|
||||
),
|
||||
on_done=self._finish_auto_correlate)
|
||||
if not started:
|
||||
self._set_controls_enabled(True)
|
||||
self.lbl_status.setText("Could not start cross-correlation (busy) — try again.")
|
||||
|
||||
def _on_correlate_angle_done(self, angle_idx: int, rotation_deg: float,
|
||||
shift_x_mm: float, shift_y_mm: float,
|
||||
score: float, source: str):
|
||||
self._angle_params[angle_idx] = ManualAngleParams(rotation_deg, (shift_x_mm, shift_y_mm))
|
||||
self._fit_notes[angle_idx] = (score, source)
|
||||
self._correlate_done_count += 1
|
||||
self.lbl_status.setText(
|
||||
f"Cross-correlating: {self._correlate_done_count}/{self._correlate_total} angle(s)…")
|
||||
|
||||
def _on_correlate_error(self, msg: str):
|
||||
self.lbl_status.setText(f"Cross-correlation error: {msg}")
|
||||
|
||||
def _finish_auto_correlate(self):
|
||||
self._sync_active_spinboxes()
|
||||
self._rebuild_preview_canvas()
|
||||
self._set_controls_enabled(True)
|
||||
self.lbl_status.setText(
|
||||
f"Cross-correlated {self._correlate_done_count} angle(s) against "
|
||||
f"Angle {self._ref_angle_idx}.\n" + self._fit_report())
|
||||
|
||||
def _fit_report(self) -> str:
|
||||
"""Per-angle registration quality, worst first.
|
||||
|
||||
Surfaced rather than buried because a single bad acquisition (stage
|
||||
glitch, laser dropout) registers poorly and would otherwise be fused in
|
||||
silently — seeing which angle it is, is what makes dropping it with
|
||||
sras_edit_scans.py actionable. The deviation from the stage's own
|
||||
reported angle is shown alongside: a large one means the search and the
|
||||
stage disagree, which is either a genuine mechanical error or a sign
|
||||
that this angle's fit is not to be trusted.
|
||||
"""
|
||||
if not self._fit_notes:
|
||||
return ""
|
||||
rows = sorted(self._fit_notes.items(), key=lambda kv: kv[1][0])
|
||||
worst = rows[0]
|
||||
lines = [f"Worst fit: angle {worst[0]} (score {worst[1][0]:.3f}, "
|
||||
f"{worst[1][1]})."]
|
||||
drifted = []
|
||||
for a, _note in rows:
|
||||
nominal = compute.nominal_delta_deg(self._sras, a, self._ref_angle_idx)
|
||||
got = self._angle_params[a].rotation_deg
|
||||
dev = min(abs(got - nominal), abs(got + nominal))
|
||||
if dev > 1.0:
|
||||
drifted.append(f"{a} ({dev:.2f}°)")
|
||||
if drifted:
|
||||
lines.append("Rotation differs from the stage angle by >1° for "
|
||||
"angle(s) " + ", ".join(drifted) + ".")
|
||||
lines.append("Nudge from here for any remaining fine correction.")
|
||||
return " ".join(lines)
|
||||
|
||||
def _on_save(self):
|
||||
threshold = self.spin_mask_threshold_mv.value()
|
||||
resolved = dict(self._angle_params) # already concrete floats
|
||||
try:
|
||||
path = save_manual_alignment(self._sras, self._ref_angle_idx, threshold, resolved)
|
||||
result = build_manual_alignment(self._sras, self._ref_angle_idx,
|
||||
threshold, resolved)
|
||||
except OSError as exc:
|
||||
QMessageBox.warning(self, "Save Alignment Failed", str(exc))
|
||||
return
|
||||
self.lbl_status.setText(f"Saved to {path.name}.")
|
||||
self.alignment_saved.emit(result, str(path))
|
||||
|
||||
def _on_clear(self):
|
||||
reply = QMessageBox.question(
|
||||
self, "Clear Alignment",
|
||||
"This resets every angle back to raw/unaligned (0° rotation, no "
|
||||
"shift) and deletes the saved alignment file for this scan, if "
|
||||
"any. This cannot be undone. Continue?",
|
||||
QMessageBox.StandardButton.Yes | QMessageBox.StandardButton.No,
|
||||
QMessageBox.StandardButton.No)
|
||||
if reply != QMessageBox.StandardButton.Yes:
|
||||
return
|
||||
try:
|
||||
existed = delete_manual_alignment(self._sras)
|
||||
except OSError as exc:
|
||||
QMessageBox.warning(self, "Clear Alignment Failed",
|
||||
f"Could not delete the saved alignment file: {exc}")
|
||||
return
|
||||
self._angle_params = {a: ManualAngleParams() for a in range(self._sras.n_angles)}
|
||||
self._fit_notes = {}
|
||||
self._sync_active_spinboxes()
|
||||
self._rebuild_preview_canvas()
|
||||
self.lbl_status.setText(
|
||||
"Alignment cleared; saved file removed." if existed
|
||||
else "Alignment cleared (there was no saved file).")
|
||||
self.alignment_cleared.emit()
|
||||
|
||||
def _set_controls_enabled(self, enabled: bool):
|
||||
self._masks_ready = enabled
|
||||
self.combo_active_angle.setEnabled(enabled)
|
||||
self.grp_manual_adjust.setEnabled(enabled and self._active_angle != self._ref_angle_idx)
|
||||
self.grp_step_sizes.setEnabled(enabled)
|
||||
self.grp_mask_threshold.setEnabled(enabled)
|
||||
self.grp_correlate.setEnabled(enabled)
|
||||
self.btn_auto_derotate.setEnabled(enabled)
|
||||
self.btn_save.setEnabled(enabled)
|
||||
self.btn_clear.setEnabled(enabled)
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,3 +0,0 @@
|
||||
PyQt6==6.10.2
|
||||
numpy==2.4.1
|
||||
matplotlib==3.10.8
|
||||
+409
@@ -0,0 +1,409 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Background workers for the SRAS viewer.
|
||||
|
||||
Every worker is a plain QObject moved onto its own QThread by
|
||||
SrasViewerWindow._run_worker, exposing signals only. Workers must never touch
|
||||
GUI-thread-owned state (the display caches in particular) — they take
|
||||
everything they need through their constructor and hand results back by signal.
|
||||
"""
|
||||
|
||||
import os
|
||||
from concurrent.futures import ProcessPoolExecutor, ThreadPoolExecutor, as_completed
|
||||
from concurrent.futures.process import BrokenProcessPool
|
||||
|
||||
import numpy as np
|
||||
from PyQt6.QtCore import QObject, pyqtSignal
|
||||
|
||||
import sras_compute as compute
|
||||
from sras_compute import (
|
||||
cache_file, compute_angle_alignment, compute_rf_image, dc_image_mv,
|
||||
)
|
||||
from sras_format import CH3_IDX, CH4_IDX, SrasFile
|
||||
|
||||
# Concurrency caps. Batch conversion runs one process per file, and each of
|
||||
# those processes threads internally, so the two must be divided rather than
|
||||
# both set to the core count. Files also commonly sit on one external drive,
|
||||
# where a dozen concurrent readers is slower than a few — hence the low
|
||||
# default, overridable from the environment.
|
||||
_BATCH_MAX_PROCS = int(os.environ.get("SRAS_BATCH_PROCS", 0)) or min(
|
||||
4, os.cpu_count() or 2)
|
||||
|
||||
# Spawning a pool costs roughly a second of interpreter startup (each child
|
||||
# re-imports the entry module). That is noise against a multi-GB scan but
|
||||
# dominates a batch of small files, where it would make the job *slower* —
|
||||
# so below this total size the batch just runs in the worker thread.
|
||||
_BATCH_POOL_MIN_BYTES = int(os.environ.get("SRAS_BATCH_POOL_MIN_MB", 512)) * 1024 * 1024
|
||||
|
||||
|
||||
class CancellableWorker(QObject):
|
||||
"""A worker whose compute polls stop() between row chunks.
|
||||
|
||||
Without this a shutdown has to wait out whatever is in flight, and on a
|
||||
large scan a single angle is ~40 s — far too long to block closing the
|
||||
window. Chunk-level polling bounds the wait to one chunk instead.
|
||||
"""
|
||||
|
||||
def __init__(self):
|
||||
super().__init__()
|
||||
self._stop = False
|
||||
|
||||
def stop(self):
|
||||
self._stop = True
|
||||
|
||||
def _stopped(self) -> bool:
|
||||
return self._stop
|
||||
|
||||
|
||||
class _PooledWorker(CancellableWorker):
|
||||
"""Fans a per-item computation across a thread pool, emitting each result
|
||||
from this worker's own thread as it lands (never from a pool thread).
|
||||
|
||||
Subclasses provide _plan() -> n_workers (stashing whatever per-run
|
||||
context they need), _items(), _one(item) -> result, and _emit(result).
|
||||
On stop(): queued items are dropped, in-flight ones are not waited for —
|
||||
that is what keeps closing the window responsive on a large scan.
|
||||
"""
|
||||
finished = pyqtSignal()
|
||||
error = pyqtSignal(str)
|
||||
|
||||
def run(self):
|
||||
try:
|
||||
pool = ThreadPoolExecutor(max_workers=max(1, self._plan()))
|
||||
try:
|
||||
futures = [pool.submit(self._one, it) for it in self._items()]
|
||||
for fut in as_completed(futures):
|
||||
if self._stop:
|
||||
break
|
||||
self._emit(fut.result())
|
||||
finally:
|
||||
pool.shutdown(wait=not self._stop, cancel_futures=True)
|
||||
self.finished.emit()
|
||||
except Exception as exc:
|
||||
self.error.emit(str(exc))
|
||||
|
||||
|
||||
class LoadWorker(QObject):
|
||||
finished = pyqtSignal(object) # SrasFile | None
|
||||
error = pyqtSignal(str)
|
||||
|
||||
def __init__(self, path: str):
|
||||
super().__init__()
|
||||
self._path = path
|
||||
|
||||
def run(self):
|
||||
try:
|
||||
self.finished.emit(SrasFile(self._path))
|
||||
except Exception as exc:
|
||||
self.error.emit(str(exc))
|
||||
self.finished.emit(None)
|
||||
|
||||
|
||||
class ComputeWorker(CancellableWorker):
|
||||
"""Computes one displayable image for (angle, channel).
|
||||
|
||||
For CH1/Velocity (FFT-derived) channels, the FFT is only run for pixels
|
||||
whose DC4 (Bias B) mean is at or above dc_threshold_mv — masked pixels are
|
||||
left at 0 MHz without ever being FFT'd, since that's the expensive part of
|
||||
a scan. If the DC4 image for this angle is already known, pass it in as
|
||||
*dc4_mv* to skip re-reading the CH4 channel from disk entirely.
|
||||
|
||||
Emits a plain ``np.ndarray`` already in display units.
|
||||
"""
|
||||
finished = pyqtSignal(object)
|
||||
error = pyqtSignal(str)
|
||||
|
||||
def __init__(self, sras: SrasFile, angle_idx: int, ch_idx: int,
|
||||
apply_bg_sub: bool = True, n_fft: int | None = None,
|
||||
dc_threshold_mv: float = 0.0,
|
||||
dc4_mv: np.ndarray | None = None,
|
||||
is_fft_mode: bool = False):
|
||||
super().__init__()
|
||||
self._sras = sras
|
||||
self._angle = angle_idx
|
||||
self._ch = ch_idx
|
||||
self._apply_bg_sub = apply_bg_sub
|
||||
self._n_fft = n_fft
|
||||
self._dc_threshold = dc_threshold_mv
|
||||
self._dc4_mv = dc4_mv
|
||||
self._is_fft_mode = is_fft_mode
|
||||
|
||||
def run(self):
|
||||
try:
|
||||
if self._is_fft_mode:
|
||||
img = compute_rf_image(
|
||||
self._sras, self._angle, dc_threshold_mv=self._dc_threshold,
|
||||
apply_bg_sub=self._apply_bg_sub, n_fft=self._n_fft,
|
||||
dc4_mv=self._dc4_mv, should_stop=self._stopped)
|
||||
else:
|
||||
img = dc_image_mv(self._sras, self._angle, self._ch,
|
||||
should_stop=self._stopped)
|
||||
# On cancellation the image is only partly filled, so hand back
|
||||
# None rather than something that would be cached as real. The
|
||||
# signal still fires either way — it is what quits the thread.
|
||||
self.finished.emit(None if self._stop else img)
|
||||
except Exception as exc:
|
||||
self.error.emit(str(exc))
|
||||
|
||||
|
||||
class DcPrecomputeWorker(_PooledWorker):
|
||||
"""Computes CH3/CH4 DC images for every angle in the background.
|
||||
|
||||
DC images are cheap (a per-waveform mean, no FFT) compared to the
|
||||
CH1/Velocity FFT, so precomputing them for the whole file right after load
|
||||
makes switching angles instant while on a DC channel, and also means the
|
||||
FFT masking step (which needs a DC4 image) rarely has to wait on anything.
|
||||
"""
|
||||
angle_done = pyqtSignal(int, np.ndarray, np.ndarray) # angle_idx, dc3_mv, dc4_mv
|
||||
|
||||
def __init__(self, sras: SrasFile):
|
||||
super().__init__()
|
||||
self._sras = sras
|
||||
self._angle_budget = 0
|
||||
|
||||
def _plan(self) -> int:
|
||||
n_workers, self._angle_budget = compute.plan_angle_level(self._sras)
|
||||
return n_workers
|
||||
|
||||
def _items(self):
|
||||
return range(self._sras.n_angles)
|
||||
|
||||
def _one(self, a: int) -> tuple[int, np.ndarray, np.ndarray]:
|
||||
# max_workers=1 *and* a budget share: this call is one of several
|
||||
# concurrent angles, and both the thread count and the buffer size
|
||||
# have to be divided (see compute.plan_angle_level).
|
||||
kw = dict(max_workers=1, budget=self._angle_budget,
|
||||
should_stop=self._stopped)
|
||||
return (a,
|
||||
dc_image_mv(self._sras, a, CH3_IDX, **kw),
|
||||
dc_image_mv(self._sras, a, CH4_IDX, **kw))
|
||||
|
||||
def _emit(self, result):
|
||||
self.angle_done.emit(*result)
|
||||
|
||||
|
||||
class BatchCacheWorker(QObject):
|
||||
"""Batch-computes and stores DC or FFT images into each of *paths*'s v7
|
||||
CACH tail, in place — converting v6 sources to v7 on first use, or updating
|
||||
an existing v7 file's cache blocks without disturbing whatever the other
|
||||
block already holds.
|
||||
|
||||
*mode* is ``"dc"`` (CH3/CH4 mean images), ``"fft"`` (CH1 peak-frequency
|
||||
images, unmasked — masking is applied at display time, same as v5's PREC
|
||||
convention), or ``"fft_rowavg"`` (same-row, distance-weighted CH1
|
||||
averaging before the FFT — needs *dc_threshold_mv* and a positive
|
||||
*row_avg_n*; see ``sras_compute.cache_file``).
|
||||
|
||||
Files are processed one per subprocess: they are fully independent, each
|
||||
opens its own memmap and writes only its own bytes, and only path strings
|
||||
and scalars cross the process boundary. Emits ``progress(int)`` (0–100 by
|
||||
files completed), ``file_done(str, str)`` (path, error message or "") so
|
||||
one file's failure doesn't abort the batch, and ``finished()``.
|
||||
"""
|
||||
progress = pyqtSignal(int)
|
||||
file_done = pyqtSignal(str, str)
|
||||
finished = pyqtSignal()
|
||||
|
||||
def __init__(self, paths: list[str], mode: str, apply_bg_sub: bool,
|
||||
dc_threshold_mv: float | None = None, row_avg_n: int = 0):
|
||||
super().__init__()
|
||||
self._paths = paths
|
||||
self._mode = mode
|
||||
self._apply_bg_sub = apply_bg_sub
|
||||
self._dc_threshold = dc_threshold_mv
|
||||
self._row_avg_n = row_avg_n
|
||||
|
||||
def _report(self, path: str, err: str, done: int, total: int):
|
||||
self.file_done.emit(path, err)
|
||||
self.progress.emit(int(done / max(1, total) * 100))
|
||||
|
||||
def _run_pooled(self, paths: list[str], n_procs: int) -> list[str]:
|
||||
"""Process the batch across *n_procs* subprocesses. Returns the paths
|
||||
that never got a real answer because the pool itself died, so the
|
||||
caller can retry them in-process.
|
||||
|
||||
Under spawn each child re-imports the entry module, so the batch must
|
||||
survive that going wrong (an unguarded __main__, a frozen build, a
|
||||
sandbox that forbids subprocesses) rather than reporting every file as
|
||||
failed — hence the retry list instead of a per-file error.
|
||||
"""
|
||||
# Each child threads internally; divide the machine rather than
|
||||
# letting every process claim every core.
|
||||
per_proc_workers = max(1, (os.cpu_count() or 4) // n_procs)
|
||||
unresolved: list[str] = []
|
||||
done = 0
|
||||
|
||||
with ProcessPoolExecutor(max_workers=n_procs) as executor:
|
||||
futures = {
|
||||
executor.submit(cache_file, p, self._mode, self._apply_bg_sub,
|
||||
compute.get_fft_backend(), per_proc_workers,
|
||||
dc_threshold_mv=self._dc_threshold,
|
||||
row_avg_n=self._row_avg_n): p
|
||||
for p in paths
|
||||
}
|
||||
for fut in as_completed(futures):
|
||||
path = futures[fut]
|
||||
try:
|
||||
err = fut.result()
|
||||
except BrokenProcessPool:
|
||||
unresolved.append(path)
|
||||
continue
|
||||
except Exception as exc:
|
||||
err = str(exc)
|
||||
done += 1
|
||||
self._report(path, err, done, len(paths))
|
||||
|
||||
return unresolved
|
||||
|
||||
def _run_inline(self, paths: list[str], done: int, total: int):
|
||||
"""Fallback / single-file path: compute in this thread. Still uses the
|
||||
full core count internally, since nothing else is competing."""
|
||||
for path in paths:
|
||||
try:
|
||||
err = cache_file(path, self._mode, self._apply_bg_sub,
|
||||
compute.get_fft_backend(),
|
||||
compute.default_max_workers(),
|
||||
dc_threshold_mv=self._dc_threshold,
|
||||
row_avg_n=self._row_avg_n)
|
||||
except Exception as exc:
|
||||
err = str(exc)
|
||||
done += 1
|
||||
self._report(path, err, done, total)
|
||||
|
||||
def _worth_pooling(self, paths: list[str]) -> bool:
|
||||
if len(paths) < 2:
|
||||
return False
|
||||
total = 0
|
||||
for p in paths:
|
||||
try:
|
||||
total += os.path.getsize(p)
|
||||
except OSError:
|
||||
pass # unreadable files are reported by cache_file
|
||||
return total >= _BATCH_POOL_MIN_BYTES
|
||||
|
||||
def run(self):
|
||||
paths = self._paths
|
||||
n_procs = max(1, min(_BATCH_MAX_PROCS, len(paths)))
|
||||
|
||||
if not self._worth_pooling(paths):
|
||||
self._run_inline(paths, 0, len(paths))
|
||||
self.finished.emit()
|
||||
return
|
||||
|
||||
try:
|
||||
unresolved = self._run_pooled(paths, n_procs)
|
||||
except Exception:
|
||||
# The pool could not be created or collapsed wholesale.
|
||||
unresolved = list(paths)
|
||||
|
||||
if unresolved:
|
||||
self._run_inline(unresolved, len(paths) - len(unresolved), len(paths))
|
||||
|
||||
self.finished.emit()
|
||||
|
||||
|
||||
class AngleAlignmentWorker(QObject):
|
||||
"""Computes the rigid (rotation + translation, never scale) alignment for
|
||||
every angle in *sras* against *ref_angle_idx*, by cross-correlating each
|
||||
angle's CH4 image against the reference's. Both the rotation and the
|
||||
translation are found from image content — see compute_angle_alignment.
|
||||
"""
|
||||
progress = pyqtSignal(int) # 0–100
|
||||
finished = pyqtSignal(object, str) # AlignmentResult|None, error ("" = success)
|
||||
|
||||
def __init__(self, sras: SrasFile, ref_angle_idx: int, dc_threshold_mv: float):
|
||||
super().__init__()
|
||||
self._sras = sras
|
||||
self._ref = ref_angle_idx
|
||||
self._threshold = dc_threshold_mv
|
||||
|
||||
def run(self):
|
||||
try:
|
||||
result = compute_angle_alignment(
|
||||
self._sras, self._ref, self._threshold,
|
||||
progress_cb=self.progress.emit)
|
||||
self.finished.emit(result, "")
|
||||
except Exception as exc:
|
||||
self.finished.emit(None, str(exc))
|
||||
|
||||
|
||||
class Ch4MaskWorker(_PooledWorker):
|
||||
"""Fetches each requested angle's CH4 (Bias B) DC image in mV, for
|
||||
ManualAlignmentDialog's initial threshold-mask overlay.
|
||||
|
||||
Reuses dc_image_mv, which prefers a stored v5/v7 cache over recomputing
|
||||
from raw waveforms, so this only does real work for a file that hasn't
|
||||
gone through the v7 "Convert" batch step and for angles the main
|
||||
window's own DcPrecomputeWorker (which runs automatically right after
|
||||
every file load) hasn't reached yet. In the common case — the user opens
|
||||
Fusion -> Manual Alignment after DC precompute has already finished —
|
||||
*angle_indices* is empty and this worker is never even constructed (see
|
||||
ManualAlignmentDialog._start_mask_prep).
|
||||
"""
|
||||
angle_done = pyqtSignal(int, np.ndarray) # angle_idx, dc4_mv
|
||||
|
||||
def __init__(self, sras: SrasFile, angle_indices: list[int]):
|
||||
super().__init__()
|
||||
self._sras = sras
|
||||
self._angles = angle_indices
|
||||
self._budget = 0
|
||||
|
||||
def _plan(self) -> int:
|
||||
n_workers, self._budget = compute.plan_angle_level(self._sras)
|
||||
return n_workers
|
||||
|
||||
def _items(self):
|
||||
return self._angles
|
||||
|
||||
def _one(self, a: int) -> tuple[int, np.ndarray]:
|
||||
return a, dc_image_mv(self._sras, a, CH4_IDX,
|
||||
max_workers=1, budget=self._budget)
|
||||
|
||||
def _emit(self, result):
|
||||
self.angle_done.emit(*result)
|
||||
|
||||
|
||||
class CrossCorrelateWorker(_PooledWorker):
|
||||
"""Rigid registration (rotation + translation, never scale) of each of
|
||||
*angle_indices* against *ref_angle_idx*, for ManualAlignmentDialog's Auto
|
||||
Cross-Correlate button.
|
||||
|
||||
Runs on a background thread — registering a real many-angle,
|
||||
high-resolution scan takes long enough that doing it on the GUI thread
|
||||
would visibly freeze the dialog. Rotation is *searched*, not taken from the
|
||||
stage's reported angle: see compute.register_angle_to_reference, which
|
||||
seeds from that angle but scores both of its signs and refines from there.
|
||||
dc4_mv is the dialog's own already-in-memory per-angle CH4 image — this
|
||||
worker does no fetching of its own.
|
||||
"""
|
||||
# angle_idx, rotation_deg, shift_x_mm, shift_y_mm, score, source
|
||||
angle_done = pyqtSignal(int, float, float, float, float, str)
|
||||
|
||||
def __init__(self, sras: SrasFile, ref_angle_idx: int, angle_indices: list[int],
|
||||
dc4_mv: dict[int, np.ndarray], *,
|
||||
sources: tuple[str, ...], dc_threshold_mv: float,
|
||||
search_deg: float):
|
||||
super().__init__()
|
||||
self._sras = sras
|
||||
self._ref = ref_angle_idx
|
||||
self._angles = angle_indices
|
||||
self._dc4_mv = dc4_mv
|
||||
self._sources = sources
|
||||
self._threshold = dc_threshold_mv
|
||||
self._search_deg = search_deg
|
||||
|
||||
def _plan(self) -> int:
|
||||
return compute.registration_workers(self._sras)
|
||||
|
||||
def _items(self):
|
||||
return self._angles
|
||||
|
||||
def _one(self, a: int) -> tuple[int, compute.RigidFit]:
|
||||
return a, compute.register_angle_to_reference(
|
||||
self._sras, a, self._ref, self._dc4_mv,
|
||||
dc_threshold_mv=self._threshold, sources=self._sources,
|
||||
search_deg=self._search_deg)
|
||||
|
||||
def _emit(self, result):
|
||||
a, fit = result
|
||||
self.angle_done.emit(a, fit.rotation_deg, fit.shift_mm[0],
|
||||
fit.shift_mm[1], fit.score, fit.source)
|
||||
@@ -0,0 +1,16 @@
|
||||
"""Shared test setup: repo-root imports, the offscreen Qt platform, and
|
||||
hermetic QSettings (tests must not read or write the user's real viewer
|
||||
settings)."""
|
||||
|
||||
import os
|
||||
import sys
|
||||
import tempfile
|
||||
from pathlib import Path
|
||||
|
||||
os.environ.setdefault("QT_QPA_PLATFORM", "offscreen")
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
|
||||
|
||||
from PyQt6.QtCore import QSettings # noqa: E402
|
||||
|
||||
QSettings.setPath(QSettings.Format.IniFormat, QSettings.Scope.UserScope,
|
||||
tempfile.mkdtemp(prefix="sras_qsettings_"))
|
||||
@@ -0,0 +1,212 @@
|
||||
"""Angle-alignment tests: does registration actually stack the scans?
|
||||
|
||||
Builds a synthetic scan in which one sample is imaged at several *known*
|
||||
rotations and offsets (tools/make_test_sras.write_rotating) and checks that the
|
||||
alignment path recovers them, that the shared canvas is angle 0's own pixel
|
||||
grid extended, and that nothing in the result depends on any other angle's
|
||||
stage coordinates.
|
||||
|
||||
No Qt — this exercises sras_compute directly. See tests/test_gui.py for the
|
||||
dialog and Aligned-View plumbing.
|
||||
"""
|
||||
|
||||
from types import SimpleNamespace
|
||||
|
||||
import numpy as np
|
||||
import pytest
|
||||
|
||||
import sras_compute as compute
|
||||
from sras_format import CH4_IDX, SrasFile, adc_to_mv
|
||||
import tools.make_test_sras as gen
|
||||
|
||||
# Registration is limited by how far a feature moves per degree: with this
|
||||
# sample's ~1 mm radius and a ~16 µm registration pitch, a quarter degree is
|
||||
# already sub-pixel, so it is the floor of what any metric can resolve here.
|
||||
_ROT_TOL_DEG = 0.5
|
||||
_SHIFT_TOL_MM = 0.02
|
||||
_STACK_IOU_MIN = 0.90
|
||||
_THRESHOLD_MV = 80.0
|
||||
|
||||
|
||||
def dc4_images(sras: SrasFile) -> dict[int, np.ndarray]:
|
||||
return {a: adc_to_mv(compute.compute_dc_image(sras, a, CH4_IDX), *sras.cal(CH4_IDX))
|
||||
for a in range(sras.n_angles)}
|
||||
|
||||
|
||||
def mm_transform(sras: SrasFile, result, angle_idx: int) -> np.ndarray:
|
||||
"""Recover the pure mm-space rotation from a canvas->raw affine.
|
||||
|
||||
matrix == D @ R^T @ A_out, where A_out and D only carry the canvas and
|
||||
per-angle pixel pitches; undoing both must leave something orthonormal, or
|
||||
the transform is smuggling in a scale or a shear.
|
||||
"""
|
||||
dx_a, dy_a = compute.pixel_pitch_mm(sras, angle_idx)
|
||||
A_out = np.array([[0.0, result.canvas_dx_mm], [result.canvas_dy_mm, 0.0]])
|
||||
D = np.array([[0.0, 1.0 / dy_a], [1.0 / dx_a, 0.0]])
|
||||
return np.linalg.inv(D) @ result.per_angle[angle_idx].matrix @ np.linalg.inv(A_out)
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def rig(tmp_path_factory):
|
||||
"""The rotating-sample scan plus everything computed from it once."""
|
||||
tmpdir = tmp_path_factory.mktemp("sras_align")
|
||||
path = tmpdir / "rotating.sras"
|
||||
meta = gen.write_rotating(path, n_angles=5)
|
||||
sras = SrasFile(str(path))
|
||||
dc4 = dc4_images(sras)
|
||||
fits = {a: compute.register_angle_to_reference(
|
||||
sras, a, 0, dc4, dc_threshold_mv=_THRESHOLD_MV)
|
||||
for a in range(sras.n_angles)}
|
||||
result = compute.compute_angle_alignment(sras, 0, _THRESHOLD_MV)
|
||||
return SimpleNamespace(path=path, sras=sras, truth=meta["truth"],
|
||||
dc4=dc4, fits=fits, result=result)
|
||||
|
||||
|
||||
def test_registration_recovers_truth(rig):
|
||||
"""Per-angle rigid registration (rotation + translation, no scale)."""
|
||||
for a, fit in rig.fits.items():
|
||||
t_rot, t_shift = rig.truth[a]
|
||||
rot_err = abs(fit.rotation_deg - t_rot)
|
||||
shift_err = float(np.hypot(fit.shift_mm[0] - t_shift[0],
|
||||
fit.shift_mm[1] - t_shift[1]))
|
||||
assert rot_err <= _ROT_TOL_DEG, \
|
||||
(f"angle {a}: got {fit.rotation_deg:.3f}°, truth {t_rot:.3f}° "
|
||||
f"(err {rot_err:.3f}°)")
|
||||
assert shift_err <= _SHIFT_TOL_MM, f"angle {a}: err {shift_err:.4f} mm"
|
||||
assert rig.fits[0] == compute.RigidFit(0.0, (0.0, 0.0), 1.0, "reference"), \
|
||||
"reference angle registers as exact identity"
|
||||
|
||||
|
||||
def test_stage_angle_sign_is_not_trusted(rig):
|
||||
# The stage's rotational sense relative to this module's math-positive
|
||||
# convention is not knowable from the file, and the old code hardcoded a
|
||||
# guess. Flipping every reported angle must therefore change nothing: the
|
||||
# search scores both signs and the images decide.
|
||||
flipped = SrasFile(str(rig.path))
|
||||
flipped.angles_deg = -flipped.angles_deg
|
||||
flipped_fits = {a: compute.register_angle_to_reference(
|
||||
flipped, a, 0, rig.dc4, dc_threshold_mv=_THRESHOLD_MV)
|
||||
for a in range(1, flipped.n_angles)}
|
||||
mismatches = {a: (flipped_fits[a].rotation_deg, rig.fits[a].rotation_deg)
|
||||
for a in flipped_fits if flipped_fits[a] != rig.fits[a]}
|
||||
assert not mismatches, \
|
||||
f"negating every reported stage angle changed fits: {mismatches}"
|
||||
|
||||
|
||||
def test_stage_coordinates_are_not_consulted(rig):
|
||||
# Move every non-reference angle's scan window somewhere else entirely.
|
||||
# Only angle 0's coordinates may matter, so every fit must be untouched.
|
||||
moved = SrasFile(str(rig.path))
|
||||
for a in range(1, moved.n_angles):
|
||||
moved.x_start_mm[a] += 13.5 * a
|
||||
moved.y_pos_per_angle[a] = moved.y_pos_per_angle[a] - 9.25 * a
|
||||
moved_dc4 = dc4_images(moved)
|
||||
moved_fits = {a: compute.register_angle_to_reference(
|
||||
moved, a, 0, moved_dc4, dc_threshold_mv=_THRESHOLD_MV)
|
||||
for a in range(1, moved.n_angles)}
|
||||
mismatches = {a: (round(moved_fits[a].rotation_deg, 4), rig.fits[a].rotation_deg)
|
||||
for a in moved_fits if moved_fits[a] != rig.fits[a]}
|
||||
assert not mismatches, \
|
||||
f"relocating every other angle's scan window changed fits: {mismatches}"
|
||||
|
||||
|
||||
def test_canvas_is_reference_grid_extended(rig):
|
||||
sras, result = rig.sras, rig.result
|
||||
t0 = result.per_angle[0]
|
||||
assert np.allclose(t0.matrix, np.eye(2)), \
|
||||
f"angle 0's transform has rotation/scale/shear: {t0.matrix}"
|
||||
assert np.allclose(t0.offset, np.round(t0.offset)), \
|
||||
f"angle 0 does not land on whole canvas pixels: {t0.offset}"
|
||||
assert ((result.canvas_dx_mm, result.canvas_dy_mm)
|
||||
== compute.pixel_pitch_mm(sras, 0)), \
|
||||
"canvas pitch is angle 0's own pitch"
|
||||
|
||||
n_rows, n_cols = result.canvas_shape
|
||||
x_axis = result.canvas_origin_mm[0] + np.arange(n_cols) * result.canvas_dx_mm
|
||||
y_axis = result.canvas_origin_mm[1] + np.arange(n_rows) * result.canvas_dy_mm
|
||||
row0, col0 = int(round(-t0.offset[0])), int(round(-t0.offset[1]))
|
||||
a0_rows, a0_cols = sras.image_shape(0)
|
||||
assert np.allclose(x_axis[col0:col0 + a0_cols], sras.x_axis_mm(0)), \
|
||||
"canvas X axis reproduces angle 0's own X coordinates"
|
||||
assert np.allclose(y_axis[row0:row0 + a0_rows], sras.y_positions_mm(0)), \
|
||||
"canvas Y axis reproduces angle 0's own Y coordinates"
|
||||
assert (n_rows >= max(int(sras.n_rows[a]) for a in range(sras.n_angles))
|
||||
and n_cols >= max(int(sras.n_frames[a]) for a in range(sras.n_angles))), \
|
||||
f"canvas does not cover every angle's footprint: {result.canvas_shape}"
|
||||
|
||||
|
||||
def test_transforms_are_pure_rotations(rig):
|
||||
"""No scaling anywhere in the per-angle transforms."""
|
||||
for a in range(rig.sras.n_angles):
|
||||
R = mm_transform(rig.sras, rig.result, a)
|
||||
assert (np.allclose(R @ R.T, np.eye(2), atol=1e-9)
|
||||
and abs(abs(np.linalg.det(R)) - 1.0) < 1e-9), \
|
||||
f"angle {a}: det={np.linalg.det(R):.6f}"
|
||||
|
||||
|
||||
def test_all_angles_stack(rig):
|
||||
aligned = {a: compute.apply_alignment(rig.result, a, rig.dc4[a])
|
||||
for a in range(rig.sras.n_angles)}
|
||||
base = aligned[0] >= _THRESHOLD_MV
|
||||
for a in range(1, rig.sras.n_angles):
|
||||
other = aligned[a] >= _THRESHOLD_MV
|
||||
iou = float((base & other).sum()) / max(1, int((base | other).sum()))
|
||||
assert iou >= _STACK_IOU_MIN, f"angle {a}: IoU {iou:.4f}"
|
||||
|
||||
|
||||
def test_downsampled_preview_lands_with_full_res(rig):
|
||||
# ManualAlignmentDialog reprojects block-mean-downsampled masks, so the
|
||||
# affine has to account for the factor. When it did not, every preview
|
||||
# layer came out magnified by that factor and offset — the overlay showed a
|
||||
# blown-up crop of each mask, which is not something you can align by eye.
|
||||
sras, result = rig.sras, rig.result
|
||||
pitch = (result.canvas_dx_mm, result.canvas_dy_mm)
|
||||
a = sras.n_angles - 1
|
||||
p = result.per_angle[a]
|
||||
full_mask = (rig.dc4[a] >= _THRESHOLD_MV).astype(np.float32)
|
||||
full = compute.reproject_mask(
|
||||
sras, a, 0, full_mask, p.rotation_deg, p.shift_mm, pitch,
|
||||
result.canvas_origin_mm, result.canvas_shape)
|
||||
fy, fx = 4, 16
|
||||
small = compute.reproject_mask(
|
||||
sras, a, 0, compute.block_mean_2d(full_mask, fy, fx),
|
||||
p.rotation_deg, p.shift_mm, (pitch[0] * fx, pitch[1] * fy),
|
||||
result.canvas_origin_mm,
|
||||
(result.canvas_shape[0] // fy, result.canvas_shape[1] // fx),
|
||||
src_downsample=(fy, fx))
|
||||
|
||||
# Compare in mm, via each layer's own center of mass.
|
||||
def com_mm(layer, px, py):
|
||||
rows, cols = np.nonzero(layer > 0.5)
|
||||
return np.array([cols.mean() * px, rows.mean() * py])
|
||||
|
||||
d = com_mm(small, pitch[0] * fx, pitch[1] * fy) - com_mm(full, *pitch)
|
||||
assert (abs(d[0]) <= abs(pitch[0] * fx) and abs(d[1]) <= abs(pitch[1] * fy)), \
|
||||
f"downsampled preview offset {d[0]:+.4f}, {d[1]:+.4f} mm"
|
||||
|
||||
|
||||
def test_manual_path_reproduces_geometry(rig):
|
||||
sras, result = rig.sras, rig.result
|
||||
params = {a: compute.ManualAngleParams(t.rotation_deg, t.shift_mm)
|
||||
for a, t in result.per_angle.items()}
|
||||
manual = compute.build_manual_alignment(sras, 0, _THRESHOLD_MV, params)
|
||||
assert (manual.canvas_shape == result.canvas_shape
|
||||
and np.allclose(manual.canvas_origin_mm, result.canvas_origin_mm)
|
||||
and all(np.allclose(manual.per_angle[a].matrix, result.per_angle[a].matrix)
|
||||
and np.allclose(manual.per_angle[a].offset, result.per_angle[a].offset)
|
||||
for a in range(sras.n_angles))), \
|
||||
"build_manual_alignment matches compute_angle_alignment for the same params"
|
||||
|
||||
|
||||
def test_sidecar_roundtrip(rig):
|
||||
sras, result = rig.sras, rig.result
|
||||
params = {a: compute.ManualAngleParams(t.rotation_deg, t.shift_mm)
|
||||
for a, t in result.per_angle.items()}
|
||||
compute.save_manual_alignment(sras, 0, _THRESHOLD_MV, params)
|
||||
loaded = compute.load_manual_alignment(sras)
|
||||
assert (loaded is not None
|
||||
and all(np.isclose(loaded.per_angle[a].rotation_deg, params[a].rotation_deg)
|
||||
and np.allclose(loaded.per_angle[a].shift_mm, params[a].shift_mm)
|
||||
for a in range(sras.n_angles))), \
|
||||
"sidecar reloads every angle's params"
|
||||
assert compute.delete_manual_alignment(sras), "sidecar deletes cleanly"
|
||||
@@ -0,0 +1,356 @@
|
||||
"""Behavioural tests for the compute/format layer.
|
||||
|
||||
Covers what the golden-hash harness can't: the v6->v7 cache round-trip
|
||||
(including block carry-forward), parallel-vs-serial identity, the no-mask
|
||||
fast path, and the ROI bounding-box mask optimisation.
|
||||
"""
|
||||
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
import numpy as np
|
||||
import pytest
|
||||
|
||||
import sras_compute as compute
|
||||
from sras_compute import (
|
||||
cache_file, compute_dc_image, compute_rf_image, dc_image_mv,
|
||||
)
|
||||
from sras_format import CH3_IDX, CH4_IDX, SrasFile, adc_to_mv
|
||||
import tools.make_test_sras as gen
|
||||
|
||||
REPO = Path(__file__).resolve().parent.parent
|
||||
|
||||
|
||||
def test_cache_roundtrip(tmp_path):
|
||||
"""v6 -> v7 for DC, then FFT, asserting the first block survives the
|
||||
second write (the carry-forward path in write_v7_cache)."""
|
||||
path = tmp_path / "roundtrip.sras"
|
||||
gen.write(path, n_angles=3, seed=1, samples_per_frame=64)
|
||||
|
||||
src = SrasFile(str(path))
|
||||
assert src.version == 6, f"got v{src.version}"
|
||||
expect_dc3 = [dc_image_mv(src, a, CH3_IDX) for a in range(src.n_angles)]
|
||||
expect_dc4 = [dc_image_mv(src, a, CH4_IDX) for a in range(src.n_angles)]
|
||||
expect_fft = [compute_rf_image(src, a, dc_threshold_mv=None, apply_bg_sub=True)
|
||||
for a in range(src.n_angles)]
|
||||
|
||||
err = cache_file(str(path), "dc", True)
|
||||
assert err == "", err
|
||||
|
||||
after_dc = SrasFile(str(path))
|
||||
assert after_dc.version == 7, f"got v{after_dc.version}"
|
||||
assert all(x is not None for x in after_dc.precomputed_dc3_mv)
|
||||
assert all(np.allclose(after_dc.precomputed_dc3_mv[a], expect_dc3[a], atol=1e-4)
|
||||
for a in range(after_dc.n_angles))
|
||||
assert all(np.allclose(after_dc.precomputed_dc4_mv[a], expect_dc4[a], atol=1e-4)
|
||||
for a in range(after_dc.n_angles))
|
||||
assert all(x is None for x in after_dc.precomputed_freq_mhz), "no fft block yet"
|
||||
assert (after_dc.precomputed_dc3_mv[0].dtype == np.float32
|
||||
and after_dc.precomputed_dc3_mv[0].dtype.byteorder in ("=", "|")), \
|
||||
"cached images are native float32"
|
||||
assert after_dc.precomputed_dc3_mv[0].flags.writeable
|
||||
|
||||
err = cache_file(str(path), "fft", True)
|
||||
assert err == "", err
|
||||
|
||||
both = SrasFile(str(path))
|
||||
assert all(x is not None for x in both.precomputed_freq_mhz)
|
||||
assert all(np.allclose(both.precomputed_freq_mhz[a], expect_fft[a], atol=1e-3)
|
||||
for a in range(both.n_angles))
|
||||
assert all(np.allclose(both.precomputed_dc3_mv[a], expect_dc3[a], atol=1e-4)
|
||||
for a in range(both.n_angles)), \
|
||||
"DC block carried forward through the FFT write"
|
||||
assert both.precomputed_bg_sub is True
|
||||
|
||||
# The fast path must reproduce a fresh compute, and masking must still
|
||||
# apply on top of a cached (unmasked) image.
|
||||
fresh = SrasFile(str(path))
|
||||
fresh.precomputed_freq_mhz = [None] * fresh.n_angles
|
||||
dc4 = dc_image_mv(both, 0, CH4_IDX)
|
||||
thr = float(np.median(dc4))
|
||||
assert np.allclose(
|
||||
compute_rf_image(both, 0, dc_threshold_mv=None, apply_bg_sub=True),
|
||||
compute_rf_image(fresh, 0, dc_threshold_mv=None, apply_bg_sub=True),
|
||||
atol=1e-3), "cached fast path == fresh compute (unmasked)"
|
||||
assert np.allclose(
|
||||
compute_rf_image(both, 0, dc_threshold_mv=thr, apply_bg_sub=True),
|
||||
compute_rf_image(fresh, 0, dc_threshold_mv=thr, apply_bg_sub=True),
|
||||
atol=1e-3), "cached fast path == fresh compute (masked)"
|
||||
|
||||
# Waveform data must be byte-identical to the pre-cache file.
|
||||
orig = tmp_path / "roundtrip_orig.sras"
|
||||
gen.write(orig, n_angles=3, seed=1, samples_per_frame=64)
|
||||
o, n = SrasFile(str(orig)), SrasFile(str(path))
|
||||
assert all(np.array_equal(np.asarray(o.data[a]), np.asarray(n.data[a]))
|
||||
for a in range(o.n_angles)), \
|
||||
"waveform data untouched by the cache write"
|
||||
|
||||
|
||||
def test_partial_v7_cache(tmp_path):
|
||||
"""Only some angles cached: uncached angles must compute, not read zeros.
|
||||
This is the v5 bug the ragged normalisation fixed, checked via v7."""
|
||||
path = tmp_path / "partial.sras"
|
||||
gen.write(path, n_angles=3, seed=2, samples_per_frame=64)
|
||||
|
||||
src = SrasFile(str(path))
|
||||
expected = [compute_rf_image(src, a, dc_threshold_mv=None, apply_bg_sub=True)
|
||||
for a in range(src.n_angles)]
|
||||
partial = [expected[0], None, expected[2]] # angle 1 deliberately absent
|
||||
src.write_v7_cache(new_freq_mhz=partial, new_bg_sub=True)
|
||||
|
||||
reread = SrasFile(str(path))
|
||||
assert reread.precomputed_freq_mhz[1] is None
|
||||
assert (reread.precomputed_freq_mhz[0] is not None
|
||||
and reread.precomputed_freq_mhz[2] is not None)
|
||||
img1 = compute_rf_image(reread, 1, dc_threshold_mv=None, apply_bg_sub=True)
|
||||
assert np.any(img1 != 0) and np.allclose(img1, expected[1], atol=1e-3), \
|
||||
"uncached angle computes rather than returning zeros"
|
||||
|
||||
|
||||
def test_parallel_identity(tmp_path, monkeypatch):
|
||||
"""Forcing 1 worker vs many must give identical output — catches
|
||||
chunk-boundary and race bugs."""
|
||||
path = tmp_path / "parallel.sras"
|
||||
# Many rows, so the row loop actually splits into several chunks.
|
||||
n_rows, n_frames, spf = 48, 9, 256
|
||||
gen.write(path, n_angles=1, seed=3, samples_per_frame=spf,
|
||||
geometry=[(n_rows, n_frames)])
|
||||
sras = SrasFile(str(path))
|
||||
|
||||
# Shrink the budget so the outer row loop splits into many chunks, and
|
||||
# the block size so every chunk splits into many FFT tasks — the worst
|
||||
# case for boundary bugs.
|
||||
monkeypatch.setattr(compute, "_TOTAL_BYTES_BUDGET", 8 * n_frames * spf * 4)
|
||||
monkeypatch.setattr(compute, "_FFT_BLOCK", 4)
|
||||
fft_rows = compute._plan_fft_rows(n_frames, spf, compute._TOTAL_BYTES_BUDGET)
|
||||
assert fft_rows < n_rows, \
|
||||
f"FFT work actually splits into multiple chunks ({fft_rows} of {n_rows})"
|
||||
dc_rows = compute._chunk_rows_for(n_frames, spf, compute._TOTAL_BYTES_BUDGET)
|
||||
assert dc_rows < n_rows, \
|
||||
f"DC work actually splits into multiple chunks ({dc_rows} of {n_rows})"
|
||||
|
||||
monkeypatch.setattr(compute, "_MAX_WORKERS", 1)
|
||||
dc_serial = compute_dc_image(sras, 0, CH4_IDX)
|
||||
rf_serial = compute_rf_image(sras, 0, dc_threshold_mv=None, apply_bg_sub=True)
|
||||
dc4 = adc_to_mv(dc_serial, *sras.cal(CH4_IDX))
|
||||
thr = float(np.median(dc4))
|
||||
rf_masked_serial = compute_rf_image(sras, 0, dc_threshold_mv=thr,
|
||||
apply_bg_sub=True)
|
||||
rf_pad_serial = compute_rf_image(sras, 0, dc_threshold_mv=thr,
|
||||
apply_bg_sub=True, n_fft=spf * 8)
|
||||
|
||||
monkeypatch.setattr(compute, "_MAX_WORKERS", 8)
|
||||
dc_par = compute_dc_image(sras, 0, CH4_IDX)
|
||||
rf_par = compute_rf_image(sras, 0, dc_threshold_mv=None, apply_bg_sub=True)
|
||||
rf_masked_par = compute_rf_image(sras, 0, dc_threshold_mv=thr, apply_bg_sub=True)
|
||||
rf_pad_par = compute_rf_image(sras, 0, dc_threshold_mv=thr,
|
||||
apply_bg_sub=True, n_fft=spf * 8)
|
||||
|
||||
assert np.array_equal(dc_serial, dc_par), "dc image identical"
|
||||
assert np.array_equal(rf_serial, rf_par), "rf image identical (unmasked)"
|
||||
assert np.array_equal(rf_masked_serial, rf_masked_par), \
|
||||
"rf image identical (masked)"
|
||||
assert np.array_equal(rf_pad_serial, rf_pad_par), \
|
||||
"rf image identical (masked, padded/zoom)"
|
||||
|
||||
|
||||
@pytest.mark.parametrize("spf,bps", [(64, 2), (37, 1)])
|
||||
def test_zoom_identity(tmp_path, monkeypatch, spf, bps):
|
||||
"""The zoom peak search must reproduce the full padded-rfft argmax
|
||||
bit-for-bit, across pad factors, masking, bg-sub, dtype, and backend."""
|
||||
path = tmp_path / f"zoom_{spf}.sras"
|
||||
gen.write(path, n_angles=2, seed=6, samples_per_frame=spf, bps=bps)
|
||||
sras = SrasFile(str(path))
|
||||
dc4 = dc_image_mv(sras, 0, CH4_IDX)
|
||||
thr = float(np.median(dc4))
|
||||
|
||||
backends = ["scipy"] + (["pyfftw"] if compute.PYFFTW_AVAILABLE else [])
|
||||
for backend in backends:
|
||||
monkeypatch.setattr(compute, "_fft_backend", backend)
|
||||
for pad in (4, 8, 40):
|
||||
n_fft = spf * pad
|
||||
for thr_v in (None, thr):
|
||||
for bg in (False, True):
|
||||
ref = compute_rf_image(sras, 0, dc_threshold_mv=thr_v,
|
||||
apply_bg_sub=bg, n_fft=n_fft,
|
||||
exact=True)
|
||||
zoom = compute_rf_image(sras, 0, dc_threshold_mv=thr_v,
|
||||
apply_bg_sub=bg, n_fft=n_fft)
|
||||
diff = int((ref != zoom).sum())
|
||||
assert diff == 0, \
|
||||
(f"{diff} px differ: backend={backend} pad={pad} "
|
||||
f"thr={thr_v} bg={bg} spf={spf}")
|
||||
|
||||
# A threshold above every pixel masks everything: both paths must agree
|
||||
# on an all-zero image.
|
||||
all_masked = compute_rf_image(sras, 0, dc_threshold_mv=1e9, n_fft=spf * 8)
|
||||
assert not all_masked.any()
|
||||
|
||||
|
||||
def test_zoom_identity_fuzz():
|
||||
"""Hammer _peak_bins_zoom directly with adversarial spectra: noise,
|
||||
un-subtracted DC offsets, on-bin and off-bin tones, near-tie tone pairs,
|
||||
and all-zero rows."""
|
||||
import scipy.fft as scipy_fft
|
||||
|
||||
rng = np.random.default_rng(42)
|
||||
for _ in range(25):
|
||||
spf = int(rng.integers(16, 220))
|
||||
pad = int(rng.choice([4, 5, 8, 16, 40]))
|
||||
n_fft = spf * pad
|
||||
n_wf = 24
|
||||
w = rng.normal(scale=20.0, size=(n_wf, spf))
|
||||
t = np.arange(spf)
|
||||
# rows 0-5: pure/noisy tones (some off-bin), row 6-7: near-tie pair,
|
||||
# row 8: big DC offset, row 9: all zeros, rest: plain noise.
|
||||
for r in range(6):
|
||||
f = rng.uniform(1.0, spf / 2 - 1)
|
||||
w[r] = 60 * np.sin(2 * np.pi * f * t / spf) + w[r] * (r % 2)
|
||||
f1, f2 = rng.uniform(2.0, spf / 2 - 2, size=2)
|
||||
w[6] = 50 * np.sin(2 * np.pi * f1 * t / spf) \
|
||||
+ 49.9 * np.sin(2 * np.pi * f2 * t / spf)
|
||||
w[7] = 50 * np.sin(2 * np.pi * f1 * t / spf) \
|
||||
+ 50 * np.cos(2 * np.pi * f2 * t / spf)
|
||||
w[8] = 90 + rng.normal(scale=5.0, size=spf)
|
||||
w[9] = 0.0
|
||||
w = w.astype(np.float32)
|
||||
|
||||
S = scipy_fft.rfft(w, n=n_fft, axis=-1, workers=1)
|
||||
P = S.real ** 2
|
||||
P += S.imag ** 2
|
||||
P[:, 0] = 0.0
|
||||
ref = np.argmax(P, axis=1)
|
||||
|
||||
zp = compute._zoom_plan(spf, n_fft)
|
||||
got = compute._peak_bins_zoom(w, zp)
|
||||
bad = np.nonzero(ref != got)[0]
|
||||
assert not len(bad), \
|
||||
(f"spf={spf} pad={pad}: rows {bad.tolist()} picked "
|
||||
f"{got[bad].tolist()} instead of {ref[bad].tolist()}")
|
||||
|
||||
|
||||
def test_nomask_equals_low_threshold(tmp_path):
|
||||
"""dc_threshold_mv=None must equal a threshold below every pixel, while
|
||||
skipping the CH4 read."""
|
||||
path = tmp_path / "nomask.sras"
|
||||
gen.write(path, n_angles=2, seed=4, samples_per_frame=128)
|
||||
sras = SrasFile(str(path))
|
||||
for a in range(sras.n_angles):
|
||||
none_img = compute_rf_image(sras, a, dc_threshold_mv=None, apply_bg_sub=True)
|
||||
low_img = compute_rf_image(sras, a, dc_threshold_mv=-1e9, apply_bg_sub=True)
|
||||
assert np.array_equal(none_img, low_img), \
|
||||
f"angle {a}: None == -1e9 threshold"
|
||||
assert len(np.unique(none_img)) > 1, \
|
||||
f"angle {a}: image is degenerate ({len(np.unique(none_img))} unique)"
|
||||
|
||||
|
||||
def test_roi_mask():
|
||||
"""The bbox-restricted mask must equal a full-grid point-in-polygon test."""
|
||||
from matplotlib.path import Path as MplPath
|
||||
from sras_viewer import RoiQuad
|
||||
|
||||
rng = np.random.default_rng(0)
|
||||
x = np.linspace(-2.0, 3.0, 137)
|
||||
y = np.linspace(1.0, 4.0, 91)
|
||||
|
||||
cases = {
|
||||
"axis-aligned rect": np.array([[0.0, 1.5], [1.0, 1.5], [1.0, 3.0], [0.0, 3.0]]),
|
||||
"skewed quad": np.array([[-0.5, 1.2], [1.7, 1.9], [1.2, 3.4], [-1.0, 2.6]]),
|
||||
"entirely outside": np.array([[8.0, 8.0], [9.0, 8.0], [9.0, 9.0], [8.0, 9.0]]),
|
||||
"covers whole grid": np.array([[-9.0, -9.0], [9.0, -9.0], [9.0, 9.0], [-9.0, 9.0]]),
|
||||
"straddles left edge": np.array([[-4.0, 2.0], [0.5, 2.0], [0.5, 3.0], [-4.0, 3.0]]),
|
||||
}
|
||||
for _ in range(5):
|
||||
cases[f"random {_}"] = rng.uniform([-2.5, 0.5], [3.5, 4.5], size=(4, 2))
|
||||
|
||||
for name, pts in cases.items():
|
||||
roi = RoiQuad(pts)
|
||||
fast = roi.mask_for_grid(x, y)
|
||||
X, Y = np.meshgrid(x.astype(np.float64), y.astype(np.float64))
|
||||
slow = MplPath(pts).contains_points(
|
||||
np.column_stack([X.ravel(), Y.ravel()])).reshape(X.shape)
|
||||
assert np.array_equal(fast, slow), f"{name} ({int(slow.sum())} px inside)"
|
||||
|
||||
# Descending y axis (images are stored top-down in some scans).
|
||||
roi = RoiQuad(cases["skewed quad"])
|
||||
y_desc = y[::-1]
|
||||
fast = roi.mask_for_grid(x, y_desc)
|
||||
X, Y = np.meshgrid(x.astype(np.float64), y_desc.astype(np.float64))
|
||||
slow = MplPath(cases["skewed quad"]).contains_points(
|
||||
np.column_stack([X.ravel(), Y.ravel()])).reshape(X.shape)
|
||||
assert np.array_equal(fast, slow), "descending y axis"
|
||||
|
||||
|
||||
def test_legacy_parse(tmp_path):
|
||||
"""v2-v4 parsing against known written data."""
|
||||
for version in (2, 3, 4):
|
||||
path = tmp_path / f"legacy_v{version}.sras"
|
||||
meta = gen.write_legacy(path, version=version, n_angles=2, n_rows=4,
|
||||
n_frames=12, samples_per_frame=32, seed=version)
|
||||
s = SrasFile(str(path))
|
||||
assert s.version == version, f"got v{s.version}"
|
||||
assert list(s.n_rows) == [4, 4] and list(s.n_frames) == [12, 12], \
|
||||
f"rows={list(s.n_rows)} frames={list(s.n_frames)}"
|
||||
assert all(np.array_equal(np.asarray(s.data[a]), meta["data"][a])
|
||||
for a in range(s.n_angles)), \
|
||||
f"v{version} waveform data matches what was written"
|
||||
assert (s.background is not None) == (version >= 4), \
|
||||
f"v{version} background {'present' if version >= 4 else 'absent'}"
|
||||
assert (isinstance(s.precomputed_freq_mhz, list)
|
||||
and len(s.precomputed_freq_mhz) == s.n_angles), \
|
||||
f"v{version} precomputed stores are ragged lists"
|
||||
# DC image must equal a direct mean of the known input.
|
||||
expect = meta["data"][0][:, CH3_IDX, :, :].astype(np.float64).mean(axis=-1)
|
||||
assert np.allclose(compute_dc_image(s, 0, CH3_IDX), expect, atol=1e-3), \
|
||||
f"v{version} DC image equals a direct mean"
|
||||
|
||||
|
||||
def test_sras_average(tmp_path):
|
||||
"""The sras_average.py CLI: frame averaging with remainder handling."""
|
||||
src = tmp_path / "legacy_v4.sras"
|
||||
meta = gen.write_legacy(src, version=4, n_angles=2, n_rows=4, n_frames=12,
|
||||
samples_per_frame=32, seed=4)
|
||||
dst = tmp_path / "legacy_v4_avg.sras"
|
||||
proc = subprocess.run(
|
||||
[sys.executable, str(REPO / "sras_average.py"), str(src), str(dst), "--n", "4"],
|
||||
capture_output=True, text=True, cwd=REPO)
|
||||
assert proc.returncode == 0, (proc.stderr or proc.stdout).strip()[-200:]
|
||||
|
||||
avg = SrasFile(str(dst))
|
||||
assert avg.version == 4
|
||||
assert list(avg.n_frames) == [3, 3], f"{list(avg.n_frames)}"
|
||||
assert (avg.n_angles == 2 and list(avg.n_rows) == [4, 4]
|
||||
and avg.n_channels == meta["n_channels"])
|
||||
assert np.allclose(avg.ch_ymult_mv, SrasFile(str(src)).ch_ymult_mv), \
|
||||
"calibration preserved"
|
||||
assert np.array_equal(avg.background, SrasFile(str(src)).background), \
|
||||
"background preserved"
|
||||
src_data = meta["data"]
|
||||
expect0 = src_data[0][:, :, 0:4, :].astype(np.float32).mean(axis=2).astype(np.int16)
|
||||
assert np.array_equal(np.asarray(avg.data[0])[:, :, 0, :], expect0), \
|
||||
"first averaged group equals the mean of its 4 source frames"
|
||||
|
||||
# Remainder handling: 12 frames / 5 -> 2 full groups + 1 partial.
|
||||
dst2 = tmp_path / "legacy_v4_avg5.sras"
|
||||
subprocess.run([sys.executable, str(REPO / "sras_average.py"),
|
||||
str(src), str(dst2), "--n", "5"],
|
||||
capture_output=True, text=True, cwd=REPO)
|
||||
assert list(SrasFile(str(dst2)).n_frames) == [3, 3], \
|
||||
"partial trailing group kept by default"
|
||||
dst3 = tmp_path / "legacy_v4_avg5d.sras"
|
||||
subprocess.run([sys.executable, str(REPO / "sras_average.py"),
|
||||
str(src), str(dst3), "--n", "5", "--discard-remainder"],
|
||||
capture_output=True, text=True, cwd=REPO)
|
||||
assert list(SrasFile(str(dst3)).n_frames) == [2, 2], \
|
||||
"--discard-remainder drops the partial group"
|
||||
|
||||
|
||||
def test_unsupported_version_reported(tmp_path):
|
||||
"""cache_file must report, not raise, for a file it can't handle."""
|
||||
bogus = tmp_path / "bogus.sras"
|
||||
bogus.write_bytes(b"SRAS" + bytes([99]) + b"\x00" * 200)
|
||||
err = cache_file(str(bogus), "dc", True)
|
||||
assert err, "bad version returns an error string"
|
||||
missing = cache_file(str(tmp_path / "does_not_exist.sras"), "dc", True)
|
||||
assert missing, "missing file returns an error string"
|
||||
@@ -0,0 +1,501 @@
|
||||
"""Headless GUI test: drives SrasViewerWindow through the real Qt widgets,
|
||||
signals and worker threads under the offscreen platform plugin.
|
||||
|
||||
Covers the interactions a manual smoke test would: load, switch angles and
|
||||
channels, background DC precompute, lazy FFT compute, threshold and bg-sub
|
||||
changes, angle alignment, manual angle alignment, aligned view, ROI
|
||||
draw/move, and CSV export.
|
||||
|
||||
NOTE: this module is one ordered integration sequence over a single shared
|
||||
window — the tests build on each other's state and must run in definition
|
||||
order (pytest's default within a module). Run the whole module, not single
|
||||
tests.
|
||||
"""
|
||||
|
||||
import json
|
||||
from types import SimpleNamespace
|
||||
from unittest.mock import patch
|
||||
|
||||
import numpy as np
|
||||
import pytest
|
||||
from PyQt6.QtCore import QEventLoop, Qt, QTimer
|
||||
from PyQt6.QtTest import QTest
|
||||
from PyQt6.QtWidgets import QApplication, QMessageBox
|
||||
|
||||
import sras_compute as compute
|
||||
from sras_format import CH1_IDX, CH3_IDX, CH4_IDX, SrasFile
|
||||
from sras_viewer import RoiQuad, SrasViewerWindow, VELOCITY_MODE_IDX
|
||||
import tools.make_test_sras as gen
|
||||
|
||||
|
||||
def pump(ms: int = 250):
|
||||
"""Run the event loop for a while so queued signals and worker threads
|
||||
make progress."""
|
||||
loop = QEventLoop()
|
||||
QTimer.singleShot(ms, loop.quit)
|
||||
loop.exec()
|
||||
|
||||
|
||||
def wait_until(pred, timeout_ms: int = 20000, step: int = 100) -> bool:
|
||||
waited = 0
|
||||
while waited < timeout_ms:
|
||||
if pred():
|
||||
return True
|
||||
pump(step)
|
||||
waited += step
|
||||
return pred()
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def ctx(tmp_path_factory):
|
||||
"""The shared window, test file, and cross-test state for the sequence."""
|
||||
app = QApplication.instance() or QApplication([])
|
||||
tmpdir = tmp_path_factory.mktemp("sras_gui")
|
||||
path = tmpdir / "gui.sras"
|
||||
gen.write(path, n_angles=4, seed=11, samples_per_frame=256)
|
||||
|
||||
win = SrasViewerWindow()
|
||||
win.show()
|
||||
errors: list[str] = []
|
||||
# Capture anything the app reports as an error via the status bar.
|
||||
win.statusBar().messageChanged.connect(
|
||||
lambda m: errors.append(m) if m and "error" in m.lower() else None)
|
||||
|
||||
c = SimpleNamespace(app=app, win=win, path=path, tmpdir=tmpdir,
|
||||
errors=errors, s=None)
|
||||
yield c
|
||||
if win.isVisible():
|
||||
win.close()
|
||||
pump(400)
|
||||
|
||||
|
||||
def test_load(ctx):
|
||||
win = ctx.win
|
||||
win._load_file(str(ctx.path))
|
||||
assert wait_until(lambda: win._sras is not None), "file loaded"
|
||||
ctx.s = s = win._sras
|
||||
assert s.version == 6, f"v{s.version}"
|
||||
assert win.combo_channel.currentIndex() == CH4_IDX, "defaults to CH4"
|
||||
assert win._current_image is not None, "image displayed"
|
||||
assert win.spin_angle.maximum() == s.n_angles - 1, \
|
||||
"angle spinbox ranges over all angles"
|
||||
assert win._info["Angles"].text() == f"Angles: {s.n_angles}", \
|
||||
win._info["Angles"].text()
|
||||
|
||||
|
||||
def test_dc_precompute_all_angles(ctx):
|
||||
win, s = ctx.win, ctx.s
|
||||
ok = wait_until(lambda: all((a, CH4_IDX) in win._dc_cache
|
||||
and (a, CH3_IDX) in win._dc_cache
|
||||
for a in range(s.n_angles)))
|
||||
assert ok, f"every angle cached for CH3 and CH4 ({len(win._dc_cache)} entries)"
|
||||
assert "ready for all angles" in win.lbl_dc_precompute.text(), \
|
||||
win.lbl_dc_precompute.text()
|
||||
|
||||
|
||||
def test_angle_switching_from_cache(ctx):
|
||||
win, s = ctx.win, ctx.s
|
||||
for a in range(s.n_angles):
|
||||
win.spin_angle.setValue(a)
|
||||
win._on_view_changed()
|
||||
pump(60)
|
||||
expected = win._sras.image_shape(a)
|
||||
assert win._current_image.shape == expected, \
|
||||
f"angle {a} shows its own geometry {expected}, got {win._current_image.shape}"
|
||||
assert not win._job_running("compute"), \
|
||||
"no compute job needed for cached DC angles"
|
||||
|
||||
|
||||
def test_channel_switching(ctx):
|
||||
win = ctx.win
|
||||
win.spin_angle.setValue(0)
|
||||
win._on_view_changed()
|
||||
pump(60)
|
||||
win.combo_channel.setCurrentIndex(CH3_IDX)
|
||||
assert wait_until(lambda: win._current_ch == CH3_IDX), "CH3 displayed"
|
||||
|
||||
win.combo_channel.setCurrentIndex(CH1_IDX)
|
||||
assert wait_until(
|
||||
lambda: win._current_ch == CH1_IDX and not win._job_running("compute")), \
|
||||
"CH1 (FFT) computed"
|
||||
assert len(win._fft_cache) > 0, "FFT result cached"
|
||||
ctx.rf_img = win._current_image
|
||||
assert len(np.unique(ctx.rf_img)) > 1, \
|
||||
f"FFT image is degenerate ({len(np.unique(ctx.rf_img))} unique values)"
|
||||
|
||||
|
||||
def test_velocity_mode(ctx):
|
||||
"""Velocity mode is a pure post-multiply, no recompute."""
|
||||
win = ctx.win
|
||||
ctx.n_fft_before = len(win._fft_cache)
|
||||
win.combo_channel.setCurrentIndex(VELOCITY_MODE_IDX)
|
||||
assert wait_until(
|
||||
lambda: win._current_ch == VELOCITY_MODE_IDX
|
||||
and not win._job_running("compute")), "velocity displayed"
|
||||
grating = win.spin_grating_um.value()
|
||||
assert np.allclose(win._current_image, ctx.rf_img * grating, atol=1e-3), \
|
||||
"velocity == freq x grating"
|
||||
assert len(win._fft_cache) == ctx.n_fft_before, \
|
||||
f"velocity reused the cached FFT ({ctx.n_fft_before} -> {len(win._fft_cache)})"
|
||||
assert win.grp_velocity.isVisible(), "grating spinbox visible in velocity mode"
|
||||
|
||||
|
||||
def test_threshold_change_recomputes(ctx):
|
||||
"""A threshold change is a genuine cache-key change."""
|
||||
win = ctx.win
|
||||
win.combo_channel.setCurrentIndex(CH1_IDX)
|
||||
wait_until(lambda: not win._job_running("compute"))
|
||||
dc4 = win._dc_cache[(0, CH4_IDX)]
|
||||
win.spin_threshold_mv.setValue(float(np.median(dc4)))
|
||||
win._on_threshold_changed()
|
||||
assert wait_until(
|
||||
lambda: not win._job_running("compute")
|
||||
and len(win._fft_cache) > ctx.n_fft_before), "recomputed at new threshold"
|
||||
n_zero = int((win._current_image == 0).sum())
|
||||
assert n_zero > 0, \
|
||||
f"masking zeroed some pixels ({n_zero} of {win._current_image.size})"
|
||||
|
||||
|
||||
def test_bg_sub_toggle(ctx):
|
||||
win = ctx.win
|
||||
n_before = len(win._fft_cache)
|
||||
win.chk_bg_sub.setChecked(False)
|
||||
assert wait_until(
|
||||
lambda: not win._job_running("compute") and len(win._fft_cache) > n_before), \
|
||||
"recomputed without bg-sub"
|
||||
win.chk_bg_sub.setChecked(True)
|
||||
pump(200)
|
||||
assert not win._job_running("compute"), \
|
||||
"returning to bg-sub was a cache hit (no recompute)"
|
||||
|
||||
|
||||
def test_roi_and_csv_export(ctx):
|
||||
win, s = ctx.win, ctx.s
|
||||
x = s.x_axis_mm(0)
|
||||
y = s.y_positions_mm(0)
|
||||
roi = RoiQuad.from_bbox(float(x[1]), float(y[1]),
|
||||
float(x[-2]), float(y[-2]))
|
||||
win.image_canvas.set_roi(roi)
|
||||
pump(120)
|
||||
assert win.image_canvas.get_roi() is not None, "ROI registered"
|
||||
assert ("pixels inside" in win.lbl_roi_npix.text()
|
||||
and win.lbl_roi_npix.text() != "pixels inside: —"), \
|
||||
win.lbl_roi_npix.text()
|
||||
npix = int(win.lbl_roi_npix.text().split(":")[1])
|
||||
assert 0 < npix <= win._current_image.size, f"{npix}"
|
||||
assert win.btn_export_roi.isEnabled(), "Export ROI enabled"
|
||||
|
||||
csv_path = ctx.tmpdir / "roi.csv"
|
||||
with patch("sras_viewer.main_window.QFileDialog.getSaveFileName",
|
||||
return_value=(str(csv_path), "")):
|
||||
win._on_export_roi_csv()
|
||||
assert csv_path.exists(), "ROI CSV written"
|
||||
body = [l for l in csv_path.read_text().splitlines() if not l.startswith("#")]
|
||||
assert len(body) == npix + 1, \
|
||||
f"ROI CSV has {len(body)} lines for {npix} pixels (want header + one per pixel)"
|
||||
|
||||
img_csv = ctx.tmpdir / "img.csv"
|
||||
with patch("sras_viewer.main_window.QFileDialog.getSaveFileName",
|
||||
return_value=(str(img_csv), "")):
|
||||
win._on_export_csv()
|
||||
assert img_csv.exists(), "image CSV written"
|
||||
arr = np.loadtxt(img_csv, delimiter=",")
|
||||
assert (arr.shape == win._current_image.shape
|
||||
and np.allclose(arr, win._current_image, rtol=1e-5, atol=1e-4)), \
|
||||
"image CSV round-trips the displayed image"
|
||||
|
||||
|
||||
def test_roi_survives_switches(ctx):
|
||||
win = ctx.win
|
||||
win.spin_angle.setValue(1)
|
||||
win._on_view_changed()
|
||||
wait_until(lambda: not win._job_running("compute"))
|
||||
assert win.image_canvas.get_roi() is not None, \
|
||||
"ROI still present after angle switch"
|
||||
win.combo_channel.setCurrentIndex(CH4_IDX)
|
||||
wait_until(lambda: win._current_ch == CH4_IDX)
|
||||
assert win.image_canvas.get_roi() is not None, \
|
||||
"ROI still present after channel switch"
|
||||
|
||||
|
||||
def test_angle_alignment(ctx):
|
||||
win, s = ctx.win, ctx.s
|
||||
win.spin_angle.setValue(0)
|
||||
win._on_view_changed()
|
||||
wait_until(lambda: not win._job_running("compute"))
|
||||
assert win._alignment_act.isEnabled(), "alignment action enabled"
|
||||
win._on_angle_alignment()
|
||||
assert wait_until(
|
||||
lambda: win._alignment_result is not None and not win._job_running("align"),
|
||||
timeout_ms=60000), "alignment completed"
|
||||
|
||||
r = win._alignment_result
|
||||
assert len(r.per_angle) == s.n_angles, "transform for every angle"
|
||||
assert all(r.canvas_shape[0] >= int(s.n_rows[a])
|
||||
and r.canvas_shape[1] >= int(s.n_frames[a])
|
||||
for a in range(s.n_angles)), \
|
||||
f"canvas is at least as large as any single angle: {r.canvas_shape}"
|
||||
assert r.per_angle[r.ref_angle_idx].shift_mm == (0.0, 0.0), \
|
||||
"reference angle has zero shift"
|
||||
assert win.chk_aligned_view.isEnabled() and win.chk_aligned_view.isChecked(), \
|
||||
"Aligned View auto-enabled and checked"
|
||||
pump(200)
|
||||
assert win.image_canvas._img_shape == r.canvas_shape, \
|
||||
f"{win.image_canvas._img_shape} vs {r.canvas_shape}"
|
||||
|
||||
win.chk_aligned_view.setChecked(False)
|
||||
pump(200)
|
||||
assert win.image_canvas._img_shape == s.image_shape(0), \
|
||||
f"unchecking returns to the raw per-angle grid: {win.image_canvas._img_shape}"
|
||||
|
||||
|
||||
def test_manual_alignment_geometry(ctx):
|
||||
"""Local mm is anchored on each angle's array center, not its stage
|
||||
position: that is what makes a scan's placement independent of where its
|
||||
window happened to sit. (Registration accuracy itself is covered by
|
||||
tests/test_alignment.py, which has a synthetic sample to register.)"""
|
||||
win, s = ctx.win, ctx.s
|
||||
assert win._manual_align_act.isEnabled(), "manual alignment action enabled"
|
||||
|
||||
n_rows, n_frames = s.image_shape(0)
|
||||
assert np.allclose(compute._center_idx(s, 0),
|
||||
[(n_rows - 1) / 2, (n_frames - 1) / 2]), \
|
||||
"array center is the geometric center of the pixel grid"
|
||||
dx0, dy0 = compute.pixel_pitch_mm(s, 0)
|
||||
assert np.allclose(compute._local_half_extent_mm(s, 0),
|
||||
[(n_frames - 1) / 2 * abs(dx0), (n_rows - 1) / 2 * abs(dy0)]), \
|
||||
"local half-extent is derived from shape and pitch alone"
|
||||
identity = {a: compute.ManualAngleParams() for a in range(s.n_angles)}
|
||||
origin_a, shape_a = compute.canvas_for_params(s, 0, (dx0, dy0), identity)
|
||||
moved = SrasFile(str(ctx.path))
|
||||
for a in range(1, moved.n_angles):
|
||||
moved.x_start_mm[a] += 7.5
|
||||
moved.y_pos_per_angle[a] = moved.y_pos_per_angle[a] + 3.25
|
||||
origin_b, shape_b = compute.canvas_for_params(moved, 0, (dx0, dy0), identity)
|
||||
assert shape_a == shape_b and np.allclose(origin_a, origin_b), \
|
||||
("moving every non-reference angle's scan window must leave the canvas "
|
||||
f"unchanged: {origin_a} {shape_a} vs {origin_b} {shape_b}")
|
||||
|
||||
# Both signs of the stage's reported angle are searched.
|
||||
cands = compute._rotation_candidates(30.0, 6.0, 2.0)
|
||||
assert min(cands) < -29.0 and max(cands) > 29.0, f"{min(cands)}..{max(cands)}"
|
||||
|
||||
# Whole-pixel translation must not wrap content around the edge.
|
||||
arr = np.zeros((6, 6), dtype=np.float32)
|
||||
arr[0, 0] = 1.0
|
||||
assert compute._shift_into(arr, -1, -1).sum() == 0.0, \
|
||||
"_shift_into zero-fills rather than wrapping"
|
||||
assert compute._shift_into(arr, 2, 3)[2, 3] == 1.0, \
|
||||
"_shift_into moves content by exactly the requested offset"
|
||||
|
||||
|
||||
def test_manual_dialog_opens_at_identity(ctx):
|
||||
"""Open must NOT seed from the still-live automatic AlignmentResult.
|
||||
Manual mode exists to fix up whatever the automatic registration got
|
||||
wrong, so it must start from identity (every angle centered on the
|
||||
reference, no rotation) regardless of whatever the automatic run last
|
||||
computed. Only a previously *saved manual* alignment (sidecar) should
|
||||
ever seed this dialog."""
|
||||
win, s = ctx.win, ctx.s
|
||||
win._on_manual_alignment()
|
||||
assert win._manual_align_dialog is not None, "dialog opened"
|
||||
ctx.dlg = dlg = win._manual_align_dialog
|
||||
assert not win._job_running("manual_align_masks"), \
|
||||
"mask prep needed no background worker (already DC-cached)"
|
||||
assert all(dlg._angle_params[a] == compute.ManualAngleParams()
|
||||
for a in range(s.n_angles)), \
|
||||
"no manual sidecar yet -> dialog starts at identity, not the automatic result"
|
||||
|
||||
|
||||
def test_reference_angle_is_locked(ctx):
|
||||
dlg = ctx.dlg
|
||||
dlg.combo_active_angle.setCurrentIndex(dlg._ref_angle_idx)
|
||||
pump(30)
|
||||
before_ref = dlg._angle_params[dlg._ref_angle_idx]
|
||||
dlg._on_nudge_translate(1, 0, False)
|
||||
dlg._on_nudge_rotate(1, False)
|
||||
assert not dlg.grp_manual_adjust.isEnabled(), "reference angle group disabled"
|
||||
assert dlg._angle_params[dlg._ref_angle_idx] == before_ref, \
|
||||
"reference angle untouched by nudge attempts"
|
||||
|
||||
|
||||
def test_nudges(ctx):
|
||||
"""Nudging a real angle (fine + coarse, translate + rotate)."""
|
||||
dlg, s = ctx.dlg, ctx.s
|
||||
ctx.active = active = 1 if s.n_angles > 1 else 0
|
||||
dlg.combo_active_angle.setCurrentIndex(active)
|
||||
pump(30)
|
||||
before = dlg._angle_params[active].shift_mm
|
||||
dlg._on_nudge_translate(1, 0, False) # fine +X
|
||||
fine_step = dlg.spin_step_translate_mm.value()
|
||||
assert abs(dlg._angle_params[active].shift_mm[0] - (before[0] + fine_step)) < 1e-9, \
|
||||
"fine translate nudge moved shift_x by exactly one fine step"
|
||||
|
||||
before = dlg._angle_params[active].shift_mm
|
||||
dlg._on_nudge_translate(0, -1, True) # coarse -Y
|
||||
coarse_step = fine_step * dlg.spin_step_multiplier.value()
|
||||
assert abs(dlg._angle_params[active].shift_mm[1] - (before[1] - coarse_step)) < 1e-9, \
|
||||
"coarse translate nudge uses the multiplier"
|
||||
|
||||
before_rot = dlg._angle_params[active].rotation_deg
|
||||
dlg._on_nudge_rotate(1, False)
|
||||
assert dlg._angle_params[active].rotation_deg != before_rot, \
|
||||
"rotate nudge changed rotation_deg"
|
||||
assert len(dlg._preview_layers) == s.n_angles, \
|
||||
"preview canvas rebuilt for every angle after a rotation nudge"
|
||||
|
||||
# Real key-event wiring (proves keyPressEvent -> signal -> slot).
|
||||
before = dlg._angle_params[active].shift_mm
|
||||
QTest.keyClick(dlg.canvas, Qt.Key.Key_Right)
|
||||
assert dlg._angle_params[active].shift_mm[0] > before[0], \
|
||||
"a real Right-arrow key event nudged shift_x"
|
||||
|
||||
|
||||
def test_auto_derotate(ctx):
|
||||
"""Auto De-rotate: seeds rotation from the stage angle, no translation."""
|
||||
dlg, s, active = ctx.dlg, ctx.s, ctx.active
|
||||
shift_before_derotate = dlg._angle_params[active].shift_mm
|
||||
dlg._on_auto_derotate()
|
||||
nominal = compute.nominal_delta_deg(s, active, dlg._ref_angle_idx)
|
||||
assert abs(dlg._angle_params[active].rotation_deg - nominal) < 1e-6, \
|
||||
"auto de-rotate seeded rotation from the stage's reported angle"
|
||||
assert dlg._angle_params[active].shift_mm == shift_before_derotate, \
|
||||
"auto de-rotate left translation untouched"
|
||||
assert dlg._angle_params[dlg._ref_angle_idx].rotation_deg == 0.0, \
|
||||
"reference angle stays identity after auto de-rotate"
|
||||
# Clicking again offers the other sign, since which one lines the scans up
|
||||
# is not knowable from the file.
|
||||
dlg._on_auto_derotate()
|
||||
assert abs(dlg._angle_params[active].rotation_deg + nominal) < 1e-6, \
|
||||
"auto de-rotate offers the opposite sign on a second click"
|
||||
|
||||
|
||||
def test_auto_cross_correlate(ctx):
|
||||
"""Auto Cross-Correlate: searches rotation *and* translation."""
|
||||
win, dlg, s = ctx.win, ctx.dlg, ctx.s
|
||||
assert dlg.btn_auto_correlate.isEnabled(), \
|
||||
"cross-correlate action enabled once masks are ready"
|
||||
for label_idx, (label, _sources) in enumerate(dlg._CORRELATE_SOURCES):
|
||||
dlg.combo_correlate_source.setCurrentIndex(label_idx)
|
||||
dlg._on_auto_correlate()
|
||||
assert wait_until(
|
||||
lambda: not win._job_running("manual_align_correlate"),
|
||||
timeout_ms=60000), f"auto cross-correlate completed ({label})"
|
||||
assert all(a in dlg._fit_notes for a in range(s.n_angles)
|
||||
if a != dlg._ref_angle_idx), \
|
||||
f"every non-reference angle got a fit ({label})"
|
||||
assert dlg._angle_params[dlg._ref_angle_idx] == compute.ManualAngleParams(), \
|
||||
"auto cross-correlate reference angle stays identity"
|
||||
assert dlg.grp_correlate.isEnabled() and dlg.btn_save.isEnabled(), \
|
||||
"auto cross-correlate re-enabled controls when done"
|
||||
assert len(dlg._preview_layers) == s.n_angles, \
|
||||
"preview canvas rebuilt after cross-correlate"
|
||||
assert dlg._fit_report(), "fit quality is reported per angle"
|
||||
|
||||
|
||||
def test_save_sidecar(ctx):
|
||||
win, dlg, s, active = ctx.win, ctx.dlg, ctx.s, ctx.active
|
||||
dlg._on_save()
|
||||
sidecar = compute.sidecar_path(s.path)
|
||||
assert sidecar.exists(), "sidecar file written"
|
||||
ctx.sidecar = sidecar
|
||||
ctx.sidecar_raw = raw = json.loads(sidecar.read_text())
|
||||
assert raw.get("schema_version") == compute._SIDECAR_SCHEMA_VERSION, \
|
||||
"sidecar schema_version is current"
|
||||
assert all(raw.get("per_angle", {}).get(str(a), {}).get("rotation_deg")
|
||||
== dlg._angle_params[a].rotation_deg for a in range(s.n_angles)), \
|
||||
"sidecar per_angle round-trips the dialog's resolved params"
|
||||
assert (win._alignment_result is not None
|
||||
and win._alignment_result.per_angle[active].rotation_deg
|
||||
== dlg._angle_params[active].rotation_deg), \
|
||||
"main window's alignment_result replaced by the manual build"
|
||||
assert win.chk_aligned_view.isEnabled() and win.chk_aligned_view.isChecked(), \
|
||||
"Aligned View auto-enabled after Save"
|
||||
|
||||
|
||||
def test_stale_schema_sidecar_ignored(ctx):
|
||||
"""An old-schema sidecar (pre-pivot/sign fix) is treated as absent."""
|
||||
s, raw, sidecar = ctx.s, ctx.sidecar_raw, ctx.sidecar
|
||||
stale = dict(raw)
|
||||
stale["schema_version"] = compute._SIDECAR_SCHEMA_VERSION - 1
|
||||
sidecar.write_text(json.dumps(stale))
|
||||
assert compute.load_manual_alignment(s) is None, \
|
||||
"a sidecar with an old schema_version is not loaded"
|
||||
sidecar.write_text(json.dumps(raw)) # restore for the rest of the sequence
|
||||
|
||||
|
||||
def test_clear_with_confirmation(ctx):
|
||||
win, dlg, s = ctx.win, ctx.dlg, ctx.s
|
||||
with patch("sras_viewer.dialogs.QMessageBox.question",
|
||||
return_value=QMessageBox.StandardButton.Yes):
|
||||
dlg._on_clear()
|
||||
assert not ctx.sidecar.exists(), "sidecar file deleted"
|
||||
assert all(dlg._angle_params[a] == compute.ManualAngleParams()
|
||||
for a in range(s.n_angles)), "dialog params reset to identity"
|
||||
assert win._alignment_result is None, "main window alignment_result cleared"
|
||||
assert (not win.chk_aligned_view.isEnabled()
|
||||
and not win.chk_aligned_view.isChecked()), \
|
||||
"Aligned View disabled after Clear"
|
||||
|
||||
dlg.close()
|
||||
pump(150)
|
||||
assert win._manual_align_dialog is None, "dialog reference released on close"
|
||||
|
||||
|
||||
def test_sidecar_restored_on_reload(ctx):
|
||||
win, active = ctx.win, ctx.active
|
||||
win._on_manual_alignment()
|
||||
dlg = win._manual_align_dialog
|
||||
dlg.combo_active_angle.setCurrentIndex(active)
|
||||
pump(30)
|
||||
dlg._on_auto_derotate()
|
||||
dlg._on_nudge_translate(1, 1, True)
|
||||
saved_rotation = dlg._angle_params[active].rotation_deg
|
||||
saved_shift = dlg._angle_params[active].shift_mm
|
||||
dlg._on_save()
|
||||
dlg.close()
|
||||
pump(150)
|
||||
|
||||
old_sras_id = id(win._sras)
|
||||
win._load_file(str(ctx.path)) # reload the same file fresh
|
||||
assert wait_until(
|
||||
lambda: win._sras is not None and id(win._sras) != old_sras_id), \
|
||||
"file reloaded"
|
||||
ctx.s = win._sras
|
||||
assert win._manual_align_dialog is None, \
|
||||
"manual dialog force-closed by a reload"
|
||||
assert win._alignment_result is not None, \
|
||||
"reload restores the saved manual alignment automatically"
|
||||
assert abs(win._alignment_result.per_angle[active].rotation_deg
|
||||
- saved_rotation) < 1e-9, "restored rotation matches what was saved"
|
||||
assert win._alignment_result.per_angle[active].shift_mm == saved_shift, \
|
||||
"restored shift matches what was saved"
|
||||
assert win.chk_aligned_view.isChecked(), \
|
||||
"Aligned View auto-checked after restoring a saved alignment"
|
||||
|
||||
|
||||
def test_pixel_inspector(ctx):
|
||||
win = ctx.win
|
||||
win.chk_aligned_view.setChecked(False)
|
||||
pump(100)
|
||||
win._on_pixel_clicked(0, 0)
|
||||
pump(150)
|
||||
assert win.lbl_wave_hint.isHidden(), "waveform hint hidden after a click"
|
||||
win.combo_channel.setCurrentIndex(CH1_IDX)
|
||||
wait_until(lambda: not win._job_running("compute"))
|
||||
win._on_pixel_clicked(1, 1)
|
||||
pump(150)
|
||||
assert len(win.wave_canvas.ax_wave.lines) > 0, \
|
||||
f"RF waveform panel rendered ({len(win.wave_canvas.ax_wave.lines)} lines)"
|
||||
|
||||
|
||||
def test_shutdown(ctx):
|
||||
win = ctx.win
|
||||
win.close()
|
||||
pump(400)
|
||||
assert len(win._jobs) == 0, f"all background jobs released: {list(win._jobs)}"
|
||||
|
||||
|
||||
def test_no_status_bar_errors(ctx):
|
||||
unexpected = [e for e in ctx.errors if e]
|
||||
assert not unexpected, f"status-bar errors seen: {unexpected}"
|
||||
@@ -0,0 +1,278 @@
|
||||
"""Row-averaged FFT: same-row, distance-weighted CH1 waveform smoothing.
|
||||
|
||||
Covers the properties the design depends on: the kernel is symmetric and
|
||||
n=0 is a true no-op; the masked/renormalized convolution matches an
|
||||
independent brute-force reference and gives masked neighbors exactly zero
|
||||
weight regardless of their content; background subtraction after averaging
|
||||
is algebraically identical to subtracting before; chunking/worker count
|
||||
never changes the result; and a pixel that's itself masked is never
|
||||
"rescued" by averaging.
|
||||
"""
|
||||
|
||||
import numpy as np
|
||||
import pytest
|
||||
|
||||
import sras_compute as compute
|
||||
from sras_compute import compute_rf_image, dc_image_mv
|
||||
from sras_format import CH4_IDX, SrasFile
|
||||
import tools.make_test_sras as gen
|
||||
|
||||
|
||||
def _reference_row_average(masked_waves: np.ndarray, valid: np.ndarray,
|
||||
weights: np.ndarray) -> np.ndarray:
|
||||
"""Independent, unvectorized reference for _row_average_waveforms: for
|
||||
each row position, sum weighted valid neighbors within the kernel's
|
||||
radius and normalize by the actual included weight sum. Same
|
||||
definition, computed by brute-force nested loops instead of
|
||||
correlate1d, so it can't share a bug with the implementation."""
|
||||
n_frames, spf = masked_waves.shape
|
||||
n = len(weights) // 2
|
||||
out = np.zeros_like(masked_waves)
|
||||
for i in range(n_frames):
|
||||
num = np.zeros(spf, dtype=np.float64)
|
||||
den = 0.0
|
||||
for d in range(-n, n + 1):
|
||||
j = i + d
|
||||
if 0 <= j < n_frames and valid[j]:
|
||||
w = float(weights[d + n])
|
||||
num += w * masked_waves[j].astype(np.float64)
|
||||
den += w
|
||||
out[i] = num / den if den > 0 else 0.0
|
||||
return out
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# _row_average_weights
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def test_row_average_weights_shape_and_symmetry():
|
||||
w0 = compute._row_average_weights(0)
|
||||
assert w0.shape == (1,) and w0[0] == 1.0
|
||||
|
||||
for n in (1, 2, 5):
|
||||
w = compute._row_average_weights(n)
|
||||
assert w.shape == (2 * n + 1,)
|
||||
assert w[n] == pytest.approx(1.0), "center tap is the peak weight"
|
||||
assert np.allclose(w, w[::-1]), "symmetric about the center"
|
||||
half = w[n:]
|
||||
assert np.all(np.diff(half) < 0), "strictly decreasing away from center"
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# _row_average_waveforms
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def test_row_average_matches_hand_rolled_reference():
|
||||
rng = np.random.default_rng(0)
|
||||
n_frames, spf = 15, 6
|
||||
raw = rng.integers(-50, 51, size=(n_frames, spf)).astype(np.float32)
|
||||
valid = np.ones(n_frames, dtype=bool)
|
||||
valid[[2, 3, 9]] = False # a run of two invalid, plus a lone invalid
|
||||
masked = raw.copy()
|
||||
masked[~valid] = 0.0
|
||||
|
||||
weights = compute._row_average_weights(3)
|
||||
got = compute._row_average_waveforms(masked, valid, weights)
|
||||
ref = _reference_row_average(masked, valid, weights)
|
||||
|
||||
assert np.allclose(got[valid], ref[valid], atol=1e-4)
|
||||
|
||||
|
||||
def test_row_average_edge_of_row():
|
||||
"""A window wider than the row itself must still renormalize correctly
|
||||
at both ends -- mode='constant', cval=0.0 zero-pads both the numerator
|
||||
and denominator, so this is not a special case, but it's the one most
|
||||
likely to break if that padding were ever mismatched between the two."""
|
||||
n_frames, spf = 6, 3
|
||||
raw = np.arange(n_frames * spf, dtype=np.float32).reshape(n_frames, spf)
|
||||
valid = np.ones(n_frames, dtype=bool)
|
||||
weights = compute._row_average_weights(4) # window (9 taps) > n_frames (6)
|
||||
|
||||
got = compute._row_average_waveforms(raw, valid, weights)
|
||||
ref = _reference_row_average(raw, valid, weights)
|
||||
assert np.allclose(got, ref, atol=1e-4)
|
||||
|
||||
|
||||
def test_row_average_excludes_masked_neighbor_from_normalization():
|
||||
"""A masked neighbor must contribute zero *weight* to the normalization,
|
||||
not participate as a legitimate zero-valued sample at full weight --
|
||||
the two give different answers, and only the former is correct. (Note:
|
||||
masked_waves must already be 0 at invalid positions per
|
||||
_row_average_waveforms's contract -- that's what read_row's zero-filled
|
||||
scratch buffer guarantees in production -- so the only way to vary
|
||||
"what a masked position looks like" while respecting that contract is
|
||||
whether its weight is excluded from the denominator at all.)"""
|
||||
n_frames, spf = 9, 4
|
||||
weights = compute._row_average_weights(2)
|
||||
|
||||
# A: position 4 is masked -- excluded from the weight sum entirely.
|
||||
valid_a = np.ones(n_frames, dtype=bool)
|
||||
valid_a[4] = False
|
||||
masked_a = np.zeros((n_frames, spf), dtype=np.float32)
|
||||
masked_a[valid_a] = 1.0
|
||||
got_a = compute._row_average_waveforms(masked_a, valid_a, weights)
|
||||
|
||||
# B: position 4 is valid but genuinely zero-valued -- included in the
|
||||
# weight sum, diluting neighbors' averages.
|
||||
valid_b = np.ones(n_frames, dtype=bool)
|
||||
masked_b = np.ones((n_frames, spf), dtype=np.float32)
|
||||
masked_b[4] = 0.0
|
||||
got_b = compute._row_average_waveforms(masked_b, valid_b, weights)
|
||||
|
||||
# Every position whose window reaches index 4 must average *higher* in
|
||||
# A (excluded from the denominator) than in B (included as a real zero).
|
||||
affected = [2, 3, 5, 6]
|
||||
assert np.all(got_a[affected] > got_b[affected]), \
|
||||
"masking must exclude a neighbor from normalization, not just zero its value"
|
||||
# Positions outside the window (radius 2) are unaffected either way.
|
||||
assert np.allclose(got_a[[0, 1, 7, 8]], got_b[[0, 1, 7, 8]])
|
||||
|
||||
|
||||
def test_background_subtracted_once_equals_subtract_then_average():
|
||||
"""Algebraic identity the implementation relies on: subtracting a fixed
|
||||
background from the already-averaged waveform equals subtracting it
|
||||
from every valid neighbor first, because the denominator is always the
|
||||
*actual* included weight sum (never a fixed total)."""
|
||||
rng = np.random.default_rng(1)
|
||||
n_frames, spf = 11, 8
|
||||
raw = rng.integers(-40, 41, size=(n_frames, spf)).astype(np.float32)
|
||||
valid = np.ones(n_frames, dtype=bool)
|
||||
valid[[1, 7]] = False
|
||||
masked = raw.copy()
|
||||
masked[~valid] = 0.0
|
||||
background = rng.integers(-5, 6, size=spf).astype(np.float32)
|
||||
weights = compute._row_average_weights(3)
|
||||
|
||||
# Order A (what the code does): average first, subtract background once.
|
||||
order_a = compute._row_average_waveforms(masked, valid, weights) - background
|
||||
|
||||
# Order B: subtract background from every valid neighbor first (restoring
|
||||
# the "0 at invalid positions" contract afterward), then average.
|
||||
bg_subbed = masked - background
|
||||
bg_subbed[~valid] = 0.0
|
||||
order_b = compute._row_average_waveforms(bg_subbed, valid, weights)
|
||||
|
||||
assert np.allclose(order_a[valid], order_b[valid], atol=1e-3)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# compute_rf_image(row_avg_n=...) integration
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def test_row_average_zero_is_identity(tmp_path):
|
||||
"""row_avg_n=0 must take the exact same code path as before this
|
||||
feature existed (row_avg_weights stays None), not a single-tap kernel
|
||||
that merely computes to the same answer."""
|
||||
path = tmp_path / "zero.sras"
|
||||
gen.write(path, n_angles=1, seed=10, samples_per_frame=64)
|
||||
sras = SrasFile(str(path))
|
||||
plain = compute_rf_image(sras, 0, dc_threshold_mv=None, apply_bg_sub=True)
|
||||
explicit_zero = compute_rf_image(sras, 0, dc_threshold_mv=None,
|
||||
apply_bg_sub=True, row_avg_n=0)
|
||||
assert np.array_equal(plain, explicit_zero)
|
||||
|
||||
|
||||
def test_row_average_respects_own_center_mask(tmp_path):
|
||||
"""A pixel that's itself below threshold stays masked (0) after row
|
||||
averaging -- averaging never rescues a masked pixel, matching the
|
||||
'valid neighbors only' design (masked pixels are excluded from other
|
||||
pixels' averages, and are never themselves smoothed)."""
|
||||
path = tmp_path / "center_mask.sras"
|
||||
gen.write(path, n_angles=1, seed=13, samples_per_frame=64)
|
||||
sras = SrasFile(str(path))
|
||||
dc4 = dc_image_mv(sras, 0, CH4_IDX)
|
||||
thr = float(np.percentile(dc4, 50))
|
||||
mask = dc4 >= thr
|
||||
assert mask.any() and not mask.all(), "threshold actually splits the image"
|
||||
|
||||
img = compute_rf_image(sras, 0, dc_threshold_mv=thr, apply_bg_sub=True,
|
||||
row_avg_n=4)
|
||||
assert np.array_equal(img == 0, ~mask), \
|
||||
"masked pixels stay exactly 0 after row averaging; valid ones don't"
|
||||
|
||||
|
||||
def test_row_average_composes_with_padding(tmp_path):
|
||||
"""row_avg_n and n_fft (zero-padding) are independent knobs: using them
|
||||
together must not raise, and must still agree with the exact (non-zoom)
|
||||
reference path at that pad factor -- i.e. row-averaging composes with
|
||||
the zoom peak search correctly, not just with the direct one."""
|
||||
path = tmp_path / "padded_rowavg.sras"
|
||||
gen.write(path, n_angles=1, seed=12, samples_per_frame=64)
|
||||
sras = SrasFile(str(path))
|
||||
spf = sras.samples_per_frame
|
||||
|
||||
raw_natural = compute_rf_image(sras, 0, dc_threshold_mv=None, apply_bg_sub=True)
|
||||
avg_natural = compute_rf_image(sras, 0, dc_threshold_mv=None, apply_bg_sub=True,
|
||||
row_avg_n=3)
|
||||
avg_padded_zoom = compute_rf_image(sras, 0, dc_threshold_mv=None, apply_bg_sub=True,
|
||||
row_avg_n=3, n_fft=spf * 40)
|
||||
avg_padded_exact = compute_rf_image(sras, 0, dc_threshold_mv=None, apply_bg_sub=True,
|
||||
row_avg_n=3, n_fft=spf * 40, exact=True)
|
||||
|
||||
assert avg_natural.shape == raw_natural.shape == avg_padded_zoom.shape
|
||||
assert np.all(np.isfinite(avg_padded_zoom))
|
||||
assert np.array_equal(avg_padded_zoom, avg_padded_exact), \
|
||||
"row-averaged waveforms feed the zoom and exact FFT paths identically"
|
||||
|
||||
|
||||
def test_row_average_improves_snr_recovery():
|
||||
"""The actual point of the feature: averaging same-row waveforms that
|
||||
share a true underlying tone but carry independent noise recovers that
|
||||
tone far more reliably than any single raw (unaveraged) waveform does."""
|
||||
rng = np.random.default_rng(42)
|
||||
n_frames, spf = 21, 128
|
||||
true_bin = 9
|
||||
t = np.arange(spf)
|
||||
tone = 15.0 * np.sin(2 * np.pi * true_bin * t / spf) # same true signal
|
||||
# at every position
|
||||
noise_sigma = 40.0 # much larger than the tone -- deliberately poor SNR
|
||||
raw = (tone[None, :] + rng.normal(scale=noise_sigma, size=(n_frames, spf))
|
||||
).astype(np.float32)
|
||||
valid = np.ones(n_frames, dtype=bool)
|
||||
|
||||
weights = compute._row_average_weights(8) # wide window: lots of averaging
|
||||
averaged = compute._row_average_waveforms(raw, valid, weights)
|
||||
|
||||
raw_bins = compute._peak_bins_direct(raw, spf)
|
||||
avg_bins = compute._peak_bins_direct(averaged, spf)
|
||||
|
||||
raw_hits = int(np.sum(raw_bins == true_bin))
|
||||
avg_hits = int(np.sum(avg_bins == true_bin))
|
||||
assert avg_hits > raw_hits, (
|
||||
f"row averaging should recover the true bin ({true_bin}) more often "
|
||||
f"than raw per-pixel estimates: raw {raw_hits}/{n_frames}, "
|
||||
f"averaged {avg_hits}/{n_frames}")
|
||||
assert avg_hits >= n_frames * 0.7, \
|
||||
f"averaged recovery should be reliable, not just barely better: {avg_hits}/{n_frames}"
|
||||
|
||||
|
||||
def test_row_average_parallel_identity(tmp_path, monkeypatch):
|
||||
"""Forcing 1 worker vs many must give an identical row-averaged image --
|
||||
catches chunk-boundary bugs (there should be none, since averaging never
|
||||
crosses rows, but this is the empirical proof, not just inspection)."""
|
||||
path = tmp_path / "parallel_rowavg.sras"
|
||||
n_rows, n_frames, spf = 40, 13, 128
|
||||
gen.write(path, n_angles=1, seed=11, samples_per_frame=spf,
|
||||
geometry=[(n_rows, n_frames)])
|
||||
sras = SrasFile(str(path))
|
||||
|
||||
monkeypatch.setattr(compute, "_TOTAL_BYTES_BUDGET", 8 * n_frames * spf * 4)
|
||||
monkeypatch.setattr(compute, "_FFT_BLOCK", 4)
|
||||
# row_avg_n > 0 halves the effective budget before chunk planning.
|
||||
fft_rows = compute._plan_fft_rows(n_frames, spf, compute._TOTAL_BYTES_BUDGET // 2)
|
||||
assert fft_rows < n_rows, \
|
||||
f"row-averaged FFT work actually splits into multiple chunks ({fft_rows} of {n_rows})"
|
||||
|
||||
dc4 = dc_image_mv(sras, 0, CH4_IDX)
|
||||
thr = float(np.median(dc4))
|
||||
|
||||
monkeypatch.setattr(compute, "_MAX_WORKERS", 1)
|
||||
serial = compute_rf_image(sras, 0, dc_threshold_mv=thr, apply_bg_sub=True,
|
||||
row_avg_n=4)
|
||||
|
||||
monkeypatch.setattr(compute, "_MAX_WORKERS", 8)
|
||||
parallel = compute_rf_image(sras, 0, dc_threshold_mv=thr, apply_bg_sub=True,
|
||||
row_avg_n=4)
|
||||
|
||||
assert np.array_equal(serial, parallel), \
|
||||
"row-averaged rf image identical regardless of chunking/worker count"
|
||||
@@ -0,0 +1,558 @@
|
||||
"""Does a batch-computed FFT cache actually spare the viewer the FFT?
|
||||
|
||||
Storing a peak-frequency image per angle in the file is only worth doing if
|
||||
displaying it is then free. The regression this module pins down is the
|
||||
viewer's *dispatch* decision: it used to find the stored image only inside
|
||||
ComputeWorker, so after a batch every angle change still queued a background
|
||||
job behind a "Computing FFT…" popup for an image already on disk.
|
||||
|
||||
Both layers are covered — cached_rf_image's accept/reject rules, and the
|
||||
window never reaching _start_compute for a batch-cached angle.
|
||||
"""
|
||||
|
||||
import struct
|
||||
from types import SimpleNamespace
|
||||
from unittest.mock import patch
|
||||
|
||||
import numpy as np
|
||||
import pytest
|
||||
from PyQt6.QtCore import QEventLoop, QTimer
|
||||
from PyQt6.QtWidgets import QApplication, QDialog
|
||||
|
||||
import sras_compute as compute
|
||||
import sras_format as fmt
|
||||
from sras_compute import cache_file, cached_rf_image, compute_rf_image, dc_image_mv
|
||||
from sras_format import CH1_IDX, CH3_IDX, CH4_IDX, SrasFile
|
||||
from sras_viewer import SrasViewerWindow, VELOCITY_MODE_IDX
|
||||
import tools.make_test_sras as gen
|
||||
|
||||
_THRESHOLD_MV = 50.0 # the viewer's own default
|
||||
|
||||
|
||||
def pump(ms: int = 200):
|
||||
loop = QEventLoop()
|
||||
QTimer.singleShot(ms, loop.quit)
|
||||
loop.exec()
|
||||
|
||||
|
||||
def wait_until(pred, timeout_ms: int = 20000, step: int = 100) -> bool:
|
||||
waited = 0
|
||||
while waited < timeout_ms:
|
||||
if pred():
|
||||
return True
|
||||
pump(step)
|
||||
waited += step
|
||||
return pred()
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def rig(tmp_path_factory):
|
||||
"""A v6 file, the FFT images a from-scratch compute gives for it, and the
|
||||
same file after Batch Compute FFT has written them into its v7 cache."""
|
||||
path = tmp_path_factory.mktemp("stored_cache") / "cached.sras"
|
||||
gen.write(path, n_angles=4, seed=7, samples_per_frame=256)
|
||||
|
||||
src = SrasFile(str(path))
|
||||
fresh = {a: compute_rf_image(src, a, dc_threshold_mv=_THRESHOLD_MV,
|
||||
apply_bg_sub=True)
|
||||
for a in range(src.n_angles)}
|
||||
assert src.background is not None, "the fixture file must have a background"
|
||||
|
||||
err = cache_file(str(path), "fft", True)
|
||||
assert err == "", err
|
||||
cached = SrasFile(str(path))
|
||||
assert all(x is not None for x in cached.precomputed_freq_mhz)
|
||||
assert all(x is None for x in cached.precomputed_dc4_mv), \
|
||||
"FFT-only batch: the mask has to come from the viewer, not the file"
|
||||
|
||||
return SimpleNamespace(path=path, fresh=fresh, sras=cached,
|
||||
n_angles=cached.n_angles)
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def dc_rig(tmp_path_factory):
|
||||
"""A file that has been through Batch Compute DC and Store."""
|
||||
path = tmp_path_factory.mktemp("stored_dc") / "dc_cached.sras"
|
||||
gen.write(path, n_angles=4, seed=9, samples_per_frame=128)
|
||||
err = cache_file(str(path), "dc", True)
|
||||
assert err == "", err
|
||||
|
||||
sras = SrasFile(str(path))
|
||||
assert all(x is not None for x in sras.precomputed_dc3_mv)
|
||||
assert all(x is not None for x in sras.precomputed_dc4_mv)
|
||||
assert len(np.unique(sras.precomputed_dc4_mv[0])) > 1, \
|
||||
"a degenerate DC image would make the comparisons below vacuous"
|
||||
return SimpleNamespace(path=path, sras=sras, n_angles=sras.n_angles)
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def no_fft(monkeypatch):
|
||||
"""Make any real FFT work loud: returns a list that stays empty unless a
|
||||
peak search actually runs."""
|
||||
calls = []
|
||||
for name in ("_peak_bins_direct", "_peak_bins_zoom"):
|
||||
original = getattr(compute, name)
|
||||
|
||||
def spy(*args, _f=original, **kwargs):
|
||||
calls.append(_f.__name__)
|
||||
return _f(*args, **kwargs)
|
||||
|
||||
monkeypatch.setattr(compute, name, spy)
|
||||
return calls
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# cached_rf_image: when may the stored image stand in for a compute?
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def test_stored_image_matches_a_fresh_compute(rig, no_fft):
|
||||
for a in range(rig.n_angles):
|
||||
dc4 = dc_image_mv(SrasFile(str(rig.path)), a, CH4_IDX)
|
||||
img = cached_rf_image(rig.sras, a, dc_threshold_mv=_THRESHOLD_MV,
|
||||
apply_bg_sub=True, dc4_mv=dc4)
|
||||
assert img is not None, f"angle {a} is cached in the file"
|
||||
assert np.allclose(img, rig.fresh[a], atol=1e-3), \
|
||||
f"angle {a} differs from a from-scratch compute"
|
||||
assert not no_fft, f"the stored image was used, no FFT ran: {no_fft}"
|
||||
|
||||
|
||||
def test_unmasked_when_no_threshold(rig):
|
||||
img = cached_rf_image(rig.sras, 0, dc_threshold_mv=None, apply_bg_sub=True)
|
||||
assert img is not None and np.array_equal(img, rig.sras.precomputed_freq_mhz[0])
|
||||
img[:] = -1.0
|
||||
assert not np.any(rig.sras.precomputed_freq_mhz[0] == -1.0), \
|
||||
"callers get a copy, never the file's own array"
|
||||
|
||||
|
||||
def test_settings_the_stored_image_cannot_serve(rig):
|
||||
"""A stored image carries one bg-sub state and one padding, so anything
|
||||
else must fall through to a real compute rather than lie."""
|
||||
spf = rig.sras.samples_per_frame
|
||||
assert cached_rf_image(rig.sras, 0, _THRESHOLD_MV, apply_bg_sub=True,
|
||||
n_fft=spf * 4) is None, \
|
||||
"cache was written at pad 1, a pad-4 view resolves different peaks"
|
||||
assert cached_rf_image(rig.sras, 0, _THRESHOLD_MV, apply_bg_sub=False) is None, \
|
||||
"cache was written with bg-sub on"
|
||||
|
||||
uncached = SrasFile(str(rig.path))
|
||||
uncached.precomputed_freq_mhz[1] = None
|
||||
assert cached_rf_image(uncached, 1, _THRESHOLD_MV, apply_bg_sub=True) is None
|
||||
|
||||
|
||||
@pytest.mark.parametrize("pad", [2, 10])
|
||||
def test_cache_is_stored_at_the_configured_pad(tmp_path, pad):
|
||||
"""Batching at a pad factor must produce a cache that view can read back —
|
||||
a pad-1-only cache is one the padded viewer can never use."""
|
||||
path = tmp_path / f"pad{pad}.sras"
|
||||
gen.write(path, n_angles=2, seed=13, samples_per_frame=256)
|
||||
spf = SrasFile(str(path)).samples_per_frame
|
||||
|
||||
assert cache_file(str(path), "fft", True, "scipy", 0, pad) == ""
|
||||
sras = SrasFile(str(path))
|
||||
assert sras.precomputed_pad_factor == pad, "pad factor survives the round trip"
|
||||
|
||||
assert cached_rf_image(sras, 0, None, apply_bg_sub=True,
|
||||
n_fft=spf * pad) is not None, f"usable at pad {pad}"
|
||||
assert cached_rf_image(sras, 0, None, apply_bg_sub=True) is None, \
|
||||
"not usable unpadded"
|
||||
assert cached_rf_image(sras, 0, None, apply_bg_sub=True,
|
||||
n_fft=spf * (pad + 1)) is None, "not usable at another pad"
|
||||
|
||||
# The stored numbers must be the padded ones, not pad-1 relabelled.
|
||||
fresh = SrasFile(str(path))
|
||||
fresh.precomputed_freq_mhz = [None] * fresh.n_angles
|
||||
for a in range(sras.n_angles):
|
||||
assert np.allclose(
|
||||
compute_rf_image(sras, a, dc_threshold_mv=None, apply_bg_sub=True,
|
||||
n_fft=spf * pad),
|
||||
compute_rf_image(fresh, a, dc_threshold_mv=None, apply_bg_sub=True,
|
||||
n_fft=spf * pad), atol=1e-3), \
|
||||
f"angle {a}: stored image is the pad-{pad} answer"
|
||||
|
||||
|
||||
def test_cach_v1_reads_as_natural_resolution(tmp_path):
|
||||
"""Files cached before the pad factor existed must keep working: a v1 tail
|
||||
has no pad field and is pad 1 by construction."""
|
||||
path = tmp_path / "v1.sras"
|
||||
gen.write(path, n_angles=2, seed=14, samples_per_frame=256)
|
||||
assert cache_file(str(path), "fft", True) == ""
|
||||
|
||||
# Rewrite the tail as a genuine CACH v1 block (old header, no pad field).
|
||||
v2 = SrasFile(str(path))
|
||||
freq, entries = v2.precomputed_freq_mhz, list(range(v2.n_angles))
|
||||
payload = struct.pack(fmt.CACH_HDR_FMT, fmt.CACH_MAGIC, 1, fmt.CACH_FLAG_FFT)
|
||||
payload += struct.pack(fmt.SFFT_HDR_FMT_V1, fmt.SFFT_MAGIC,
|
||||
fmt.SFFT_FLAG_BG_SUB, len(entries))
|
||||
for a in entries:
|
||||
payload += struct.pack(">H", a) + freq[a].astype(">f4").tobytes()
|
||||
head = path.read_bytes()[:v2._cache_tail_offset()]
|
||||
path.write_bytes(head + payload)
|
||||
|
||||
v1 = SrasFile(str(path))
|
||||
assert v1.precomputed_pad_factor == 1
|
||||
assert v1.precomputed_bg_sub is True
|
||||
assert all(np.array_equal(v1.precomputed_freq_mhz[a], freq[a]) for a in entries), \
|
||||
"v1 images read back unchanged"
|
||||
assert cached_rf_image(v1, 0, None, apply_bg_sub=True) is not None
|
||||
assert cached_rf_image(v1, 0, None, apply_bg_sub=True,
|
||||
n_fft=v1.samples_per_frame * 10) is None
|
||||
|
||||
|
||||
def test_mask_read_can_be_refused(rig, no_fft):
|
||||
"""With no DC4 in hand, building the mask means reading a whole channel —
|
||||
the GUI thread asks for None instead."""
|
||||
assert cached_rf_image(rig.sras, 0, _THRESHOLD_MV, apply_bg_sub=True,
|
||||
allow_dc_recompute=False) is None
|
||||
dc4 = dc_image_mv(SrasFile(str(rig.path)), 0, CH4_IDX)
|
||||
img = cached_rf_image(rig.sras, 0, _THRESHOLD_MV, apply_bg_sub=True,
|
||||
dc4_mv=dc4, allow_dc_recompute=False)
|
||||
assert img is not None and np.allclose(img, rig.fresh[0], atol=1e-3)
|
||||
assert not no_fft, f"no FFT on either branch: {no_fft}"
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# The viewer: no compute job at all for a batch-cached angle
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def test_viewer_shows_stored_angles_without_computing(rig, no_fft, monkeypatch):
|
||||
app = QApplication.instance() or QApplication([]) # noqa: F841
|
||||
win = SrasViewerWindow()
|
||||
win.show()
|
||||
|
||||
dispatched = []
|
||||
original_start = type(win)._start_compute
|
||||
monkeypatch.setattr(type(win), "_start_compute",
|
||||
lambda self: (dispatched.append(self.spin_angle.value()),
|
||||
original_start(self))[1])
|
||||
try:
|
||||
win._load_file(str(rig.path))
|
||||
assert wait_until(lambda: win._sras is not None), "file loaded"
|
||||
# The file carries no DC block, so the mask comes from the window's own
|
||||
# background precompute — the state a user is in by the time they click.
|
||||
assert wait_until(lambda: all((a, CH4_IDX) in win._dc_cache
|
||||
for a in range(rig.n_angles))), \
|
||||
"DC precompute finished"
|
||||
|
||||
dispatched.clear()
|
||||
win.combo_channel.setCurrentIndex(CH1_IDX)
|
||||
assert wait_until(lambda: win._current_ch == CH1_IDX), "CH1 displayed"
|
||||
|
||||
for a in list(range(rig.n_angles)) + [1, 0]:
|
||||
win.spin_angle.setValue(a)
|
||||
win._on_view_changed()
|
||||
pump(60)
|
||||
assert win._current_angle == a, f"angle {a} displayed"
|
||||
assert np.allclose(win._current_image, rig.fresh[a], atol=1e-3), \
|
||||
f"angle {a} shows the stored image"
|
||||
|
||||
assert dispatched == [], \
|
||||
f"stored angles need no compute job, dispatched for {dispatched}"
|
||||
assert not no_fft, f"no FFT ran for any stored angle: {no_fft}"
|
||||
|
||||
# Velocity is still a post-multiply of the same stored image.
|
||||
win.combo_channel.setCurrentIndex(VELOCITY_MODE_IDX)
|
||||
pump(120)
|
||||
assert np.allclose(win._current_image,
|
||||
rig.fresh[0] * win.spin_grating_um.value(), atol=1e-3)
|
||||
assert dispatched == [] and not no_fft
|
||||
|
||||
# ...but a setting the stored image cannot serve must still recompute,
|
||||
# or the fast path would be showing the wrong picture.
|
||||
win.chk_bg_sub.setChecked(False)
|
||||
assert wait_until(lambda: not win._job_running("compute") and bool(no_fft)), \
|
||||
"bg-sub off falls through to a real FFT"
|
||||
finally:
|
||||
win.close()
|
||||
pump(300)
|
||||
|
||||
|
||||
def test_batch_caches_at_the_viewers_pad_factor(tmp_path, no_fft, monkeypatch):
|
||||
"""The bug a pad-10 user hits: Batch Compute FFT used to store pad-1
|
||||
images regardless, so the padded view recomputed every angle forever.
|
||||
"""
|
||||
path = tmp_path / "padded_gui.sras"
|
||||
gen.write(path, n_angles=3, seed=15, samples_per_frame=256)
|
||||
|
||||
app = QApplication.instance() or QApplication([]) # noqa: F841
|
||||
win = SrasViewerWindow()
|
||||
win.show()
|
||||
|
||||
dispatched = []
|
||||
original_start = type(win)._start_compute
|
||||
monkeypatch.setattr(type(win), "_start_compute",
|
||||
lambda self: (dispatched.append(self.spin_angle.value()),
|
||||
original_start(self))[1])
|
||||
try:
|
||||
win._fft_pad_factor = 10
|
||||
win._load_file(str(path))
|
||||
assert wait_until(lambda: win._sras is not None), "file loaded"
|
||||
assert wait_until(lambda: all((a, CH4_IDX) in win._dc_cache
|
||||
for a in range(win._sras.n_angles))), \
|
||||
"DC precompute finished"
|
||||
|
||||
# Convert -> Batch Compute FFT, on the open file, through the real slot.
|
||||
with patch("sras_viewer.main_window.QFileDialog.getOpenFileNames",
|
||||
return_value=([str(path)], "")):
|
||||
win._on_batch_compute("fft")
|
||||
assert wait_until(lambda: not win._job_running("batch"), 60000), "batch ran"
|
||||
assert wait_until(lambda: win._sras is not None
|
||||
and win._sras.version == 7), "file reloaded as v7"
|
||||
pump(200)
|
||||
assert win._sras.precomputed_pad_factor == 10, \
|
||||
f"cached at the viewer's pad, got {win._sras.precomputed_pad_factor}"
|
||||
|
||||
expected = {a: compute.cached_rf_image(
|
||||
win._sras, a, dc_threshold_mv=win.spin_threshold_mv.value(),
|
||||
apply_bg_sub=win.chk_bg_sub.isChecked(),
|
||||
n_fft=win._current_n_fft(),
|
||||
dc4_mv=win._dc_cache.get((a, CH4_IDX)))
|
||||
for a in range(win._sras.n_angles)}
|
||||
assert all(v is not None for v in expected.values()), "cache is readable at pad 10"
|
||||
|
||||
no_fft.clear()
|
||||
dispatched.clear()
|
||||
win.combo_channel.setCurrentIndex(CH1_IDX)
|
||||
assert wait_until(lambda: win._current_ch == CH1_IDX), "CH1 displayed"
|
||||
for a in range(win._sras.n_angles):
|
||||
win.spin_angle.setValue(a)
|
||||
pump(60)
|
||||
assert np.allclose(win._current_image, expected[a], atol=1e-3), \
|
||||
f"angle {a} served from the pad-10 cache"
|
||||
assert dispatched == [] and not no_fft, \
|
||||
f"no recompute at pad 10 (jobs={dispatched}, fft={no_fft})"
|
||||
assert "unusable" not in win.lbl_frame_warn.text()
|
||||
|
||||
# Change the pad and the cache legitimately stops applying — and the
|
||||
# info panel has to say so rather than leave it a mystery.
|
||||
win._fft_pad_factor = 4
|
||||
win._update_scan_info_labels()
|
||||
assert "Cached FFT unusable" in win.lbl_frame_warn.text(), \
|
||||
win.lbl_frame_warn.text()
|
||||
assert "pad 10x" in win.lbl_frame_warn.text()
|
||||
win._refresh_display()
|
||||
assert wait_until(lambda: not win._job_running("compute") and bool(no_fft)), \
|
||||
"pad 4 recomputes rather than reusing the pad-10 cache"
|
||||
finally:
|
||||
win.close()
|
||||
pump(300)
|
||||
|
||||
|
||||
def test_viewer_shows_stored_dc_without_computing(dc_rig, monkeypatch):
|
||||
"""Same for the DC half, with the background precompute silenced so the
|
||||
file's stored block is the only thing that can be carrying the display."""
|
||||
app = QApplication.instance() or QApplication([]) # noqa: F841
|
||||
win = SrasViewerWindow()
|
||||
win.show()
|
||||
|
||||
dispatched = []
|
||||
original_start = type(win)._start_compute
|
||||
monkeypatch.setattr(type(win), "_start_compute",
|
||||
lambda self: (dispatched.append(self.spin_angle.value()),
|
||||
original_start(self))[1])
|
||||
monkeypatch.setattr(type(win), "_start_dc_precompute", lambda self: None)
|
||||
try:
|
||||
win._load_file(str(dc_rig.path))
|
||||
assert wait_until(lambda: win._sras is not None), "file loaded"
|
||||
pump(120)
|
||||
|
||||
for ch in (CH3_IDX, CH4_IDX):
|
||||
win.combo_channel.setCurrentIndex(ch)
|
||||
for a in range(dc_rig.n_angles):
|
||||
win.spin_angle.setValue(a)
|
||||
pump(60)
|
||||
assert (win._current_angle, win._current_ch) == (a, ch), \
|
||||
f"angle {a} on channel {ch} displayed"
|
||||
assert np.array_equal(win._current_image,
|
||||
dc_rig.sras.cached_dc_mv(a, ch)), \
|
||||
f"angle {a} channel {ch} shows the file's stored DC image"
|
||||
|
||||
assert dispatched == [], \
|
||||
f"stored DC angles need no compute job, dispatched for {dispatched}"
|
||||
finally:
|
||||
win.close()
|
||||
pump(300)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Row-averaged FFT: cache_file("fft_rowavg", ...) and its on-disk provenance
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def test_row_average_flag_and_n_round_trip(tmp_path):
|
||||
path = tmp_path / "rowavg_roundtrip.sras"
|
||||
gen.write(path, n_angles=2, seed=20, samples_per_frame=128)
|
||||
err = cache_file(str(path), "fft_rowavg", True, dc_threshold_mv=-1e9, row_avg_n=5)
|
||||
assert err == "", err
|
||||
|
||||
sras = SrasFile(str(path))
|
||||
assert sras.version == 7
|
||||
assert sras.precomputed_row_avg_n == 5
|
||||
assert all(x is not None for x in sras.precomputed_freq_mhz)
|
||||
|
||||
|
||||
def test_fft_rowavg_mode_requires_positive_n_and_threshold(tmp_path):
|
||||
path = tmp_path / "rowavg_bad_args.sras"
|
||||
gen.write(path, n_angles=1, seed=27, samples_per_frame=64)
|
||||
assert cache_file(str(path), "fft_rowavg", True, dc_threshold_mv=0.0, row_avg_n=0)
|
||||
assert cache_file(str(path), "fft_rowavg", True, dc_threshold_mv=None, row_avg_n=5)
|
||||
|
||||
|
||||
def test_raw_and_row_averaged_caches_never_cross_served(tmp_path):
|
||||
"""The central regression this feature must never allow: a raw request
|
||||
served a row-averaged image (or vice versa), or a request at one window
|
||||
size served a cache stored at a different one."""
|
||||
path = tmp_path / "cross_serve.sras"
|
||||
gen.write(path, n_angles=1, seed=21, samples_per_frame=128)
|
||||
err = cache_file(str(path), "fft_rowavg", True, dc_threshold_mv=-1e9, row_avg_n=5)
|
||||
assert err == "", err
|
||||
|
||||
sras = SrasFile(str(path))
|
||||
assert cached_rf_image(sras, 0, None, apply_bg_sub=True, row_avg_n=0) is None, \
|
||||
"a raw request must not be served a row-averaged cache"
|
||||
assert cached_rf_image(sras, 0, None, apply_bg_sub=True, row_avg_n=3) is None, \
|
||||
"a request at the wrong window size must not be served either"
|
||||
served = cached_rf_image(sras, 0, None, apply_bg_sub=True, row_avg_n=5)
|
||||
assert served is not None
|
||||
assert np.array_equal(served, sras.precomputed_freq_mhz[0])
|
||||
|
||||
|
||||
def test_write_v7_cache_row_avg_n_carries_forward(tmp_path):
|
||||
"""A later DC-only write must leave a previously-written row-averaged
|
||||
FFT block -- including its row_avg_n -- byte-for-byte unchanged."""
|
||||
path = tmp_path / "carry_forward.sras"
|
||||
gen.write(path, n_angles=2, seed=22, samples_per_frame=64)
|
||||
err = cache_file(str(path), "fft_rowavg", True, dc_threshold_mv=-1e9, row_avg_n=7)
|
||||
assert err == "", err
|
||||
|
||||
before = SrasFile(str(path))
|
||||
assert before.precomputed_row_avg_n == 7
|
||||
freq_before = [x.copy() for x in before.precomputed_freq_mhz]
|
||||
|
||||
err = cache_file(str(path), "dc", True)
|
||||
assert err == "", err
|
||||
|
||||
after = SrasFile(str(path))
|
||||
assert after.precomputed_row_avg_n == 7, "row_avg_n survives a DC-only write"
|
||||
assert all(np.array_equal(after.precomputed_freq_mhz[a], freq_before[a])
|
||||
for a in range(after.n_angles)), \
|
||||
"the row-averaged FFT block itself is untouched by a DC-only write"
|
||||
|
||||
|
||||
def test_row_average_never_touches_dc_images(tmp_path):
|
||||
path = tmp_path / "dc_untouched.sras"
|
||||
gen.write(path, n_angles=2, seed=23, samples_per_frame=64)
|
||||
|
||||
src = SrasFile(str(path))
|
||||
expect_dc3 = [dc_image_mv(src, a, CH3_IDX) for a in range(src.n_angles)]
|
||||
expect_dc4 = [dc_image_mv(src, a, CH4_IDX) for a in range(src.n_angles)]
|
||||
|
||||
assert cache_file(str(path), "dc", True) == ""
|
||||
assert cache_file(str(path), "fft_rowavg", True,
|
||||
dc_threshold_mv=-1e9, row_avg_n=6) == ""
|
||||
|
||||
after = SrasFile(str(path))
|
||||
assert all(np.allclose(after.precomputed_dc3_mv[a], expect_dc3[a], atol=1e-4)
|
||||
for a in range(after.n_angles))
|
||||
assert all(np.allclose(after.precomputed_dc4_mv[a], expect_dc4[a], atol=1e-4)
|
||||
for a in range(after.n_angles))
|
||||
|
||||
|
||||
def test_row_average_never_modifies_raw_waveform_data(tmp_path):
|
||||
path = tmp_path / "waveform_untouched.sras"
|
||||
gen.write(path, n_angles=2, seed=24, samples_per_frame=64)
|
||||
orig = tmp_path / "waveform_untouched_orig.sras"
|
||||
gen.write(orig, n_angles=2, seed=24, samples_per_frame=64)
|
||||
|
||||
assert cache_file(str(path), "fft_rowavg", True,
|
||||
dc_threshold_mv=-1e9, row_avg_n=5) == ""
|
||||
|
||||
o, n = SrasFile(str(orig)), SrasFile(str(path))
|
||||
assert all(np.array_equal(np.asarray(o.data[a]), np.asarray(n.data[a]))
|
||||
for a in range(o.n_angles)), \
|
||||
"waveform data untouched by a row-averaged cache write"
|
||||
|
||||
|
||||
def test_cach_v1_backward_compat_defaults_row_avg_n_zero(tmp_path):
|
||||
"""A v1 CACH tail predates row-averaged FFT caching entirely (no
|
||||
row_avg_n byte at all) -- readers must still parse it in full, treating
|
||||
it as row_avg_n=0. This is what protects an existing real-world v7
|
||||
file's already-stored FFT cache from silently becoming unusable after
|
||||
this change ships."""
|
||||
path = tmp_path / "v1_rowavg.sras"
|
||||
gen.write(path, n_angles=2, seed=25, samples_per_frame=128)
|
||||
assert cache_file(str(path), "fft", True) == ""
|
||||
|
||||
v2 = SrasFile(str(path))
|
||||
freq, entries = v2.precomputed_freq_mhz, list(range(v2.n_angles))
|
||||
payload = struct.pack(fmt.CACH_HDR_FMT, fmt.CACH_MAGIC, 1, fmt.CACH_FLAG_FFT)
|
||||
payload += struct.pack(fmt.SFFT_HDR_FMT_V1, fmt.SFFT_MAGIC,
|
||||
fmt.SFFT_FLAG_BG_SUB, len(entries))
|
||||
for a in entries:
|
||||
payload += struct.pack(">H", a) + freq[a].astype(">f4").tobytes()
|
||||
head = path.read_bytes()[:v2._cache_tail_offset()]
|
||||
path.write_bytes(head + payload)
|
||||
|
||||
v1 = SrasFile(str(path))
|
||||
assert v1.precomputed_row_avg_n == 0
|
||||
assert all(np.array_equal(v1.precomputed_freq_mhz[a], freq[a]) for a in entries), \
|
||||
"v1 images read back unchanged"
|
||||
assert cached_rf_image(v1, 0, None, apply_bg_sub=True, row_avg_n=0) is not None
|
||||
assert cached_rf_image(v1, 0, None, apply_bg_sub=True, row_avg_n=5) is None, \
|
||||
"a v1 tail (predating this feature) can never satisfy a row-averaged request"
|
||||
|
||||
|
||||
def test_viewer_batch_row_average_dispatch(tmp_path, monkeypatch):
|
||||
"""Driving the new 'Batch Compute Row-Averaged FFT and Store' action
|
||||
end-to-end through the real menu handler: dialog values reach the
|
||||
worker, the worker reaches cache_file, and the written file is
|
||||
self-describing afterward. Deliberately does not assert anything about
|
||||
whether viewing an angle afterward dispatches a compute job -- that is
|
||||
a separate, pre-existing gap in _refresh_display shared with the plain
|
||||
DC/FFT batch actions (see test_viewer_shows_stored_angles_without_computing
|
||||
/ test_viewer_shows_stored_dc_without_computing above), not something
|
||||
row-averaging introduces or is responsible for fixing."""
|
||||
path = tmp_path / "rowavg_gui.sras"
|
||||
gen.write(path, n_angles=2, seed=26, samples_per_frame=128)
|
||||
|
||||
class _StubDialog:
|
||||
def __init__(self, *a, **k):
|
||||
pass
|
||||
|
||||
def exec(self):
|
||||
return QDialog.DialogCode.Accepted
|
||||
|
||||
def get_half_width(self):
|
||||
return 6
|
||||
|
||||
def get_threshold_mv(self):
|
||||
return -1e9 # mask nothing, keep the comparison simple
|
||||
|
||||
monkeypatch.setattr("sras_viewer.main_window.RowAverageFftOptionsDialog", _StubDialog)
|
||||
|
||||
app = QApplication.instance() or QApplication([]) # noqa: F841
|
||||
win = SrasViewerWindow()
|
||||
win.show()
|
||||
try:
|
||||
win._load_file(str(path))
|
||||
assert wait_until(lambda: win._sras is not None), "file loaded"
|
||||
assert wait_until(lambda: all((a, CH4_IDX) in win._dc_cache
|
||||
for a in range(win._sras.n_angles))), \
|
||||
"DC precompute finished"
|
||||
|
||||
with patch("sras_viewer.main_window.QFileDialog.getOpenFileNames",
|
||||
return_value=([str(path)], "")):
|
||||
win._on_batch_compute_row_avg()
|
||||
assert wait_until(lambda: not win._job_running("batch"), 60000), "batch ran"
|
||||
assert wait_until(lambda: win._sras is not None
|
||||
and win._sras.version == 7), "file reloaded as v7"
|
||||
pump(200)
|
||||
|
||||
assert win._sras.precomputed_row_avg_n == 6
|
||||
assert "row-averaged n=6" in win.lbl_frame_warn.text(), win.lbl_frame_warn.text()
|
||||
|
||||
expected = compute.cached_rf_image(win._sras, 0, dc_threshold_mv=None,
|
||||
apply_bg_sub=win.chk_bg_sub.isChecked(),
|
||||
row_avg_n=6)
|
||||
assert expected is not None, "the batch write left a readable row-averaged cache"
|
||||
finally:
|
||||
win.close()
|
||||
pump(300)
|
||||
@@ -0,0 +1,106 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Benchmark the FFT peak-search path: exact vs zoom, serial vs pooled.
|
||||
|
||||
Reports wall time, waveforms/s, CPU utilization (utime+stime over wall, in
|
||||
cores), and verifies every variant against the exact reference image.
|
||||
|
||||
Usage:
|
||||
python tools/bench_fft.py # synthetic, pads 1/8/40
|
||||
python tools/bench_fft.py --pads 40 --spf 2500 --rows 8 --frames 1024
|
||||
python tools/bench_fft.py --real /path/big.sras --real-rows 32 --pads 40
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import resource
|
||||
import sys
|
||||
import tempfile
|
||||
import time
|
||||
from pathlib import Path
|
||||
|
||||
import numpy as np
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
|
||||
|
||||
import sras_compute as compute # noqa: E402
|
||||
from sras_compute import compute_rf_image, set_fft_backend # noqa: E402
|
||||
from sras_format import SrasFile # noqa: E402
|
||||
import tools.make_test_sras as gen # noqa: E402
|
||||
from tools.check_equivalence import row_slice # noqa: E402
|
||||
|
||||
|
||||
def _timed(fn):
|
||||
r0 = resource.getrusage(resource.RUSAGE_SELF)
|
||||
t0 = time.perf_counter()
|
||||
out = fn()
|
||||
wall = time.perf_counter() - t0
|
||||
r1 = resource.getrusage(resource.RUSAGE_SELF)
|
||||
cpu = (r1.ru_utime - r0.ru_utime) + (r1.ru_stime - r0.ru_stime)
|
||||
return out, wall, cpu / max(wall, 1e-9)
|
||||
|
||||
|
||||
def bench(sras, pads, backends):
|
||||
n_wf = sum(int(sras.n_rows[a]) * int(sras.n_frames[a])
|
||||
for a in range(sras.n_angles))
|
||||
spf = sras.samples_per_frame
|
||||
print(f"{n_wf} waveforms x {spf} samples, {sras.n_angles} angle(s)")
|
||||
print(f"{'pad':>4} {'backend':>8} {'variant':>16} {'wall':>9} "
|
||||
f"{'wf/s':>10} {'util':>6} match")
|
||||
|
||||
for pad in pads:
|
||||
n_fft = spf * pad if pad > 1 else None
|
||||
for backend in backends:
|
||||
set_fft_backend(backend)
|
||||
|
||||
def run(**kw):
|
||||
imgs = [compute_rf_image(sras, a, dc_threshold_mv=None,
|
||||
apply_bg_sub=True, n_fft=n_fft, **kw)
|
||||
for a in range(sras.n_angles)]
|
||||
return np.concatenate([i.ravel() for i in imgs])
|
||||
|
||||
ref, wall, util = _timed(lambda: run(exact=True))
|
||||
rows = [("exact(serial)", ref, wall, util, True)]
|
||||
for label, kw in (("zoom(serial)", dict(max_workers=1)),
|
||||
("zoom(pool)", {})):
|
||||
img, wall, util = _timed(lambda: run(**kw))
|
||||
rows.append((label, img, wall, util, bool(np.array_equal(img, ref))))
|
||||
for label, img, wall, util, ok in rows:
|
||||
print(f"{pad:>4} {backend:>8} {label:>16} {wall:>8.2f}s "
|
||||
f"{n_wf / wall:>10.0f} {util:>5.1f}x "
|
||||
f"{'OK' if ok else 'MISMATCH'}")
|
||||
|
||||
|
||||
def main():
|
||||
p = argparse.ArgumentParser(description=__doc__)
|
||||
p.add_argument("--pads", default="1,8,40",
|
||||
help="comma-separated pad factors (default 1,8,40)")
|
||||
p.add_argument("--spf", type=int, default=2500)
|
||||
p.add_argument("--rows", type=int, default=8)
|
||||
p.add_argument("--frames", type=int, default=1024)
|
||||
p.add_argument("--backends", default=None,
|
||||
help="comma-separated (default: scipy,pyfftw if available)")
|
||||
p.add_argument("--real", help="path to a real .sras file")
|
||||
p.add_argument("--real-rows", type=int, default=32,
|
||||
help="rows of angle 0 to use from the real file")
|
||||
args = p.parse_args()
|
||||
|
||||
pads = [int(x) for x in args.pads.split(",")]
|
||||
if args.backends:
|
||||
backends = args.backends.split(",")
|
||||
else:
|
||||
backends = ["scipy"] + (["pyfftw"] if compute.PYFFTW_AVAILABLE else [])
|
||||
|
||||
if args.real:
|
||||
sras = row_slice(SrasFile(args.real), 0, args.real_rows)
|
||||
sras.data = [sras.data[0]]
|
||||
sras.n_angles = 1
|
||||
bench(sras, pads, backends)
|
||||
else:
|
||||
with tempfile.TemporaryDirectory(prefix="sras_bench_") as tmp:
|
||||
path = Path(tmp) / "bench.sras"
|
||||
gen.write(path, n_angles=1, seed=0, samples_per_frame=args.spf,
|
||||
geometry=[(args.rows, args.frames)])
|
||||
bench(SrasFile(str(path)), pads, backends)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,194 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Golden-output equivalence harness for compute-path refactors.
|
||||
|
||||
Computes a battery of DC / FFT / alignment outputs and prints a stable hash
|
||||
for each. Run it before a refactor to capture a baseline, then again after
|
||||
and diff the two reports — every line must match.
|
||||
|
||||
Hashes canonicalise to native little-endian float64 before hashing, so a
|
||||
deliberate dtype/byte-order change that preserves values does not show up as
|
||||
a false mismatch.
|
||||
|
||||
Usage:
|
||||
python tools/check_equivalence.py --out baseline.txt
|
||||
python tools/check_equivalence.py --out after.txt --real /path/to/big.sras
|
||||
diff baseline.txt after.txt
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import copy
|
||||
import hashlib
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
import numpy as np
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
|
||||
|
||||
from sras_format import SrasFile, CH3_IDX, CH4_IDX, adc_to_mv # noqa: E402
|
||||
from sras_compute import ( # noqa: E402
|
||||
apply_alignment, compute_angle_alignment, compute_dc_image, compute_rf_image,
|
||||
)
|
||||
import tools.make_test_sras as gen # noqa: E402
|
||||
|
||||
|
||||
def h(arr) -> str:
|
||||
"""Stable hash of an array's *values*, independent of dtype/byte order."""
|
||||
a = np.ascontiguousarray(np.asarray(arr, dtype=np.float64))
|
||||
return hashlib.sha256(a.tobytes()).hexdigest()[:16]
|
||||
|
||||
|
||||
def row_slice(sras: SrasFile, angle_idx: int, n_rows: int) -> SrasFile:
|
||||
"""A shallow view of *sras* restricted to the first *n_rows* rows of
|
||||
*angle_idx*, so the huge real file can be exercised in seconds."""
|
||||
view = copy.copy(sras)
|
||||
n = min(int(n_rows), int(sras.n_rows[angle_idx]))
|
||||
view.n_rows = np.array(sras.n_rows, copy=True)
|
||||
view.n_rows[angle_idx] = n
|
||||
view.data = list(sras.data)
|
||||
view.data[angle_idx] = sras.data[angle_idx][:n]
|
||||
view.y_pos_per_angle = list(sras.y_pos_per_angle)
|
||||
view.y_pos_per_angle[angle_idx] = sras.y_pos_per_angle[angle_idx][:n]
|
||||
return view
|
||||
|
||||
|
||||
def report(lines: list[str], label: str, value: str):
|
||||
lines.append(f"{label:<58} {value}")
|
||||
|
||||
|
||||
def check_file(path: Path, lines: list[str], tag: str,
|
||||
angles: list[int], n_rows: int | None):
|
||||
sras = SrasFile(str(path))
|
||||
report(lines, f"[{tag}] version/n_angles",
|
||||
f"v{sras.version} n={sras.n_angles}")
|
||||
report(lines, f"[{tag}] geometry",
|
||||
f"rows={list(map(int, sras.n_rows))} frames={list(map(int, sras.n_frames))}")
|
||||
report(lines, f"[{tag}] calibration",
|
||||
" ".join(f"{m:.6g}/{o:.6g}/{z:.6g}" for m, o, z in
|
||||
zip(sras.ch_ymult_mv, sras.ch_yoff_adc, sras.ch_yzero_mv)))
|
||||
report(lines, f"[{tag}] angles_deg", h(sras.angles_deg))
|
||||
if sras.background is not None:
|
||||
report(lines, f"[{tag}] background", h(sras.background))
|
||||
|
||||
for a in angles:
|
||||
if a >= sras.n_angles:
|
||||
continue
|
||||
s = row_slice(sras, a, n_rows) if n_rows else sras
|
||||
|
||||
report(lines, f"[{tag}] x_axis_mm(a={a})", h(s.x_axis_mm(a)))
|
||||
report(lines, f"[{tag}] y_positions_mm(a={a})", h(s.y_positions_mm(a)))
|
||||
|
||||
for ch, name in ((CH3_IDX, "CH3"), (CH4_IDX, "CH4")):
|
||||
raw = compute_dc_image(s, a, ch)
|
||||
report(lines, f"[{tag}] dc_adc(a={a},{name})", h(raw))
|
||||
mv = adc_to_mv(raw, s.ch_ymult_mv[ch], s.ch_yoff_adc[ch],
|
||||
s.ch_yzero_mv[ch])
|
||||
report(lines, f"[{tag}] dc_mv(a={a},{name})", h(mv))
|
||||
|
||||
dc4 = adc_to_mv(compute_dc_image(s, a, CH4_IDX),
|
||||
s.ch_ymult_mv[CH4_IDX], s.ch_yoff_adc[CH4_IDX],
|
||||
s.ch_yzero_mv[CH4_IDX])
|
||||
thresholds = [-1e9, float(np.median(dc4))]
|
||||
|
||||
for bg in (False, True):
|
||||
if bg and s.background is None:
|
||||
continue
|
||||
for pad in (1, 2, 4, 8, 40):
|
||||
n_fft = s.samples_per_frame * pad if pad > 1 else None
|
||||
for ti, thr in enumerate(thresholds):
|
||||
img = compute_rf_image(s, a, dc_threshold_mv=thr,
|
||||
apply_bg_sub=bg, n_fft=n_fft)
|
||||
report(lines,
|
||||
f"[{tag}] rf(a={a},bg={int(bg)},pad={pad},thr{ti})",
|
||||
h(img))
|
||||
# dc4_mv passthrough must give the identical result
|
||||
img2 = compute_rf_image(s, a, dc_threshold_mv=thr,
|
||||
apply_bg_sub=bg, n_fft=n_fft,
|
||||
dc4_mv=dc4)
|
||||
same = "SAME" if h(img) == h(img2) else "DIFFER"
|
||||
report(lines,
|
||||
f"[{tag}] rf-dc4arg(a={a},bg={int(bg)},pad={pad},thr{ti})",
|
||||
same)
|
||||
|
||||
|
||||
def check_alignment(path: Path, lines: list[str], tag: str):
|
||||
sras = SrasFile(str(path))
|
||||
if sras.n_angles < 2:
|
||||
return
|
||||
dc4 = adc_to_mv(compute_dc_image(sras, 0, CH4_IDX),
|
||||
sras.ch_ymult_mv[CH4_IDX], sras.ch_yoff_adc[CH4_IDX],
|
||||
sras.ch_yzero_mv[CH4_IDX])
|
||||
thr = float(np.median(dc4))
|
||||
res = compute_angle_alignment(sras, 0, thr)
|
||||
report(lines, f"[{tag}] align canvas_shape", str(res.canvas_shape))
|
||||
report(lines, f"[{tag}] align canvas_origin",
|
||||
f"{res.canvas_origin_mm[0]:.9g},{res.canvas_origin_mm[1]:.9g}")
|
||||
report(lines, f"[{tag}] align canvas_pitch",
|
||||
f"{res.canvas_dx_mm:.9g},{res.canvas_dy_mm:.9g}")
|
||||
for a in sorted(res.per_angle):
|
||||
t = res.per_angle[a]
|
||||
report(lines, f"[{tag}] align shift_mm(a={a})",
|
||||
f"{t.shift_mm[0]:.9g},{t.shift_mm[1]:.9g}")
|
||||
report(lines, f"[{tag}] align rot(a={a})", f"{t.rotation_deg:.9g}")
|
||||
report(lines, f"[{tag}] align matrix(a={a})", h(t.matrix))
|
||||
report(lines, f"[{tag}] align offset(a={a})", h(t.offset))
|
||||
img = compute_dc_image(sras, a, CH4_IDX)
|
||||
report(lines, f"[{tag}] align resampled(a={a})",
|
||||
h(apply_alignment(res, a, img)))
|
||||
|
||||
|
||||
def main():
|
||||
p = argparse.ArgumentParser(description=__doc__)
|
||||
p.add_argument("--out", required=True, help="report file to write")
|
||||
p.add_argument("--real", help="optional path to a real .sras file")
|
||||
p.add_argument("--real-rows", type=int, default=2,
|
||||
help="rows per angle to sample from the real file")
|
||||
p.add_argument("--real-angles", type=int, default=2,
|
||||
help="how many angles to sample from the real file")
|
||||
p.add_argument("--scratch", default=".",
|
||||
help="directory for generated synthetic files")
|
||||
args = p.parse_args()
|
||||
|
||||
lines = [f"# numpy: {np.__version__}"]
|
||||
|
||||
scratch = Path(args.scratch)
|
||||
synth = scratch / "equiv_synth.sras"
|
||||
gen.write(synth, n_angles=4, seed=0, samples_per_frame=64)
|
||||
check_file(synth, lines, "synth", angles=[0, 1, 2, 3], n_rows=None)
|
||||
check_alignment(synth, lines, "synth")
|
||||
|
||||
# A second synthetic with an odd sample count, to catch off-by-one in
|
||||
# rfft bin handling and chunk-boundary arithmetic.
|
||||
synth_odd = scratch / "equiv_synth_odd.sras"
|
||||
gen.write(synth_odd, n_angles=2, seed=7, samples_per_frame=37)
|
||||
check_file(synth_odd, lines, "odd", angles=[0, 1], n_rows=None)
|
||||
|
||||
# A legacy v4 file exercises the uniform-geometry legacy layout through
|
||||
# the same DC/FFT battery.
|
||||
synth_v4 = scratch / "equiv_synth_v4.sras"
|
||||
gen.write_legacy(synth_v4, version=4, n_angles=2, n_rows=6,
|
||||
n_frames=14, samples_per_frame=48, seed=5)
|
||||
check_file(synth_v4, lines, "v4", angles=[0, 1], n_rows=None)
|
||||
|
||||
# A big-endian int16 v6 file (real acquisitions are >i2; the other
|
||||
# synthetics are int8).
|
||||
synth_i16 = scratch / "equiv_synth_i16.sras"
|
||||
gen.write(synth_i16, n_angles=2, seed=9, samples_per_frame=64, bps=2)
|
||||
check_file(synth_i16, lines, "int16", angles=[0, 1], n_rows=None)
|
||||
|
||||
if args.real:
|
||||
real = Path(args.real)
|
||||
if real.exists():
|
||||
check_file(real, lines, "real",
|
||||
angles=list(range(args.real_angles)),
|
||||
n_rows=args.real_rows)
|
||||
else:
|
||||
lines.append(f"# real file not found: {real}")
|
||||
|
||||
Path(args.out).write_text("\n".join(lines) + "\n")
|
||||
print("\n".join(lines))
|
||||
print(f"\nWrote {args.out} ({len(lines)} lines)")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,326 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Generate small synthetic .sras files for testing.
|
||||
|
||||
Writes v6 files (per-angle geometry, ragged waveform blocks) matching
|
||||
scan_format.md, with deterministic pseudo-random waveform content so a test
|
||||
can compute expected DC/FFT images independently of the reader under test.
|
||||
|
||||
Usage:
|
||||
python tools/make_test_sras.py out.sras [--angles 3] [--seed 0]
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import struct
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
import numpy as np
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
|
||||
|
||||
# Single source of truth for the byte layout: the reader's own constants.
|
||||
# The byte *assembly* below stays independent, so a writer bug can't be
|
||||
# masked by a matching reader bug.
|
||||
from sras_format import HDR_FMT as HDR_FMT_LEGACY # noqa: E402
|
||||
from sras_format import GEO_FMT_V6, HDR_FMT_V6 # noqa: E402
|
||||
from sras_compute import _rotation_matrix as _rot # noqa: E402
|
||||
|
||||
# Per-angle (n_rows, n_frames) — deliberately different per angle so ragged
|
||||
# geometry handling is actually exercised.
|
||||
_GEOMETRY = [(5, 7), (4, 11), (6, 9), (3, 13), (7, 6)]
|
||||
|
||||
_SAMPLE_RATE_HZ = 6.25e9
|
||||
_VELOCITY_MM_S = 20.0
|
||||
_LASER_FREQ_HZ = 1000.0
|
||||
_ROW_SPACING_MM = 0.05
|
||||
|
||||
|
||||
def _preamble(ymult_v: float, yoff_adc: float, yzero_v: float) -> bytes:
|
||||
"""A Tektronix WFMOutpre string in verbose (keyword) form — the reader
|
||||
pulls YMULT/YOFF/YZERO out of it by name, so the keywords must be
|
||||
present literally. YMULT/YZERO are in volts, as the scope reports them."""
|
||||
return (
|
||||
":WFMOUTPRE:BYT_NR 1;BIT_NR 8;ENCDG BIN;BN_FMT RI;BYT_OR MSB;"
|
||||
'WFID "Ch1, DC coupling";NR_PT 2500;PT_FMT Y;'
|
||||
"XINCR 1.6000E-10;XZERO 0.0E0;XUNIT \"s\";"
|
||||
f"YMULT {ymult_v:.6E};YOFF {yoff_adc:.6E};YZERO {yzero_v:.6E};"
|
||||
'YUNIT "V"'
|
||||
).encode("utf-8")
|
||||
|
||||
|
||||
def build(n_angles: int, seed: int, samples_per_frame: int,
|
||||
geometry: list[tuple[int, int]] | None = None,
|
||||
bps: int = 1) -> tuple[bytes, dict]:
|
||||
rng = np.random.default_rng(seed)
|
||||
src_geom = geometry or _GEOMETRY
|
||||
geom = [src_geom[a % len(src_geom)] for a in range(n_angles)]
|
||||
n_ch = 3
|
||||
|
||||
angles_deg = np.linspace(0.0, 60.0, n_angles, dtype=np.float32)
|
||||
# Distinct calibration per channel so a swapped-channel bug is visible.
|
||||
cal = [
|
||||
(1.5625e-3, -87.04, 0.0),
|
||||
(2.0000e-3, -60.00, 1.0e-3),
|
||||
(2.5000e-3, -40.00, -2.0e-3),
|
||||
]
|
||||
|
||||
out = bytearray()
|
||||
out += struct.pack(
|
||||
HDR_FMT_V6, b"SRAS", 6, n_angles,
|
||||
0.0, 0.0, 1.0, 1.0, _ROW_SPACING_MM,
|
||||
_VELOCITY_MM_S, _LASER_FREQ_HZ,
|
||||
samples_per_frame, _SAMPLE_RATE_HZ, bps, n_ch,
|
||||
)
|
||||
out += angles_deg.astype(">f4").tobytes()
|
||||
|
||||
x_starts = []
|
||||
for a, (n_rows, n_frames) in enumerate(geom):
|
||||
x_start = -0.5 + 0.1 * a
|
||||
x_starts.append(x_start)
|
||||
out += struct.pack(GEO_FMT_V6, x_start, 1.0, n_frames, n_rows)
|
||||
|
||||
y_positions = []
|
||||
for a, (n_rows, _) in enumerate(geom):
|
||||
y = (0.2 * a + np.arange(n_rows) * _ROW_SPACING_MM).astype(np.float32)
|
||||
y_positions.append(y)
|
||||
out += y.astype(">f4").tobytes()
|
||||
|
||||
for ymult_v, yoff, yzero_v in cal:
|
||||
p = _preamble(ymult_v, yoff, yzero_v)
|
||||
out += struct.pack(">H", len(p)) + p
|
||||
|
||||
background = rng.integers(-8, 9, size=samples_per_frame, dtype=np.int8)
|
||||
out += struct.pack(">I", samples_per_frame) + background.tobytes()
|
||||
|
||||
# Waveform data. CH1 gets a sinusoid at a per-pixel frequency so the FFT
|
||||
# peak is predictable; CH3/CH4 get per-pixel DC levels so the mean is too.
|
||||
t = np.arange(samples_per_frame)
|
||||
waveforms = []
|
||||
for a, (n_rows, n_frames) in enumerate(geom):
|
||||
block = np.empty((n_rows, n_ch, n_frames, samples_per_frame), dtype=np.int8)
|
||||
for r in range(n_rows):
|
||||
for f in range(n_frames):
|
||||
bin_idx = 3 + ((a + r + f) % 17)
|
||||
phase = 2 * np.pi * bin_idx * t / samples_per_frame
|
||||
block[r, 0, f] = np.clip(
|
||||
np.round(60 * np.sin(phase)), -128, 127).astype(np.int8)
|
||||
block[r, 1, f] = np.int8((a * 7 + r * 3 + f) % 100 - 50)
|
||||
block[r, 2, f] = np.int8((a * 5 + r * 11 + f * 2) % 120 - 60)
|
||||
waveforms.append(block)
|
||||
# bps=2 stores the same values big-endian int16, exercising the
|
||||
# reader's >i2 memmap path.
|
||||
out += (block.astype(">i2") if bps == 2 else block).tobytes()
|
||||
|
||||
meta = {
|
||||
"n_angles": n_angles,
|
||||
"geometry": geom,
|
||||
"angles_deg": angles_deg,
|
||||
"x_starts": x_starts,
|
||||
"y_positions": y_positions,
|
||||
"cal": cal,
|
||||
"background": background,
|
||||
"waveforms": waveforms,
|
||||
"samples_per_frame": samples_per_frame,
|
||||
"sample_rate_hz": _SAMPLE_RATE_HZ,
|
||||
}
|
||||
return bytes(out), meta
|
||||
|
||||
|
||||
def write(path: Path, n_angles: int = 3, seed: int = 0,
|
||||
samples_per_frame: int = 64,
|
||||
geometry: list[tuple[int, int]] | None = None,
|
||||
bps: int = 1) -> dict:
|
||||
payload, meta = build(n_angles, seed, samples_per_frame, geometry, bps=bps)
|
||||
path.write_bytes(payload)
|
||||
return meta
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Rotating-sample scan: one shape, imaged at several known rotations
|
||||
# ---------------------------------------------------------------------------
|
||||
#
|
||||
# The scan the angle-alignment path actually has to solve: every angle images
|
||||
# the *same* sample at a different known rotation and offset, and a correct
|
||||
# alignment stacks them all back into one shape. Two properties are
|
||||
# deliberately hostile:
|
||||
#
|
||||
# * every angle gets a different window size and a different, meaningless
|
||||
# stage x_start / y0 — alignment must ignore per-angle stage coordinates
|
||||
# entirely, so any code that reads them will visibly fail here;
|
||||
# * the pixel grid is strongly anisotropic (5 µm along x, 50 µm along y),
|
||||
# like the real instrument, so any registration that rotates raw indices
|
||||
# instead of millimetres shears the image and cannot converge.
|
||||
|
||||
_ROT_DX_MM = 0.005 # x pitch, from velocity/laser_freq below
|
||||
_ROT_DY_MM = 0.05 # row spacing
|
||||
_ROT_BG_MV = 4.0
|
||||
_ROT_FG_MV = 160.0
|
||||
|
||||
|
||||
# How far the sample sits from the rotation axis. Non-zero on purpose: on the
|
||||
# real instrument every angle's scan window is centred on the rotation axis
|
||||
# while the sample is not, so each scan sees the sample somewhere else along a
|
||||
# circle. That offset is exactly what a wrong rotation pivot turns into a ring
|
||||
# of scans instead of a stack, so a centred test sample would hide the bug.
|
||||
_ROT_SAMPLE_OFFSET_MM = (0.55, 0.40)
|
||||
|
||||
|
||||
def _sample_shape_mv(u: np.ndarray, v: np.ndarray) -> np.ndarray:
|
||||
"""An asymmetric test sample in its own mm frame, chirally distinct at
|
||||
every rotation (no 180° ambiguity) and with structure at several radii so
|
||||
rotation is well determined."""
|
||||
u = u - _ROT_SAMPLE_OFFSET_MM[0]
|
||||
v = v - _ROT_SAMPLE_OFFSET_MM[1]
|
||||
img = np.full(u.shape, _ROT_BG_MV, dtype=np.float32)
|
||||
img[((u / 0.85) ** 2 + (v / 0.40) ** 2) <= 1.0] = _ROT_FG_MV # bar
|
||||
img[(np.abs(u - 0.55) <= 0.22) & (np.abs(v - 0.62) <= 0.22)] = _ROT_FG_MV # nub
|
||||
img[((u + 0.75) ** 2 + (v + 0.30) ** 2) <= 0.20 ** 2] = _ROT_FG_MV # dot
|
||||
return img
|
||||
|
||||
|
||||
def write_rotating(path: Path, n_angles: int = 5, samples_per_frame: int = 4,
|
||||
seed: int = 0) -> dict:
|
||||
"""Write a v6 file whose CH4 DC image is one sample seen at n_angles known
|
||||
rotations, and return the ground truth each angle should register to.
|
||||
|
||||
``truth[a] = (rotation_deg, (shift_x_mm, shift_y_mm))`` is the rigid map
|
||||
from angle *a*'s local mm (origin at its own array center) to angle 0's —
|
||||
exactly what ``register_angle_to_reference`` is supposed to recover.
|
||||
"""
|
||||
rng = np.random.default_rng(seed)
|
||||
n_ch, bps = 3, 1
|
||||
cal = [(1.5625e-3, -87.04, 0.0), (2.0e-3, -60.0, 1.0e-3), (2.5e-3, -40.0, -2.0e-3)]
|
||||
ymult_mv, yoff, yzero_mv = cal[2][0] * 1000, cal[2][1], cal[2][2] * 1000
|
||||
|
||||
stage_angles, geom, x_starts, y_starts, thetas, offsets = [], [], [], [], [], []
|
||||
for a in range(n_angles):
|
||||
stage = -37.0 * a # what the rotation stage reports
|
||||
stage_angles.append(stage)
|
||||
# The true image rotation is the negative of the stage's reported
|
||||
# angle: the stage's positive sense is the opposite of math-positive
|
||||
# (x toward y) in scan mm. Nothing may depend on knowing that — the
|
||||
# registration search tries both signs.
|
||||
thetas.append(-stage)
|
||||
offsets.append((0.0, 0.0) if a == 0
|
||||
else (float(rng.uniform(-0.3, 0.3)), float(rng.uniform(-0.3, 0.3))))
|
||||
# A different window per angle, all centred on the same array center —
|
||||
# the real instrument grows each angle's axis-aligned bounding box to
|
||||
# cover the rotated ROI. Sized so the off-axis sample stays inside every
|
||||
# window at every angle, keeping the expected result unambiguous.
|
||||
geom.append((88 + 8 * a, 780 + 60 * a))
|
||||
# Meaningless per-angle stage positions: correct alignment never reads
|
||||
# them, so scattering them proves it.
|
||||
x_starts.append(float(20.0 + rng.uniform(-6.0, 6.0)))
|
||||
y_starts.append(float(30.0 + rng.uniform(-6.0, 6.0)))
|
||||
|
||||
out = bytearray()
|
||||
out += struct.pack(
|
||||
HDR_FMT_V6, b"SRAS", 6, n_angles,
|
||||
x_starts[0], y_starts[0], 1.0, 1.0, _ROT_DY_MM,
|
||||
_VELOCITY_MM_S, _VELOCITY_MM_S / _ROT_DX_MM, # velocity/freq -> 5 µm pitch
|
||||
samples_per_frame, _SAMPLE_RATE_HZ, bps, n_ch,
|
||||
)
|
||||
out += np.array(stage_angles, dtype=">f4").tobytes()
|
||||
for a, (n_rows, n_frames) in enumerate(geom):
|
||||
out += struct.pack(GEO_FMT_V6, x_starts[a], 1.0, n_frames, n_rows)
|
||||
for a, (n_rows, _) in enumerate(geom):
|
||||
out += (y_starts[a] + np.arange(n_rows) * _ROT_DY_MM).astype(">f4").tobytes()
|
||||
for ymult_v, yoff_a, yzero_v in cal:
|
||||
p = _preamble(ymult_v, yoff_a, yzero_v)
|
||||
out += struct.pack(">H", len(p)) + p
|
||||
background = rng.integers(-8, 9, size=samples_per_frame, dtype=np.int8)
|
||||
out += struct.pack(">I", samples_per_frame) + background.tobytes()
|
||||
|
||||
truth, dc4_images = {}, []
|
||||
for a, (n_rows, n_frames) in enumerate(geom):
|
||||
# Local mm of every pixel, measured from this angle's own array center.
|
||||
lx = (np.arange(n_frames) - (n_frames - 1) / 2.0) * _ROT_DX_MM
|
||||
ly = (np.arange(n_rows) - (n_rows - 1) / 2.0) * _ROT_DY_MM
|
||||
gx, gy = np.meshgrid(lx, ly)
|
||||
# local = R(theta) @ sample + offset, so sample = R(theta)^T @ (local - offset)
|
||||
rel = np.stack([gx - offsets[a][0], gy - offsets[a][1]], axis=-1)
|
||||
s = rel @ _rot(thetas[a]) # == rel @ R^T.T == R^T @ rel
|
||||
dc4 = _sample_shape_mv(s[..., 0], s[..., 1])
|
||||
dc4_images.append(dc4)
|
||||
|
||||
inv = _rot(-thetas[a])
|
||||
truth[a] = (-thetas[a],
|
||||
tuple(float(v) for v in -(inv @ np.array(offsets[a]))))
|
||||
|
||||
adc4 = np.clip(np.round((dc4 - yzero_mv) / ymult_mv + yoff), -128, 127).astype(np.int8)
|
||||
block = np.zeros((n_rows, n_ch, n_frames, samples_per_frame), dtype=np.int8)
|
||||
block[:, 2] = adc4[:, :, None] # CH4 carries the sample
|
||||
block[:, 1] = 10 # CH3 flat
|
||||
block[:, 0] = rng.integers(-40, 41, size=(n_rows, n_frames, samples_per_frame),
|
||||
dtype=np.int8) # CH1 noise
|
||||
out += block.tobytes()
|
||||
|
||||
path.write_bytes(bytes(out))
|
||||
return {"n_angles": n_angles, "geometry": geom, "stage_angles_deg": stage_angles,
|
||||
"truth": truth, "dc4_mv": dc4_images, "x_starts": x_starts,
|
||||
"y_starts": y_starts, "dx_mm": _ROT_DX_MM, "dy_mm": _ROT_DY_MM}
|
||||
|
||||
|
||||
|
||||
|
||||
def write_legacy(path: Path, version: int = 4, n_angles: int = 2,
|
||||
n_rows: int = 4, n_frames: int = 10,
|
||||
samples_per_frame: int = 32, seed: int = 0) -> dict:
|
||||
"""Write a v2/v3/v4 file: uniform geometry, one flat waveform block.
|
||||
|
||||
Used to exercise sras_average.py, which only handles the legacy formats.
|
||||
"""
|
||||
rng = np.random.default_rng(seed)
|
||||
n_ch, bps = 3, 1
|
||||
|
||||
out = bytearray()
|
||||
out += struct.pack(
|
||||
HDR_FMT_LEGACY, b"SRAS", version, n_angles, n_rows,
|
||||
-0.5, 1.0, _VELOCITY_MM_S, _LASER_FREQ_HZ,
|
||||
n_frames, samples_per_frame, _SAMPLE_RATE_HZ, bps, n_ch,
|
||||
)
|
||||
angles = np.linspace(0.0, 45.0, n_angles, dtype=np.float32)
|
||||
out += angles.astype(">f4").tobytes()
|
||||
y = (np.arange(n_rows) * _ROW_SPACING_MM).astype(np.float32)
|
||||
out += y.astype(">f4").tobytes()
|
||||
|
||||
if version >= 3:
|
||||
for ymult_v, yoff, yzero_v in ((1.5625e-3, -87.04, 0.0),
|
||||
(2.0e-3, -60.0, 1.0e-3),
|
||||
(2.5e-3, -40.0, -2.0e-3))[:n_ch]:
|
||||
p = _preamble(ymult_v, yoff, yzero_v)
|
||||
out += struct.pack(">H", len(p)) + p
|
||||
|
||||
background = rng.integers(-8, 9, size=samples_per_frame, dtype=np.int8)
|
||||
if version >= 4:
|
||||
out += struct.pack(">I", samples_per_frame) + background.tobytes()
|
||||
|
||||
data = rng.integers(-100, 101,
|
||||
size=(n_angles, n_rows, n_ch, n_frames, samples_per_frame),
|
||||
dtype=np.int8)
|
||||
out += data.tobytes()
|
||||
path.write_bytes(bytes(out))
|
||||
return {"version": version, "n_angles": n_angles, "n_rows": n_rows,
|
||||
"n_frames": n_frames, "samples_per_frame": samples_per_frame,
|
||||
"n_channels": n_ch, "data": data, "angles_deg": angles,
|
||||
"y_positions": y, "background": background}
|
||||
|
||||
|
||||
def main():
|
||||
p = argparse.ArgumentParser(description=__doc__)
|
||||
p.add_argument("output")
|
||||
p.add_argument("--angles", type=int, default=3)
|
||||
p.add_argument("--seed", type=int, default=0)
|
||||
p.add_argument("--spf", type=int, default=64, help="samples per frame")
|
||||
args = p.parse_args()
|
||||
|
||||
out = Path(args.output)
|
||||
meta = write(out, args.angles, args.seed, args.spf)
|
||||
print(f"Wrote {out} ({out.stat().st_size:,} bytes)")
|
||||
print(f" angles : {meta['n_angles']}")
|
||||
print(f" geometry : {meta['geometry']}")
|
||||
print(f" spf : {meta['samples_per_frame']}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Reference in New Issue
Block a user