IonImage

离子晶格图像处理与分析工具集。本项目包含多种互不替代的定位思路：以 ion_detect 包为核心的 2D 高斯拟合检测、可选的 阈值二值化 + 连通域矩形、以及针对上下缘漏检的 外缘条带剖面 + 中心合并 与 第二层 y 行 / slab 等。根目录 ion_detection.py 为兼容入口（detect_ions 与命令行）。

文档结构（按用途）

章节	内容
1. 环境依赖	Python 与 pip
2. 数据与目录约定	输入目录、output_paths、各 outputs/ 子文件夹
3. 识别与定位方法	高斯流水线、blob、条带合并、第二层 / 批量 slab
4. 诊断与一维剖面	外缘条带列剖面、固定 x 条带的 y 向分层
5. 交互浏览与统计分析	Gallery、形变拟合、构型距离、数据集概览、导出 PNG、补充直方图脚本
6. ion_detect 包内模块分工	便于二次开发的模块表
7. 推荐工作流	从检测到合并的典型顺序
8. 调参建议	常见参数与注意点
9. 项目文件索引	仓库内主要文件说明

---

1. 环境依赖

建议 Python 3.10+。

pip install numpy scipy matplotlib

读 JPEG 等栅格图时，需 Pillow（一般随 matplotlib 依赖安装；若缺则 pip install pillow）。

---

2. 数据与目录约定

• 输入：默认 20260305_1727/（见 DEFAULT_DATA_DIR）。python -m ion_detect 支持该目录下的 .npy 与常见 栅格图（.jpg/.jpeg/.png/.tif/…，见 ion_detect.frame_io）；其它脚本多数仍仅扫 .npy。
• 路径约定：根目录 output_paths.py 集中定义 DEFAULT_DATA_DIR 与各 OUT_*。多数输出目录固定；例外：python -m ion_detect --save-pos --pos-out-dir DIR 可将离子坐标写入自定义目录。

outputs/ 下常用子目录

子目录	用途
outputs/ion_detect_imgs/	python -m ion_detect 主结果：ion_positions_*.png（灰度图 + 晶格边界 + 洋红 +，与合并后坐标一致）
outputs/bgsub_imgs/	减高斯背景（--save-bgsub-img）
outputs/bgsub_binarize_imgs/	bgsub 与二值 mask（--bgsub-binarize-threshold）
outputs/blob_connected/	python -m ion_detect.blob_cli 双栏 PNG
outputs/blob/	blob_cli 的 --log（merge_split.log）、--hist（hist_merge_split.png）
outputs/pixel_hist/	blob_cli 的 --plot-pixel-hist
outputs/IonPos/	离子中心 N×2（--save-pos）；可用 --pos-out-dir 改目录，文件名为源帧去扩展名 + .npy
outputs/amp_y_fit/	y 向振幅拟合系数
outputs/stretch_analysis/	stretching_analysis.py
outputs/histogram/	dist.py、plot_batch_log_ion_histogram.py、hist_*.py 等
outputs/dataset_viz/	project_info.py
outputs/npy_plots/	vis_selected_npy.py
outputs/edge_strip_profiles/	edge_strip_profile.py
outputs/y_layer_profiles/	y_layer_profile.py
outputs/ion_centers_merged/	merge_ion_centers.py
outputs/second_layer_peaks/	second_layer_ion_peaks.py
outputs/batch_merge_slab_<时间戳>/	batch_merge_second_layer_slab.py（含 batch_run.log）

---

3. 识别与定位方法

方法	典型入口	要点
高斯拟合	python -m ion_detect、detect_ions	每峰 2D 高斯拟合 → ion-dist 合并 → 主图仅 洋红 + 与边界；--save-pos 存合并后坐标
Blob	python -m ion_detect.blob_cli	阈值二值化 → 连通域 → 轴对齐矩形
条带 + 合并	merge_ion_centers.py	外缘条带辅助峰/COM 与 detect 按规则合并
第二层 / slab	merge --second-layer-slab、second_layer_ion_peaks.py、批量脚本	y 直方图选行 + x 剖面 + COM

