Files
spectrometer/PEAK_FINDER.md
T

20 KiB
Raw Blame History

寻峰与峰信息导出(peak_finder.py)

peak_finder.py 在 hq_record.py 录制的 RAW 数据里找谱线峰:用 hq_spectrum.py 的解码和降维方式得到 R/G/B 三条谱,扣除局部基线后寻峰、拟合、给出峰形和像素坐标, 最后把选中的峰导出为图片、CSV、JSON 和原始像素块。

本程序不做标定。 它测的是传感器列坐标(sensor_x_px);只有当你在命令行里显式给出 --calibration <某个 calibration.json> 时,才会按该文件里的系数把列坐标换算成波长 (wavelength_nm = polyval(coefficients_descending, sensor_x_px))。不给就只输出像素, 波长列留空。这会避免把某一次实验的标定悄悄套到别的录制上——标定是否适用由你判断, 依据(系数、确认范围、参考录制)会原样写进 peaks.json。

支持的数据是 hq_record.py 录制的 RAW(BGGR_PISP_COMP1、2028×1520、uint8 容器)。 逐帧元数据里的黑电平(SensorBlackLevels,本数据集为 4096)会被自动使用。

标定:把峰交给 wavelength_calibration.py

标定不再是另起一套寻峰,而是消费本程序导出的峰:

# 1. 导出峰(不给 --calibration 就只导出像素坐标)
python peak_finder.py --input $rec --select all
#    → peak_exports/<recording>_f0000/peaks.json

# 2. 看一眼峰表(编号 P001…、列坐标、FWHM、SNR、是否饱和)
python wavelength_calibration.py --peaks peak_exports/<recording>_f0000/peaks.json

# 3. 指定身份后拟合(ID:波长)
python wavelength_calibration.py --peaks peak_exports/<recording>_f0000/peaks.json ^
    --assign "P001:404.6563,P002:435.8328,P003:546.0735,P004:576.9598,P005:579.0663"

--peaks 也可以指向 selected_peaks.csv(例如你用 --pick 挑过的那几条)。若改用 --input <录制>,标定脚本会在进程内调用本程序的 analyse(),得到同一套峰——两边 不存在第二套寻峰实现。

依赖:Python 3 + NumPy + Matplotlib,不需要 SciPy。脚本放在 hq_spectrum.py 同目录即可(本目录里那份 hq_spectrum.py 是 2026-11-14 版的副本,方便单独运行; 你自己的 hq_spectrum.py 更新后记得同步过来,或用 --module-dir 指过去)。

兼容性:与 2026-10-24 版和 2026-11-14 版 hq_spectrum.py 都测过。新版把 PC1B 解码器 改成了按需处理 qmode 3 + 直接写入 uint16(实测三份录制逐像素完全一致),并重写了 make_preview——后者现在要求整数 Bayer 帧,本程序已改为把原始 uint16 帧(多帧 平均时是四舍五入后的均值)交给它。

快速开始

在 peak_finder.py 所在目录运行。先设两个路径变量(换成你自己的),下面直接引用:

$rec = "C:\Users\peng0\Dev\Light\recordings\hq_20261101_114417"   # 录制目录
$cal = "C:\Users\peng0\Dev\Light\Programs\wavelength_calibration\calibration.json"

# 1. 先只看找到了哪些峰(不导出图片,速度快)
python peak_finder.py --input $rec --select none

# 2. 导出全部峰(每峰一张峰形图 + CSV + 原始像素块)
python peak_finder.py --input $rec --select all

# 3. 只导出 540–560 nm 的峰和最强的两条(按波长选就必须给 --calibration)
python peak_finder.py --input "C:\Users\peng0\Dev\Light\recordings\hq_20261110_230441" `
    --calibration $cal --select nm:540-560,top:2

# 4. 按编号导出(编号以上一次输出的 P001… 为准)
python peak_finder.py --input $rec --select id:2,id:4-5

# 5. 在窗口里点选:左边全谱,右边跟着鼠标显示该峰的 RAW 像素块和放大谱形
#    悬停预览、点击切换选/不选,a=全选,n=全不选,e=导出,q=取消
python peak_finder.py --input $rec --pick

# 6. 平均多帧降噪;只取 ROI 中的一段行,减小谱线倾斜造成的展宽
python peak_finder.py --input "C:\Users\peng0\Dev\Light\recordings\hq_20261111_092116" `
    --frame 5 --average 8 --rows 600,760

