diff --git a/README.md b/README.md
index bdb4a9f..5edf47b 100644
--- a/README.md
+++ b/README.md
@@ -8,10 +8,11 @@
LamellarSAXS2D reads calibrated detector frames (CBF, EDF, TIFF, NPY/NPZ, HDF5), builds physical `q`, `chi`, `qx`, and `qy` from a PONI file through pyFAI, traces observed butterfly arcs, and reports what the image actually supports:
-| A typical frame reports | Only when an interior ellipse is supported |
+| A typical frame reports | Only when a radial reflection or interior ellipse is supported |
| --- | --- |
-| First-order `q*` and **L ring** = `2π/q*` | Apparent `a`, `b/a`, `θ` |
-| Occupied sides, quality, and flags | Unpublished **Ln / Lz / L major** candidates |
+| q-ring profiles, observed petal trajectories, quality, and flags | First-order `q*` and **L ring** = `2π/q*` |
+| Occupied sides and supported branches | Apparent `a`, `b/a`, `θ` |
+| Missing lobes/rings remain missing | Unpublished **Ln / Lz / L major** candidates |
| `ring` when the fit sits on a bound or the major axis runs away | Never a silent overwrite of user bounds or of ring L into the Ln column |
`success=True` is not scientific acceptance. Pixel-q never invents a physical period. Opposite quadrants are never fabricated.
@@ -25,11 +26,14 @@ Synthetic demonstration (pixel-q): the Wang/Grubb double ellipse drawn on a gene
## What it does
- **Butterfly arcs** (`ridge_method=butterfly_curvature`): curvature ridges, branch/side labels (QI+QIII vs QII+QIV), first-order family vs harmonics, sparse-ring fill. See the [butterfly arc guide](docs/butterfly_arcs_zh.md).
+- **Annular butterfly trajectories**: the new workbench session defaults to fixed-q annuli and angular profiles `I(χ)`, connecting up to four observed lobe maxima into long butterfly petals. Each ring retains its raw profile, counts, and coverage; missing lobes/rings remain missing. See the [annular trajectory guide](docs/annular_trajectories_zh.md).
+- **Independent radial diagnostics**: `radial_sector` measures fixed-χ `I(q)` profiles for a separate check. Its `q*` values are not the default butterfly trajectory or the primary ellipse input. See the [radial-sector guide](docs/sector_peaks_zh.md).
- **Honest ellipse publication**: `flat_ellipse` (editable `b/a` bounds, default `0.005–0.35`) and `very_flat_ellipse`. A cap, floor, or major axis longer than the observed first-order ridge is **ring-only** — `a`, tilt, and ellipticity stay unpublished.
- **Batch review**: independent frames, cancel/progress, checkpoints, streaming CSV/JSON/NPZ. The table shows `WARN · ring` / `WARN · ellipse`, L ring, and candidate-period tooltips. Warm-start stays quality-gated.
-- **Workbench**: Identify arcs → Evaluate; bilingual UI; first-order ring overlay instead of a capped tilted ellipse; lamellar studio and 0.4 publication artboards are schematics, not a unique inversion ([studio](docs/lamellar_workbench_zh.md), [figures](docs/publication_figures_zh.md)).
+- **Workbench**: Identify trajectories → Evaluate; bilingual UI; first-order ring overlay instead of a capped tilted ellipse; lamellar studio and 0.4 publication artboards are schematics, not a unique inversion ([studio](docs/lamellar_workbench_zh.md), [figures](docs/publication_figures_zh.md)).
- **Optional `full2d`**: empirical whole-pixel intensity refinement. It is a different model from the butterfly geometry measurement.
- **Measurement and fit figures**: export fixed-size SVG/PDF and high-resolution TIFF/PNG with source arrays, curve/profile CSVs, and checksums. Inspect measured data, candidate ellipses, overlays, and actual `full2d` predictions without promoting a candidate to a scientifically accepted result. See the [figure export guide](docs/butterfly_figures_zh.md).
+- **Figure delivery**: choose column width and resolution in one export window, then browse the complete figure bundle offline through `index.html`. Annular/radial source CSV and technical figure checks accompany the images; formatting checks do not imply scientific acceptance.
- **Peak diagnostics**: locate the raw brightest pixel separately from supported lobe peaks; inspect measured/model peak positions, local zooms, angular/radial profiles, and clean overlays from each fit source. Peak coordinates and support flags also travel through batch exports.
- **Preflight and P3/P4 gates**: read-only package checks and evidence reports. They do not freeze science or replace named human review.
@@ -98,6 +102,8 @@ bsaxs preflight data/package --manifest manifest.csv \
--poni geometry.poni --mask mask.npy -o results/preflight
```
+For an unattended package run, use `bsaxs batch "data/package/images/*.edf" --unattended data/package --manifest data/package/manifest.csv --poni data/package/geometry.poni --mask data/package/mask.npy -o results/unattended_001`. This performs preflight before fitting, writes a checkpoint and streams batch evidence. A red preflight blocks fitting; warnings or failed frames return a nonzero exit status. Keep the output outside the raw package and use `--resume` with the same inputs and settings after interruption.
+
`bsaxs analyze ... --full2d` is the optional empirical intensity fit. `bsaxs-gui` is the crash-visible desktop entry (same as `启动_LamellarSAXS2D.cmd`); `bsaxs gui` remains a supported CLI alias that opens the workbench.
Agents (and any non-interactive operator) should start with `bsaxs describe` or a bare `bsaxs`. That prints a JSON catalog of commands, exit codes, and scientific invariants. Environment checks: `bsaxs doctor --json` (same as `bsaxs-doctor`). Failed commands emit a JSON error envelope on stdout and a human `错误：` line on stderr. See [AGENTS.md](AGENTS.md).
@@ -118,6 +124,8 @@ Agents (and any non-interactive operator) should start with `bsaxs describe` or
| Agent / automation CLI contract | [AGENTS.md](AGENTS.md) |
| CLI, TOML, batch, masks, exports | [docs/user_guide_zh.md](docs/user_guide_zh.md) |
| Butterfly arcs and publication rules | [docs/butterfly_arcs_zh.md](docs/butterfly_arcs_zh.md) |
+| Fixed-q annular butterfly trajectories | [docs/annular_trajectories_zh.md](docs/annular_trajectories_zh.md) |
+| Fixed-χ radial sector peaks | [docs/sector_peaks_zh.md](docs/sector_peaks_zh.md) |
| Measurement / peak figures | [docs/butterfly_figures_zh.md](docs/butterfly_figures_zh.md) |
| Symbols, units, and interpretation limits | [docs/scientific_basis_zh.md](docs/scientific_basis_zh.md) |
| Architecture | [docs/architecture_zh.md](docs/architecture_zh.md) |
@@ -126,21 +134,15 @@ Agents (and any non-interactive operator) should start with `bsaxs describe` or
## Scientific scope
-The double ellipse is an **empirical reciprocal-space measurement**, following the Wang/Grubb picture of a butterfly as a pair of origin-centred ellipses. One 2D pattern does not uniquely recover a 3D lamellar stack or a deformation mechanism.
-
-- [Wang, Murthy & Grubb (2007)](https://doi.org/10.1016/j.polymer.2007.04.026)
-- [Grubb, Murthy & Francescangeli (2016)](https://doi.org/10.1002/polb.23930)
-- [Grubb et al. (2021)](https://doi.org/10.1016/j.polymer.2021.123566)
-
-The papers are not redistributed here.
+The double ellipse is an **empirical reciprocal-space measurement**. The current annular engineering route is documented against Murthy & Grubb (2024), especially §4.1 on z-slices, minimum-curvature peak trajectories, and the two-ellipse butterfly description: [IUCr article](https://journals.iucr.org/j/issues/2024/04/00/tu5052/). It is not claimed as a reproduction of the 2021 algorithm; the 2007 and 2021 full texts were not obtained and read for this tuning. One 2D pattern does not uniquely recover a 3D lamellar stack or a deformation mechanism.
---
## 中文说明
-LamellarSAXS2D 面向取向层片的各向异性二维 SAXS 蝴蝶纹：用 PONI（pyFAI）得到物理 `q/chi/qx/qy`，识别观测弧，并只发表图像真正支持的量。
+LamellarSAXS2D 面向取向层片的各向异性二维 SAXS 蝴蝶纹：用 PONI（pyFAI）得到物理 `q/chi/qx/qy`，提取固定 q 环的 `I(χ)` 花瓣轨迹，并只发表图像真正支持的量。
-多数实验帧给出的是**一阶环周期**（`q*` 与 **环 L**）。只有内凹椭圆真正成立时，才显示表观 `a`、`b/a`、`θ`，以及未发表的 **Ln / Lz / 长轴 L** 候选。贴在 `flat_ellipse` 上下界、或长轴超出一阶脊线范围的解，按 **仅环** 处理，不会把求解器的倾角或环 L 写进 Ln 列。`success=True` 不是科学验收；像素 q 不能冒充物理周期；缺失象限不会被镜像补齐。
+只有在径向反射峰有明确支持、单位有效且级次解释另有依据时，才把 `q*` 换算为一阶环周期 **L = 2π/q***。annular 的 `q_annulus` 只是固定 q 环采样坐标。只有内凹椭圆真正成立时，才显示表观 `a`、`b/a`、`θ`，以及未发表的 **Ln / Lz / 长轴 L** 候选。贴在 `flat_ellipse` 上下界、或长轴超出观测支持的解，按 **仅环/候选限制** 处理，不会把求解器的倾角或环 L 写进 Ln 列。`success=True` 不是科学验收；像素 q 不能冒充物理周期；缺失象限不会被镜像补齐。
### 安装与启动
@@ -158,7 +160,11 @@ py -3.13 -m venv .venv-project
.\启动_LamellarSAXS2D.cmd
```
-蝴蝶页建议顺序：**识别弧 → 评估**。详见[首次启动](docs/first_run_zh.md)。
+蝴蝶页建议顺序：**识别 → 评估**（曲率模式下识别步骤显示为“识别弧”）。详见[首次启动](docs/first_run_zh.md)。
+
+新建 GUI 会话默认按固定 q 环计算角向 `I(χ)`，用 q 环上的角向峰连接四条花瓣轨迹；默认 q 环数 40、方位角分箱 72。每个 q 环最多保留四个实际支持峰，少于四个就保留少数峰，不镜像补象限；缺环造成的轨迹断点也不桥接。历史项目缺少 `trace_method` 时保持曲率路径兼容，历史 `ridge_method=butterfly_curvature` 的分支/象限 family 仍可复现。固定 χ 的 `radial_sector` 只作为独立径向诊断，不是默认主椭圆输入。详见[固定 q 环花瓣轨迹](docs/annular_trajectories_zh.md)与[径向扇区诊断](docs/sector_peaks_zh.md)。
+
+annular 点的 `q_annulus` 是预设 q 环的采样坐标，不是径向反射峰 `q*`，不能换算成 `2π/q`。椭圆拟合使用固定参考轴的对角配对，不能逐个花瓣重新指派；外层 q 窗口边界也不能冒充真实长轴尖端。
评估后可在「叠加图层」分别检查实测谱、观测轨迹、几何候选和全像素模型椭圆；峰位表区分原始最亮点 G 与受支持峰 P，选中行即可定位。导出同时包含干净叠加图、峰位图、局部放大、剖面及 CSV/NPZ 源数据。匹配差或参数不稳定时会保留明确提示，不能仅凭曲线看起来像蝴蝶判定拟合正确。详见[测量图与峰位导出](docs/butterfly_figures_zh.md)。
@@ -171,6 +177,10 @@ bsaxs inspect data/frame_0001.edf --poni geometry/detector.poni --mask masks/det
bsaxs analyze data/frame_0001.edf --poni geometry/detector.poni --mask masks/detector.npy \
--ridge-method butterfly_curvature --ellipse-preset flat_ellipse \
--butterfly-stage evaluate --butterfly-resamples 0 -o results/frame_0001
+bsaxs analyze data/frame_0001.edf --poni geometry/detector.poni --mask masks/detector.npy \
+ --butterfly-stage evaluate --butterfly-trace-method annular_peak \
+ --annular-rings 40 --annular-angles 72 --butterfly-resamples 0 \
+ -o results/frame_0001_annular
bsaxs batch "data/frame_*.edf" --poni geometry/detector.poni --mask masks/detector.npy \
--ridge-method butterfly_curvature --ellipse-preset flat_ellipse \
--butterfly-stage evaluate --mode independent -o results/batch
diff --git a/docs/annular_trajectories_zh.md b/docs/annular_trajectories_zh.md
new file mode 100644
index 0000000..e414aa1
--- /dev/null
+++ b/docs/annular_trajectories_zh.md
@@ -0,0 +1,81 @@
+# 固定 q 环的 `I(χ)` 花瓣轨迹
+
+`annular_peak` 是当前 GUI 新会话的主蝴蝶路径。它把 q 窗口划成一组固定的 q 环，在每个 q 环上计算角向 profile `I(χ)`，从每个 profile 中提取实际支持的角向峰，再沿 q 方向连接成最多四条、支持充分时呈四条的长花瓣弧。这个观测定义对应用户在二维图上看到的 4 条蓝色花瓣轨迹；它不再把每个 bar 的局部最亮点直接当作主轨迹。
+
+固定 χ 的 `radial_sector` 仍可用于独立的 `I(q)` 径向诊断，但其 `q*` 不属于默认 annular 主轨迹，也不是默认主椭圆输入。局部二维曲率 `curvature` 保留为历史项目和高级诊断路径。
+
+## 默认采样与原始 profile
+
+GUI 新建会话默认使用 40 个 q 环和 72 个方位角分箱。实际有效 q 像素会按 q 环和 χ 分箱；每个 q 环的原始角向强度定义为：
+
+```text
+I_raw(χₗ | qₖ) = sum(Iₚ) / count(Iₚ)
+```
+
+其中 `p` 只包括当前 mask、q 窗口和有限强度允许的像素。每个 q 环的 `raw_mean`、`raw_sum`、`counts` 和 `coverage` 都保留在结果中；`raw_sum` 不应脱离 count 单独比较。空分箱保持为空，不用零或镜像数据填充。
+
+环积分层不额外施加探测器效率、固角、偏振或绝对强度校正，也不把输入强度重新解释为另一种 pyFAI 校正积分。输入数据已有的校正和强度单位随上下文记录。q 环中心来自 PONI 的 q 坐标；若只有 pixel-q，只能按采样坐标解释。
+
+每个 q 环最多保留四个实际观测峰，每个参考象限最多一个 dominant 峰。少于四个时保留实际存在的峰，不补齐缺失象限；某个 q 环没有可靠峰时保留 profile 和缺环状态，不跨过缺环强行连接。当前默认最小连续轨迹长度为 3 个 q 环，短于该长度的候选不升级为连续花瓣弧。
+
+## 峰筛选和轨迹连接
+
+一个角向候选需要在该环上有足够 coverage、连续的角向支持、局部突出度和噪声支持，并通过有效像素贡献与热像素主导检查。相邻候选峰过于接近或强度证据不足时保留歧义/拒绝原因；程序不会为了得到四瓣而强行选峰。
+
+轨迹只连接相邻 q 环中同一参考象限的实际峰，并限制角度跳变。mask、beam stop、探测器缝隙或低 coverage 造成的断开会原样记录。`I(χ)` profile 以及每个环的 candidates 仍可在 GUI 和离线图包中检查，即使该环最终没有进入花瓣弧。
+
+当前真实 frame110/120 中看到的 point 数和 4 条 arc 只是某一组 q 环/角度分箱下的调校示例。它们不应写成最终验证数字、普适结构计数或科学接受结论；改变 q 窗口、mask、PONI 或分箱会改变可见支持。
+
+## 固定对角配对与椭圆拟合
+
+轨迹建立前先按用户给定的参考轴固定象限和 branch：
+
+- family 0：参考轴内的 QI 与 QIII；
+- family 1：参考轴内的 QII 与 QIV。
+
+这是一种固定的对角配对。拟合接收已经分配好的 branch、side 和 arc 身份，不能在优化过程中把某一条花瓣重新指派给另一个 individual petal，也不能靠最近距离替换缺失象限。配对、缺口和支撑状态会写入结果诊断。
+
+拟合得到的双椭圆仍是观测几何候选，不是唯一的三维结构反演。长轴、倾角和 `Ln/Lz` 只有在真实二维支持足够且参数可辨识时才可解释；求解器成功、残差较小或图形完整都不等于科学验收。
+
+## q 环坐标和长轴边界
+
+`q_annulus` 是预先规定的 q 环采样坐标，只说明该点来自哪个 q 环。它不是径向强度峰 `q*`，不能用 `2π/q_annulus` 换算层片间距，也不能自动命名为一阶反射。
+
+分析 q 窗口的外边界是采样范围，不是真实长轴尖端。annular 路径已禁用共享的 `observed_tip_constraint`，避免把 q 窗口边界塞进长轴估计；用户明确给出的参数上下界仍然保留。若 q 支持不足以辨识很长的 `a`，结果应标记为不可辨识、ring-only 或候选限制状态，不强报长轴、`Ln` 或 `L`。
+
+## GUI、CLI 与旧项目
+
+新建 GUI 会话的识别方式是 `annular_peak`，控制栏默认显示 q 环数量 40 和方位角分箱 72。历史项目配方缺少 `trace_method` 时，继续使用历史 `curvature` 语义；历史 `ridge_method=butterfly_curvature` 的 family、象限和分支标记仍保留。需要切换到 annular 时应明确选择方法并重新识别。
+
+CLI 的主路径写法为：
+
+```powershell
+bsaxs analyze data/frame_0001.edf `
+ --poni geometry/detector.poni `
+ --mask masks/detector.npy `
+ --butterfly-stage evaluate `
+ --butterfly-trace-method annular_peak `
+ --annular-rings 40 `
+ --annular-angles 72 `
+ --butterfly-resamples 0 `
+ -o results/frame_0001_annular
+```
+
+`--annular-rings` 是请求的 q 环数量，实际数量仍受 q 像素采样限制；`--annular-angles` 是每个 q 环的方位角分箱数。显式指定 `--butterfly-trace-method` 时，CLI 会选择蝴蝶工作流；不要与其他 `--ridge-method` 混用，除非该值也是 `butterfly_curvature`。`radial_sector` 的 `--sector-width`/`--sector-step` 只改变独立径向诊断。
+
+## 文献边界
+
+本路线的文献依据只采用已核读的 Murthy 与 Grubb 2024 年 Journal of Applied Crystallography 文章[《Evolution of elliptical SAXS patterns in aligned systems》](https://journals.iucr.org/j/issues/2024/04/00/tu5052/)，尤其是 §4.1：先用 z slices 观察层片反射峰位，再以强度曲面的 minimum-curvature 轨迹扩展椭圆拟合；butterfly 需要两条椭圆。该文支持“峰位轨迹可以呈椭圆、蝴蝶需要两个椭圆”的物理和几何背景，不等同于本项目的 annular 工程算法。
+
+本项目的 `annular_peak` 是固定 q 环、逐环 `I(χ)`、实际峰支持和连续轨迹连接的工程实现，不能称作对 2021 年算法的复刻。2007/2021 文献全文在本次调校中未取得并逐篇核读，因此不把它们写成已验证的实现依据。最终椭圆参数、反射级次和材料结构解释仍需独立实验与人工审查。
+
+## 图稿和源数据
+
+含 `annular_peaks` 的图包会新增：
+
+- `annular_qchi.svg/pdf/png/tiff`：q–χ 原始均值和受支持角向峰；
+- `annular_profiles.svg/pdf/png/tiff`：代表 q 环的原始/平滑 `I(χ)`、count 和 coverage；
+- `annular_profiles.csv`、`annular_peaks.csv`、`annular_profiles.npz`：profile、候选峰、选择状态、覆盖和原始数组；
+- `annular_caption.txt`、`annular_manifest.json`：方法定义、解释边界和文件哈希。
+
+导出器只消费已完成的 annular 结果，不在图稿阶段重积分、补象限、跨缺环桥接或重新拟合椭圆。Nature 单栏/双栏尺寸和矢量输出有助于排版与复核，但图件生成成功不保证几何模型适用、参数可发表或科学验收。
diff --git a/docs/butterfly_figures_zh.md b/docs/butterfly_figures_zh.md
index 2c0a24b..dc23832 100644
--- a/docs/butterfly_figures_zh.md
+++ b/docs/butterfly_figures_zh.md
@@ -2,18 +2,22 @@
`butterfly_saxs.butterfly_figure` 从观测强度、逐像素 `qx/qy` 和蝴蝶页 `current_result` 直接生成科研图，不依赖 Qt。主图使用输入的二维 q 坐标网格，因此支持非仿射网格和坐标递增、递减的情况；不会用图像尺寸推算 q 轴。
+结果可以来自新 GUI 默认的 `annular_peak` 固定 q 环 `I(χ)` 花瓣轨迹、历史 `curvature` 脊线，或独立的 `radial_sector` 径向 profile。三者的点定义不能混用：annular 点来自逐环角向峰，`q_annulus` 是采样坐标；radial `q*` 来自固定 χ 的 `I(q)` profile，属于独立诊断，不是默认主椭圆输入。annular 原始强度与 radial profile 都按有效像素 `sum / count` 均值保存，并保留 counts/coverage；导出不额外施加 detector correction，输入强度的已有校正和单位按上下文记录。方法细节见[固定 q 环花瓣轨迹](annular_trajectories_zh.md)和[径向扇区诊断](sector_peaks_zh.md)。
+
主图只叠加结果提供的脊线点，以及满足来源条件的已观测弧段。每个点都必须带有效的源像素坐标，且落在调用方提供的有效域和当前显示 q 窗口内；仅有 q 坐标的旧结果不会猜测像素位置。缺少像素坐标、超出图像边界或落在无效像素上的点不绘制，但会原样保留在结果文件和逐点 CSV，并记录省略原因。弧段必须显式标记为有效、包含唯一且明确接受的有序源点，并且整段路径不能穿过显示有效域外的像素。接受、拒绝和状态缺失使用不同符号表示；未知支路或侧别保持原样，不镜像补点。主图不绘制候选椭圆。
同一导出目录另含四面板比较图：观测强度、单独的候选椭圆曲线、观测强度叠加测得轨迹与候选曲线、以及已有拟合残差诊断。有限的 ring-only、边界受限或未收敛几何可以作为虚线候选诊断曲线导出，并明确标记为“候选 / 非定量 / 非科学接受”；缺失、非有限或不物理的几何不画。候选曲线完整范围不是观测弧支持。若没有逐点投影/法向残差或可用法向强度 profile，诊断面板明确显示不可用，不构造残差。另有单独的 ellipse-only SVG/PDF/PNG/TIFF，供独立排版。
## 判断拟合是否可信，以及定位最强点
-蝴蝶页现在可分别选择实测谱、观测轨迹、几何候选、全像素强度模型椭圆及两者对比。几何椭圆来自脊线点；强度模型椭圆使用当前优化结果的参数与参考轴。它们对应不同目标函数，不应混称为同一个拟合。角向包络、径向展宽和分量叠加都会使模型强度最大值偏离名义椭圆曲线。
+蝴蝶页现在可分别选择实测谱、annular 观测轨迹、历史曲率候选、几何候选、全像素强度模型椭圆及两者对比。几何椭圆使用已经固定 branch/family 的观测轨迹；强度模型椭圆使用当前优化结果的参数与参考轴。它们对应不同目标函数，不应混称为同一个拟合。角向包络、径向展宽和分量叠加都会使模型强度最大值偏离名义椭圆曲线。
页面显示几何残差相对于定位误差的比值，并沿用分析结果中已有的筛查限值。超过限值时明确显示匹配较差；优化器收敛不代表科学验收。强度模型的条件数、参数边界和参数来源随图一起记录。改变分析条件后，旧的峰标记与模型图层失效，重新计算后才能用于当前结果。
峰位表中的 `G` 是所选有效分析域内的原始最亮像素，可能位于低 q 尾部或窗口边缘。`P1–P4` 是受像素覆盖、角向局部突出程度及噪声检查支持的局部信号峰，最多四个，不会补造缺失峰。峰位用实际像素的 qx/qy 标定坐标表示；平滑只用于稳健定位，原始强度同时保留。选择表格行可定位相应标记并检查角向、径向曲线。P 编号按本帧方位排序，不能直接作为跨帧跟踪标识。
+上段的 G/P 说明适用于历史曲率和像素峰诊断。使用 `annular_peak` 时，sector 表不再是主轨迹证据；图包会列出每个 q 环的完整 `I(χ)` profile、count、coverage、候选峰和实际选择的 0–4 个角向峰。少于四个峰和缺环都保留，不镜像补象限、不跨缺环桥接。使用 `radial_sector` 时，表中仍列出固定 χ 的 `I(q)` profile；没有受支持径向峰的角度仍可查看失败原因，不生成假 q 空间点。`q_annulus` 不是 `q*`，两者都不能仅凭导出自动等同于一阶周期或 `Ln`。
+
局部信号峰默认使用当前径向提示给出的信号带；G 的搜索仍覆盖完整分析窗口。导出记录两者各自的域与提示来源。G、局部像素峰、径向曲线峰值和 q* 是不同量，不会把一个最亮像素自动换算成层片周期。
v2 峰位诊断先用有效像素的径向中位数估计各向同性参考，将参考采样到同一个 q 网格，并经过相同的掩膜和平滑操作。用于识别的角向曲线是观测平滑剖面减去这个参考，避免像素采样把圆环变成四瓣。原始和平滑观测曲线仍完整保留；参考及检测差值随图、CSV、NPZ 一起输出。该参考用于识别，不替代实验背景扣除。局部角向噪声默认在一分箱尺度估计，保留原有四倍噪声突出度门槛与像素噪声传播下界；估计尺度及独立像素假设写入方法记录。
@@ -34,9 +38,21 @@ v2 峰位诊断先用有效像素的径向中位数估计各向同性参考，
- `peak_zooms.*`：峰附近的局部放大图。
- `peak_landmarks.csv/json`、`peak_profiles.csv/npz`：原始/平滑强度、像素与 q 坐标、覆盖、警示和实测—模型位移。批量测量 CSV 也包含独立的 `raw_pixel_maximum` 与 `supported_lobe_pixel` 记录，其 q 半径不冒充 q*。
- `fit_assessment.json`、`fit_source_parameters.csv`、`fit_overlay_curves.npz`：两种拟合的参数来源、状态和可重绘曲线。
+- 若结果含 `annular_peaks`，另有 `annular_qchi.svg/pdf/png/tiff`（q–χ 原始均值与角向峰轨迹）、`annular_profiles.svg/pdf/png/tiff`（代表 q 环的 `I(χ)`、count/coverage 诊断）、`annular_profiles.csv`、`annular_peaks.csv`、`annular_profiles.npz`、`annular_caption.txt` 和 `annular_manifest.json`。这些图件消费已计算的 annular 结果，不在导出阶段重新积分、补象限或跨缺环连接。
+- 若结果含 `sector_peaks`，另有 `sector_qchi.svg/pdf/png/tiff`（固定 χ 径向诊断热图）、`sector_profiles.svg/pdf/png/tiff`（径向 profile 与 count/coverage 诊断）、`sector_peaks.csv`、`sector_profiles.csv`、`sector_profiles.npz`、`sector_caption.txt` 和 `sector_manifest.json`。这些图件属于独立 `radial_sector` 诊断，不能代替 annular 主轨迹。
`*` 图件均有 SVG、PDF、PNG、TIFF。画板宽度和可编辑文字遵循 [Nature 官方科研图指南](https://research-figure-guide.nature.com/figures/building-and-exporting-figure-panels/) 的单/双栏规格；排版合规与实验模型有效性分别检查。
+## 从界面直接生成图包
+
+完成“识别轨迹 → 评估”并检查实测叠加后，点击“导出图稿”。在同一个窗口选择保存位置、单栏 89 mm 或双栏 183 mm，以及 300 / 600 / 1200 dpi。尺寸示意仅表示纸面比例；不会为了预览重新拟合或改变观测数据。SVG/PDF 保留矢量文字，DPI 主要决定嵌入图像与 PNG/TIFF 的像素数。通常可先用 600 dpi，再按目标期刊和具体图件要求调整。
+
+输出写入新的图包子目录；已有目录不会被覆盖。后台导出期间可取消。完成后可打开图包中的 `index.html`，离线浏览实测图、annular q–χ 花瓣轨迹、各环 profile、历史曲率/像素峰诊断、独立径向 profile 与可用模型图，并访问对应图注、矢量文件和源数据。页面不依赖联网脚本或远程字体。
+
+图包同时提供 `radial_profile.csv`，保存主图径向剖面的分箱边界、q 中心、原始强度和、均值及有效像素数。空分箱的均值留空，像素数不表示独立重复实验数，也不作为误差棒或置信区间。
+
+`figure_qa.json` 核对导出配置并记录科学解释边界；它不逐个解析生成的图像或验证版面。配置检查通过不证明模型适用、结构参数可发表或所有标签均无重叠；投稿前仍应核对实际文件，并在最终版面尺寸下检查所有图件。Nature 各子刊要求可能不同，应以目标期刊的最新说明为准。
+
## Python
```python
@@ -69,7 +85,7 @@ bsaxs analyze frame.edf --poni geometry.poni --mask mask.npy `
--figure-width 183 --figure-dpi 600
```
-当配置未指定其他脊线方法时，图稿导出使用 `butterfly_curvature`；如果用户明确配置了另一种方法，导出请求会在分析前被拒绝。图稿尺寸选项独立于分析先验：默认的 `b/a` 先验仍由分析配置控制（当前默认范围为 `0.005–0.35`），固定栏宽、字体或分辨率不会改变拟合结果。
+图稿导出按 `current_result` 中实际记录的 `annular_peak`、`radial_sector` 或 `curvature` 方法生成对应章节；不会把一个方法的点重新解释成另一个方法的点。若从 CLI 新算结果，应显式选择目标方法。图稿尺寸选项独立于分析先验；annular 路径不会把 q 窗口外边界当成真实长轴尖端，用户明确给出的参数上下界仍按配置保留。
## 文件与解释
@@ -84,6 +100,8 @@ bsaxs analyze frame.edf --poni geometry.poni --mask mask.npy `
- `ellipse_curves.csv` / `ellipse_curves.npz`：源 `candidate_fit` 生成的曲线坐标、角度与来源支路标识；无可用候选时保存空曲线数组及 CSV 表头。
- `point_residuals.csv`：逐点保存实际 `projection_residual_q` / `normal_residual_q` 等字段；没有数据的字段留空。
- `normal_profiles.csv`：仅当输入结果包含可配对的 offset、raw 与 fit profile 时输出。诊断图若使用一个代表 profile，按“有效已接受点中 q 半径最接近中位数者”选取并写入设置，避免任意选择首条。
+- `annular_qchi.*`、`annular_profiles.*` 与对应 CSV/NPZ/caption/manifest：固定 q 环 `I(χ)`、最多四个实际角向峰、branch/family 轨迹支持和缺环状态。`q_annulus` 是采样坐标，不转换为 `2π/q`。
+- `sector_qchi.*`、`sector_profiles.*` 与对应 CSV/NPZ/caption/manifest：仅在结果含 `sector_peaks` 时生成，属于固定 χ `I(q)` 独立诊断。
- 若传入 `model`，另有 `model_comparison.svg/pdf/png/tiff`、`model_comparison_data.npz` 和 `model_comparison_caption.txt`。
- `source_data.npz`：原始 `observed`、`qx`、`qy`、调用方提供的选择 mask、完整有效像素 mask、数组自身的掩码、q 单位，以及径向分箱边缘、raw 强度和、raw 均值与计数。调用方的 `valid_mask` 可能已合并探测器、q 窗口、ROI 或其他分析域限制；导出器不把它称为探测器专用 mask。旧键 `valid_mask` 保留为兼容别名；新键 `supplied_valid_mask` 与 role 字段明确其来源；数组可用 `numpy.load(..., allow_pickle=False)` 读取。
- `ridge_points.csv`：逐点 q/像素坐标、来源标记、侧别、接受状态、是否绘出、未绘出的原因及完整源记录 JSON。
@@ -93,4 +111,6 @@ bsaxs analyze frame.edf --poni geometry.poni --mask mask.npy `
默认 `log1p` 变换仅用于主图显示，并保留负强度符号；原始阵列不会改写。颜色限值取显示区域有效像素变换后强度的 0.5 与 99.5 百分位，裁剪计数写入设置。辅助图 b 是以输入 q 坐标原点为中心的等宽径向分箱，显示未经强度变换的逐像素均值及每箱有效像素数；图中 `n` 表示每箱有效源像素数，纵轴使用有记录阈值的 symlog，原始有符号均值和各箱强度和均随 NPZ 导出。该曲线不是各向同性拟合，也不对像素面积或噪声进行额外加权。未知或像素 q 单位原样标在轴上，不据此换算层片周期。
+径向扇区图中的 FWHM 是 `I(q)` profile 峰宽，annular 图中的角向 FWHM 是 `I(χ)` 峰宽；bin 分辨率是采样限制，二者都不是置信区间。annular 的 q 环与角向分箱是预设采样坐标，不能把 q 环中心或角向峰自动换算为层片周期。Nature 尺寸、矢量文字和离线源数据包便于排版与复核，但图稿格式检查或导出成功本身不保证模型适用、结构参数可发表或科学验收。
+
版式采用固定单栏 89 mm 或双栏 183 mm，画板高度不超过 170 mm，正文 6.5 pt 无衬线字体，面板字母为粗体小写 8 pt。该导出是可审阅的图稿工件；目标期刊的最终规范、图注、实验判断与科学验收仍需独立核对。
diff --git a/docs/first_run_zh.md b/docs/first_run_zh.md
index a4ce5eb..6c236e4 100644
--- a/docs/first_run_zh.md
+++ b/docs/first_run_zh.md
@@ -67,13 +67,25 @@ bsaxs doctor --json
1. **打开图像**：确认帧和 HDF5/NPZ dataset 选择正确。
2. **加载 PONI**：只有物理 `q` 坐标建立后，间距和 reciprocal-space 尺度才可解释。`pixel-q` 仅用于算法检查或合成数据。
3. **设置 mask、ROI 和 q 范围**：先排除 beam stop、坏点、探测器缝隙和无效边界，再确定分析区间。
-4. **识别弧（Identify）**：在蝴蝶页提取观测弧、分支/象限标签和 ridge 点；这是几何测量，不是 full2d 强度拟合。
-5. **评估（Evaluate）**：在已识别弧上拟合镜像约束双椭圆，并查看占用边、flags 与质量诊断。贴在 `flat_ellipse` 边界上的解按仅环处理。
-6. **检查叠加与峰位**：核对实测图、观测轨迹、几何候选和（若已运行）full2d 椭圆；峰位表区分原始最亮点与受支持峰。
+4. **识别（Identify）**：新建会话默认在固定 q 环上计算角向 `I(χ)`（默认 40 个 q 环、72 个角度分箱），从每个环提取最多四个实际支持峰并沿 q 连接花瓣轨迹；旧项目缺少 `trace_method` 时仍按历史曲率脊线处理。这是观测测量，不是 `full2d` 强度拟合。
+5. **评估（Evaluate）**：在固定参考轴和对角 family 配对的观测轨迹上拟合镜像约束双椭圆，并查看缺环、占用边、flags 与质量诊断。拟合不能重新指派 individual petals；贴在先验边界上的解仍按候选限制或仅环处理。
+6. **检查叠加与峰位**：核对实测图、q 环 `I(χ)` profile、观测花瓣轨迹、几何候选和（若已运行）`full2d` 椭圆。每个环少于四个峰时保留实际支持，不补象限；缺环不桥接。固定 χ 的 `radial_sector` 只作为独立 `I(q)` 诊断，不能与 annular 主轨迹混用。
7. **可选 Preview / Optimize**：高级强度页的 Preview/Optimize 只服务经验 `full2d` 模型，不能代替 Identify → Evaluate，也不能当作科学验收。
8. **人工接受或拒绝**：具名 `Accept/Reject` 仅记录当前会话审核，不等于 P3/P4 科学证据门通过。
9. **导出图包或进入批处理**：跨帧比较必须保持 PONI、mask、q 范围、权重和配置一致。
+固定 q 环路径的原始角向强度定义为有效像素的 `sum / count`，并同时保存 count 和 coverage；本测量层不追加固角、偏振或探测器效率校正。每个 q 环最多四个实际支持峰，按参考轴固定为 QI+QIII 与 QII+QIV 两个对角 family；dominant 选择和至少连续 3 个 q 环的轨迹门槛用于阻止孤立噪声，少于四瓣或缺环都保留原状。`q_annulus` 是采样坐标，不是 `q*`，不能直接换算 `2π/q`。
+
+annular 路径不把 q 窗口外边界当成长轴真实尖端，已禁用共享 `observed_tip_constraint`，但保留用户明确给出的参数上下界。长轴不可辨识时标记限制状态，不强报 `a`、`Ln` 或 `L`。完整判据与 CLI 选项见[固定 q 环花瓣轨迹](annular_trajectories_zh.md)。
+
+固定 χ 的径向诊断见[径向扇区](sector_peaks_zh.md)：它默认使用 10° 扇区宽度、5° 步长，允许 profile-only、边界截断、低覆盖、歧义、热像素和宽峰诊断；FWHM 与 bin 分辨率不是置信区间。真实 frame110/120 当前显示的 points 与 4 条 arcs 只是当前分箱示例，不能写成最终验证数字或科学接受结论。
+
+页面上方的质量摘要集中显示当前阶段、工程质量、观测支持与结果限制。只有当前分析明确提供且单位有效的 `q*` 和环周期才显示数值；未标定或过期的结果不显示旧的物理周期。较长的参数状态和原因可把指针停留在表格单元格上查看。摘要中的“候选”和工程 `PASS` 都不等于科学验收。
+
+计算异常或取消会使旧测量失效；本次计算已返回但质量不通过的结果，仍保留为当前诊断，允许带失败标记导出。图稿导出失败不会改变已有测量质量。切换帧或设置后，已完成的旧图包会明确标为此前快照。
+
+图稿导出窗口把保存位置、栏宽和分辨率放在一起；完成后可打开离线图包查看图件、图注与源数据，详见[测量图导出](butterfly_figures_zh.md)。图稿统一采用显示有效域的 0.5–99.5% 颜色范围，这与工作台临时调整的显示百分位可能不同；原始数值不会因此改变。
+
右侧控制栏已改为可滚动布局；在 980×680 或笔记本屏幕上，底部 ROI、人工审核和快照控件仍可访问。
## 5. 结果解释边界
diff --git a/docs/sector_peaks_zh.md b/docs/sector_peaks_zh.md
new file mode 100644
index 0000000..9d7db4b
--- /dev/null
+++ b/docs/sector_peaks_zh.md
@@ -0,0 +1,78 @@
+# 固定 χ 径向扇区：独立 `I(q)` 诊断
+
+`radial_sector` 保留了“在一个方位角附近沿 q 方向看 profile”的测量，用来检查某个方向上的径向峰形、窗口截断和 q 位置稳定性。它是独立诊断路径，不是新 GUI 的主蝴蝶轨迹，也不替代默认的固定 q 环 `I(χ)` 花瓣轨迹；默认主路径见[固定 q 环花瓣轨迹](annular_trajectories_zh.md)。
+
+## 何时使用
+
+在 GUI 的识别方式中显式选择“扇区径向 `I(q)`”后，程序会在固定 χ 附近取一个有限角宽的扇区，将有效像素按 q 分箱，得到原始和平滑 profile。每个 profile 可以有受支持的径向峰，也可以只作为 profile-only 诊断保留。它适合检查：
+
+- 某个花瓣方向的径向峰是否真的有两侧回落；
+- q 窗口、mask 或探测器边界是否截断了峰；
+- 低 q 尾部、宽峰、双峰或热像素是否让“最强点”不可靠；
+- annular 主轨迹的某个 q 区间是否需要额外的方向性核对。
+
+径向诊断产生的 `q*` 不自动进入默认主椭圆输入，也不自动分配反射级次。若用户明确选择它，结果必须与 annular 或历史曲率结果分开保存和解释。
+
+## 计算定义
+
+对中心角 `χ₀`、完整角宽 `w` 和 q 分箱 `Bⱼ`，程序使用 PONI 产生的逐像素 q/χ 坐标，并只保留有效 mask、有限强度和当前 q 窗口内的像素：
+
+```text
+I_raw(qⱼ, χ₀) = sum(Iₚ) / count(Iₚ), p ∈ Bⱼ ∩ sector(χ₀, w)
+```
+
+原始 profile 的强度是有效像素的 `sum / count` 均值；`raw_sum`、`raw_count`、coverage 和几何覆盖也会保存。不同 q 分箱的像素数量不同，因此 `raw_sum` 不能直接当作强度比较。空分箱保持为空，不用零填充。
+
+这条测量层不额外施加探测器效率、固角、偏振或绝对强度校正，也不把输入强度重新变成 pyFAI 校正积分。输入文件已经完成的校正和单位仍随上下文记录；q 轴没有 PONI 时只能按 pixel-q 解释。
+
+## 角度设置与支持判据
+
+径向模式默认扇区完整角宽为 10°，中心角步长为 5°。相邻 profile 因扇区重叠而相关，不能视为独立重复实验。q 分箱受到局部 q 像素步长限制，`sampling_sigma_q` 和 `half_bin_resolution` 是采样/分箱分辨率指标，不是置信区间。
+
+程序不会强制每个角度都有 `q*`。候选峰需要有连续 q 支持、足够 coverage、相对于稳健原始 profile 基线的突出度和高度，并有可检查的两侧回落；还会检查有效贡献像素数和单个像素是否主导。常见的 profile-only 状态包括：
+
+- 峰贴近 q 窗口边界，左侧或右侧回落不可见；
+- mask、beam stop、探测器缝隙造成低覆盖或支持断裂；
+- 相近候选峰无法区分，结果保持歧义；
+- 一个热像素或极少数像素制造尖峰；
+- profile 只有低 q 尾部、负向起伏或不足以支持峰的对比度。
+
+连续支持足够时，宽峰可以保留；默认不会用窗口比例硬门槛把宽峰一概剔除。平滑曲线只服务定位和显示，原始均值、count、coverage 始终保留。没有峰的 profile 仍可在 GUI、CSV、NPZ 和离线图包中查看，不生成假 q 空间点。
+
+## q* 的解释边界
+
+径向模式的 `q*` 是该固定 χ profile 的观测峰位。它没有自动的反射级次；`2π/q*` 只有在单位、峰级次和物理模型另有证据时才可作相应长度解释。单独的径向 profile 不足以宣布一阶环、`Ln`、`Lz` 或长轴参数。
+
+径向 FWHM 描述 profile 峰形，`sampling_sigma_q`/bin 分辨率描述采样限制；二者都不是置信区间，不能直接替代重复测量或实验误差分析。工程状态、SNR 或图件导出成功也不等于科学验收。
+
+## GUI、CLI 与旧项目
+
+新 GUI 会话默认是 `annular_peak`。旧项目配方没有 `trace_method` 时仍按历史 `curvature` 解释；历史 `ridge_method=butterfly_curvature` 的分支、象限和 family 语义继续保留。要运行径向诊断，必须在 GUI 明确切换方法，或通过 CLI 显式指定：
+
+```powershell
+bsaxs analyze data/frame_0001.edf `
+ --poni geometry/detector.poni `
+ --mask masks/detector.npy `
+ --butterfly-stage trace `
+ --butterfly-trace-method radial_sector `
+ --sector-width 10 `
+ --sector-step 5 `
+ --butterfly-resamples 0 `
+ -o results/frame_0001_radial_diagnostic
+```
+
+`--butterfly-trace-method` 接受 `curvature`、`radial_sector` 和 `annular_peak`。显式指定它时 CLI 选择蝴蝶工作流；不要再传入其他 `--ridge-method`，除非该值也是 `butterfly_curvature`。径向参数是 `--sector-width` 和 `--sector-step`；固定 q 环主路径的参数则是 `--annular-rings` 和 `--annular-angles`。
+
+## 输出与人工检查
+
+结果保留每个角度的 q 边界/中心、原始均值、平滑均值、count、coverage、候选峰、支持状态和失败原因。选中的峰会记录 prominence、SNR、径向 FWHM、代表支持像素和采样分辨率；代表像素只是二维图定位锚点，`q*` 来自 profile 统计量，不是像素最大值。
+
+建议检查：
+
+1. 原始 profile 在峰两侧是否有真实回落；
+2. count/coverage 是否连续，是否被 q 边界或 mask 截断；
+3. 相邻 5° profile 的变化是否考虑了重叠相关性；
+4. 是否存在热像素、双峰歧义或低 q 尾部假峰；
+5. PONI、q_unit、mask、q 窗口和输入强度校正是否与实验记录一致。
+
+真实数据的窗口必须由目标峰和探测器覆盖决定。某一帧在 `q_max=0.5 nm^-1` 时出现的边界截断，不能推出所有帧都应使用 `0.8 nm^-1`；扩大窗口后也不能把不同窗口下的 SNR 直接比较。
diff --git a/docs/user_guide_zh.md b/docs/user_guide_zh.md
index 8f0eaa2..86ce8f2 100644
--- a/docs/user_guide_zh.md
+++ b/docs/user_guide_zh.md
@@ -242,6 +242,23 @@ PowerShell 中若使用通配符，建议加引号让 CLI 自己展开；CLI 也
--series hold_375C --range 60:120:2 --stream
```
+无人值守分析使用同一 `batch` 入口，加 `--unattended PACKAGE` 串联逐帧预检、逐环花瓣脊线识别、双椭圆候选评估、流式批次导出和检查点。`PACKAGE` 是原始数据包根目录，应包含所选图像、PONI 与 mask；输出必须在数据包外。首次运行指定新的输出目录，恢复时原命令加 `--resume`：
+
+```powershell
+.\.venv-project\Scripts\python.exe -m butterfly_saxs batch "data\package\images\*.edf" `
+ --unattended data\package --poni data\package\geometry\detector.poni `
+ --mask data\package\masks\detector.npy --manifest data\package\sequence.csv `
+ -o results\unattended_001 --mode independent
+
+# 中断或失败后：仅在输入、PONI、mask 与科学配置未改变时恢复；失败帧会重试。
+.\.venv-project\Scripts\python.exe -m butterfly_saxs batch "data\package\images\*.edf" `
+ --unattended data\package --poni data\package\geometry\detector.poni `
+ --mask data\package\masks\detector.npy --manifest data\package\sequence.csv `
+ -o results\unattended_001 --mode independent --resume
+```
+
+该模式缺省选择 `butterfly_curvature` 工作流、`annular_peak` 逐环提峰、`evaluate` 阶段与 0 次重采样；TOML 或显式 CLI 科学参数仍可覆盖具体追踪设置，但不能把无人值守工作流切换为非蝴蝶方法或仅 trace。`--full2d` 仍须显式指定，表示另做整幅像素强度拟合。可用 `-c project.toml` 固定 q 窗口等分析参数，`--preflight-context` 提供数据包背景。运行时预检只读取原始数据，将证据写入 `preflight/`；红灯阻止拟合并返回 2，黄灯继续保留批次证据但最终返回 1。`checkpoint.json`、CSV/JSONL、`results.npz` 与 `evolution.png` 写到输出目录；stdout 只列逐帧状态与证据路径，完整数值读导出文件。返回 0 只表示预检无警告且所有帧通过工程质量门，**不表示科学接受或发表许可**。
+
`manifest` 可用 CSV/JSON 提供 `path`、`frame_id`、`time`、`order`、`dataset`、零基 `frame`（或 `frame_index`）等元数据。manifest 文件中的相对 `path` 按 manifest 所在目录解析。它可以让同一个 HDF5/NPZ/TIFF 容器中的不同 dataset/frame 成为独立批处理记录；这些选择器会传给实际读取器并进入 checkpoint 身份。没有 manifest 时使用自然文件名排序。`checkpoint` 记录输入内容 hash、配置 hash、模式和每帧控制状态；`--resume` 只有 hash/mode 相符时才恢复。
配置 hash 还绑定 PONI、mask、valid-mask、sigma、weights 和 uncertainty 文件的当前 SHA-256 内容；文件被替换即使路径不变也会拒绝恢复。输入/校准/mask 源保持只读。
@@ -249,6 +266,8 @@ PowerShell 中若使用通配符，建议加引号让 CLI 自己展开；CLI 也
`--stream` 逐帧把 CSV、JSONL 和 NPZ 数组写入临时证据包，并释放已处理帧的 detector 数组；适合 1679×1475 或更大探测器的长序列。流式 checkpoint 仍只保存数组摘要。resume 会先验证上一轮 manifest、NPZ 元数据和声明的数组成员，再保留已恢复帧的原始数组，只替换实际重跑的帧；如果上一轮 bundle 没有可验证的 manifest/数组，会拒绝恢复。参数、ridge、lobe、椭圆和 flags 仍逐帧保留。取消请求会在当前帧结束后停止，并把 `cancelled`、`processed_count`、`elapsed_s` 与最后 checkpoint 写出。
+当椭圆的 `quantitative_parameters` 未给出全部可用的轴长与倾角时，批次参数表中由该椭圆推得的 `L_N`、`L_z` 和长轴周期的 `value` 留空；原始拟合数值仅写入带 `identifiability_status=undetermined` 的 `candidate_value`。径向反射环的独立周期字段不受这条椭圆门槛影响。
+
恢复只接受 checkpoint 中 `status=ok` 且质量检查通过的帧；失败、质量 FAIL 或不完整帧会在恢复时重新读取和拟合，这是预期的 failed-frame retry 行为。若所有选中帧都能从已验证 checkpoint 恢复，stream exporter 会走 no-op fast path，保留原 NPZ 成员而不重新压缩；这只优化 I/O，不把质量 WARN/FAIL 改写成 PASS。
Qt/service 批处理还支持 `stage = "geometry"`（或 `full2d = false`）只提取 observed ridge/lobe/椭圆；省略这两个字段时保持旧的 full2d 优化行为。geometry 阶段的 `parameters` 是实际测得的椭圆参数，full2d 强度参数保存在独立的 `intensity_parameters` 字段，不会覆盖用户的强度初值。流式导出额外写出 `lobe_measurements.csv`，其中每个观测 lobe 的角度、radial `q_star`、FWHM、SNR、面积、coverage、valid/reason 和 q 单位都是标量列；这张表不把 azimuthal annulus q 冒充 radial 峰。
diff --git a/pyproject.toml b/pyproject.toml
index b7cb760..848417d 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project]
name = "butterfly-saxs"
-version = "0.4.1"
+version = "0.4.2"
description = "Identify and parameterize butterfly-pattern 2D SAXS: first-order ring L, constrained double ellipses, and in-situ batch review"
readme = "README.md"
requires-python = ">=3.11,<3.14"
diff --git a/scripts/benchmark_sparse_ring.py b/scripts/benchmark_sparse_ring.py
new file mode 100644
index 0000000..4fbc591
--- /dev/null
+++ b/scripts/benchmark_sparse_ring.py
@@ -0,0 +1,222 @@
+"""Benchmark the sparse first-order sector kernel before and after packing.
+
+The benchmark uses a deterministic synthetic ring and an in-script copy of
+the pre-optimization sector scan. It measures the 16-sector peak kernel;
+point/arc bookkeeping and scientific acceptance are intentionally excluded.
+Results are evidence for engineering performance only.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import platform
+import sys
+import time
+from pathlib import Path
+
+import numpy as np
+
+from butterfly_saxs.butterfly_ridge import (
+ METHOD_VERSION,
+ _prepare_sparse_first_order_samples,
+ _sector_first_order_peak,
+)
+
+
+SECTORS = tuple(
+ 30.0 + quadrant + offset
+ for quadrant in (0.0, 90.0, 180.0, 270.0)
+ for offset in (30.0, 45.0, 60.0, 75.0)
+)
+
+
+def legacy_sector_first_order_peak(
+ qx: np.ndarray,
+ qy: np.ndarray,
+ q: np.ndarray,
+ intensity: np.ndarray,
+ valid: np.ndarray,
+ *,
+ sector_deg: float,
+ halfwidth_deg: float,
+ hint: float,
+) -> dict[str, float] | None:
+ """Reference sector scan corresponding to the pre-optimization path."""
+
+ if not (np.isfinite(hint) and hint > 0.0):
+ return None
+ ang = np.degrees(np.arctan2(qy, qx))
+ delta = np.abs(((ang - float(sector_deg) + 180.0) % 360.0) - 180.0)
+ q_lo, q_hi = 0.70 * hint, 1.45 * hint
+ selected = (
+ np.asarray(valid, dtype=bool)
+ & np.isfinite(q)
+ & np.isfinite(intensity)
+ & (delta <= float(halfwidth_deg))
+ & (q >= q_lo)
+ & (q <= q_hi)
+ )
+ if int(np.count_nonzero(selected)) < 12:
+ return None
+ radii = np.asarray(q[selected], dtype=float)
+ values = np.asarray(intensity[selected], dtype=float)
+ edges = np.linspace(q_lo, q_hi, 9)
+ profile = np.full(edges.size - 1, np.nan, dtype=float)
+ counts = np.zeros(edges.size - 1, dtype=int)
+ idx = np.digitize(radii, edges) - 1
+ for bin_i in range(edges.size - 1):
+ in_bin = idx == bin_i
+ counts[bin_i] = int(np.count_nonzero(in_bin))
+ if counts[bin_i] >= 2:
+ profile[bin_i] = float(np.nanmedian(values[in_bin]))
+ usable = np.isfinite(profile)
+ if int(np.count_nonzero(usable)) < 3:
+ return None
+ peak_i = int(np.nanargmax(np.where(usable, profile, -np.inf)))
+ peak = float(profile[peak_i])
+ baseline = float(np.nanmedian(profile[usable]))
+ if not (np.isfinite(peak) and np.isfinite(baseline) and baseline > 0 and peak >= 1.30 * baseline):
+ return None
+ q_star = float(0.5 * (edges[peak_i] + edges[peak_i + 1]))
+ in_bin = selected & (q >= edges[peak_i]) & (q < edges[peak_i + 1])
+ if int(np.count_nonzero(in_bin)) < 3:
+ in_bin = selected
+ median_qx = float(np.nanmedian(qx[in_bin]))
+ median_qy = float(np.nanmedian(qy[in_bin]))
+ if not (np.isfinite(median_qx) and np.isfinite(median_qy)):
+ return None
+ rows, cols = np.nonzero(in_bin)
+ nearest = int(np.argmin((qx[in_bin] - median_qx) ** 2 + (qy[in_bin] - median_qy) ** 2))
+ return {
+ "qx": median_qx,
+ "qy": median_qy,
+ "q_star": q_star,
+ "intensity": peak,
+ "contrast": peak / baseline,
+ "pixel_x": float(cols[nearest]),
+ "pixel_y": float(rows[nearest]),
+ "sector_deg": float(sector_deg),
+ }
+
+
+def _result_key(result: dict[str, float] | None) -> tuple[tuple[str, float], ...] | None:
+ if result is None:
+ return None
+ return tuple(sorted((key, float(value)) for key, value in result.items()))
+
+
+def _benchmark_data(size: int) -> tuple[np.ndarray, ...]:
+ axis = np.linspace(-1.0, 1.0, size)
+ qx, qy = np.meshgrid(axis, axis)
+ q = np.hypot(qx, qy)
+ valid = (q >= 0.49) & (q <= 0.51)
+ image = 0.2 + 4.0 * np.exp(-0.5 * ((q - 0.50) / 0.03) ** 2)
+ return qx, qy, q, image, valid
+
+
+def _time_call(callable_: object, repeats: int) -> float:
+ samples = []
+ for _ in range(repeats):
+ started = time.perf_counter()
+ callable_()
+ samples.append(time.perf_counter() - started)
+ return float(np.median(samples))
+
+
+def run_benchmark(*, size: int, rounds: int, repeats: int) -> dict[str, object]:
+ qx, qy, q, image, valid = _benchmark_data(size)
+ hint = 0.50
+
+ def legacy_sweep() -> tuple[dict[str, float] | None, ...]:
+ return tuple(
+ legacy_sector_first_order_peak(
+ qx, qy, q, image, valid, sector_deg=sector, halfwidth_deg=7.5, hint=hint
+ )
+ for sector in SECTORS
+ )
+
+ def optimized_sweep() -> tuple[dict[str, float] | None, ...]:
+ prepared = _prepare_sparse_first_order_samples(qx, qy, q, image, valid, hint=hint)
+ return tuple(
+ _sector_first_order_peak(
+ qx,
+ qy,
+ q,
+ image,
+ valid,
+ sector_deg=sector,
+ halfwidth_deg=7.5,
+ hint=hint,
+ prepared=prepared,
+ )
+ for sector in SECTORS
+ )
+
+ legacy_reference = tuple(map(_result_key, legacy_sweep()))
+ optimized_reference = tuple(map(_result_key, optimized_sweep()))
+ if legacy_reference != optimized_reference:
+ raise AssertionError("optimized sparse-ring sector results differ from the legacy oracle")
+
+ legacy_times: list[float] = []
+ optimized_times: list[float] = []
+ for round_index in range(rounds):
+ first, second = (legacy_sweep, optimized_sweep) if round_index % 2 == 0 else (optimized_sweep, legacy_sweep)
+ first_time = _time_call(first, repeats)
+ second_time = _time_call(second, repeats)
+ if first is legacy_sweep:
+ legacy_times.append(first_time)
+ optimized_times.append(second_time)
+ else:
+ optimized_times.append(first_time)
+ legacy_times.append(second_time)
+ legacy_median = float(np.median(legacy_times))
+ optimized_median = float(np.median(optimized_times))
+ return {
+ "schema_version": "sparse_ring_benchmark.v1",
+ "scope": "16-sector sparse first-order peak kernel; point/arc bookkeeping excluded",
+ "method_version": METHOD_VERSION,
+ "scientific_acceptance": False,
+ "python": sys.version,
+ "implementation": platform.python_implementation(),
+ "numpy": np.__version__,
+ "shape": list(q.shape),
+ "effective_pixels": int(np.count_nonzero(valid)),
+ "hint": hint,
+ "sector_count": len(SECTORS),
+ "rounds": rounds,
+ "repeats_per_round": repeats,
+ "legacy_times_s": legacy_times,
+ "optimized_times_s": optimized_times,
+ "legacy_median_s": legacy_median,
+ "optimized_median_s": optimized_median,
+ "speedup": legacy_median / optimized_median,
+ "input": "deterministic synthetic ring; no experimental acceptance claim",
+ }
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--size", type=int, default=1024)
+ parser.add_argument("--rounds", type=int, default=3)
+ parser.add_argument("--repeats", type=int, default=3)
+ parser.add_argument(
+ "--output",
+ type=Path,
+ default=Path("outputs/benchmarks/sparse_ring.json"),
+ )
+ parser.add_argument("--force", action="store_true")
+ args = parser.parse_args()
+ if args.size < 32 or args.rounds < 1 or args.repeats < 1:
+ parser.error("size must be >= 32 and rounds/repeats must be positive")
+ if args.output.exists() and not args.force:
+ parser.error(f"output exists; pass --force to overwrite: {args.output}")
+ report = run_benchmark(size=args.size, rounds=args.rounds, repeats=args.repeats)
+ args.output.parent.mkdir(parents=True, exist_ok=True)
+ args.output.write_text(json.dumps(report, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ print(json.dumps({"output": str(args.output), **report}, sort_keys=True))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/src/butterfly_saxs/__init__.py b/src/butterfly_saxs/__init__.py
index 6518fd2..c2ea14c 100644
--- a/src/butterfly_saxs/__init__.py
+++ b/src/butterfly_saxs/__init__.py
@@ -11,7 +11,7 @@
from importlib import import_module
from typing import Any
-__version__ = "0.4.1"
+__version__ = "0.4.2"
_LAZY_EXPORTS: dict[str, tuple[str, str]] = {
"PublicationStyle": (".publication_models", "PublicationStyle"),
diff --git a/src/butterfly_saxs/annular_peak_figures.py b/src/butterfly_saxs/annular_peak_figures.py
new file mode 100644
index 0000000..aca80bd
--- /dev/null
+++ b/src/butterfly_saxs/annular_peak_figures.py
@@ -0,0 +1,710 @@
+"""Publication assets for annulus-wise angular SAXS peak trajectories.
+
+The annular measurement is performed upstream. This module is intentionally
+only a renderer and evidence writer: it consumes ``result['annular_peaks']``
+and never re-integrates pixels, chooses a different peak, bridges a missing
+ring, or fits an ellipse. A point's ``q`` coordinate is the centre of its
+sampled q annulus. It is therefore not a radial ``q*`` and is never converted
+to ``2*pi/q`` here.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+import csv
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+import matplotlib as mpl
+from matplotlib.backends.backend_agg import FigureCanvasAgg
+from matplotlib.figure import Figure
+from matplotlib.lines import Line2D
+import numpy as np
+
+from .cancellation import raise_if_cancelled
+from .csv_utils import safe_csv_cell
+from .figure_support import _EXPORT_LOCK, _FIGURE_RC
+from .serialization import json_safe
+
+
+ANNULAR_FIGURE_METHOD_VERSION = "annular-peak-figures-v1"
+ANNULAR_FIGURE_SCHEMA_VERSION = "annular-peak-figure-export-v1"
+
+_COLORS = ("#0072B2", "#D55E00", "#009E73")
+_TARGET_Q = (0.25, 0.40, 0.60)
+
+
+def _finite(value: Any) -> float | None:
+ try:
+ number = float(value)
+ except (TypeError, ValueError, OverflowError):
+ return None
+ return number if np.isfinite(number) else None
+
+
+def _number(value: Any, default: float = float("nan")) -> float:
+ number = _finite(value)
+ return default if number is None else number
+
+
+def _csv_number(value: Any) -> str:
+ number = _finite(value)
+ return "" if number is None else format(number, ".17g")
+
+
+def _array(value: Any, *, dtype: Any = float) -> np.ndarray:
+ """Read a result array without changing the supplied result."""
+
+ if value is None:
+ return np.asarray([], dtype=dtype)
+ try:
+ values = value.tolist() if isinstance(value, np.ndarray) else value
+ if dtype is float:
+ return np.asarray(
+ [np.nan if item is None else float(item) for item in values],
+ dtype=np.float64,
+ )
+ return np.asarray(values, dtype=dtype)
+ except (TypeError, ValueError, OverflowError) as exc:
+ raise ValueError("annular result arrays must be one-dimensional numeric values") from exc
+
+
+def _mapping(value: Any, name: str) -> Mapping[str, Any]:
+ if not isinstance(value, Mapping):
+ raise TypeError(f"{name} must be a mapping")
+ return value
+
+
+def _payload(result: Mapping[str, Any]) -> Mapping[str, Any]:
+ """Accept either the annular mapping or a full page result."""
+
+ if not isinstance(result, Mapping):
+ raise TypeError("result must be a mapping")
+ nested = result.get("annular_peaks")
+ if isinstance(nested, Mapping):
+ return nested
+ return result
+
+
+def _angle_delta(left: float, right: float) -> float:
+ return abs((float(left) - float(right) + 180.0) % 360.0 - 180.0)
+
+
+def _normalise(result: Mapping[str, Any]) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+ """Normalize the already-measured annuli for rendering and tabulation."""
+
+ payload = _payload(result)
+ q_unit = str(payload.get("q_unit", "unknown") or "unknown")
+ q_edges = _array(payload.get("q_edges"), dtype=float)
+ angle_centers = _array(payload.get("angle_centers_deg"), dtype=float)
+ raw_annuli = payload.get("annuli", ())
+ if raw_annuli is None:
+ raw_annuli = ()
+ if isinstance(raw_annuli, (str, bytes)) or not isinstance(raw_annuli, Sequence):
+ raise TypeError("annular_peaks.annuli must be a sequence")
+ if angle_centers.size and not np.all(np.isfinite(angle_centers)):
+ raise ValueError("angle_centers_deg must contain finite values")
+
+ rows: list[dict[str, Any]] = []
+ for fallback_index, raw in enumerate(raw_annuli):
+ annulus = dict(_mapping(raw, f"annular_peaks.annuli[{fallback_index}]"))
+ index_value = annulus.get("annulus_index", fallback_index)
+ try:
+ annulus_index = int(index_value)
+ except (TypeError, ValueError, OverflowError) as exc:
+ raise ValueError("annulus_index must be an integer") from exc
+ angles = _array(annulus.get("angle_centers_deg"), dtype=float)
+ if angles.size == 0:
+ angles = angle_centers.copy()
+ if angles.size and not np.all(np.isfinite(angles)):
+ raise ValueError(f"annulus {annulus_index} angle centers must be finite")
+ raw_mapping = annulus.get("raw")
+ raw_mapping = raw_mapping if isinstance(raw_mapping, Mapping) else {}
+ arrays = {
+ "raw_mean": _array(annulus.get("raw_mean", raw_mapping.get("mean"))),
+ "raw_sum": _array(annulus.get("raw_sum", raw_mapping.get("sum"))),
+ "counts": _array(annulus.get("counts", raw_mapping.get("count")), dtype=np.int64),
+ "geometry_counts": _array(
+ annulus.get("geometry_counts", annulus.get("geometric_counts")),
+ dtype=np.int64,
+ ),
+ "coverage": _array(annulus.get("coverage")),
+ "smoothed_intensity": _array(annulus.get("smoothed_intensity")),
+ }
+ lengths = {key: len(value) for key, value in arrays.items() if len(value)}
+ if angles.size == 0 and lengths:
+ raise ValueError(f"annulus {annulus_index} needs angle_centers_deg")
+ if lengths and len(set(lengths.values())) != 1:
+ raise ValueError(f"annulus {annulus_index} arrays have inconsistent lengths: {lengths}")
+ length = len(angles)
+ if lengths and next(iter(lengths.values())) != length:
+ raise ValueError(f"annulus {annulus_index} arrays must match angle_centers_deg")
+ for key, values in tuple(arrays.items()):
+ if len(values) == 0 and length:
+ fill: Any = np.zeros(length, dtype=np.int64) if key in {"counts", "geometry_counts"} else np.full(length, np.nan)
+ arrays[key] = fill
+ selected = annulus.get("selected_peaks", ())
+ if selected is None:
+ selected = ()
+ if isinstance(selected, (str, bytes)) or not isinstance(selected, Sequence):
+ raise TypeError(f"annulus {annulus_index} selected_peaks must be a sequence")
+ selected_rows = [dict(_mapping(item, f"annulus {annulus_index} selected peak")) for item in selected]
+ if len(selected_rows) > 4:
+ raise ValueError(f"annulus {annulus_index} contains more than four selected peaks")
+ candidates = annulus.get("candidates", ())
+ if candidates is None:
+ candidates = ()
+ if isinstance(candidates, (str, bytes)) or not isinstance(candidates, Sequence):
+ raise TypeError(f"annulus {annulus_index} candidates must be a sequence")
+ candidate_rows = [dict(_mapping(item, f"annulus {annulus_index} candidate")) for item in candidates]
+ annulus.update(
+ {
+ "annulus_index": annulus_index,
+ "q_center": _number(annulus.get("q_center")),
+ "q_min": _number(annulus.get("q_min")),
+ "q_max": _number(annulus.get("q_max")),
+ "profile_id": str(annulus.get("profile_id", f"annulus-{annulus_index}")),
+ "angle_centers_deg": angles,
+ **arrays,
+ "selected_peaks": selected_rows,
+ "candidates": candidate_rows,
+ "status": str(annulus.get("status", "unknown")),
+ "reason": str(annulus.get("reason") or ""),
+ }
+ )
+ rows.append(annulus)
+ rows.sort(key=lambda row: row["annulus_index"])
+ if q_edges.size not in {0, len(rows) + 1}:
+ raise ValueError("q_edges must have one more value than annuli")
+ if q_edges.size and not np.all(np.isfinite(q_edges)):
+ raise ValueError("q_edges must contain finite values")
+ if angle_centers.size == 0 and rows:
+ angle_centers = np.asarray(rows[0]["angle_centers_deg"], dtype=float)
+ if angle_centers.size and any(len(row["angle_centers_deg"]) != len(angle_centers) for row in rows):
+ raise ValueError("all annuli must use the same angle-centre grid")
+ # The detector accumulator may use a conventional -180..180 grid while
+ # refined point angles are reported as 0..360. Canonicalize only the
+ # display grid and carry every profile array along with it. The source
+ # arrays remain untouched for CSV/NPZ auditability; ``_display_*`` fields
+ # are internal render-only views.
+ display_angles = np.mod(np.asarray(angle_centers, dtype=float), 360.0)
+ angle_order = np.argsort(display_angles, kind="stable") if display_angles.size else np.asarray([], dtype=int)
+ display_angles = display_angles[angle_order]
+ for row in rows:
+ source_angles = np.asarray(row["angle_centers_deg"], dtype=float)
+ source_display_angles = np.mod(source_angles, 360.0)
+ source_order = np.argsort(source_display_angles, kind="stable") if source_display_angles.size else np.asarray([], dtype=int)
+ for key in ("raw_mean", "raw_sum", "counts", "geometry_counts", "coverage", "smoothed_intensity"):
+ values = np.asarray(row[key])
+ if len(values) and len(source_order) == len(values):
+ row[f"_display_{key}"] = values[source_order]
+ else:
+ row[f"_display_{key}"] = values.copy()
+ row["_source_angle_centers_deg"] = source_angles.copy()
+ row["_display_angle_centers_deg"] = source_display_angles[source_order]
+ display_indices: list[int | None] = []
+ for peak in row["selected_peaks"]:
+ source_index = peak.get("angular_bin_index")
+ try:
+ source_index_int = int(source_index)
+ except (TypeError, ValueError, OverflowError):
+ source_index_int = -1
+ if 0 <= source_index_int < len(source_order):
+ display_index = int(np.flatnonzero(source_order == source_index_int)[0])
+ else:
+ chi = _finite(peak.get("chi_deg"))
+ if chi is None or not len(row["_display_angle_centers_deg"]):
+ display_index = None
+ else:
+ display_index = int(np.argmin([_angle_delta(value, chi) for value in row["_display_angle_centers_deg"]]))
+ display_indices.append(display_index)
+ row["_selected_display_indices"] = display_indices
+ payload_norm = {
+ "q_unit": q_unit,
+ "q_edges": q_edges,
+ "angle_centers_deg": np.asarray(angle_centers, dtype=float),
+ "display_angle_centers_deg": display_angles,
+ "settings": payload.get("settings") if isinstance(payload.get("settings"), Mapping) else {},
+ "method_version": payload.get("method_version"),
+ "q_window": payload.get("q_window"),
+ "sector_overlap": payload.get("sector_overlap"),
+ }
+ return payload_norm, rows
+
+
+def _intensity_unit(data: Mapping[str, Any]) -> tuple[str, str]:
+ context = data.get("context")
+ if isinstance(context, Mapping):
+ metadata = context.get("metadata")
+ if isinstance(metadata, Mapping):
+ header = metadata.get("header")
+ if isinstance(header, Mapping):
+ value = header.get("IntensityUnit")
+ if value is not None and str(value).strip():
+ return str(value).strip(), "context.metadata.header.IntensityUnit"
+ return "input intensity units", "fallback: caller-supplied intensity scale; no unit inferred"
+
+
+def _q_bounds(payload: Mapping[str, Any], rows: Sequence[Mapping[str, Any]]) -> tuple[float | None, float | None]:
+ edges = np.asarray(payload.get("q_edges", ()), dtype=float)
+ finite = edges[np.isfinite(edges)]
+ if finite.size:
+ return float(np.min(finite)), float(np.max(finite))
+ centers = np.asarray([_number(row.get("q_center")) for row in rows], dtype=float)
+ centers = centers[np.isfinite(centers)]
+ if centers.size:
+ return float(np.min(centers)), float(np.max(centers))
+ return None, None
+
+
+def _metadata(data: Mapping[str, Any], payload: Mapping[str, Any], rows: Sequence[Mapping[str, Any]]) -> dict[str, Any]:
+ intensity_unit, intensity_source = _intensity_unit(data)
+ q_min, q_max = _q_bounds(payload, rows)
+ settings = payload.get("settings") if isinstance(payload.get("settings"), Mapping) else {}
+ overlap = payload.get("sector_overlap") if isinstance(payload.get("sector_overlap"), Mapping) else {}
+ selected_count = sum(len(row["selected_peaks"]) for row in rows)
+ return {
+ "schema_version": ANNULAR_FIGURE_SCHEMA_VERSION,
+ "method_version": ANNULAR_FIGURE_METHOD_VERSION,
+ "source_measurement_method_version": payload.get("method_version"),
+ "q_unit": str(payload.get("q_unit", "unknown")),
+ "intensity_unit": intensity_unit,
+ "intensity_unit_source": intensity_source,
+ "q_range": [q_min, q_max] if q_min is not None and q_max is not None else None,
+ "settings": json_safe(settings),
+ "sector_overlap": json_safe(overlap),
+ "overlap_correlation_warning": str(overlap.get("correlation_statement", "overlapping q annuli may share detector pixels and are correlated; they are not independent samples")),
+ "annulus_count": len(rows),
+ "angle_bin_count": int(len(payload.get("angle_centers_deg", ()))),
+ "selected_peak_count": selected_count,
+ "max_selected_peaks_per_annulus": 4,
+ "q_coordinate_is_annulus_center": True,
+ "radial_q_star_not_used": True,
+ "spacing_conversion_not_performed": True,
+ "quadrants_are_not_synthesized": True,
+ "missing_bins_are_left_blank": True,
+ "smooth_is_locator_only": True,
+ "no_ellipse_fitted_or_drawn": True,
+ "candidate_selection_repeated_at_export": False,
+ }
+
+
+def _q_edges_for_rows(payload: Mapping[str, Any], rows: Sequence[Mapping[str, Any]]) -> np.ndarray:
+ provided = np.asarray(payload.get("q_edges", ()), dtype=float)
+ if len(provided) == len(rows) + 1 and np.all(np.isfinite(provided)):
+ return provided.copy()
+ centers = np.asarray([_number(row.get("q_center")) for row in rows], dtype=float)
+ if not len(rows):
+ return np.asarray([0.0, 1.0])
+ edges = np.full(len(rows) + 1, np.nan, dtype=float)
+ for index, row in enumerate(rows):
+ left = _finite(row.get("q_min"))
+ right = _finite(row.get("q_max"))
+ if left is not None:
+ edges[index] = left
+ if right is not None:
+ edges[index + 1] = right
+ finite_centers = np.isfinite(centers)
+ if np.any(finite_centers):
+ for index in range(len(edges)):
+ if np.isfinite(edges[index]):
+ continue
+ if index == 0:
+ edges[index] = centers[finite_centers][0]
+ elif index == len(edges) - 1:
+ edges[index] = centers[finite_centers][-1]
+ else:
+ edges[index] = np.nanmean(centers[max(0, index - 1): min(len(centers), index + 1)])
+ else:
+ edges = np.arange(len(rows) + 1, dtype=float)
+ return edges
+
+
+def _angle_edges(centers: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+ if centers.size == 0:
+ return np.asarray([0.0, 360.0]), np.asarray([], dtype=int)
+ order = np.argsort(centers)
+ sorted_centers = centers[order]
+ if sorted_centers.size == 1:
+ half = 1.0
+ return np.asarray([sorted_centers[0] - half, sorted_centers[0] + half]), order
+ gaps = np.diff(sorted_centers)
+ first_gap = float(gaps[0])
+ last_gap = float(gaps[-1])
+ edges = np.empty(sorted_centers.size + 1, dtype=float)
+ edges[1:-1] = 0.5 * (sorted_centers[:-1] + sorted_centers[1:])
+ edges[0] = sorted_centers[0] - 0.5 * first_gap
+ edges[-1] = sorted_centers[-1] + 0.5 * last_gap
+ return edges, order
+
+
+def _selected_intensity(peak: Mapping[str, Any]) -> float | None:
+ for key in ("raw_intensity", "intensity", "peak_intensity"):
+ value = _finite(peak.get(key))
+ if value is not None:
+ return value
+ return None
+
+
+def _build_qchi(payload: Mapping[str, Any], rows: Sequence[Mapping[str, Any]], metadata: Mapping[str, Any], *, width_mm: float, dpi: int) -> Figure:
+ height_mm = 108.0 if width_mm == 183.0 else 132.0
+ fig = Figure(figsize=(width_mm / 25.4, height_mm / 25.4), dpi=dpi, facecolor="white", edgecolor="white")
+ FigureCanvasAgg(fig)
+ if width_mm == 183.0:
+ ax = fig.add_axes([0.10, 0.20, 0.77, 0.64])
+ cax = fig.add_axes([0.90, 0.27, 0.018, 0.48])
+ footer_y = 0.055
+ else:
+ ax = fig.add_axes([0.17, 0.25, 0.67, 0.56])
+ cax = fig.add_axes([0.88, 0.34, 0.027, 0.38])
+ footer_y = 0.045
+ if not rows:
+ ax.text(0.5, 0.5, "No annular profiles supplied", transform=ax.transAxes, ha="center", va="center", fontsize=5.5, color="#555555")
+ ax.set_axis_off()
+ fig.suptitle("Raw annular I(q, χ) · no data", y=0.96, fontsize=7.0)
+ return fig
+ n_angles = max(len(row["_display_angle_centers_deg"]) for row in rows)
+ if n_angles == 0:
+ ax.text(0.5, 0.5, "No angular bins supplied", transform=ax.transAxes, ha="center", va="center", fontsize=5.5, color="#555555")
+ ax.set_axis_off()
+ return fig
+ matrix = np.full((len(rows), n_angles), np.nan, dtype=float)
+ for row_index, row in enumerate(rows):
+ values = np.asarray(row["_display_raw_mean"], dtype=float)
+ matrix[row_index, : len(values)] = values
+ q_edges = _q_edges_for_rows(payload, rows)
+ angles = np.asarray(payload.get("display_angle_centers_deg", rows[0]["_display_angle_centers_deg"]), dtype=float)
+ angle_edges, angle_order = _angle_edges(angles)
+ matrix = matrix[:, angle_order].T
+ masked = np.ma.masked_invalid(matrix)
+ finite = masked.compressed()
+ if finite.size:
+ low, high = np.nanpercentile(finite, [0.5, 99.5])
+ if not np.isfinite(low) or not np.isfinite(high) or high <= low:
+ low, high = float(np.nanmin(finite)), float(np.nanmax(finite))
+ if high <= low:
+ low, high = low - 0.5, high + 0.5
+ mesh = ax.pcolormesh(q_edges, angle_edges, masked, shading="auto", cmap="cividis", vmin=float(low), vmax=float(high), rasterized=True)
+ cbar = fig.colorbar(mesh, cax=cax)
+ cbar.set_label(f"raw mean I ({metadata['intensity_unit']})", fontsize=5.5, labelpad=2.0)
+ cbar.ax.tick_params(labelsize=5.0, length=1.2, width=0.4, pad=1.0)
+ for row in rows:
+ q_center = _finite(row.get("q_center"))
+ if q_center is None:
+ continue
+ for peak in row["selected_peaks"]:
+ chi = _finite(peak.get("chi_deg"))
+ if chi is not None:
+ ax.scatter([q_center], [float(np.mod(chi, 360.0))], s=15, marker="o", facecolors="none", edgecolors="#D55E00", linewidths=0.75, zorder=5)
+ ax.set_xlabel(f"q annulus centre ({metadata['q_unit']})")
+ ax.set_ylabel("Azimuth χ (degree)")
+ ax.set_title("Raw annular intensity I(q, χ) + observed angular maxima", fontsize=7.0)
+ ax.tick_params(direction="out", length=2.0, width=0.5, pad=1.5)
+ for spine in ax.spines.values():
+ spine.set_linewidth(0.5)
+ marker = Line2D([0], [0], marker="o", markerfacecolor="none", markeredgecolor="#D55E00", linestyle="None", markersize=3.0, label="observed angular maximum (≤4 per q annulus)")
+ # Keep the marker key below the title so it does not collide with the q
+ # xlabel or the two-line scientific boundary footer on the narrow panel.
+ fig.legend(handles=[marker], loc="upper center", bbox_to_anchor=(0.5, 0.925), frameon=False, fontsize=5.0, handletextpad=0.35)
+ footer = "Blank cells = missing measured angular support; no missing quadrant is synthesized.\nq is a sampled annulus coordinate; no 2π/q conversion or ellipse fit is applied."
+ fig.text(0.5, footer_y, footer, ha="center", va="center", fontsize=5.0, linespacing=1.25, color="#555555")
+ return fig
+
+
+def _representative_rows(rows: Sequence[Mapping[str, Any]]) -> tuple[list[Mapping[str, Any]], list[dict[str, Any]]]:
+ finite_rows = [row for row in rows if _finite(row.get("q_center")) is not None]
+ if not finite_rows:
+ return [], []
+ q_values = np.asarray([float(row["q_center"]) for row in finite_rows], dtype=float)
+ q_low, q_high = float(np.min(q_values)), float(np.max(q_values))
+ selected: list[Mapping[str, Any]] = []
+ info: list[dict[str, Any]] = []
+ used: set[int] = set()
+ for index, target in enumerate(_TARGET_Q):
+ in_range = q_low <= target <= q_high
+ effective = target if in_range else float(np.quantile(q_values, (0.2, 0.5, 0.8)[index]))
+ order = sorted(range(len(finite_rows)), key=lambda item: abs(q_values[item] - effective))
+ choice = next((item for item in order if item not in used), order[0])
+ used.add(choice)
+ selected.append(finite_rows[choice])
+ info.append({"requested_q": target, "effective_q": effective, "annulus_index": int(finite_rows[choice]["annulus_index"]), "selection": "target_q" if in_range else "effective_q_quantile"})
+ return selected, info
+
+
+def _build_profiles(payload: Mapping[str, Any], rows: Sequence[Mapping[str, Any]], metadata: Mapping[str, Any], *, width_mm: float, dpi: int) -> Figure:
+ height_mm = 120.0 if width_mm == 183.0 else 145.0
+ fig = Figure(figsize=(width_mm / 25.4, height_mm / 25.4), dpi=dpi, facecolor="white", edgecolor="white")
+ FigureCanvasAgg(fig)
+ reps, _ = _representative_rows(rows)
+ fig.suptitle("Representative annular I(χ) · raw mean + locator-only smooth" if width_mm == 183.0 else "Representative annular I(χ)\nraw mean + locator-only smooth", x=0.5, y=0.965, fontsize=7.0, linespacing=1.05)
+ legend_handles = [Line2D([0], [0], color="#555555", marker="o", markerfacecolor="none", linewidth=0.75, markersize=2.5, label="raw annular mean"), Line2D([0], [0], color="#555555", linestyle="--", linewidth=0.95, label="locator-only smooth")]
+ fig.legend(handles=legend_handles, loc="upper center", bbox_to_anchor=(0.5, 0.91), frameon=False, ncol=2, fontsize=5.0, handlelength=1.3, handletextpad=0.3, columnspacing=0.7)
+ if not reps:
+ ax = fig.add_axes([0.18, 0.24, 0.68, 0.52])
+ ax.text(0.5, 0.5, "No finite annular q centres supplied", transform=ax.transAxes, ha="center", va="center", fontsize=5.5, color="#555555")
+ ax.set_axis_off()
+ else:
+ left, right = (0.16, 0.89) if width_mm == 183.0 else (0.21, 0.86)
+ bottom = 0.14
+ top = 0.82
+ gap = 0.055
+ height = (top - bottom - gap * (len(reps) - 1)) / max(1, len(reps))
+ for index, row in enumerate(reps):
+ y = top - (index + 1) * height - index * gap
+ ax = fig.add_axes([left, y, right - left, height])
+ angles = np.asarray(row["_display_angle_centers_deg"], dtype=float)
+ raw = np.asarray(row["_display_raw_mean"], dtype=float)
+ smooth = np.asarray(row["_display_smoothed_intensity"], dtype=float)
+ color = _COLORS[index % len(_COLORS)]
+ finite_raw = np.isfinite(raw)
+ if finite_raw.any():
+ # Keep NaN bins in the plotted arrays so Matplotlib breaks the
+ # trace at an unsupported angular bin instead of connecting
+ # measurements across a masked gap.
+ ax.plot(angles, raw, color=color, linewidth=0.7, marker="o", markersize=1.4, markerfacecolor="none", label="raw annular mean")
+ finite_smooth = np.isfinite(smooth)
+ if finite_smooth.any():
+ ax.plot(angles, smooth, color=color, linewidth=1.0, linestyle="--", label="locator-only smooth")
+ peak_x: list[float] = []
+ peak_y: list[float] = []
+ for peak in row["selected_peaks"]:
+ chi = _finite(peak.get("chi_deg"))
+ intensity = _selected_intensity(peak)
+ if intensity is None and chi is not None and angles.size:
+ # A few measurement payloads carry the selected angle but
+ # omit its duplicate intensity. Read the supplied raw
+ # bin at that angle for display; this does not reselect a
+ # peak or alter the stored selected record.
+ nearest = int(np.argmin([_angle_delta(value, chi) for value in angles]))
+ if nearest < len(raw):
+ intensity = _finite(raw[nearest])
+ if chi is not None and intensity is not None:
+ peak_x.append(float(np.mod(chi, 360.0)))
+ peak_y.append(intensity)
+ if peak_x:
+ ax.scatter(peak_x, peak_y, s=17, marker="o", facecolors="white", edgecolors=color, linewidths=0.9, zorder=6)
+ q_min, q_max = _finite(row.get("q_min")), _finite(row.get("q_max"))
+ q_center = _finite(row.get("q_center"))
+ q_text = f"q annulus [{q_min:.4g}, {q_max:.4g}]" if q_min is not None and q_max is not None else f"q annulus centre {q_center:.4g}" if q_center is not None else "q annulus"
+ ax.set_title(f"{q_text} · {len(row['selected_peaks'])} observed angular maxima", fontsize=5.4, loc="left", pad=1.5, color=color)
+ ax.set_ylabel(f"I ({metadata['intensity_unit']})", fontsize=5.4)
+ if index == len(reps) - 1:
+ ax.set_xlabel("Azimuth χ (degree)", fontsize=5.4)
+ else:
+ ax.tick_params(labelbottom=False)
+ # The display convention is a full azimuthal turn even when the
+ # first/last bin centres sit half a bin inside 0 and 360 degrees.
+ ax.set_xlim(0.0, 360.0 if angles.size else 1.0)
+ ax.tick_params(direction="out", length=2.0, width=0.5, pad=1.3, labelsize=5.0)
+ ax.grid(axis="y", color="#dddddd", linewidth=0.3)
+ for spine in ax.spines.values():
+ spine.set_linewidth(0.5)
+ footer = (
+ "Raw I(χ) and locator-only smooth are copied from the result; markers = selected peaks.\n"
+ "q is an annulus coordinate; no 2π/q conversion or gap filling."
+ if width_mm == 89.0
+ else "Raw I(χ) and locator-only smoothing are copied from the supplied annular result; markers are supplied selected peaks.\n"
+ "q is an annulus coordinate, not radial q*; no missing peaks or quadrants are filled."
+ )
+ fig.text(0.5, 0.045, footer, ha="center", va="center", fontsize=5.0, linespacing=1.25, color="#555555")
+ return fig
+
+
+def _selected_for_angle(row: Mapping[str, Any], angle: float) -> list[Mapping[str, Any]]:
+ centers = np.asarray(row["_display_angle_centers_deg"], dtype=float)
+ if centers.size == 0:
+ return []
+ target_index = int(np.argmin([_angle_delta(value, angle) for value in centers]))
+ peaks = []
+ display_indices = row.get("_selected_display_indices", ())
+ for peak_index, peak in enumerate(row["selected_peaks"]):
+ if peak_index < len(display_indices) and display_indices[peak_index] is not None:
+ if int(display_indices[peak_index]) == target_index:
+ peaks.append(peak)
+ continue
+ chi = _finite(peak.get("chi_deg"))
+ if chi is not None:
+ nearest_index = int(np.argmin([_angle_delta(value, chi) for value in centers]))
+ if nearest_index == target_index:
+ peaks.append(peak)
+ return peaks
+
+
+def _selected_for_source_angle(row: Mapping[str, Any], angle: float) -> list[Mapping[str, Any]]:
+ """Associate supplied peaks with a source bin for the audit CSV."""
+
+ centers = np.asarray(row["_source_angle_centers_deg"], dtype=float)
+ if centers.size == 0:
+ return []
+ target_index = int(np.argmin([_angle_delta(value, angle) for value in centers]))
+ peaks = []
+ for peak in row["selected_peaks"]:
+ source_index = peak.get("angular_bin_index")
+ try:
+ source_index_int = int(source_index)
+ except (TypeError, ValueError, OverflowError):
+ source_index_int = -1
+ if 0 <= source_index_int < len(centers):
+ if source_index_int == target_index:
+ peaks.append(peak)
+ continue
+ chi = _finite(peak.get("chi_deg"))
+ if chi is not None:
+ nearest_index = int(np.argmin([_angle_delta(value, chi) for value in centers]))
+ if nearest_index == target_index:
+ peaks.append(peak)
+ return peaks
+
+
+_PROFILE_FIELDS = (
+ "record_type", "annulus_index", "profile_id", "q_unit", "intensity_unit", "q_min", "q_max", "q_center", "angle_index", "chi_deg", "raw_mean", "raw_sum", "counts", "geometry_counts", "coverage", "smoothed_intensity", "status", "reason", "selected", "selected_point_ids", "candidate_count", "candidate_json",
+)
+
+
+def _write_profiles_csv(path: Path, rows: Sequence[Mapping[str, Any]], metadata: Mapping[str, Any]) -> None:
+ with path.open("w", encoding="utf-8-sig", newline="") as stream:
+ writer = csv.DictWriter(stream, fieldnames=_PROFILE_FIELDS, extrasaction="ignore")
+ writer.writeheader()
+ for row in rows:
+ angles = np.asarray(row["_source_angle_centers_deg"], dtype=float)
+ for index, angle in enumerate(angles):
+ selected = _selected_for_source_angle(row, float(angle))
+ values = {
+ "record_type": "profile", "annulus_index": row["annulus_index"], "profile_id": row["profile_id"], "q_unit": metadata["q_unit"], "intensity_unit": metadata["intensity_unit"], "q_min": _csv_number(row.get("q_min")), "q_max": _csv_number(row.get("q_max")), "q_center": _csv_number(row.get("q_center")), "angle_index": index, "chi_deg": _csv_number(angle),
+ "raw_mean": _csv_number(row["raw_mean"][index]), "raw_sum": _csv_number(row["raw_sum"][index]), "counts": int(row["counts"][index]) if len(row["counts"]) > index else "", "geometry_counts": int(row["geometry_counts"][index]) if len(row["geometry_counts"]) > index else "", "coverage": _csv_number(row["coverage"][index]), "smoothed_intensity": _csv_number(row["smoothed_intensity"][index]), "status": row["status"], "reason": row["reason"], "selected": bool(selected), "selected_point_ids": json.dumps([str(peak.get("point_id", "")) for peak in selected], ensure_ascii=False), "candidate_count": len(row["candidates"]), "candidate_json": json.dumps(json_safe(row["candidates"]), ensure_ascii=False, sort_keys=True, allow_nan=False),
+ }
+ writer.writerow({key: safe_csv_cell(value) for key, value in values.items()})
+
+
+_PEAK_FIELDS = (
+ "record_type", "annulus_index", "profile_id", "q_unit", "intensity_unit", "q_min", "q_max", "q_center", "point_id", "trajectory_id", "chi_deg", "qx", "qy", "accepted", "status", "reason", "raw_intensity", "intensity", "prominence", "snr", "candidate_count", "selected_count", "candidate_json",
+)
+
+
+def _write_peaks_csv(path: Path, rows: Sequence[Mapping[str, Any]], metadata: Mapping[str, Any]) -> None:
+ with path.open("w", encoding="utf-8-sig", newline="") as stream:
+ writer = csv.DictWriter(stream, fieldnames=_PEAK_FIELDS, extrasaction="ignore")
+ writer.writeheader()
+ for row in rows:
+ base = {"annulus_index": row["annulus_index"], "profile_id": row["profile_id"], "q_unit": metadata["q_unit"], "intensity_unit": metadata["intensity_unit"], "q_min": _csv_number(row.get("q_min")), "q_max": _csv_number(row.get("q_max")), "q_center": _csv_number(row.get("q_center")), "candidate_count": len(row["candidates"]), "selected_count": len(row["selected_peaks"])}
+ for record_type, values in (("selected", row["selected_peaks"]), ("candidate", row["candidates"])):
+ for peak in values:
+ output = {**base, "record_type": record_type, "point_id": peak.get("point_id", ""), "trajectory_id": peak.get("trajectory_id", ""), "chi_deg": _csv_number(peak.get("chi_deg")), "qx": _csv_number(peak.get("qx")), "qy": _csv_number(peak.get("qy")), "accepted": peak.get("accepted", ""), "status": peak.get("status", row["status"]), "reason": peak.get("reason", row["reason"]), "raw_intensity": _csv_number(peak.get("raw_intensity")), "intensity": _csv_number(peak.get("intensity")), "prominence": _csv_number(peak.get("prominence")), "snr": _csv_number(peak.get("snr")), "candidate_json": json.dumps(json_safe(peak), ensure_ascii=False, sort_keys=True, allow_nan=False)}
+ writer.writerow({key: safe_csv_cell(value) for key, value in output.items()})
+
+
+def _write_npz(path: Path, payload: Mapping[str, Any], rows: Sequence[Mapping[str, Any]], metadata: Mapping[str, Any]) -> None:
+ n = len(rows)
+ m = max((len(row["angle_centers_deg"]) for row in rows), default=0)
+ def matrix(key: str, *, dtype: Any = float, fill: Any = np.nan) -> np.ndarray:
+ output = np.full((n, m), fill, dtype=dtype)
+ for index, row in enumerate(rows):
+ values = np.asarray(row[key], dtype=dtype)
+ output[index, : min(m, len(values))] = values[:m]
+ return output
+ np.savez_compressed(path, annulus_index=np.asarray([row["annulus_index"] for row in rows], dtype=np.int64), profile_id=np.asarray([str(row["profile_id"]) for row in rows], dtype="U128"), q_center=np.asarray([_number(row.get("q_center")) for row in rows], dtype=float), q_min=np.asarray([_number(row.get("q_min")) for row in rows], dtype=float), q_max=np.asarray([_number(row.get("q_max")) for row in rows], dtype=float), q_edges=np.asarray(payload.get("q_edges", ()), dtype=float), angle_centers_deg=np.asarray(payload.get("angle_centers_deg", ()), dtype=float), display_angle_centers_deg=np.asarray(payload.get("display_angle_centers_deg", ()), dtype=float), raw_mean=matrix("raw_mean"), raw_sum=matrix("raw_sum"), counts=matrix("counts", dtype=np.int64, fill=0), geometry_counts=matrix("geometry_counts", dtype=np.int64, fill=0), coverage=matrix("coverage"), smoothed_intensity=matrix("smoothed_intensity"), selected_peak_count=np.asarray([len(row["selected_peaks"]) for row in rows], dtype=np.int64), q_unit=np.asarray(str(metadata["q_unit"])), intensity_unit=np.asarray(str(metadata["intensity_unit"])), schema_version=np.asarray(ANNULAR_FIGURE_SCHEMA_VERSION))
+
+
+def _sha256(path: Path) -> str:
+ digest = hashlib.sha256()
+ with path.open("rb") as stream:
+ for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+ digest.update(chunk)
+ return digest.hexdigest()
+
+
+def _write_json(path: Path, payload: Any) -> None:
+ with path.open("w", encoding="utf-8", newline="\n") as stream:
+ json.dump(json_safe(payload), stream, ensure_ascii=False, indent=2, sort_keys=True, allow_nan=False)
+ stream.write("\n")
+
+
+def _caption(metadata: Mapping[str, Any], rows: Sequence[Mapping[str, Any]], representative_info: Sequence[Mapping[str, Any]]) -> str:
+ q_range = metadata.get("q_range")
+ q_text = f"[{q_range[0]:.6g}, {q_range[1]:.6g}] {metadata['q_unit']}" if q_range else f"unknown range in {metadata['q_unit']}"
+ selected = metadata["selected_peak_count"]
+ rep_text = ", ".join(f"{item['effective_q']:.5g} ({item['selection']})" for item in representative_info) or "none"
+ return (
+ "Annular angular-peak trajectory evidence. Each raw profile is the supplied arithmetic-mean I(χ) in one sampled q annulus; "
+ f"the q range is {q_text} and {len(rows)} annuli contribute {selected} supplied selected angular maxima. "
+ "The q–χ panel retains finite measured means and leaves missing support blank. At most four selected peaks per q annulus are drawn; "
+ "candidate lists and rejected annuli remain in the CSV/JSON evidence, and no missing peak or quadrant is synthesized. "
+ "The representative profiles use target q values 0.25, 0.40 and 0.60 when in range, otherwise the nearest effective q quantiles "
+ f"({rep_text}). Smoothing is locator-only and is copied from the supplied result. A peak q is the sampled annulus coordinate, not a radial q*; "
+ "no 2π/q spacing conversion, ellipse fit, or scientific acceptance is performed. Counts and coverage are support statistics, and overlapping annuli may be correlated. "
+ f"The source intensity scale is {metadata['intensity_unit']} ({metadata['intensity_unit_source']})."
+ )
+
+
+def render_annular_peak_figures(result: Mapping[str, Any], *, data: Mapping[str, Any] | None = None, width_mm: float = 183.0, dpi: int = 600) -> dict[str, Figure]:
+ if not isinstance(result, Mapping):
+ raise TypeError("result must be an annular_peaks mapping")
+ width = float(width_mm)
+ if width not in {89.0, 183.0}:
+ raise ValueError("width_mm must be 89 or 183")
+ if isinstance(dpi, bool) or int(dpi) != dpi or int(dpi) <= 0:
+ raise ValueError("dpi must be a positive integer")
+ payload, rows = _normalise(result)
+ metadata = _metadata(data or {}, payload, rows)
+ with _EXPORT_LOCK, mpl.rc_context(_FIGURE_RC):
+ figures = {"annular_qchi": _build_qchi(payload, rows, metadata, width_mm=width, dpi=int(dpi)), "annular_profiles": _build_profiles(payload, rows, metadata, width_mm=width, dpi=int(dpi))}
+ for figure in figures.values():
+ figure.canvas.draw()
+ return figures
+
+
+def export_annular_peak_figures(stage: str | Path, *, data: Mapping[str, Any], result: Mapping[str, Any], cancel_event: Any = None) -> tuple[dict[str, Path], dict[str, Any]]:
+ """Export annular assets into a caller-owned existing stage directory."""
+
+ raise_if_cancelled(cancel_event, "annular-peak-figures:validate")
+ stage_path = Path(stage).expanduser().resolve(strict=True)
+ if not stage_path.is_dir():
+ raise ValueError("stage must be an existing directory")
+ if not isinstance(data, Mapping) or not isinstance(result, Mapping):
+ raise TypeError("data and result must be mappings")
+ width = float(data.get("width_mm", 183.0))
+ dpi_raw = data.get("dpi", 600)
+ if width not in {89.0, 183.0}:
+ raise ValueError("data.width_mm must be 89 or 183")
+ if isinstance(dpi_raw, bool) or int(dpi_raw) != dpi_raw or int(dpi_raw) <= 0:
+ raise ValueError("data.dpi must be a positive integer")
+ dpi = int(dpi_raw)
+ payload, rows = _normalise(result)
+ metadata = _metadata(data, payload, rows)
+ _, representative_info = _representative_rows(rows)
+ outputs = {key: stage_path / name for key, name in {"annular_qchi_svg": "annular_qchi.svg", "annular_qchi_pdf": "annular_qchi.pdf", "annular_qchi_png": "annular_qchi.png", "annular_qchi_tiff": "annular_qchi.tiff", "annular_profiles_svg": "annular_profiles.svg", "annular_profiles_pdf": "annular_profiles.pdf", "annular_profiles_png": "annular_profiles.png", "annular_profiles_tiff": "annular_profiles.tiff", "annular_profiles_csv": "annular_profiles.csv", "annular_peaks_csv": "annular_peaks.csv", "annular_profiles_npz": "annular_profiles.npz", "annular_caption": "annular_caption.txt", "annular_manifest": "annular_manifest.json"}.items()}
+ existing = next((path for path in outputs.values() if path.exists()), None)
+ if existing is not None:
+ raise FileExistsError(f"annular figure output already exists in stage: {existing.name}")
+ # Keep the normalized rows for tabulation, but pass the caller's original
+ # result back through the renderer. ``payload`` intentionally contains
+ # only shared metadata and does not duplicate the annulus arrays.
+ figures = render_annular_peak_figures(result, data=data, width_mm=width, dpi=dpi)
+ try:
+ with _EXPORT_LOCK, mpl.rc_context(_FIGURE_RC):
+ for stem, figure in figures.items():
+ raise_if_cancelled(cancel_event, f"annular-peak-figures:render-{stem}")
+ for suffix, file_format in (("svg", "svg"), ("pdf", "pdf"), ("png", "png"), ("tiff", "tiff")):
+ raise_if_cancelled(cancel_event, f"annular-peak-figures:save-{stem}-{suffix}")
+ figure.savefig(outputs[f"{stem}_{suffix}"], format=file_format, dpi=dpi if suffix in {"png", "tiff"} else None, facecolor="white", transparent=False)
+ figure.clear()
+ finally:
+ for figure in figures.values():
+ figure.clear()
+ raise_if_cancelled(cancel_event, "annular-peak-figures:write-data")
+ _write_profiles_csv(outputs["annular_profiles_csv"], rows, metadata)
+ _write_peaks_csv(outputs["annular_peaks_csv"], rows, metadata)
+ _write_npz(outputs["annular_profiles_npz"], payload, rows, metadata)
+ outputs["annular_caption"].write_text(_caption(metadata, rows, representative_info) + "\n", encoding="utf-8", newline="\n")
+ for path in outputs.values():
+ if path.parent != stage_path:
+ raise RuntimeError("annular exporter attempted to write outside its caller-owned stage")
+ file_hashes = {path.name: _sha256(path) for key, path in outputs.items() if key != "annular_manifest"}
+ manifest = {**metadata, "width_mm": width, "dpi": dpi, "representative_profiles": json_safe(representative_info), "files": list(file_hashes), "sha256": file_hashes, "manifest_excluded_from_own_sha256": True, "caption_file": "annular_caption.txt", "profiles_csv_file": "annular_profiles.csv", "peaks_csv_file": "annular_peaks.csv", "profiles_npz_file": "annular_profiles.npz", "figure_files": ["annular_qchi.svg", "annular_qchi.pdf", "annular_qchi.png", "annular_qchi.tiff", "annular_profiles.svg", "annular_profiles.pdf", "annular_profiles.png", "annular_profiles.tiff"]}
+ _write_json(outputs["annular_manifest"], manifest)
+ return outputs, json_safe(manifest)
+
+
+__all__ = ["ANNULAR_FIGURE_METHOD_VERSION", "ANNULAR_FIGURE_SCHEMA_VERSION", "export_annular_peak_figures", "render_annular_peak_figures"]
diff --git a/src/butterfly_saxs/annular_trace.py b/src/butterfly_saxs/annular_trace.py
new file mode 100644
index 0000000..f20eef5
--- /dev/null
+++ b/src/butterfly_saxs/annular_trace.py
@@ -0,0 +1,236 @@
+"""Track observed azimuthal maxima outwards through calibrated q annuli.
+
+The rings are prescribed sampling coordinates, not radial reflection peaks.
+No fitted ellipse selects the points and missing lobes remain missing.
+"""
+from __future__ import annotations
+
+from collections import defaultdict
+import math
+import time
+from typing import Any
+
+import numpy as np
+
+from .arc_support import freeze_observed_support
+from .butterfly_ridge import (
+ _apply_edits, _apply_seeds, _arc_topology, _assign_reference_branches,
+ _normalise_options, _parse_q_window, _point_signature, _public_point,
+ _refresh_arc_identity,
+)
+from .cancellation import raise_if_cancelled
+from .ridge_inputs import canonical_inputs
+from .sector_peaks import _local_representative_q_step
+from .settings import strict_int
+
+METHOD_VERSION = "butterfly-annular-trajectory-v1.0"
+
+
+def _select_and_connect(points, *, angle_step_deg, min_track_points=3):
+ """One supported, unambiguous peak per observed quadrant and annulus.
+
+ Ambiguous competitors remain visible as rejected candidates. Chains join
+ only consecutive annuli with a bounded angular displacement, so neither
+ masks nor a missing ring are silently bridged.
+ """
+ choices = defaultdict(list)
+ for i, point in enumerate(points):
+ if point["accepted"] and point["branch_id"] in (0, 1):
+ choices[(point["annulus_index"], point["quadrant"])].append(i)
+ elif point["accepted"]:
+ point.update(accepted=False, valid=False, reason="reference_axis_or_streak_region")
+ chosen = {}
+ for key, indices in choices.items():
+ ordered = sorted(indices, key=lambda i: points[i]["prominence"], reverse=True)
+ ambiguous = len(ordered) > 1 and points[ordered[0]]["prominence"] < 1.35 * points[ordered[1]]["prominence"]
+ for rank, index in enumerate(ordered):
+ point = points[index]
+ point["candidate_rank_in_quadrant"] = rank + 1
+ if ambiguous or rank:
+ point.update(accepted=False, valid=False,
+ reason="ambiguous_angular_peaks" if ambiguous else "weaker_angular_competitor")
+ else:
+ chosen[key] = index
+ groups, edges, used = [], [], set()
+ for key, start in sorted(chosen.items()):
+ if start in used:
+ continue
+ component = [start]
+ used.add(start)
+ ring, quadrant = key
+ while (ring + 1, quadrant) in chosen:
+ next_index = chosen[(ring + 1, quadrant)]
+ a, b = points[component[-1]], points[next_index]
+ angular_step = abs((b["chi_deg"] - a["chi_deg"] + 180) % 360 - 180)
+ if angular_step > 2.5 * angle_step_deg:
+ b["topology_flags"].append("angular_track_jump")
+ break
+ edges.append((component[-1], next_index))
+ component.append(next_index)
+ used.add(next_index)
+ ring += 1
+ track_id = len(groups)
+ for index in component:
+ point = points[index]
+ point["trajectory_id"] = track_id
+ if len(component) < min_track_points:
+ point.update(accepted=False, valid=False, reason="short_annular_track")
+ for offset, index in enumerate(component):
+ left = points[component[max(0, offset - 1)]]
+ right = points[component[min(len(component) - 1, offset + 1)]]
+ dx, dy = right["qx"] - left["qx"], right["qy"] - left["qy"]
+ norm = math.hypot(dx, dy)
+ if norm:
+ points[index].update(tangent_qx=dx / norm, tangent_qy=dy / norm)
+ groups.append(component)
+ return groups, edges
+
+
+def trace_butterfly_annuli(image, qmap, q_window, *, mask=None, reference_axis_deg=0.,
+ options=None, edits=None, cancel_event=None) -> dict[str, Any]:
+ from .observables import _azimuthal_peak_ridges, _q_unit
+
+ started = time.perf_counter()
+ data, qx, qy, q, invalid = canonical_inputs(image, qmap, mask=mask)
+ window = _parse_q_window(q_window, q)
+ options = dict(options or {})
+ edits = list(options.get("edits", []) if edits is None else edits)
+ finite = np.isfinite(qx) & np.isfinite(qy) & np.isfinite(q)
+ geometry = finite & (q >= window[0]) & (q <= window[1])
+ valid, applied, seeds = _apply_edits(geometry & ~invalid & np.isfinite(data), qx, qy, edits)
+ step, step_source, step_details = _local_representative_q_step(
+ qx, qy, q, finite, *window, q_is_supplied=True)
+ requested = strict_int(options.get("annular_radial_bins", 40), "annular_radial_bins", minimum=4)
+ requested_angles = strict_int(options.get("annular_angle_bins", 72), "annular_angle_bins", minimum=16)
+ angle_bins = requested_angles
+ if step and np.any(valid):
+ smallest_radius = float(np.min(q[valid]))
+ angular_pixel_step = math.degrees(math.atan2(step, smallest_radius))
+ angle_bins = min(requested_angles, int(math.floor(360 / angular_pixel_step)))
+ if angle_bins < 16:
+ raise ValueError("q domain is too close to the origin for resolved angular profiles")
+ n_annuli = min(requested, max(1, int((window[1] - window[0]) / step))) if step else requested
+ if n_annuli < 4:
+ raise ValueError("q window is too narrow to resolve at least four annuli; widen the analysis window")
+ accumulator = {}
+ measured, *_ = _azimuthal_peak_ridges(
+ data, qmap, window, mask=~valid, n_annuli=n_annuli, n_angle_bins=angle_bins,
+ snr_threshold=float(options.get("annular_snr_threshold", 3.)),
+ min_peak_fraction=float(options.get("annular_min_peak_fraction", .2)),
+ min_coverage=float(options.get("annular_min_coverage", .5)),
+ min_bin_count=2, diagnostics=accumulator, cancel_event=cancel_event,
+ )
+ signature = _point_signature(data, {**options, "trace_method": "annular_peak"}, window)
+ excluded = {edit.get("point_id") for edit in edits if edit.get("type") == "exclude_point"}
+ unit = _q_unit(qmap)
+ edges_q = np.asarray(accumulator["q_edges"])
+ centers_q = np.asarray(accumulator["q_centers"])
+ angle_order = np.argsort(np.asarray(accumulator["angle_centers_deg"]) % 360)
+ display_bin = np.argsort(angle_order)
+ angles_deg = (np.asarray(accumulator["angle_centers_deg"]) % 360)[angle_order]
+ dq = float(edges_q[1] - edges_q[0])
+ angle_step = 360. / angle_bins
+ points = []
+ for source in measured:
+ raise_if_cancelled(cancel_event, "annular-trace:points")
+ ring = int(source.metadata["annulus_index"])
+ point_id = f"annular-{signature}-{ring:03d}-{source.metadata['angular_bin_index']:03d}"
+ radius, chi = float(source.q), float(source.angle)
+ accepted = point_id not in excluded
+ points.append({
+ "point_id": point_id, "profile_id": f"annulus-{signature}-{ring:03d}",
+ "annulus_index": ring, "angular_bin_index": int(source.metadata["angular_bin_index"]),
+ "q_annulus": radius, "chi_deg": math.degrees(chi) % 360,
+ "qx": radius * math.cos(chi), "qy": radius * math.sin(chi),
+ "pixel_x": source.metadata["pixel_x"], "pixel_y": source.metadata["pixel_y"],
+ "source_pixel_role": "representative supporting pixel; peak angle comes from annular I(chi)",
+ "source_method": "annular_peak", "q_unit": unit,
+ "intensity": source.metadata.get("raw_intensity", source.intensity),
+ "snr": float(source.snr), "prominence": float(source.metadata["prominence"]),
+ "azimuthal_fwhm_deg": math.degrees(source.azimuthal_fwhm),
+ "n_pixels": source.n_pixels, "coverage": source.metadata["angular_bin_coverage"],
+ "normal_qx": -math.sin(chi), "normal_qy": math.cos(chi),
+ "normal_basis": "azimuthal scan direction, not necessarily the intensity ridge normal",
+ "tangent_qx": math.cos(chi), "tangent_qy": math.sin(chi),
+ "q_normal_step": radius * math.radians(angle_step),
+ "sampling_sigma_q": radius * math.radians(angle_step) / math.sqrt(12),
+ "uncertainty_source": "angular bin resolution, not a confidence interval",
+ "normal_fwhm_q": float("nan"), "localization_sigma_q": float("nan"),
+ "radial_bin_width": dq, "scale": 1., "branch_id": -1, "side": "unknown", "arc_id": -1,
+ "accepted": accepted, "valid": accepted,
+ "reason": "accepted_annular_peak" if accepted else "excluded_point_edit",
+ "score": float(source.score), "trajectory_id": None,
+ "topology_flags": ["annular_angular_maximum", "prescribed_q_not_radial_peak"],
+ })
+ topology = _normalise_options(options)
+ topology.update(reference_axis_deg=float(reference_axis_deg), min_arc_points=3)
+ _assign_reference_branches(points, topology)
+ groups, graph_edges = _select_and_connect(points, angle_step_deg=angle_step)
+ arcs = _arc_topology(groups, graph_edges, points, topology, dq)
+ seed_records = _apply_seeds(points, arcs, seeds, topology, dq)
+ _refresh_arc_identity(arcs, points)
+ for item in [*points, *arcs]:
+ item.pop("scale", None)
+ item.update(scale_stability=float("nan"), scale_stable=False, source_method="annular_peak")
+ profiles, annuli = {}, []
+ for index, radius in enumerate(centers_q):
+ profile_id = f"annulus-{signature}-{index:03d}"
+ selected = [p for p in points if p["annulus_index"] == index and p["accepted"]]
+ candidates = accumulator["annuli"][index]["candidates"]
+ by_bin = {p["angular_bin_index"]: p for p in points if p["annulus_index"] == index}
+ for candidate in candidates:
+ point = by_bin.get(candidate.get("angular_bin_index"))
+ candidate["trace_accepted"] = bool(point and point["accepted"])
+ candidate["trace_reason"] = point["reason"] if point else candidate["reason"]
+ candidate["point_id"] = point["point_id"] if point else None
+ candidate["source_angular_bin_index"] = candidate["angular_bin_index"]
+ candidate["angular_bin_index"] = int(display_bin[candidate["angular_bin_index"]])
+ candidate["chi_deg"] = float(candidate["chi_deg"]) % 360
+ for point in by_bin.values():
+ point["source_angular_bin_index"] = point["angular_bin_index"]
+ point["angular_bin_index"] = int(display_bin[point["angular_bin_index"]])
+ row = {
+ "annulus_index": index, "profile_id": profile_id, "point_id": profile_id,
+ "q_center": float(radius), "q_min": float(edges_q[index]), "q_max": float(edges_q[index + 1]),
+ "raw_mean": accumulator["raw_mean"][index][angle_order], "raw_sum": accumulator["raw_sum"][index][angle_order],
+ "counts": accumulator["counts"][index][angle_order], "geometry_counts": accumulator["geometry_counts"][index][angle_order],
+ "coverage": accumulator["coverage"][index][angle_order], "smoothed_intensity": accumulator["smoothed"][index][angle_order],
+ "candidates": candidates, "selected_peaks": [_public_point(p) for p in selected],
+ "status": "tracked" if selected else "no_tracked_peak",
+ "reason": "four_observed_lobes" if len(selected) == 4 else "partial_or_missing_lobe_support",
+ "profile_only": True, "source_method": "annular_peak",
+ }
+ annuli.append(row)
+ profiles[profile_id] = {
+ "profile_axis": "azimuthal", "angle_deg": angles_deg,
+ "raw_intensity": row["raw_mean"], "smoothed_intensity": row["smoothed_intensity"],
+ "counts": row["counts"], "coverage": row["coverage"],
+ "peak_angles_deg": [p["chi_deg"] for p in selected], "q_center": row["q_center"],
+ "q_min": row["q_min"], "q_max": row["q_max"], "q_unit": unit, "reason": row["reason"],
+ }
+ support = freeze_observed_support(points, arcs, summary_only=True, cancel_event=cancel_event)
+ settings = {"requested_radial_bins": requested, "effective_radial_bins": n_annuli,
+ "requested_angle_bins": requested_angles, "angle_bins": angle_bins,
+ "q_bin_width": dq, "angle_bin_width_deg": angle_step,
+ "minimum_track_rings": 3, "competing_peak_ratio": 1.35,
+ "maximum_track_angle_jump_deg": 2.5 * angle_step,
+ "q_step": step, "q_step_source": step_source, "q_step_details": step_details,
+ **accumulator.get("settings", {})}
+ return {
+ "method_version": METHOD_VERSION, "q_unit": unit,
+ "branch_pairing": {"reference_axis_deg": reference_axis_deg,
+ "families": {"0": ["QI", "QIII"], "1": ["QII", "QIV"]},
+ "memberships_frozen_before_fit": True},
+ "points": [_public_point(p) for p in points], "arcs": arcs, "profiles": profiles,
+ "annular_peaks": {"method_version": METHOD_VERSION, "q_unit": unit, "q_window": list(window),
+ "q_edges": edges_q, "angle_centers_deg": angles_deg,
+ "settings": settings, "annuli": annuli},
+ "diagnostics": {"method": "fixed_q_annulus_angular_peak_trajectory", "q_window": list(window),
+ "reference_axis_deg": reference_axis_deg, "n_annuli": n_annuli,
+ "n_points": len(points), "n_accepted_points": sum(p["accepted"] for p in points),
+ "n_arcs": len(arcs), "n_raw_candidates": sum(len(r["candidates"]) for r in annuli),
+ "observed_support": support, "applied_edits": applied, "seed_actions": seed_records,
+ "first_order_q_hint": {"selection_status": "not_used", "q_star": None,
+ "reason": "annuli_are_sampling_coordinates_not_radial_peaks"},
+ "elapsed_s": time.perf_counter() - started},
+ }
diff --git a/src/butterfly_saxs/arc_geometry.py b/src/butterfly_saxs/arc_geometry.py
index 551cc4c..8c3bf10 100644
--- a/src/butterfly_saxs/arc_geometry.py
+++ b/src/butterfly_saxs/arc_geometry.py
@@ -601,6 +601,7 @@ def _project_ellipse_arc(
endpoint_left = (a * np.cos(t_min) - u) ** 2 + (b * np.sin(t_min) - v) ** 2
endpoint_right = (a * np.cos(t_max) - u) ** 2 + (b * np.sin(t_max) - v) ** 2
+ active = np.ones(t.shape, dtype=bool)
for _ in range(16):
sine_t = np.sin(t)
cosine_t = np.cos(t)
@@ -612,10 +613,11 @@ def _project_ellipse_arc(
candidate_squared = (a * np.cos(candidate) - u) ** 2 + (b * np.sin(candidate) - v) ** 2
improve = np.isfinite(candidate_squared) & (candidate_squared <= current)
new_t = np.where(improve, candidate, t)
- if np.all(np.abs(new_t - t) <= 1.0e-13):
- t = new_t
+ converged = active & (np.abs(new_t - t) <= 1.0e-13)
+ t = np.where(active, new_t, t)
+ active &= ~converged
+ if not np.any(active):
break
- t = new_t
squared_refined = (a * np.cos(t) - u) ** 2 + (b * np.sin(t) - v) ** 2
choose_left = endpoint_left < squared_refined
@@ -648,6 +650,15 @@ def _side_domain(side: str) -> tuple[float, float]:
return (0.0, math.pi) if side == "upper" else (math.pi, _TAU)
+def _projection_domain(
+ side: str,
+ manual_intervals: Sequence[tuple[float, float]] | None,
+) -> list[tuple[float, float]]:
+ if manual_intervals is None:
+ return [_side_domain(side)]
+ return list(manual_intervals) if manual_intervals else []
+
+
def _ellipse_linear_coefficients(
geometry: EllipseGeometry,
tangent: np.ndarray,
@@ -900,41 +911,42 @@ def _project_point_to_support(
rectangles: Sequence[Mapping[str, Any]],
*,
include_global_oracle: bool = False,
+ precomputed_unconstrained: Sequence[Mapping[str, Any]] | None = None,
) -> dict[str, Any]:
- domain = list(manual_intervals) if manual_intervals is not None else [ _side_domain(side) ]
- if manual_intervals is not None and not manual_intervals:
- domain = []
+ domain = _projection_domain(side, manual_intervals)
candidates: list[dict[str, Any]] = []
local_candidates: list[tuple[float, float, dict[str, Any]]] = []
- unconstrained: list[dict[str, Any]] = []
- point_array = np.asarray([point], dtype=float)
- local_u, local_v = _local_coordinates(point_array, geometry) if domain else (None, None)
+ unconstrained: list[dict[str, Any]] = list(precomputed_unconstrained or ())
+ local_u, local_v = None, None
+ if domain and precomputed_unconstrained is None:
+ local_u, local_v = _local_coordinates(np.asarray([point], dtype=float), geometry)
if rectangles:
# Fast path for the common case: the unconstrained closest point in a
# manual/side domain already lies inside an observed rectangle. A
# point that is feasible for the global domain is necessarily the
# constrained optimum, so no sinusoid boundary enumeration is needed.
- u, v = local_u, local_v
- for domain_index, (domain_lo, domain_hi) in enumerate(domain):
- raw_projection = _project_ellipse_arc(
- u,
- v,
- geometry.a,
- geometry.b,
- np.asarray([domain_lo]),
- np.asarray([domain_hi]),
- include_global_oracle=include_global_oracle,
- )
- unconstrained.append(
- {
- "t": float(raw_projection["t"][0]),
- "distance": float(raw_projection["distance"][0]),
- "global_distance": float(raw_projection["global_distance"][0]),
- "at_endpoint": bool(raw_projection["at_endpoint"][0]),
- "endpoint_clipped": bool(raw_projection["endpoint_clipped"][0]),
- "domain_index": domain_index,
- }
- )
+ if precomputed_unconstrained is None:
+ u, v = local_u, local_v
+ for domain_index, (domain_lo, domain_hi) in enumerate(domain):
+ raw_projection = _project_ellipse_arc(
+ u,
+ v,
+ geometry.a,
+ geometry.b,
+ np.asarray([domain_lo]),
+ np.asarray([domain_hi]),
+ include_global_oracle=include_global_oracle,
+ )
+ unconstrained.append(
+ {
+ "t": float(raw_projection["t"][0]),
+ "distance": float(raw_projection["distance"][0]),
+ "global_distance": float(raw_projection["global_distance"][0]),
+ "at_endpoint": bool(raw_projection["at_endpoint"][0]),
+ "endpoint_clipped": bool(raw_projection["endpoint_clipped"][0]),
+ "domain_index": domain_index,
+ }
+ )
scale = max(1.0, abs(geometry.a), abs(geometry.b))
reachable = [
rectangle
@@ -980,28 +992,46 @@ def _project_point_to_support(
},
)
)
- for lo, hi, metadata in local_candidates:
- # The helper above works in a branch-local frame. Convert the observed
- # q point to that frame before evaluating it.
- projection = _project_ellipse_arc(
- local_u,
- local_v,
- geometry.a,
- geometry.b,
- np.asarray([lo]),
- np.asarray([hi]),
- include_global_oracle=include_global_oracle,
- )
- candidates.append(
- {
- "t": float(projection["t"][0]),
- "distance": float(projection["distance"][0]),
- "global_distance": float(projection["global_distance"][0]),
- "at_endpoint": bool(projection["at_endpoint"][0]),
- "endpoint_clipped": bool(projection["endpoint_clipped"][0]),
- "metadata": metadata,
+ if local_candidates:
+ if precomputed_unconstrained is None:
+ for lo, hi, metadata in local_candidates:
+ # The helper above works in a branch-local frame. Convert the observed
+ # q point to that frame before evaluating it.
+ projection = _project_ellipse_arc(
+ local_u,
+ local_v,
+ geometry.a,
+ geometry.b,
+ np.asarray([lo]),
+ np.asarray([hi]),
+ include_global_oracle=include_global_oracle,
+ )
+ candidates.append(
+ {
+ "t": float(projection["t"][0]),
+ "distance": float(projection["distance"][0]),
+ "global_distance": float(projection["global_distance"][0]),
+ "at_endpoint": bool(projection["at_endpoint"][0]),
+ "endpoint_clipped": bool(projection["endpoint_clipped"][0]),
+ "metadata": metadata,
+ }
+ )
+ else:
+ metadata_by_index = {
+ index: metadata for index, (_, _, metadata) in enumerate(local_candidates)
}
- )
+ for projection in unconstrained:
+ metadata = metadata_by_index[int(projection["domain_index"])]
+ candidates.append(
+ {
+ "t": projection["t"],
+ "distance": projection["distance"],
+ "global_distance": projection["global_distance"],
+ "at_endpoint": projection["at_endpoint"],
+ "endpoint_clipped": projection["endpoint_clipped"],
+ "metadata": metadata,
+ }
+ )
if not candidates:
if unconstrained:
# Rectangle intersection can be empty while the side/manual domain
@@ -1048,6 +1078,65 @@ def _project_point_to_support(
}
+def _batched_unconstrained_arc_projections(
+ points: np.ndarray,
+ rows: np.ndarray,
+ geometry: EllipseGeometry,
+ sides: np.ndarray,
+ interval_specs: Sequence[Mapping[str, Any]],
+ *,
+ include_global_oracle: bool,
+) -> dict[int, list[dict[str, Any]]]:
+ """Project all supported rows for one branch in one vectorized call."""
+
+ flat_rows: list[int] = []
+ flat_domain_indices: list[int] = []
+ flat_domains: list[tuple[float, float]] = []
+ for row in rows:
+ spec = interval_specs[int(row)]
+ manual_intervals = spec.get("manual_intervals")
+ rectangles = spec.get("rectangles", ())
+ # Rows with neither explicit bounds nor observed support are handled by
+ # the legacy finite penalty path. Precomputing a side projection for
+ # them would change that contract.
+ if manual_intervals is None and not rectangles:
+ continue
+ domain = _projection_domain(str(sides[row]), manual_intervals)
+ for domain_index, interval in enumerate(domain):
+ flat_rows.append(int(row))
+ flat_domain_indices.append(domain_index)
+ flat_domains.append(interval)
+ if not flat_rows:
+ return {}
+
+ flat_points = np.asarray(points[np.asarray(flat_rows, dtype=int)], dtype=float)
+ local_u, local_v = _local_coordinates(flat_points, geometry)
+ t_min = np.asarray([interval[0] for interval in flat_domains], dtype=float)
+ t_max = np.asarray([interval[1] for interval in flat_domains], dtype=float)
+ projection = _project_ellipse_arc(
+ local_u,
+ local_v,
+ geometry.a,
+ geometry.b,
+ t_min,
+ t_max,
+ include_global_oracle=include_global_oracle,
+ )
+ grouped: dict[int, list[dict[str, Any]]] = {}
+ for index, row in enumerate(flat_rows):
+ grouped.setdefault(row, []).append(
+ {
+ "t": float(projection["t"][index]),
+ "distance": float(projection["distance"][index]),
+ "global_distance": float(projection["global_distance"][index]),
+ "at_endpoint": bool(projection["at_endpoint"][index]),
+ "endpoint_clipped": bool(projection["endpoint_clipped"][index]),
+ "domain_index": flat_domain_indices[index],
+ }
+ )
+ return grouped
+
+
def _symmetric_arc_projection(
points: np.ndarray,
values: Mapping[str, float],
@@ -1088,6 +1177,14 @@ def _symmetric_arc_projection(
geometry.axis_ratio,
reference_axis + sign * geometry.theta,
)
+ unconstrained_by_row = _batched_unconstrained_arc_projections(
+ points,
+ np.flatnonzero(mask),
+ branch_geometry,
+ sides,
+ interval_specs,
+ include_global_oracle=include_global_oracle,
+ )
for row in np.flatnonzero(mask):
spec = interval_specs[int(row)]
projection = _project_point_to_support(
@@ -1097,6 +1194,7 @@ def _symmetric_arc_projection(
spec.get("manual_intervals"),
spec.get("rectangles", ()),
include_global_oracle=include_global_oracle,
+ precomputed_unconstrained=unconstrained_by_row.get(int(row)),
)
for name in (
"t", "distance", "global_distance", "at_endpoint", "endpoint_clipped",
@@ -1626,6 +1724,7 @@ def fit_arc_ellipses(
cancel_event: Any = None,
observed_support: Mapping[Any, Any] | None = None,
reference_center: Sequence[float] | None = None,
+ observed_tip_constraint: bool = True,
) -> dict[str, Any]:
"""Fit a shared-centre mirror pair to labelled bounded ellipse arcs.
@@ -1640,6 +1739,8 @@ def fit_arc_ellipses(
reference_axis = math.radians(float(reference_axis_deg))
if not np.isfinite(reference_axis):
raise ValueError("reference_axis_deg must be finite")
+ if not isinstance(observed_tip_constraint, (bool, np.bool_)):
+ raise ValueError("observed_tip_constraint must be boolean")
if isinstance(max_nfev, (bool, np.bool_)) or not isinstance(max_nfev, Integral) or int(max_nfev) < 1:
raise ValueError("max_nfev must be an integer >= 1")
multistart_count = _validate_multistart_count(multistart)
@@ -1684,7 +1785,8 @@ def fit_arc_ellipses(
]
parameter_set = _parameter_set_for_arcs(xy, parameters, reference_axis)
parameter_set = _algebraic_arc_seed(xy, source_labels, parameter_set, reference_axis)
- parameter_set = _observed_radius_seed(xy, parameter_set)
+ if observed_tip_constraint:
+ parameter_set = _observed_radius_seed(xy, parameter_set)
sigma_weights = 1.0 / sigmas
def objective(candidate: ParameterSet, labels: np.ndarray) -> np.ndarray:
diff --git a/src/butterfly_saxs/batch.py b/src/butterfly_saxs/batch.py
index 70cfe0c..92452b9 100644
--- a/src/butterfly_saxs/batch.py
+++ b/src/butterfly_saxs/batch.py
@@ -229,10 +229,20 @@ def _file_content_fingerprint(value: Any) -> dict[str, Any] | None:
return record
-def _config_with_file_fingerprints(value: Any, *, key: str | None = None) -> Any:
+def _config_with_file_fingerprints(
+ value: Any,
+ *,
+ key: str | None = None,
+ require_content_hash: bool = False,
+) -> Any:
"""Copy config while binding geometry/mask/uncertainty file contents."""
- return _config_with_file_fingerprints_cached(value, key=key, cache={})
+ return _config_with_file_fingerprints_cached(
+ value,
+ key=key,
+ cache={},
+ require_content_hash=require_content_hash,
+ )
def _config_with_file_fingerprints_cached(
@@ -240,6 +250,7 @@ def _config_with_file_fingerprints_cached(
*,
key: str | None = None,
cache: dict[str, dict[str, Any] | None],
+ require_content_hash: bool = False,
) -> Any:
"""Recursive implementation with one bounded digest per canonical path."""
@@ -284,20 +295,46 @@ def _config_with_file_fingerprints_cached(
fingerprint = _file_content_fingerprint(candidate)
if cache_key is not None:
cache[cache_key] = fingerprint
+ candidate_is_file_path = (
+ isinstance(candidate, (str, os.PathLike, Path))
+ and str(candidate).strip().casefold() not in {"in-memory", "in_memory"}
+ )
+ if (
+ require_content_hash
+ and candidate_is_file_path
+ and (fingerprint is None or fingerprint.get("sha256") is None)
+ ):
+ raise ValueError(
+ "configured analysis file SHA-256 is unavailable; "
+ f"refusing checkpoint/resume for {candidate!s}"
+ )
if fingerprint is not None:
return {"value": _json_safe(value), "content": fingerprint}
if isinstance(value, Mapping):
return {
- str(name): _config_with_file_fingerprints_cached(item, key=str(name), cache=cache)
+ str(name): _config_with_file_fingerprints_cached(
+ item,
+ key=str(name),
+ cache=cache,
+ require_content_hash=require_content_hash,
+ )
for name, item in value.items()
}
if is_dataclass(value):
return _config_with_file_fingerprints_cached(
- {item.name: getattr(value, item.name) for item in fields(value)}
- , cache=cache
+ {item.name: getattr(value, item.name) for item in fields(value)},
+ cache=cache,
+ require_content_hash=require_content_hash,
)
if isinstance(value, (list, tuple, set, frozenset)):
- return [_config_with_file_fingerprints_cached(item, cache=cache) for item in value]
+ return [
+ _config_with_file_fingerprints_cached(
+ item,
+ cache=cache,
+ require_content_hash=require_content_hash,
+ )
+ for item in value
+ ]
return _json_safe(value)
@@ -896,6 +933,7 @@ def input_fingerprint(
*,
progress: Callable[[Mapping[str, Any]], Any] | None = None,
cancel_event: Any = None,
+ require_content_hash: bool = False,
) -> str:
"""SHA-256 identity of every selected frame file.
@@ -906,6 +944,7 @@ def input_fingerprint(
items = list(refs)
records: list[dict[str, Any]] = []
+ unavailable: list[str] = []
total = len(items)
for index, ref in enumerate(items):
if _is_cancelled(cancel_event):
@@ -947,6 +986,16 @@ def input_fingerprint(
stat["content_hash_algorithm"] = "sha256"
stat["content_sha256"] = None
stat["content_hash_unavailable"] = True
+ else:
+ stat.update(
+ {
+ "content_hash_algorithm": "sha256",
+ "content_sha256": None,
+ "content_hash_unavailable": True,
+ }
+ )
+ if require_content_hash and stat.get("content_sha256") is None:
+ unavailable.append(str(path))
ref_record = ref.to_dict()
ref_record["path"] = _canonical_path(path)
records.append({"ref": ref_record, "file": stat})
@@ -958,14 +1007,27 @@ def input_fingerprint(
"total": total,
}
)
+ if unavailable:
+ raise ValueError(
+ "input content SHA-256 is unavailable; refusing checkpoint/resume for: "
+ + ", ".join(unavailable[:5])
+ )
return _hash_json(records)
-def config_fingerprint(config: Any = None, *, mode: str = "independent") -> str:
+def config_fingerprint(
+ config: Any = None,
+ *,
+ mode: str = "independent",
+ require_content_hash: bool = False,
+) -> str:
return _hash_json(
{
"mode": mode,
- "config": _config_with_file_fingerprints(config),
+ "config": _config_with_file_fingerprints(
+ config,
+ require_content_hash=require_content_hash,
+ ),
}
)
@@ -1224,6 +1286,13 @@ def _quality_failure_reason(result: Any) -> str | None:
if result is None:
return "result=None"
+ quality_status = _named_value(result, "quality_status")
+ if _is_failure_status(quality_status):
+ return f"quality_status={quality_status}"
+ quality = _named_value(result, "quality")
+ nested_quality_status = _named_value(quality, "status")
+ if _is_failure_status(nested_quality_status):
+ return f"quality.status={nested_quality_status}"
butterfly = _butterfly_payload(result)
if butterfly is None:
butterfly = _named_value(result, "butterfly")
@@ -1705,6 +1774,9 @@ def run_batch(
)
callback = progress if progress is not None else on_progress
started_batch = __import__("time").perf_counter()
+ # Checkpointed runs must carry content identities from the start. A
+ # resumed run repeats the same gate before comparing the stored hashes.
+ require_content_hash = checkpoint_file is not None or resume
def cancelled() -> bool:
return _is_cancelled(cancel_event)
@@ -1739,11 +1811,16 @@ def hash_progress(payload: Mapping[str, Any]) -> None:
refs,
progress=hash_progress if callback is not None else None,
cancel_event=cancelled,
+ require_content_hash=require_content_hash,
)
if cancelled():
raise AnalysisCancelled("batch cancelled while hashing inputs")
emit_phase("config_fingerprint")
- config_hash = config_fingerprint(fingerprint_config, mode=mode)
+ config_hash = config_fingerprint(
+ fingerprint_config,
+ mode=mode,
+ require_content_hash=require_content_hash,
+ )
if cancelled():
raise AnalysisCancelled("batch cancelled while hashing config")
emit_phase("analyze")
diff --git a/src/butterfly_saxs/butterfly.py b/src/butterfly_saxs/butterfly.py
index b19d2f2..118ac91 100644
--- a/src/butterfly_saxs/butterfly.py
+++ b/src/butterfly_saxs/butterfly.py
@@ -18,7 +18,9 @@
from .butterfly_quality import PARAMETERS, evaluate_arc_evidence
from .cancellation import raise_if_cancelled
from .public_ellipse import canonical_ellipse_payload, observed_arc_radius_period
+from .ridge_inputs import canonical_inputs
from .serialization import strict_jsonable
+from .settings import canonical_q_unit
def _read(value, name, default=None):
@@ -43,15 +45,6 @@ def _qmap_unit(qmap: Any) -> str:
return str(unit or "unknown")
-def _image(frame):
- if isinstance(frame, np.ndarray):
- return np.asarray(frame, dtype=float)
- value = _read(frame, "data", _read(frame, "image", None))
- if value is None:
- raise ValueError("butterfly analysis requires a two-dimensional image")
- return np.asarray(value, dtype=float)
-
-
def _attach_candidate_diagnostics(candidate, source):
"""Retain observed/arc diagnostics when no optimizer result exists."""
@@ -126,10 +119,14 @@ def _fit_trace(trace, *, parameters, reference, multistart, unit, cancel_event,
)
try:
reference_center = _trace_reference_center(trace)
+ sampling_options = (
+ {"observed_tip_constraint": False}
+ if trace.get("method_version", "").startswith("butterfly-annular-") else {}
+ )
result = fit_arc_ellipses(trace["points"], parameters=parameters,
reference_axis_deg=reference, multistart=multistart,
max_nfev=max_nfev, cancel_event=cancel_event,
- reference_center=reference_center)
+ reference_center=reference_center, **sampling_options)
except ValueError as exc:
# Keep the observed trace and candidate diagnostics available to the
# correction/export boundary when the optimizer rejects its input.
@@ -194,6 +191,10 @@ def _fit_trace(trace, *, parameters, reference, multistart, unit, cancel_event,
q_star, radius_period, radius_flags = observed_arc_radius_period(
supported, unit, first_order_q=hint
)
+ annular = trace.get("method_version", "").startswith("butterfly-annular-")
+ if annular:
+ q_star, radius_period = None, None
+ radius_flags = ("prescribed_q_not_radial_peak",)
bound_flags = getattr(fit, "bound_flags", {}) or {}
extra_flags = list(radius_flags)
if bound_flags.get("axis_ratio"):
@@ -201,7 +202,7 @@ def _fit_trace(trace, *, parameters, reference, multistart, unit, cancel_event,
payload["q_star_from_arcs"] = q_star
payload["L_from_observed_radius_nm"] = radius_period
payload["q_star_source"] = (
- "first_order_iq"
+ "unavailable_prescribed_annuli" if annular else "first_order_iq"
if "spacing_from_first_order_iq" in radius_flags
else "observed_arc_radius"
)
@@ -686,10 +687,16 @@ def _sensitivity(image, qmap, window, *, mask, options, parameters, reference,
if qstep is not None and window[1] - window[0] > 4 * qstep:
variants.extend([("q_contract", [window[0] + qstep, window[1] - qstep], {}),
("q_expand", [max(0., window[0] - qstep), window[1] + qstep], {})])
- scales = options.get("smoothing_scales", options.get("scales_px", [1.2, 2.2, 3.6]))
- variants.extend((f"smoothing_{factor}", window,
- {"smoothing_scales": [float(x) * factor for x in scales]})
- for factor in (0.75, 1.25))
+ if options.get("trace_method") == "annular_peak":
+ variants.extend((f"annular_bins_{factor}", window,
+ {"annular_radial_bins": max(4, round(options.get("annular_radial_bins", 40) * factor)),
+ "annular_angle_bins": max(16, round(options.get("annular_angle_bins", 72) * factor))})
+ for factor in (.75, 1.25))
+ else:
+ scales = options.get("smoothing_scales", options.get("scales_px", [1.2, 2.2, 3.6]))
+ variants.extend((f"smoothing_{factor}", window,
+ {"smoothing_scales": [float(x) * factor for x in scales]})
+ for factor in (0.75, 1.25))
if qstep is not None:
for axis in ("center_qx", "center_qy"):
for sign in (-1, 1):
@@ -843,6 +850,90 @@ def _sensitivity(image, qmap, window, *, mask, options, parameters, reference,
"center_perturbation_kind": "half_pixel_sensitivity_not_instrument_uncertainty"}
+def _sector_measurement_summary(trace: Mapping[str, Any], q_unit: Any, edits: Any) -> dict[str, Any]:
+ """Summarize selected radial-sector peaks without changing fit fields.
+
+ The sector tracer measures one profile per finite azimuthal footprint. Its
+ median is therefore an observed-sector statistic, rather than the radius
+ of a fitted ellipse or a claim that every azimuth contains one identical
+ ring. Keep this summary separate from ``candidate_fit`` so the historical
+ ``q_star_from_arcs`` field continues to describe the value actually
+ produced by the arc-fit path.
+ """
+
+ bundle = trace.get("sector_peaks") if isinstance(trace, Mapping) else None
+ bundle = bundle if isinstance(bundle, Mapping) else {}
+ sectors = bundle.get("sectors")
+ sectors = sectors if isinstance(sectors, (list, tuple)) else []
+ excluded_ids = {
+ str(edit.get("point_id"))
+ for edit in (edits if isinstance(edits, (list, tuple)) else [])
+ if isinstance(edit, Mapping)
+ and str(edit.get("type", "")) == "exclude_point"
+ and edit.get("point_id") not in (None, "")
+ }
+ selected_before: list[float] = []
+ selected_after: list[float] = []
+ for sector in sectors:
+ if not isinstance(sector, Mapping):
+ continue
+ peak = sector.get("selected_peak")
+ if isinstance(peak, Mapping):
+ q_value = peak.get("q_star", sector.get("selected_peak_q", sector.get("q_star")))
+ else:
+ q_value = sector.get("selected_peak_q", sector.get("q_star"))
+ try:
+ q_value = float(q_value)
+ except (TypeError, ValueError):
+ continue
+ if not np.isfinite(q_value) or q_value <= 0.0:
+ continue
+ selected_before.append(q_value)
+ point_id = str(sector.get("point_id", ""))
+ manually_excluded = point_id in excluded_ids or str(
+ sector.get("geometry_reason", sector.get("reason", ""))
+ ) == "excluded_point_edit"
+ if not manually_excluded:
+ selected_after.append(q_value)
+
+ q_median = float(np.median(np.asarray(selected_after, dtype=float))) if selected_after else None
+ try:
+ canonical_unit = canonical_q_unit(q_unit)
+ except (TypeError, ValueError):
+ canonical_unit = str(q_unit or "unknown")
+ if canonical_unit == "nm⁻¹":
+ q_to_nm_inverse = 1.0
+ elif canonical_unit == "Å⁻¹":
+ q_to_nm_inverse = 10.0
+ else:
+ q_to_nm_inverse = None
+ apparent_period = (
+ float(2.0 * np.pi / (q_median * q_to_nm_inverse))
+ if q_median is not None and q_to_nm_inverse is not None
+ else None
+ )
+ overlap = bundle.get("sector_overlap")
+ overlap = dict(overlap) if isinstance(overlap, Mapping) else {}
+ return {
+ "q_star_sector_median": q_median,
+ "q_star_sector_median_unit": str(q_unit or "unknown"),
+ "q_unit": str(q_unit or "unknown"),
+ "q_star_source": "selected_sector_peak_median",
+ "apparent_period_from_sector_median_nm": apparent_period,
+ "apparent_period_unit": "nm" if apparent_period is not None else None,
+ "n_selected_sector_peaks": len(selected_after),
+ "n_selected_sector_peaks_before_manual_exclusion": len(selected_before),
+ "n_manual_excluded_sector_peaks": len(selected_before) - len(selected_after),
+ "aggregation": "median of selected finite sector-profile peaks after manual exclusion",
+ "peak_order": "unassigned",
+ "interpretation": (
+ "selected-sector q* median; it does not assert one ring at every angle; "
+ "overlapping sectors are correlated and reflection order is unassigned"
+ ),
+ "sector_overlap": overlap,
+ }
+
+
def analyze_butterfly(image, qmap, q_window, *, mask=None, options=None,
parameters=None, reference_axis_deg=0., multistart=7, cancel_event=None,
_radial_hint_cache=None):
@@ -853,9 +944,9 @@ def analyze_butterfly(image, qmap, q_window, *, mask=None, options=None,
settings = normalize_butterfly_settings(options)
settings.setdefault("snr_threshold", DEFAULT_ANALYSIS_SETTINGS["ridge_snr_threshold"])
settings.setdefault("max_nfev", DEFAULT_ANALYSIS_SETTINGS["max_nfev"])
- image = _image(image)
- if image.ndim != 2:
- raise ValueError("butterfly analysis requires a 2D image")
+ image, _qx, _qy, _q, input_invalid = canonical_inputs(image, qmap, mask=mask)
+ mask = input_invalid
+ base_invalid = np.asarray(input_invalid, dtype=bool)
q_unit = _qmap_unit(qmap)
for qname, pname in (("center_qx", "cx"), ("center_qy", "cy")):
if isinstance(parameters, Mapping) and pname in parameters:
@@ -864,15 +955,37 @@ def analyze_butterfly(image, qmap, q_window, *, mask=None, options=None,
radial_hint_cache = _radial_hint_cache
if (
radial_hint_cache is None
+ and settings["trace_method"] == "curvature"
and settings["stage"] == "evaluate"
and settings["resamples"] > 0
):
radial_hint_cache = _RadialHintGeometryCache()
raise_if_cancelled(cancel_event, "butterfly:trace")
- trace = trace_butterfly_ridges(image, qmap, q_window, mask=mask,
- reference_axis_deg=reference_axis_deg, options=settings,
- edits=settings["edits"], cancel_event=cancel_event,
- radial_hint_cache=radial_hint_cache)
+ if settings["trace_method"] == "annular_peak":
+ from .annular_trace import trace_butterfly_annuli
+
+ trace = trace_butterfly_annuli(
+ image, qmap, q_window, mask=mask, reference_axis_deg=reference_axis_deg,
+ options=settings, edits=settings["edits"], cancel_event=cancel_event,
+ )
+ elif settings["trace_method"] == "radial_sector":
+ from .sector_trace import trace_butterfly_sector_peaks
+
+ trace = trace_butterfly_sector_peaks(
+ image, qmap, q_window, mask=mask, reference_axis_deg=reference_axis_deg,
+ options=settings, edits=settings["edits"], cancel_event=cancel_event,
+ )
+ else:
+ # UI-only sector controls must not change the historical curvature
+ # point identity or invalidate saved point exclusions for that method.
+ curvature_settings = {
+ key: value for key, value in settings.items()
+ if key != "trace_method" and not key.startswith(("sector_", "annular_"))
+ }
+ trace = trace_butterfly_ridges(image, qmap, q_window, mask=mask,
+ reference_axis_deg=reference_axis_deg, options=curvature_settings,
+ edits=settings["edits"], cancel_event=cancel_event,
+ radial_hint_cache=radial_hint_cache)
candidate = _empty_candidate(q_unit, reference_axis_deg, diagnostics=trace)
uncertainty = {"intervals": {}, "coverage_calibrated": False, "status": "not_run"}
sensitivity = {"completed": False, "records": [], "held_out_arcs": []}
@@ -886,7 +999,18 @@ def analyze_butterfly(image, qmap, q_window, *, mask=None, options=None,
def refit(perturbed, overrides):
overrides = dict(overrides)
perturbed_qmap = overrides.pop("qmap", qmap)
- perturbed_mask = overrides.pop("mask", mask)
+ override_mask = overrides.pop("mask", None)
+ if override_mask is None:
+ perturbed_mask = base_invalid
+ else:
+ try:
+ override_mask = np.asarray(
+ np.broadcast_to(np.asarray(override_mask, dtype=bool), base_invalid.shape),
+ dtype=bool,
+ )
+ except (TypeError, ValueError) as exc:
+ raise ValueError("resampling mask must broadcast to image shape") from exc
+ perturbed_mask = base_invalid | override_mask
replicate_radial_cache = radial_hint_cache
qmap_perturbation = overrides.get("qmap_perturbation")
if isinstance(qmap_perturbation, Mapping):
@@ -925,13 +1049,55 @@ def refit(perturbed, overrides):
for row in evidence["quantitative_parameters"].values():
row.update(status="not_evaluated", empirical_status="not_evaluated",
reason="geometry_not_evaluated", reasons=["geometry_not_evaluated"])
+ method_version = trace["method_version"] if settings["trace_method"] != "curvature" else METHOD_VERSION
+ sector_measurement = None
+ if settings["trace_method"] == "radial_sector":
+ candidate["flags"] = list(dict.fromkeys([
+ *(candidate.get("flags") or ()), "peak_order_unassigned", "finite_sector_footprint",
+ ]))
+ evidence["quality"]["measurement_definition"] = "dominant peak of a finite azimuthal-sector radial mean profile"
+ # Keep this observed-sector statistic independent from the historical
+ # arc-fit aliases. In particular, do not relabel a fitted
+ # ``q_star_from_arcs`` value as a sector median when the two happen to
+ # be numerically close.
+ sector_measurement = _sector_measurement_summary(
+ trace, q_unit, settings.get("edits", [])
+ )
+ if settings["trace_method"] == "annular_peak":
+ candidate["flags"] = list(dict.fromkeys([
+ *(candidate.get("flags") or ()), "prescribed_q_not_radial_peak", "angular_scan_not_normal_ridge",
+ ]))
+ evidence["quality"]["measurement_definition"] = "azimuthal maxima on successive prescribed q annuli"
+ candidate["major_axis_prior"] = {
+ "observed_tip_constraint": False,
+ "reason": "the analysis q boundary is not evidence of an ellipse tip",
+ "explicit_user_bounds_preserved": True,
+ }
+ observed_radii = [float(np.hypot(p["qx"], p["qy"])) for p in trace["points"] if p.get("accepted")]
+ extent = max(observed_radii, default=0.)
+ major = candidate.get("a")
+ extrapolated = bool(major is not None and extent > 0 and major > 3 * extent)
+ candidate["axis_identifiability"] = {
+ "major_axis_status": "not_identified" if extrapolated else "requires_sensitivity_review",
+ "observed_radius_max_q": extent or None,
+ "a_over_observed_radius_max": float(major / extent) if major is not None and extent else None,
+ "sampling_scale_is_not_measurement_uncertainty": True,
+ "optimizer_weighting": "inverse angular-bin sampling scale; not detector-error weighting",
+ }
payload = {**trace, **evidence, "candidate_fit": candidate, "uncertainty": uncertainty,
"sensitivity": sensitivity, "edits": settings["edits"], "settings": settings,
- "method_version": METHOD_VERSION}
+ "method_version": method_version}
+ if sector_measurement is not None:
+ payload["measurement_summary"] = sector_measurement
+ payload["q_star_sector_median"] = sector_measurement["q_star_sector_median"]
+ payload["q_star_sector_median_unit"] = sector_measurement["q_star_sector_median_unit"]
+ payload["apparent_period_from_sector_median_nm"] = sector_measurement[
+ "apparent_period_from_sector_median_nm"
+ ]
payload["ellipse_local"] = ellipse_local_views(trace.get("points", []), candidate)
payload["recipe_sha256"] = hashlib.sha256(json.dumps(settings, sort_keys=True,
ensure_ascii=True, allow_nan=False).encode()).hexdigest()
- candidate.update({**evidence, "method_version": METHOD_VERSION,
+ candidate.update({**evidence, "method_version": method_version,
"uncertainty": uncertainty, "sensitivity": sensitivity})
return strict_jsonable(payload)
@@ -955,7 +1121,6 @@ def measure_butterfly_observables(frame, qmap, q_window, *, mask=None, options=N
# Landmarks are independent display/measurement diagnostics. Calculate
# them once at this public adapter, never in each uncertainty refit.
from .peak_landmarks import compute_peak_landmarks
- from .ridge_inputs import canonical_inputs
from .butterfly_ridge import _parse_q_window, _apply_edits
peak_image, peak_qx, peak_qy, peak_q, peak_invalid = canonical_inputs(frame, qmap, mask=mask)
@@ -964,6 +1129,7 @@ def measure_butterfly_observables(frame, qmap, q_window, *, mask=None, options=N
& np.isfinite(peak_qy) & np.isfinite(peak_q)
& (peak_q >= peak_window[0]) & (peak_q <= peak_window[1]))
peak_valid, peak_edits, _ = _apply_edits(peak_valid, peak_qx, peak_qy, result.get("edits", []))
+ companion_mask = ~peak_valid
peak_hint = result.get("diagnostics", {}).get("first_order_q_hint", {})
signal_window = peak_hint.get("band") if peak_hint.get("selection_status") == "selected" else None
peak_options = dict(settings.get("peak_landmark_options") or {})
@@ -977,17 +1143,27 @@ def measure_butterfly_observables(frame, qmap, q_window, *, mask=None, options=N
options=peak_options, cancel_event=cancel_event,
)
result["peak_landmarks"]["domain"]["applied_polygon_edits"] = peak_edits
- unit = str(_read(qmap, "q_unit", "unknown"))
+ unit = _qmap_unit(qmap)
if settings.get("companion_observables", True):
raise_if_cancelled(cancel_event, "butterfly:angular-spectrum")
- angular = measure_angular_spectrum(frame, qmap, q_window, n_bins=n_angular_bins, mask=mask)
+ angular = measure_angular_spectrum(
+ frame, qmap, q_window, n_bins=n_angular_bins, mask=companion_mask
+ )
raise_if_cancelled(cancel_event, "butterfly:angular-spectrum")
lobes = measure_four_lobe_peaks(angular, symmetric_refine=True,
reference_axis_deg=draw_axis_deg - 90.)
raise_if_cancelled(cancel_event, "butterfly:lobe-peaks")
- profiles, radial_peaks = _measure_lobe_radial_observables(frame, qmap, q_window, lobes,
- n_radial_bins=n_radial_bins, snr_threshold=float(result["settings"]["snr_threshold"]),
- min_coverage=0., mask=mask, cancel_event=cancel_event)
+ profiles, radial_peaks = _measure_lobe_radial_observables(
+ frame,
+ qmap,
+ q_window,
+ lobes,
+ n_radial_bins=n_radial_bins,
+ snr_threshold=float(result["settings"]["snr_threshold"]),
+ min_coverage=0.,
+ mask=companion_mask,
+ cancel_event=cancel_event,
+ )
raise_if_cancelled(cancel_event, "butterfly:lobe-profiles")
tilt, spread = apparent_lamellar_tilt(lobes, draw_axis_deg=draw_axis_deg)
raise_if_cancelled(cancel_event, "butterfly:lobe-summary")
@@ -1008,9 +1184,10 @@ def measure_butterfly_observables(frame, qmap, q_window, *, mask=None, options=N
profiles, radial_peaks = [], []
tilt, spread = float("nan"), float("nan")
points = result.get("points", [])
- ridge = {"points": points, "q_unit": unit, "flags": [METHOD_VERSION],
+ ridge = {"points": points, "q_unit": unit,
+ "flags": [str(result.get("method_version") or METHOD_VERSION)],
"valid_fraction": sum(bool(p.get("accepted")) for p in points) / max(1, len(points)),
- "method": "butterfly_curvature"}
+ "method": result["settings"]["trace_method"] if result["settings"]["trace_method"] != "curvature" else "butterfly_curvature"}
return ObservableSet(angular=angular, lobes=lobes, ridge=ridge,
ellipse=result["candidate_fit"], phi_app_deg=tilt, phi_app_std_deg=spread,
draw_axis_deg=draw_axis_deg, q_unit=unit, lobe_radial_profiles=profiles,
diff --git a/src/butterfly_saxs/butterfly_figure.py b/src/butterfly_saxs/butterfly_figure.py
index 3f0db59..1d13ed5 100644
--- a/src/butterfly_saxs/butterfly_figure.py
+++ b/src/butterfly_saxs/butterfly_figure.py
@@ -11,6 +11,7 @@
from collections.abc import Callable, Mapping, Sequence
import csv
import hashlib
+import html
import importlib.metadata
import json
import os
@@ -40,6 +41,9 @@
FIGURE_METHOD_VERSION = "butterfly-measurement-figure-v1"
+NATURE_FIGURE_GUIDE_URL = (
+ "https://research-figure-guide.nature.com/figures/building-and-exporting-figure-panels/"
+)
_RIDGE_CSV_FIELDS = (
@@ -61,6 +65,17 @@
"source_json",
)
+_RADIAL_PROFILE_FIELDS = (
+ "bin_index",
+ "q_unit",
+ "edge_left",
+ "edge_right",
+ "center",
+ "raw_sum",
+ "raw_mean",
+ "count",
+)
+
def _notify(
progress: Callable[[int, str], Any] | None, percent: int, phase: str
@@ -72,6 +87,8 @@ def _notify(
def _draw_radial_diagnostic(
ax_profile: Any, ax_count: Any, data: Mapping[str, Any], *, counts_bottom: bool
) -> None:
+ from matplotlib.ticker import MaxNLocator, ScalarFormatter
+
centers = data["radial_centers"]
means = data["radial_mean"]
counts = data["radial_counts"]
@@ -79,6 +96,31 @@ def _draw_radial_diagnostic(
centers, means, color="#0072b2", linewidth=0.85, marker="o", markersize=1.6
)
ax_profile.set_yscale("symlog", linthresh=data["radial_linthresh"])
+ # Matplotlib's default SymmetricalLogLocator only places major ticks at
+ # powers of ten. A narrow profile can therefore have a valid visible
+ # range with no labelled major tick at all (for example 3.2--4.2). Keep
+ # the symlog transform, but use a bounded linear-in-data locator/formatter
+ # as a display fallback when fewer than two major ticks are visible.
+ y_low, y_high = (float(value) for value in ax_profile.get_ylim())
+ locator = ax_profile.yaxis.get_major_locator()
+ try:
+ major_ticks = np.asarray(
+ locator.tick_values(y_low, y_high), dtype=np.float64
+ )
+ except (AttributeError, TypeError, ValueError, OverflowError):
+ major_ticks = np.asarray(ax_profile.get_yticks(), dtype=np.float64)
+ visible_ticks = major_ticks[
+ np.isfinite(major_ticks)
+ & (major_ticks >= y_low)
+ & (major_ticks <= y_high)
+ ]
+ if visible_ticks.size < 2:
+ ax_profile.yaxis.set_major_locator(
+ MaxNLocator(nbins=4, steps=[1, 2, 2.5, 5, 10], prune="both")
+ )
+ formatter = ScalarFormatter(useOffset=False)
+ formatter.set_powerlimits((-3, 3))
+ ax_profile.yaxis.set_major_formatter(formatter)
ax_profile.set_ylabel("Mean input intensity (symlog)")
ax_profile.set_xlim(float(data["radial_edges"][0]), float(data["radial_edges"][-1]))
ax_profile.tick_params(direction="out", length=2.0, width=0.5, pad=1.5)
@@ -184,6 +226,15 @@ def _software_version() -> str:
return "unknown"
+def _q_axis_interpretation(data: Mapping[str, Any]) -> str:
+ """Keep pixel-q labels explicitly non-physical at the export boundary."""
+
+ unit = str(data["q_unit"]).strip().lower()
+ if unit in {"pixel-q", "pixel_q"}:
+ return "uncalibrated pixel-q; no physical period is inferred"
+ return str(data["q_axis_interpretation"])
+
+
def _settings(data: Mapping[str, Any]) -> dict[str, Any]:
return {
"figure_method_version": FIGURE_METHOD_VERSION,
@@ -208,7 +259,8 @@ def _settings(data: Mapping[str, Any]) -> dict[str, Any]:
},
"q": {
"unit": data["q_unit"],
- "axis_interpretation": data["q_axis_interpretation"],
+ "axis_interpretation": _q_axis_interpretation(data),
+ "intensity_unit": "raw input scale (caller-supplied; not inferred)",
"image_coordinates": "supplied qx/qy mesh; no affine reconstruction or sorting",
"radial_origin": [0.0, 0.0],
"radial_aggregation": "raw observed intensity sum and unweighted mean across valid pixels in equal-width radial bins",
@@ -233,7 +285,8 @@ def _settings(data: Mapping[str, Any]) -> dict[str, Any]:
"color_clip_low_pixel_count": data["color_clip_low_count"],
"color_clip_high_pixel_count": data["color_clip_high_count"],
"negative_values_preserved_by_signed_transform": data["display_scale"]
- == "log1p",
+ in {"log1p", "asinh"},
+ "negative_values_preserved": True,
"invalid_pixels_masked_in_display": True,
"display_transform_changes_source_data": False,
},
@@ -321,17 +374,408 @@ def _write_ridge_csv(
)
+def _csv_number(value: Any) -> str:
+ """Serialize one finite numeric value without changing its measurement."""
+
+ try:
+ number = float(value)
+ except (TypeError, ValueError, OverflowError):
+ return ""
+ if not np.isfinite(number):
+ return ""
+ return format(number, ".17g")
+
+
+def _write_radial_profile_csv(path: Path, data: Mapping[str, Any]) -> None:
+ """Write the raw, one-pixel-per-sample radial aggregation.
+
+ ``count`` is the number of valid source pixels in each bin. Empty bins
+ retain their exact edges and center, while the undefined raw sum/mean are
+ left blank rather than serializing a misleading zero or NaN.
+ """
+
+ edges = np.asarray(data["radial_edges"], dtype=np.float64)
+ centers = np.asarray(data["radial_centers"], dtype=np.float64)
+ raw_sum = np.asarray(data["radial_sum"], dtype=np.float64)
+ raw_mean = np.asarray(data["radial_mean"], dtype=np.float64)
+ counts = np.asarray(data["radial_counts"], dtype=np.int64)
+ bin_count = len(centers)
+ if len(edges) != bin_count + 1 or len(raw_sum) != bin_count:
+ raise ValueError("radial aggregation arrays have inconsistent lengths")
+ if len(raw_mean) != bin_count or len(counts) != bin_count:
+ raise ValueError("radial aggregation arrays have inconsistent lengths")
+
+ with path.open("w", encoding="utf-8-sig", newline="") as stream:
+ writer = csv.DictWriter(stream, fieldnames=_RADIAL_PROFILE_FIELDS)
+ writer.writeheader()
+ for index in range(bin_count):
+ count = int(counts[index])
+ writer.writerow(
+ {
+ "bin_index": index,
+ "q_unit": str(data["q_unit"]),
+ "edge_left": _csv_number(edges[index]),
+ "edge_right": _csv_number(edges[index + 1]),
+ "center": _csv_number(centers[index]),
+ "raw_sum": _csv_number(raw_sum[index]) if count else "",
+ "raw_mean": _csv_number(raw_mean[index]) if count else "",
+ "count": count,
+ }
+ )
+
+
+def _figure_qa(
+ data: Mapping[str, Any], *, model_supplied: bool
+) -> dict[str, Any]:
+ """Describe export integrity and scientific limits without accepting data."""
+
+ dpi = int(data["dpi"])
+ low_dpi = dpi < 300
+ width_mm = float(data["width_mm"])
+ height_mm = float(data["height_mm"])
+ pixel_width = int(width_mm / 25.4 * dpi)
+ pixel_height = int(height_mm / 25.4 * dpi)
+ display_scale = str(data["display_scale"])
+ qa_status = "WARN" if low_dpi else "PASS"
+ result_safe = data["result_safe"]
+ result_quality = result_safe.get("quality")
+ result_quality = result_quality if isinstance(result_quality, Mapping) else {}
+ source_scientific_status = str(
+ result_safe.get("scientific_status")
+ or result_quality.get("scientific_status")
+ or "NOT_ACCEPTED"
+ )
+ dpi_check: dict[str, Any] = {
+ "status": "WARN" if low_dpi else "PASS",
+ "dpi": dpi,
+ "minimum_for_raster_submission": 300,
+ }
+ if low_dpi:
+ dpi_check["message"] = (
+ "Raster DPI is below 300; use a higher DPI for publication raster output."
+ )
+
+ scientific_boundary = {
+ "status": "recorded_only",
+ "scientific_acceptance": "not_assessed",
+ "source_scientific_status": source_scientific_status,
+ "scientific_acceptance_inferred": False,
+ "fabricated_points": False,
+ "main_measurement_panel_candidate_ellipse_drawn": False,
+ "candidate_assets_separately_labeled": True,
+ "source_provided_ridge_points_only": True,
+ "mirrored_or_synthesized_points": False,
+ "candidate_fit_preserved_in_result_json": True,
+ "model_overlay_is_diagnostic": True,
+ "caller_model_supplied": bool(model_supplied),
+ "fitted_intensity_or_residual_map_inferred": False,
+ "statement": (
+ "Figure QA records export integrity and provenance boundaries; it does "
+ "not constitute scientific acceptance."
+ ),
+ }
+ no_fabricated_points = {
+ "status": "PASS",
+ "value": True,
+ "source_ridge_point_count": len(data["points"]),
+ "drawn_source_ridge_point_count": len(data["plot_points"]),
+ "omitted_source_ridge_point_count": len(data["points"])
+ - len(data["plot_points"]),
+ "mirrored_or_interpolated_points": False,
+ "unsupported_points_retained_with_reasons": True,
+ }
+ editable_text = {
+ "status": "configured",
+ "verification": "matplotlib export settings recorded; vector files are not parsed by this QA step",
+ "svg_fonttype": _FIGURE_RC["svg.fonttype"],
+ "pdf_fonttype": _FIGURE_RC["pdf.fonttype"],
+ "editable_svg_text": _FIGURE_RC["svg.fonttype"] == "none",
+ "editable_pdf_text_setting": _FIGURE_RC["pdf.fonttype"] == 42,
+ "text_as_paths": False,
+ }
+ physical_size = {
+ "status": "configured",
+ "verification": "derived from the requested Matplotlib canvas geometry; output files are not parsed by this QA step",
+ "width_mm": width_mm,
+ "height_mm": height_mm,
+ "width_in": width_mm / 25.4,
+ "height_in": height_mm / 25.4,
+ "raster_pixel_width": pixel_width,
+ "raster_pixel_height": pixel_height,
+ }
+ q_unit = str(data["q_unit"])
+ q_units = {
+ "status": "recorded",
+ "unit": q_unit,
+ "axis_interpretation": _q_axis_interpretation(data),
+ "physical_period_conversion_performed": False,
+ "pixel_q_or_unknown_is_not_physical_period": q_unit.strip().lower()
+ in {"", "unknown", "pixel", "pixel_q", "pixel-q", "px"},
+ }
+ return {
+ "schema_version": "butterfly.figure_qa.v1",
+ "status": qa_status,
+ "status_scope": "export_integrity_only",
+ "warnings": [dpi_check["message"]] if low_dpi else [],
+ "scope": {
+ "measurement_panel": "butterfly_figure.*",
+ "candidate_assets": "ellipse_only.* and comparison diagnostics",
+ "model_assets": "model_comparison.* and fit overlay diagnostics when supplied",
+ "all_bundle_assets_hashed_in_manifest": True,
+ },
+ "physical_size_mm": {
+ "width": width_mm,
+ "height": height_mm,
+ },
+ "dpi": dpi,
+ "editable_text": editable_text,
+ "q_unit": q_unit,
+ "display_scale": display_scale,
+ "radial_profile": {
+ "file": "radial_profile.csv",
+ "fields": list(_RADIAL_PROFILE_FIELDS),
+ "aggregation": "raw observed intensity sum and unweighted mean",
+ "raw_intensity_unit": "raw input scale (caller-supplied; not inferred)",
+ "count_definition": "one valid source pixel contributes one count; not a statistical replicate count",
+ "display_transform_used": False,
+ "empty_bin_raw_sum_and_mean": "blank",
+ },
+ "scientific_acceptance": "not_assessed",
+ "source_scientific_status": source_scientific_status,
+ "no_fabricated_points": True,
+ "fabricated_points": False,
+ "nature_reference": NATURE_FIGURE_GUIDE_URL,
+ "target_specification": {
+ "reference": NATURE_FIGURE_GUIDE_URL,
+ "supported_width_mm": [89.0, 183.0],
+ "selected_width_mm": width_mm,
+ "body_font_pt": 6.5,
+ "panel_label_font_pt": 8.0,
+ "editable_text_requested": True,
+ "acceptance_claim": False,
+ },
+ "figure": {
+ "physical_size": physical_size,
+ "dpi": dpi_check,
+ "display_scale": display_scale,
+ "q_unit": q_unit,
+ },
+ "checks": {
+ "physical_size": physical_size,
+ "dpi": dpi_check,
+ "editable_text": editable_text,
+ "q_units": q_units,
+ "scientific_boundary": scientific_boundary,
+ "no_fabricated_points": no_fabricated_points,
+ },
+ "scientific_boundary": scientific_boundary,
+ }
+
+
+def _html_link(path: Path, *, label: str | None = None) -> str:
+ """Return a local-only link using a basename, never a private path."""
+
+ name = html.escape(path.name, quote=True)
+ text = html.escape(label or path.name)
+ return f'{text}'
+
+
+def _write_index_html(
+ path: Path,
+ *,
+ data: Mapping[str, Any],
+ outputs: Mapping[str, Path],
+ qa: Mapping[str, Any],
+ caption: str,
+) -> None:
+ """Write a dependency-free, local figure-bundle browser."""
+
+ # Keep paths that will be written later in the same transaction (notably
+ # manifest.json) so the browser exposes every promised download link.
+ available = {item.name: item for item in outputs.values()}
+ measured_names = (
+ "butterfly_figure.png",
+ "butterfly_figure.svg",
+ "butterfly_figure.pdf",
+ "butterfly_figure.tiff",
+ "measured_only.png",
+ "measured_only.svg",
+ "measured_only.pdf",
+ "measured_only.tiff",
+ )
+ candidate_files = {
+ path.name
+ for key, path in outputs.items()
+ if key.startswith("ellipse_only")
+ or key.startswith("ellipse_curves")
+ or key.startswith("comparison")
+ or key.startswith("geometry_overlay")
+ or key in {"point_residuals_csv", "normal_profiles_csv"}
+ }
+ model_files = {
+ path.name
+ for key, path in outputs.items()
+ if key.startswith("model_comparison")
+ or key.startswith("intensity_model_overlay")
+ or key.startswith("fit_")
+ }
+ sector_files = {
+ path.name
+ for key, path in outputs.items()
+ if key.startswith("sector_")
+ }
+ measured_files = [name for name in measured_names if name in available]
+
+ def links(names: Sequence[str] | set[str]) -> str:
+ selected = [available[name] for name in names if name in available]
+ if not selected:
+ return 'No file in this bundle.'
+ return " ".join(_html_link(item) for item in selected)
+
+ def preview(name: str, alt: str) -> str:
+ image = available.get(name)
+ if image is None or not image.is_file():
+ return 'Preview unavailable
'
+ return (
+ f''
+ f'})
'
+ )
+
+ result_safe = data["result_safe"]
+ measurement_status = html.escape(str(result_safe.get("measurement_status", "unknown")))
+ candidate_status = html.escape(
+ str((result_safe.get("candidate_fit") or {}).get("status", "not_available"))
+ )
+ quality = result_safe.get("quality")
+ quality = quality if isinstance(quality, Mapping) else {}
+ scientific_status = html.escape(
+ str(
+ result_safe.get("scientific_status")
+ or quality.get("scientific_status")
+ or "NOT_ACCEPTED"
+ )
+ )
+ caption_text = html.escape(caption.strip())
+ q_unit = html.escape(str(data["q_unit"]))
+ qa_status = html.escape(str(qa["status"]))
+ measured_files_text = links(measured_files)
+ candidate_files_text = links(sorted(candidate_files))
+ model_files_text = links(sorted(model_files))
+ sector_files_text = links(sorted(sector_files))
+ has_sector_figures = bool(sector_files)
+ annular_files = tuple(name for name in available if name.startswith("annular_"))
+ annular_files_text = links(annular_files)
+ provenance_names = (
+ "source_data.npz",
+ "radial_profile.csv",
+ "ridge_points.csv",
+ "result.json",
+ "settings.json",
+ "figure_qa.json",
+ "caption.txt",
+ "manifest.json",
+ "sector_qchi.svg",
+ "sector_qchi.pdf",
+ "sector_qchi.png",
+ "sector_qchi.tiff",
+ "sector_profiles.svg",
+ "sector_profiles.pdf",
+ "sector_profiles.png",
+ "sector_profiles.tiff",
+ "sector_profiles.csv",
+ "sector_peaks.csv",
+ "sector_profiles.npz",
+ "sector_caption.txt",
+ "sector_manifest.json",
+ )
+ provenance_links = links(provenance_names)
+ html_text = f"""
+
+
+
+
+Butterfly SAXS figure bundle
+
+
+
+Butterfly SAXS measurement figure bundle / 蝴蝶花样测量图包
+Engineering export · scientific acceptance not assessed · QA {qa_status}
+This offline browser uses only local relative files. 实测、候选几何和模型/诊断资产分开标记；图包 QA 不等于科学验收。
+
+| Measured status | {measurement_status} |
|---|
+| Candidate geometry status | {candidate_status} |
|---|
+| Scientific status | {scientific_status} |
|---|
+| q unit | {q_unit} |
|---|
+| Display scale | {html.escape(str(data["display_scale"]))} |
|---|
+| Physical size | {data["width_mm"]} × {data["height_mm"]} mm |
|---|
+| Raster resolution | {data["dpi"]} DPI |
|---|
+
+{f'''Annular flower trajectories · 逐环花瓣轨迹
+Fixed-q angular maxima
{preview("annular_qchi.png", "Azimuthal peaks on successive q rings")}
+
I(χ) on individual rings
{preview("annular_profiles.png", "Raw angular profiles of individual annuli")}
{annular_files_text}
Each ring supplies observed angular peaks to the outward petal tracks. Missing lobes remain missing. Ring q is a sampling coordinate, not a measured radial reflection position.
''' if annular_files else ""}
+Measured / observed · 实测
+Native measurement figure
{preview("butterfly_figure.png", "Measured butterfly SAXS figure")}
{measured_files_text}
Observed intensity, source-provided ridge points, supported observed segments, and raw radial profile.
Candidate geometry · 候选
+Candidate ellipse diagnostics
{preview("ellipse_only.png", "Candidate ellipse diagnostic")}
{candidate_files_text}
Candidate fits remain candidates and are not presented as accepted measurements.
Model / diagnostic · 模型
+Caller model and fit diagnostics
{preview("model_comparison.png", "Caller model comparison diagnostic")}
{model_files_text}
Model or residual assets are diagnostic comparisons and do not add measured points.
Sector-integrated primary peaks · 扇区积分主峰
+Raw I(q, χ) sector field
{preview("sector_qchi.png", "Raw sector-integrated q-chi intensity")}
Representative I(q | χ)
{preview("sector_profiles.png", "Representative sector-integrated profiles")}
{sector_files_text}
The q–χ field and I(q|χ) profiles are copied from the existing sector measurement result. Raw means remain separate from locator-only smoothing; blank bins are missing support, overlapping sectors are correlated, and candidates are not scientific acceptance.
''' if has_sector_figures else ""}
+Pixel-brightness ancillary diagnostics · 像素亮点附属诊断
+Pixel landmark maps
{preview("peak_map.png", "Pixel-brightness ancillary diagnostic")}
{links(tuple(name for name in ("peak_map.png", "peak_diagnostics.png", "peak_zooms.png") if name in available))}
G/P labels are pixel-brightness diagnostics only; they are not sector-integrated peak positions and must not be mixed with the I(q|χ) candidates.
Source data and caption · 源数据与图注
+{provenance_links}
+Figure caption
{caption_text}