3.1 高斯拟合单离子检测（detect_ions）

流程：减背景 → 匹配滤波 → 局部极大与相对阈值 → 2D 高斯拟合（可选 refine）。默认 θ=0 轴对齐（fix_theta_zero=True）。CLI 可对 detect_ions 主要参数调参（见下表「detect_ions」分组）。

后处理与出图：对拟合得到的中心做 --ion-dist 近距合并（欧氏距离 < D 的两点合并为中点，贪心取全局最近对；D≤0 关闭），与 blob_cli 中平衡位置标记一致，主图仅保留 灰度原图 + 晶格边界（cyan 虚线椭圆）+ 洋红 +（visualize_ion_positions_markers），不再叠加拟合椭圆。

入口：推荐 python -m ion_detect；等价 python .\ion_detection.py。

代码

from ion_detect import detect_ions, print_summary
from ion_detect import (
    visualize_ion_positions_markers,
    visualize_bgsub_markers,
    visualize_bgsub_binarized_markers,
)
# 兼容：from ion_detection import detect_ions, ...
# 椭圆叠加旧接口仍见 ion_detect.viz.visualize（模块内保留）

命令行

python -m ion_detect
python -m ion_detect 0 5 -1 "::3,0:10"
python -m ion_detect --data-dir D:/data/20260305_1727 --file frame001.jpg
python -m ion_detect --file D:/pics/a.npy   # 含路径则直接用该文件

选项	默认值	说明
位置参数 indices	0	数据目录内排序后帧的 numpy 风格切片并集；与 --file 同用时忽略
--data-dir DIR	DEFAULT_DATA_DIR	帧目录（.npy + 栅格图）
--file NAME	无	可重复；仅文件名/stem 时在 --data-dir 下解析；含路径时直接用该路径。优先于 indices
--save-pos	关	保存合并后最终中心（与图中 + 一致）为 N×2 的 .npy
--pos-out-dir DIR	无（即用 OUT_ION_POS）	须与 --save-pos 合用；坐标目录；文件名为源帧 stem + .npy
--ion-dist D	4	合并阈值（像素）；≤0 不合并
--save-bgsub-img	关	outputs/bgsub_imgs/，叠 洋红 +（合并后位置）
--bgsub-binarize-threshold T	未设置	outputs/bgsub_binarize_imgs/ 下 *_bgsub.png / *_mask.png（仅导出，非 blob）
--bgsub-binarize-strict	关	前景 > 而非 ≥
--show	关	弹窗

detect_ions 参数（CLI 分组，默认与 pipeline.detect_ions 一致）

选项	默认	说明
--bg-sigma-y / --bg-sigma-x	10 / 30	高斯背景 sigma（y, x）
--peak-size-y / --peak-size-x	5 / 9	detect_map 上局部极大窗口
--rel-threshold	0.025	相对 detect_map 最大值的峰阈值
--fit-hw-y / --fit-hw-x	3 / 4	高斯拟合半窗口
--sigma-min / --sigma-max	0.3 / 3.5	允许的高斯 σ 范围
--no-refine	（默认开精修）	关闭两阶段精修
--no-fix-theta-zero	（默认 θ=0）	允许拟合旋转椭圆

保存中心

python -m ion_detect "::5" --save-pos
python -m ion_detect 0:20 --save-pos --pos-out-dir D:/exports/ion_pos

每帧 N×2 的 [x0, y0]，与主图洋红标记一致。交互调参见 5.2 节。

---

3.2 阈值二值化 + 连通域 + 轴对齐矩形（blob）