# 7. 顺带对照汞灯谱线表(需要波长,所以也给标定)
python peak_finder.py --input $rec --calibration $cal --match line_tables\mercury_hg1.csv

只有第 3 条和第 7 条给了 --calibration;其余只输出像素坐标,要波长自己补上。 给了 --calibration 时终端会打印:

  id          nm      x_px  ch      SNR   height  FWHM px  FWHM nm   slit y  flags
* P001  435.6458   302.489  RB      517     2983    18.08    5.151  805.571  extrapolated, Hg I -0.19 nm
* P002  545.8237   689.157 RGB     2925    13545    10.35    2.949  763.262  saturated, Hg I -0.25 nm
  P003  579.5502   807.519 RGB      939     4346    14.74      4.2  771.807  Hg I +0.48 nm

(这三条相对 NIST 汞灯 435.8328 / 546.0735 / 579.0663 nm 的偏差为 −0.19 / −0.25 / +0.48 nm, 属于该标定本身约 0.7 nm RMS 的水平。)

交互选峰窗口(--pick)

┌───────────────────────────────┬──────────────────────┐
│                               │  RAW 预览(整幅、与  │
│      全谱(选中/未选中/聚焦)  │  播放器同款)+ROI 框 │
│                               │  +峰值所在列         │
│                               ├──────────────────────┤
│                               │  放大谱形 + 拟合曲线  │
│                               │  + 半高宽标记         │
└───────────────────────────────┴──────────────────────┘

鼠标移到某条谱线上,右边两块立刻切换成那个峰。右上就是 hq_spectrum 播放器里那张 auto-stretched RAW 预览(缩放到 ROI 区域):橙色框是 ROI,青色竖线是当前峰的传感器列, 青圈是它在缝方向的行位置;右下是放大的净信号和拟合曲线。

点一下切换选中(红色为选中、灰色为未选中、线更粗的是当前聚焦)。a 全选、 n 全不选,m 合并选中的几条、x 拆开合并线、u 撤销合并, e 导出并关闭、q 取消。见 pick_window.png。

窗口用固定的三块布局(不依赖 constrained_layout),可以随便拉伸;如果窗口比屏幕还大, 程序会先按屏幕尺寸缩一档,避免开出来就有一半在屏幕外。

导出的单峰 PNG 里那小块仍然是未去马赛克的 Bayer 像素块(inferno 色阶), 用来看像素级的线形和倾斜;想看"谱线在相机画面里的位置",看这个选峰窗口或 peaks_overview.png。

参数

输入

参数 默认 说明
--input 必填 录制目录(含 meta.json、frames.bin)
--frame 0 帧号(0 起)
--average 1 从 --frame 起平均多少帧;>1 时导出的像素块是均值(float32)
--roi auto auto 自动检测光谱带;x0,y0,x1,y1 手动;calibration 用标定 JSON 里保存的 ROI
--rows 无 在 ROI 内再限制行范围 y0,y1(全传感器行号),可减小谱线倾斜展宽
--reduce mean 沿缝方向的行合并方式 mean/median
--black / --full-scale 自动 覆盖黑电平/满量程(解码后 ADU)
--calibration 无 要换算波长时显式给出的标定 JSON;不给则只输出像素坐标(wavelength_nm 留空)
--wavelength-offset 0 给所给标定加一个固定波长偏移(nm),仅用于已确认的系统偏移;本身就是标定假设,慎用
--module-dir 脚本目录 hq_spectrum.py 所在目录
--quiet 关 不打印过程信息

寻峰

参数 默认 说明
--baseline-window 100 形态学开运算基线的窗口(传感器像素);0 表示不减基线
--peak-distance 4 同通道两峰最小间距(传感器像素,2 px = 一个采样点),再近就只留高的;调大用于合并"勉强分开"的混合峰
--peak-height 0.02 最小峰高,占该通道最大净信号的比值
--peak-prominence 0.01 最小地形突出度,占该通道最大净信号的比值
--min-snr 15 最小峰高,单位是该通道噪声估计
--max-peaks 40 每通道最多峰数
--group-tol 4 跨 R/G/B 合并成同一条谱线的距离(像素)
--fwhm-span 60 半高宽搜索的最大半程(像素);超出记为无半高宽
--fit-window 0 拟合窗半宽(像素);0 自动按半高宽定
--shape gauss 线型模型 gauss/lorentz

选择与导出

参数 默认 说明
--select all all、none、3(编号)、3-7(编号段)、nm:540-560(波长段)、546.1(波长±典型线距的一半)、top:5(SNR 前 5),可用逗号组合取并集
--pick 关 开窗口点选:左边全谱,右边实时显示鼠标所指峰的 RAW 像素块与放大谱形;悬停预览、点击切换选中
--output peak_exports/<录制名>_f<帧号> 输出目录;单帧是 _f0003,--average 8 时是 _f0003-0010_avg8
--patch-half-width 24 导出原始像素块的横向半宽(像素)
--patch-format npy 像素块格式 npy/csv/both/none
--patch-csv 关 在 npy 之外再写一份长表 CSV
--no-images 关 不生成每峰的 PNG
--match 无 谱线表(CSV/JSON),用于给出谱线身份建议
--match-tolerance 1.5 匹配容差(nm)

导出内容

peak_exports/hq_20261101_114417_f0000/
├─ peaks_overview.png          全谱:上图原始信号+基线,下图归一化净信号+峰标注
├─ peaks_all.csv               所有通道的全部候选峰(每行一个通道峰)
├─ selected_peaks.csv          选中的峰,一行一条物理谱线(只包含像素坐标等汇总)
├─ peaks.json                  清单:录制、帧、ROI、黑电平、噪声、标定、阈值、每峰的逐通道细节
└─ peaks/
   ├─ peak_P002.png            峰形图:全谱定位 + RAW 像素块 + 放大曲线与拟合
   ├─ peak_P002_shape.csv      峰形数据:逐通道 raw / 基线 / net / 拟合值 / 残差
   └─ peak_P002_raw_y572-978_x664-714.npy   该峰的 RAW 像素块(uint16;文件名即像素框)

peak_Pxxx.png 三块内容:上方是该峰在全谱中的位置;左下是把该峰附近的 RAW Bayer 像素块(未去马赛克,横轴/纵轴都是真实传感器行列号);右下是放大后的净信号、拟合曲线 (虚线)、半高宽标记,图例里的 x±… 是拟合中心的误差。标题给出波长、传感器列、通道、 SNR、FWHM;饱和峰带 [SATURATED],标定范围外带 [extrapolated],重叠双峰经联合拟合 分开的带 [pair fit]。

selected_peaks.csv 主要字段

字段 含义
id 峰编号 P001…(按传感器列排序,同一数据同参数可复现)
wavelength_nm 波长(空气,nm);无标定时为空
extrapolated 1 = 在标定确认范围之外,属于外推
channels / primary_channel 该线出现在哪些 CFA 通道 / 用哪个通道出指标
sensor_x_px 峰中心的全传感器列坐标(亚像素,加权合并各通道拟合中心)
center_spread_px 各通道中心的最大差,判断跨通道一致性
sample_index / sample_step_px 该峰在降维谱数组里的下标 / 采样步长(2 px)
dispersion_nm_per_px 该处色散
height_net_adu、snr、fwhm_px、fwhm_nm、area_net_adu_px 峰高(扣基线)、信噪比、半高宽(像素与 nm)、净面积
baseline_adu、raw_adu、saturated 基线值、峰顶原始值、是否饱和
slit_y_px 该谱线在缝方向(行方向)的强度加权中心行
roi_x0..roi_y1 使用的 ROI(全传感器坐标,半开区间)
patch_x0..patch_y1 导出的 RAW 像素块框(全传感器坐标,半开区间)
frame、frames_averaged 帧号、平均帧数
image_png、shape_csv、raw_npy、raw_csv 对应文件(相对输出目录)
match_species、match_nm、match_delta_nm 谱线表匹配结果(未启用时为空)