流程：减背景（默认开，可用 --no-bgsub 关）→ 可选匹配滤波 → 浮点图二值化（默认 --thr-norm p95：椭圆 ROI 内正值子集的 P 分位为 scale，阈值 T 作用在 z/scale 上；可用 --thr-norm none 改为在 denoised 图上直接用 T）→ label 连通域 → 轴对齐最小外接矩形 → 可选外缘小矩形合并 → 默认对矩形做 y 向 split（--max-ysize）与 x 向 refine 得到多离子位置，再按 --ion-dist 合并近邻。无单峰高斯拟合。

实现：ion_detect/binarize.py、blob_preprocess.py、blob_components.py、blob_workflow.py、blob_viz.py、blob_ion_positions.py。

# 与下列显式参数等价：--split --refine-x --x-profile-threshold 0.4 --y-edge-frac 0.35
#   --thr-norm p95 --thr-norm-pct 1 --threshold 40
python -m ion_detect.blob_cli --indices 0
python -m ion_detect.blob_cli --threshold 30 --matched-filter --indices "::5"
python -m ion_detect.blob_cli --no-split --no-refine-x --thr-norm none --threshold 50 --indices 0

选项	默认	说明
--threshold T	40	二值化阈值；--thr-norm 为 p95 / p95_all 时作用在 z/scale（前景仍为 ≥T 的比较语义，见工作流实现）
--thr-norm	p95	none：在 denoised 图上直接用 T；p95：椭圆 ROI 内仅正值的 P 分位作 scale；p95_all：ROI 内全体有限像素的有符号 P 分位作 scale（不是对绝对值取分位）
--thr-norm-pct P	1	与 p95 / p95_all 配合，分位数 P∈[1,100]
--split / --no-split	开	y 向条带分割后求平衡位置；--no-split 仅用矩形中心
--max-ysize Y	9	与 split 配合：仅当矩形 y 跨度更大时才细分
--refine-x / --no-refine-x	开	子带内按列剖面细化 x、可多离子；--no-refine-x 关闭
--x-profile-threshold P	0.4	x 列掩膜阈值（与条带内 y 向二值占有率比较；--x-profile-rel-to-max 时改为相对 max(col)）
--x-profile-rel-to-max	关	列掩膜 col_mean > P * max(col_mean)
--y-edge-frac	0.35	外缘条带参数 F（小矩形合并等，与 outer_y_edge_strip_masks 一致）
--ion-dist D	5	全部位置求出后，欧氏距离 < D 合并；≤0 关闭
--no-merge-small-rects	关	关闭椭圆 y 外缘带内薄小矩形与 AABB 合并
--min-edge-ysize	5	参与上述合并的矩形 y 向边长上限条件
--no-merge-band-clip-ellipse	关	条带掩膜不按椭圆裁剪
--no-pre-merge-drop	关	merge 前不剔除两轴跨度均 ≤1 的矩形
--log	关	追加 TSV 至 outputs/blob/merge_split.log
--hist	关	各帧最终离子数直方图 → outputs/blob/hist_merge_split.png
--plot-pixel-hist	关	椭圆内亮度直方图（标 T）→ outputs/pixel_hist/
--no-bgsub	关	不减高斯背景
--matched-filter	关	与 detect_ions 相同匹配滤波
--connectivity	4	4 或 8
--min-area-pixels N	1	忽略更小连通域
--show	关	弹窗：先打开与 viz 附录类似的空域 brightness 分布图（RdBu_r/横向色标，叠 boundary 与矩形），再显示双栏 workflow
--data-dir	DEFAULT_DATA_DIR	数据目录

输出：outputs/blob_connected/ 双栏 PNG：上为实际参与阈值的浮点图（线性 brightness 色标，文框标明 bgsub / matched filter 是否开启及显示范围），下为二值图与矩形；估计得到 boundary 时，上下栏均绘制晶格椭圆（cyan 虚线）。图上洋红等标记为 split / refine / ion-dist 之后的最终离子位置（默认启用 split 与 refine）。区别：python -m ion_detect 的 --bgsub-binarize-threshold 只导出 bgsub 与 mask PNG，不跑连通域与矩形。

---

3.3 外缘条带与混合合并（merge_ion_centers.py）

在 detect_ions 与 4.1 节 同一套外缘 y 条带几何之间合并，单 PNG 出图（边界椭圆、上下缘线、edge-x-range 竖线、各中心）。

规则

• 椭圆内 + 上下外缘条带 + x ∈ [--edge-x-range]（默认 250 750）：保留条带 辅助峰 + 列向 COM，丢弃该域内 ion_detect 中心。
• 其余：仅 detect_ions；条带在 x 段外的峰不参与。
• --ion-dist（默认 4）：detect 与 strip 距离 ≤ 阈值反复并最近一对，中心取平均 → fused_mean（洋红）。≤0 关闭；过大易误并相邻格点。

python merge_ion_centers.py 0
python merge_ion_centers.py 0 --edge-x-range 250 750 --y-edge-frac 0.25 ^
  --y-fit-frac 0.35 --peak-dist 5 --ion-dist 4
python merge_ion_centers.py ::10

选项	默认
--edge-x-range	250 750
--y-edge-frac	0.25
--y-fit-frac	0.35
--peak-dist	5
--col-metric	mean
--strip-center-mode	com
--ion-dist	4
--preprocess	raw（条带聚合图；detect 始终原图）
--data-dir	DEFAULT_DATA_DIR；PNG → outputs/ion_centers_merged/

--second-layer-slab：由 y 直方图多峰定水平条带，条带内改用第二层行寻峰（second_layer_core）。多帧单次调用 = 合并所有帧中心的画直方图；每帧独立请用 batch_merge_second_layer_slab.py。

选项	默认
--profile-x-range	未传时常 300–600
--second-layer-hist-prominence	5（second_layer_ion_peaks 默认 10）
--second-layer-prof-prominence-frac	0.08
--second-layer-prof-peak-distance	4
--second-layer-y-halfwin	3
--second-layer-com-neighbor-cols	1
--second-layer-line-first/second/third	1 / 2 / 3
--second-layer-y-cut-pad	1

---

3.4 第二层诊断与批量 slab

second_layer_ion_peaks.py：与 merge_ion_centers 相同流程得合并中心后，全帧中心合并 → y 直方图按 --line-id 选行 → x 剖面 → COM。默认 outputs/second_layer_peaks/。

python second_layer_ion_peaks.py 0 --line-id 2
python second_layer_ion_peaks.py ::10 --hist-prominence 10

batch_merge_second_layer_slab.py：每帧单独直方图与 slab；输出 outputs/batch_merge_slab_<时间戳>/。

python batch_merge_second_layer_slab.py
python batch_merge_second_layer_slab.py 800 --data-dir D:/data/one_run

plot_batch_log_ion_histogram.py：解析 离子数=… 日志行 → 直方图（outputs/histogram/…）。

python plot_batch_log_ion_histogram.py path/to/batch_run.log --bin-width 2

---

4. 诊断与一维剖面

用于理解上下缘、分层与预处理；不替代 3.1–3.4 的主定位定义。

4.1 外缘条带列剖面（edge_strip_profile.py）

几何与 |y-cy|/b ≥ 1-F 截线一致；上下轴对齐条带内按列 sum/mean/max。peel / peel_bgsub 须首轮 detect_ions 成功。

实现：ion_detect.edge_strip_profile_analysis、edge_strip_profile_viz；根脚本为 CLI。

叠图线型：红虚线+点 = 剖面全局最大（细化）；番茄/绿虚线 = 多峰示意（--peak-dist + prominence）。

python edge_strip_profile.py 0
python edge_strip_profile.py 0 --preprocess bgsub --y-edge-frac 0.25
python edge_strip_profile.py 0 --preprocess peel --plot-peel
python edge_strip_profile.py 0 --peak-col-gallery --y-fit-frac 0.35
python edge_strip_profile.py ::20