peaks_all.csv 另外给出逐通道的 center_parabola_px、center_fit_px、 center_err_px(拟合中心的形式误差)、fwhm_halfmax_px(半高宽直接测量值,可与拟合值 对照)、fit_ok、fit_rms_adu、deblended,便于判断某个峰的拟合是否可信。实际采用的 中心由 center_source 标明:fit = 高斯/洛伦兹拟合中心,apex = 拟合被拒后用峰顶三点 抛物线,sample = 平顶/饱和导致抛物线也不可用时的采样点。重叠双峰的两个分量共用同一个 fwhm_px(见下),因此两者线宽相同是正常的。

坐标约定

  • 全部为 0 起 的全分辨率传感器坐标;像素 x 覆盖 [x, x+1),第 0 行在画面顶部。
  • 降维谱每 2 px 一个采样点(CFA),拟合中心可以落在采样点之间,因此 sensor_x_px 是小数。
  • roi、patch 都是半开区间 [x0,x1) × [y0,y1),与 hq_spectrum.py 的 ROI 定义一致。
  • peak_*_raw_y572-978_x664-714.npy 的第 0 行 = 传感器第 572 行,第 0 列 = 第 664 列 (文件名里就是行列范围),可以直接 np.load 后与 patch_x0…patch_y1 对上。

方法说明

  1. 用 hq_spectrum.py 的 RecordingSource 解码一帧(或若干帧均值):PC1B 解压成 uint16 Bayer 图。

  2. extract_planes 按 BGGR 拆成 B、Gb+Gr(平均)、R 三个平面,沿缝方向(行)取 mean/median,得到一个像素一个采样点的三条谱;x 用 channel_x_positions 换算成 全传感器列号(G 在 x0+0.5+2k,R/B 在 x0+dx+2k)。

  3. 基线:对每条谱做形态学开运算(先最小值滤波再最大值滤波,窗口默认 ±50 采样点), 再去掉开运算结果的高频毛刺。它只用于测量峰高/峰宽,原始值单独导出。

  4. 噪声:中位绝对一阶差分 / (0.6745·√2),对孤立尖峰不敏感。

  5. 候选峰:局部极大值(平台取中点),要求峰高 ≥ max(高度比×通道最大, SNR 阈×噪声), 且地形突出度(topographic prominence,向上走到比它更高的点为止,取两侧谷底较高者) 达标,并与更强的峰间距 ≥ --peak-distance。用真实突出度而不是固定窗口,肩峰会被 自动排除,而真正分得开的双峰不会被并掉。

  6. 精化:加线性背景的高斯/洛伦兹拟合(自实现的 Levenberg–Marquardt,带边界投影), 同时给出参数的形式误差。拟合不合格(不收敛、宽度顶到边界、残差 RMS > 20% 峰高)时 退回峰顶(三点抛物线,center_source=apex),平顶/饱和导致抛物线也不可用时再用 检测到的采样点。全程不使用质心:质心是窗口的函数而不是峰的函数,同一个峰换个窗口 就换个值(本数据集里实测偏过 6 px 和 102 px),不能当峰位置用。

  7. 双峰去混叠:若两条相邻谱线的间距小于约 1.2 倍平均半高宽,就用「两个峰 + 一个 公共线宽 + 线性背景」做联合拟合。单峰拟合在重叠区会把两个中心都往中间拉(实测汞 577/579 会合成一条 579.5 nm),联合拟合才能把它们分开;标 deblended=1、[pair fit]。

  8. 跨通道合并:按检测到的极大值位置聚类(容差 --group-tol),同一通道只留 SNR 最高者;同一条线在不同通道被检测到位置差几像素时,按拟合中心再合并一次 (容差 1.5 px);峰中心按净峰高加权平均。

  9. 波长(仅当你给了 --calibration):wavelength_nm = np.polyval(coefficients_descending, sensor_x_px),与 wavelength_player.py 用的是同一个公式;超出该标定确认范围的峰标 extrapolated。不给标定时这一列与 nm 相关的量都留空,图上的 x 轴就是传感器列。