选项	默认
--y-edge-frac	0.25
--preprocess	raw
--col-metric	mean
--peak-dist	5

聚合与掩膜：ion_detect.edge_strip.outer_y_edge_column_profiles、outer_y_edge_strip_masks。详见 python edge_strip_profile.py -h。

4.2 y 向分层（y_layer_profile.py）

固定 x 条带内按行对 x 求和，y 为横轴。--preprocess：raw / bgsub 仅。

python y_layer_profile.py 0
python y_layer_profile.py 0 --x-range 400:601 --preprocess bgsub --show

输出：outputs/y_layer_profiles/。

---

5. 交互浏览与统计分析

5.1 脚本与识别路径对照

脚本	依赖的主要识别 / 数据来源
gallery.py	detect_ions
stretching_analysis.py	detect_ions（σ、振幅 vs y）
hist_sigma_xy_per_frame.py	detect_ions，每帧 σx/σy 直方图 → `outputs/histogram/sx
hist_sigma_near_boundary_major_axis.py	detect_ions，近长轴离子 σ 直方图
hist_y0_A_deconv_near_major_axis.py	detect_ions + ROI 反卷积与 A(y) 拟合
merge_ion_centers.py	detect_ions + 外缘条带
second_layer_*.py、batch_merge_second_layer_slab.py	合并或第二层几何
dist.py	已保存的 outputs/IonPos/*.npy

5.2 gallery.py

交互浏览 .npy 并叠加 detect_ions（英文 UI）。默认 rel=0.025，Two-pass ref. 默认开。

python .\gallery.py

改参数后点 Detect；结果按 (帧, 参数) 缓存。

5.3 stretching_analysis.py

y_rel 与 sigma_minor/sigma_major、amplitude 的统计拟合。

python .\stretching_analysis.py
python .\stretching_analysis.py -n 10
python .\stretching_analysis.py -n 100 --ratio-fit quartic --amp-fit gaussian

默认：-n 为 100；--ratio-fit / --amp-fit 均为 quadratic（可选 quartic、gaussian）。quadratic 时仅用 |y_rel| <= 40 做点。输出例：outputs/stretch_analysis/…、outputs/amp_y_fit/…。

5.4 dist.py

读 outputs/IonPos/*.npy，构型间标准化距离（对 cdist 行取最小再平均）与直方图。

python .\dist.py
python .\dist.py --count 100

默认 --pos-dir=outputs/IonPos；PNG → outputs/histogram/cdist_hist_{构型数}.png。--bins 默认 50。

5.5 vis_selected_npy.py

按 stem 从数据目录导出灰度 PNG 或预览；默认 outputs/npy_plots/。

python .\vis_selected_npy.py 20260305_005542 20260305_010000
python .\vis_selected_npy.py --one-figure --cmap inferno 20260305_005542

详见 python vis_selected_npy.py -h。

5.6 project_info.py

扫描默认数据目录，摘要 + outputs/dataset_viz/ 示例图。

python .\project_info.py

5.7 其他

• statistic.ipynb：数据集统计示例（按需）。
• hist_sigma_xy_per_frame.py、hist_sigma_near_boundary_major_axis.py、hist_y0_A_deconv_near_major_axis.py：基于 detect_ions 的专项统计图（见各文件 docstring）。

---

6. ion_detect 包内模块分工

模块	职责
ion_detect.pipeline	detect_ions 端到端
ion_detect.gaussian	2D 高斯与剥离叠加
ion_detect.boundary	晶格椭圆边界
ion_detect.preprocess	匹配滤波、局部极大候选
ion_detect.fitting	单峰拟合与精修
ion_detect.peel	y_edge_band_thresholds
ion_detect.edge_strip	外缘条带按列聚合
ion_detect.edge_strip_profile_analysis	条带列剖面分析
ion_detect.edge_strip_profile_viz	条带总览与交互
ion_detect.viz	print_summary；主结果 visualize_ion_positions_markers；可选 visualize_bgsub_markers、visualize_bgsub_binarized_markers；另含椭圆版 visualize / visualize_bgsub*（供脚本或旧流程）
ion_detect.frame_io	数据目录下列举 .npy/栅格帧、load_frame
ion_detect.cli_helpers	索引解析、--file 与 --data-dir 联合解析
ion_detect.binarize	bgsub_binarize / bgsub_binarize_u8
ion_detect.blob_*	预处理、二值、连通域、工作流、可视化
ion_detect/__main__.py	python -m ion_detect

根目录 second_layer_core.py：y 直方图 / 剖面 / COM / slab，供 merge 与批量脚本共用。

---

7. 推荐工作流

1. 检测并导出坐标：python -m ion_detect "::5" --save-pos
2. 单帧交互调参：python .\gallery.py
3. y 向形变统计：python .\stretching_analysis.py -n 100
4. 构型距离：python .\dist.py --count 100
5. （可选）剖面：edge_strip_profile.py、y_layer_profile.py
6. （可选）合并外缘：merge_ion_centers.py（含 --second-layer-slab）
7. （可选）第二层 / 批量 slab：second_layer_ion_peaks.py、batch_merge_second_layer_slab.py

---

8. 调参建议

• 漏检 / 假峰：gallery 调 rel，或 python -m ion_detect --rel-threshold ... / detect_ions(..., rel_threshold=...)；--peak-size-*、--fit-hw-* 等同理。
• 噪点多：提高 --rel-threshold（或 rel_threshold）。
• 旋转椭圆 PSF：python -m ion_detect --no-fix-theta-zero 或 detect_ions(..., fix_theta_zero=False)。
• 形变分析：增大 -n，对比 quadratic / quartic / gaussian。
• 合并中心：略减 --peak-dist 可补外缘峰；--ion-dist 过大易误并；--edge-x-range 覆盖可靠列、避开圆角误判。
• 第二层：merge 与 second_layer_ion_peaks 的 hist-prominence 默认不同（5 vs 10），对比时统一；勿混淆「单次 merge 多帧直方图」与「batch 每帧独立」。
• Blob（blob_cli）：默认已启用 p95 阈值尺度（--thr-norm-pct 默认 1）、--threshold 40、--split / --refine-x 与较大的 --y-edge-frac（0.35）。若需接近早期「仅连通域矩形、原始浮点阈值」行为，可试 --no-split --no-refine-x --thr-norm none 并显式设 --threshold。

---

9. 项目文件索引

文件	说明
output_paths.py	默认数据目录与各 OUT_*
ion_detect/	检测核心包；python -m ion_detect、python -m ion_detect.blob_cli
ion_detection.py	兼容再导出与 python ion_detection.py
gallery.py	交互浏览
stretching_analysis.py	y 向形变 / 振幅拟合
dist.py	构型距离直方图
vis_selected_npy.py	指定帧 PNG
edge_strip_profile.py	外缘条带列剖面 CLI
y_layer_profile.py	固定 x 条带 y 向积分
merge_ion_centers.py	detect + 条带合并与可选 slab
second_layer_core.py	第二层几何内核
second_layer_ion_peaks.py	第二层独立诊断
batch_merge_second_layer_slab.py	批量每帧 slab
plot_batch_log_ion_histogram.py	批日志离子数直方图
hist_sigma_xy_per_frame.py	每帧 σx/σy 直方图
hist_sigma_near_boundary_major_axis.py	近长轴 σ 直方图
hist_y0_A_deconv_near_major_axis.py	反卷积 + A(y) 拟合
project_info.py	数据集概览
statistic.ipynb	Notebook 示例
.gitignore	忽略规则