已知限制

  • 标定只对同一光学结构和传感器模式有效。 标定来自 hq_20261101_114417,其确认范围 是 436–580 nm;其它录制的同一根谱线位置可能相差几个像素(几百分之一 nm 到 1 nm)。 需要更准就重新跑 wavelength_calibration.py。--wavelength-offset 只能在已确认是 固定系统偏移时使用,不能代替重新标定。
  • 谱线沿行方向不是一条直线(弯曲 + 漂移)。 实测汞 546.1 nm(hq_20261101_114417): 照亮带(约 363 行)上谱线中心是一条 S 形曲线,峰峰值 9.6 px(≈2.7 nm),按强度加权的 1σ 是 1.76 px,而净线性漂移只有 2.6 px(0.41°)。因此沿全部 970 行平均得到 FWHM 10.35 px(2.95 nm),只用最亮的 70 行(--rows 690,760)得到 7.37 px(2.10 nm), 中心相差 1.76 px(0.50 nm)。要测真实线宽就用 --rows 取窄行窗口。 导出的 RAW 像素块只有 ~50 px 宽却横跨几百行,imshow 的 aspect="auto" 会把横向 放大约 10 倍,看着比实际"斜"得多——上面的数字才是真实几何。
  • 饱和峰:核心像素达到 65535 时标 [SATURATED],此时峰高、线宽和中心都可能偏。 降低曝光/增益或缩短曝光时间重新录制更可靠。
  • 重叠双峰要小心。 汞 576.96/579.07 nm 这类双线在默认 ROI 下间距只有约 6 px, 而单条线 FWHM 约 7.5 px。程序会用公共线宽做联合拟合把它们分成两条(本例 P004≈578.0 nm / P005≈580.4 nm),但分量位置的不确定度比孤立线大一个量级: center_err_px 约 0.2–0.5 px,而孤立线只要 0.02–0.3 px。间距小于约 1 倍半高宽时 结果对线型假设很敏感,把它当"参考位置"而不是精密测量值。
  • 弱线/连续谱:--peak-height、--peak-prominence、--min-snr 是相对的,暗弱录制 里需要适当调低;连成一片的宽峰会只报一个中心,或被 --peak-distance 合并。想把 靠得很近的线分开就把 --peak-distance 调小(最小 2 px = 一个采样点)。
  • 基线是形态学开运算的结果,宽于基线窗口的发射带会被部分当作基线;需要时可加大 --baseline-window 或设为 0。
  • 波长单位是空气波长,未做光谱响应(强度)校正,强度仍是相机 ADU。

与其它脚本的关系

脚本 作用
hq_spectrum.py 解码/实时显示/回放的核心,本脚本复用它的解码、ROI、CFA 分离
hq_record.py 录制 RAW
wavelength_calibration.py 用汞灯重新做像素→波长标定,产出 wavelength_calibration/;peak_finder 只读它的 JSON,从不改它
wavelength_player.py 带标定的回放
hq_average.py 多帧平均成新录制(本脚本用 --average 做同样的事,只是不落盘)
peak_finder.py 本脚本:寻峰 + 峰形/像素坐标导出

本脚本只读取标定,不会修改 wavelength_calibration/ 里的任何文件。

测试

# 录制不在程序目录附近时,用环境变量指过去,否则端到端用例会自动跳过
$env:PEAK_FINDER_TEST_RECORDING = "C:\Users\peng0\Dev\Light\recordings\hq_20261101_114417"
$env:PEAK_FINDER_TEST_CALIBRATION = "C:\Users\peng0\Dev\Light\Programs\wavelength_calibration\calibration.json"
python -m unittest test_peak_finder -v

覆盖基线/噪声估计、亚像素中心、高斯/洛伦兹拟合、候选筛选、跨通道合并、选择语法、 标定校验、谱线表匹配,以及一次真实的端到端导出(录制不在时会自动跳过)。