DePhaseKit（深度震相分析工具包）

DePhaseKit（包名 dephasekit，命令 dpk）是一个用于 深度震相分析的桌面 GUI 工具与计算库。它以 SAC 波形目录为输入，支持：

• 在主拾取窗中逐页查看和修改 t0-t9
• 按理论头段对齐并切换时间窗
• 用预览窗集中检查某个头段的已拾取波形
• 用颜色状态管理两类人工筛选结果
• 把拾取结果、颜色标记写回 SAC 头段
• 按震中距与方位角分组叠加，在叠加道上拾取深度震相前驱波（pmP / smP）
• 由 pP–pmP 走时差反演反射点处的地壳厚度，并给出误差预算
• 跨事件汇集穿透点与厚度，快速定位异常分组

这份 README 以“第一次用的人也能上手”为目标来写。

0. 快速开始

pip install -e .          # 或按第 3 节用 conda 建环境
dpk <事件目录>            # 启动 GUI（等价于 dephase）

python examples/01_forward_cross_validation.py   # 不需数据，验证安装

示例说明见 examples/README.md。

许可证：MIT，见 LICENSE。 引用方式：见 CITATION.cff。软件请引用 DOI 10.5281/zenodo.22180320（指向最新版本）； 方法与结果请引用配套论文。

1. 它能做什么

• 浏览一个事件目录里的 SAC 波形
• 按 gcarc、baz 或 az 排序显示
• 以某个 SAC 头段 t0/t2/t3/... 作为对齐基准
• 在主窗里直接拾取 t0-t9
• 打开某个头段的预览窗，只看已经拾过该头段的波形
• 在预览窗中给波形加两类人工状态：
  • user2：紫色波形，表示预览阶段标记出的重点波形
  • user1：绿色波形，通常表示从紫色里进一步挑出来的最终 LowQ/保留集合
• 在主拾取窗里按 user1 或 user2 集合跳转
• 做临时带通滤波显示，不改原始振幅文件
• 将拾取结果写回 SAC；将 user1 波形移动到 LowQ 目录

1.5 界面一览

工具由三个窗口构成，覆盖从单道拾取到跨事件复核的完整流程。

主拾取窗

逐页浏览事件目录里的波形，按某个 SAC 头段对齐后直接拾取 t0–t9。图中每道左上角依次是 台站名、震中距/方位角/反方位角、理论到时行，以及当前对齐头段与参考头段的时差 Δt 和振幅比； 彩色竖线是已拾取或由模型给出的震相标记。顶部三行分别是对齐与事件切换、带通滤波、理论震相控件， 右上是翻页与按人工状态跳转的按钮。

叠加子系统

按震中距与方位角分组叠加后，在叠加道上拾取深度震相前驱波。道标签中的 [group1 / t6 / N=7] 表示分组名、对齐头段与入叠道次；下一行的 pP-pmP:10.32 km 是由当前 t6（pP）与 t8（pmP）标记实时反算的地壳厚度，sP-smP 同理。 叠加道的对齐头段是结构性的（数据已按它叠好），因此只读——要重新对齐需重新叠加。 叠加子系统与主拾取窗共用同一套工具栏，控件含义见 1.6； 差别只在 File 菜单多出四个 Stack 维护项，以及预览窗多出 Stack-/Stack+ 等按钮。

厚度审阅窗

跨事件汇总所有分组的反射点与厚度，用于快速定位不合理的分组。三个视图联动： 左侧是选中分组的叠加道预览（红色为叠加道，下方为各成员道），右上是反射点分布图 （颜色代表厚度，色标 6–20 km），右下是可排序的分组表格，|z| 列给出该组厚度相对 邻近分组的异常评分。在地图上点选或在表格中选行，另外两个视图会同步。

正演与厚度反演

forward 子包提供两条相互独立的正演路径。左图是二者对同一模型给出的理论走时差： TauP 变莫霍精确射线追踪与平层解析公式的走时敏感度相差 1.13%，据此可以判断平层近似 在本震中距范围内是否成立。右图是由观测走时差反演厚度的关系，阴影为拾取误差与速度 不确定度合成的 ±σ 带。这两张图可由 examples/01_forward_cross_validation.py 复算。

1.6 主拾取窗控件详解

下图给每一个控件编了号，逐个对应到表格。带括号的字母是快捷键， 例如 Back (b) 表示按 b 等价于点该按钮。

#	控件	作用	快捷键
1	Align 下拉	选择对齐头段：所有波形按各自的这个头段对齐到 0 时刻。可选 t0 t2 t3 t7 t6 t5 t1 t4 t8 t9。切换后时间窗会按该头段的默认值重置	—
2	x1 / x2 输入框	主图时间窗的左右边界（秒，相对对齐点）。回车生效	—
3	Backup path 输入框	填入一个备份事件目录的路径后回车，把该目录里同名波形的头段恢复到当前事件。用于拾错后回滚。状态栏会报告匹配了多少条	—
4	◀ / 事件下拉 / ▶	在同一父目录下的其它事件之间切换，不必退出重开。下拉列出所有同级事件目录	—
5	Mode 下拉	横轴口径：Relative 显示相对对齐头段的时间；Absolute 显示 SAC 绝对时间	—
6	BP presets + + / -	带通滤波预设的选择、保存当前参数为新预设、删除选中预设。预设存在 bp_presets.json	—
7	c / n / p 输入框	滤波参数：c 是两个转折频率（低、高，Hz），n 是阶数 corners，p 是通过次数 passes——1 为单程滤波、保留相位延迟，更接近看初动；2 为零相位双向滤波，更接近平滑后的峰值位置	—
8	Apply BP / Reload	Apply BP 按当前参数做临时显示滤波，不改原始文件；Reload 丢弃临时滤波，重新读回原始波形	—
9	Ph 预设 + + / -	理论震相组合的预设管理，配合 15 使用。存在 phase_presets.json	—
10	Back / Next / Jump Missing	上一页 / 下一页 / 跳到下一个缺少当前对齐头段的台站（用来快速补齐漏拾）	b / n / g
11	Jump U1 / U2 / U5 / Flip	切换「跳转集合」。切换后用 ← → 在该集合内前后跳。U2 指紫色标记且未升级为 user1 的波形	—
12	Flip Current	把当前波形的极性翻转（写 user4 标记），用于震相极性相反的记录	—
13	Finish	把内存中的拾取结果与颜色标记写回 SAC，并把 user1 波形迁移到 LowQ 目录，然后关闭	Ctrl+S 仅存图，不等价
14	Preview t7/t6/t5/t0/t2/t3	打开对应头段的预览窗：只显示已经拾过该头段的波形	u y t p w e
15	Theory Phases 区	Model 选走时模型（如 iasp91）；Phases 填震相与目标头段的映射，格式如 pP-2,sP-3 表示把 pP 的理论到时画到 t2、sP 画到 t3；Apply Theory Markers 应用，Clear Theory 清除	—
16	波形区	每页显示若干道。在某道上左键单击即完成拾取，前提是先按数字键进入对应拾取模式（见 17 下方的快捷键表）	—
17	状态栏	左侧显示操作结果，中间显示当前对齐头段的完成度（如 Align P complete 20/20），stack 模式下额外显示 Stack mode	—

File 菜单（左上角）另有：Save、Stack Health、Refresh Stack Index、 Preview Invalid Stack Quarantine、Quarantine Invalid Stack Files、 Open Stack Workspace、Open Source Event、DSM 拟合对比…、Stack 厚度审阅…。 其中四个 Stack 项只在 stack 模式下可用，非 stack 模式点击会在状态栏提示。

1.7 波形标签解剖

每一道左上角的多行标签含义如下（下图取自叠加子系统，普通事件少 1 和 4 两行）。

#	内容	说明
1	DPK.STACK [group1 / t6 / N=7]	台站标识。叠加道的网络码是 DPK、台站名 STACK；方括号内依次是分组名、对齐头段、入叠道次 N。普通记录这里是真实的 台网.台站
2	dis / az / baz	震中距（度）、方位角、反方位角。叠加道给的是组内均值
3	Theory[iasp91] pP-P: sP-P:	所选模型下 pP、sP 相对 P 的理论走时差；-- 表示该模型算不出
4	pP-pmP:10.32 km	由当前标记实时反算的地壳厚度。用 t6(pP) 与 t8(pmP) 的差算 pP-pmP，用 t5(sP) 与 t9(smP) 算 sP-smP。改动标记后立即更新
5	Δt(t6-t7)	当前对齐头段与参考头段的时差
6	Amp_ratio	该道相对参考道的振幅比
7	红色竖线 t7	已拾取的震相标记。颜色由 marker_styles 决定，每个 t0–t9 一种颜色
8	青色竖线 t8	同上。此例中 t8 是前驱波 pmP
9	紫色竖线 t6	同上。此例中 t6 是 pP，也是本组的对齐头段

⚠️ 在叠加道上，对齐头段（此例 t6）是只读的——叠加数据是按它对齐生成的， 改了会让显示与数据脱节。要重新对齐必须重新叠加。其余头段仍可正常拾取。

1.8 预览窗控件详解

预览窗由三张联动的图和一条三行控件条组成。

区	内容
A	主预览图：按震中距叠放已拾过该头段的波形，对齐到 0。当前活动波形画成粗红线，标题栏显示 Picked: 台站名
B	方位角图：横轴方位角、纵轴震中距，用来看台站方位覆盖是否均匀
C	穿透点图：所选震相与模型下各道的反射点经纬度，红星是震中。可直接在图上点选波形
D	控件条：三行，逐个说明见下

第一行——显示范围与人工状态

#	控件	作用
1	x1 x2 dx	预览窗自己的时间窗与横轴主刻度间隔。dx 填 auto 表示按窗宽自动定刻度。回车生效
2	Station	台站搜索框。填入台站名或文件名片段后按 f 跳到匹配项
3	Ph	标准图与震中距图要画哪些震相线，格式 t2,t3,t5。留空则不画
4	Pierce / Model	穿透点图用的震相（pP/sP）与速度模型（prem/iasp91）
5	Amp AmpP A- A+ A= + -	振幅缩放。Amp 填倍数、A= 应用；A-/A+ 按步长增减；AmpP 是倍数预设下拉，+/- 存/删预设
6	Sel*	按当前选中波形的状态扩选同类（等同 l 键）
7	U1+ U1- U5+ U5- Flip F-	对选中波形写入/清除 user1（绿）、写入/清除 user5、翻转极性（user4）、清除翻转

第二行——拾取、视图与筛选

#	控件	作用
8	pk pkW Pk:Near	极值拾取。pk 填目标头段（可只写数字，如 7）；pkW 是搜索半窗（秒，默认 1）；按钮在 Pk:Near（就近极值）与 Pk:Std（标准）两种模式间切换
9	R RA	R 恢复上一轮被临时隐藏的波形；RA 恢复全部
10	Real / Tall	前者切换道间距：Real 按真实震中距、Even 均匀排列；后者切换窗口形状：Tall（高窗 860×1380）/Wide（宽窗），切换会重开预览窗
11	C Std	C 保存预览截图；Std 导出标准图件
12	Stack	用当前选中的波形生成叠加道
13	P A	P 进入/退出曲线批量拾取；A 把画好的曲线应用为对齐（详见 10.x 批量重对齐说明）
14	K:Sel K	按钮在 K:Sel（保留选中）与 K:Other（保留未选中）间切换；K 执行
15	Rect Circle FixRange	穿透点图上的框选、圈选工具；FixRange 锁定坐标范围，避免刷新时自动缩放
16	Grp# Ungrp	显示分组编号叠加层；只显示尚未分组的波形
17	D	把选中波形从本次预览临时移出（不改数据，用 R/RA 恢复）

第三行——选择集与头段清除

#	控件	作用
18	Group Load	Group 填分组名；Load 下拉列出已保存的分组
19	DelT	填要清除的头段（如 t3），配合 21 的 ClrT
20	SaveG LoadG ClrT DelG	保存当前选择为分组 / 载入选中分组 / 清除选中波形上 DelT 指定的头段 / 删除该分组

1.9 厚度审阅窗控件详解

区	内容
A	选目录… 与当前扫描根目录。默认扫 data/output/stack/analysis
B	预览模式 下拉（TopDist/Overlay）、异常描边（给离群组加描边）、成员下垫（在预览里叠出成员道）、重建索引，右端是当前统计 N groups / M events
C	事件筛选列表：勾选决定哪些事件参与显示；每行前的三角可展开到分组级
D	全选 / 全不选 / 展开
E	隐藏事件中心、地图、放大、缩小、重置：控制右侧地图的显示与视野
F	叠加道预览：选中分组的叠加道（红）与其成员道（蓝）。标题给出事件、分组、震相对、厚度、道次 N 与异常评分 |z|
G	反射点地图：GMT 海底地形底图 + 按厚度着色的反射点。可直接点选
H	厚度色标（km），与地图配色对应
I	分组表格：可按任意列排序。Pair 是用到的两个头段、Phase 是震相类型、N 是入叠道次、Thick(km) 是反算厚度、|z| 是相对邻近分组的异常评分、Status 是审阅标记

三个视图双向联动：在地图上点一个反射点、或在表格里选一行，另外两处会同步高亮。 表格右键菜单可改审阅状态，或直接「在主窗打开此事件」跳回拾取窗核对。

2. 文件说明

• ppk.py: 主 GUI 入口、按钮、快捷键、命令行参数
• WaveFigure.py: 波形绘制、预览窗、保存逻辑
• forward/: 正演与厚度反演子包
  • forward/taup_moho.py: 变莫霍走时正演引擎， 含平层解析公式与 TauP 精确射线追踪两条独立路径及其交叉验证
  • forward/constants.py: 地壳速度与误差预算的 默认取值及其文献依据（改动前请先读该文件）
• stack_system.py: 叠加分组的存储与元数据管理
• examples/: 三个可运行示例 + 20 条示例波形
• environment.yml: Conda 环境依赖
• pyproject.toml: 包元数据与 pip 安装配置
• bp_presets.json: 主窗滤波预设列表

3. 环境依赖

推荐使用 environment.yml：

conda env create -f environment.yml
conda activate dephasekit

或直接用 pip 安装（含命令行入口 dephase）：

pip install -e .
pip install -e '.[test]'   # 需要跑测试时

当前依赖版本：

• Python 3.12
• matplotlib 3.8.2
• numpy 1.26.2
• obspy 1.4.0
• PySide6 6.7.0
• scipy >= 1.11

4. 数据要求

输入是一个事件目录，目录里放同一事件的 SAC 文件。

下文中的 <PROJECT_ROOT> 指项目根目录，即本工具所在目录的上一级（本工具位于 <PROJECT_ROOT>/opt/dephasekit/）。代码内部通过脚本位置自动解析，不依赖硬编码绝对路径。

常见命名示例：

事件目录: 2011_12_11_01_47_25
波形文件: X1.4501.2011.345.01.47.25.BHZ.sac

程序会读取和写回 SAC 头段：

• t0 ~ t9
• user1
• user2

5. 启动方式

最简单的启动方式：

python ppk.py EVENT_DIR

常用示例：

python ppk.py EVENT_DIR -t t0 -p t7,t6,t5,t0,t2,t3
python ppk.py EVENT_DIR -t t2 -p t7,t6,t5,t0,t2,t3
python ppk.py EVENT_DIR -t t3 -p t7,t6,t5,t0,t2,t3

打开 stack 第二工作区：

python ppk_stack.py EVENT_DIR -t t6
python ppk_stack.py <PROJECT_ROOT>/data/stack/pick_jandy/2011_03_06_14_32_36 -t t6

ppk_stack.py 可以接受原始事件目录，也可以接受已经存在的 stack 工作目录。给原始事件目录时，它会自动跳到对应的：

<PROJECT_ROOT>/data/stack/<dataset>/<event>/

直接打开 stack GUI 时，工作区里必须至少有一条可读的 stack SAC。如果目录还没有 stack 结果，或者只有历史坏 SAC，ppk_stack.py 会输出 JSON 诊断并退出，不会打开一个随后崩掉的空窗口。可以先在普通事件窗口中生成 stack，或用 --init/--health/--manifest 检查工作区状态。

每次新生成的 stack SAC 现在直接平铺保存在 stack 工作区事件目录里，使用简洁文件名，例如：

<PROJECT_ROOT>/data/stack/<dataset>/<event>/stack_group1.sac
<PROJECT_ROOT>/data/stack/<dataset>/<event>/stack_visible.sac

对应的分析输出和元数据则放在另一棵输出目录里：

<PROJECT_ROOT>/data/output/process/stack/<dataset>/<event>/

其中 .stack_event.json、.stack_index.json、*.stack.json sidecar、每次 stack 的分析包目录等都在 data/output/process/stack/<dataset>/<event>/ 下。这样 stack 事件目录里只保留真正的叠加 SAC 文件，结构更干净。旧版本留下的子目录布局或平铺 stack_name.sac + stack_name.stack.json 仍然可以读取，方便兼容历史结果。

stack 窗口的主显示方式和普通拾取窗不同：它默认像 SAC 软件一样直接显示 stack SAC 自己的 b/e 时间轴，不再自动按 t0/t6/... 对齐。t0~t9 仍然可以在 stack 窗口里手动标记和保存，用于后续分析，但不作为打开 stack 结果时的默认显示基准。如果不手动传 -x，stack 窗口会优先用可读 stack SAC 的 b/e 自动设置显示时间窗。

stack 窗口里打开 Preview tX 时，预览语义会切换成“当前 stack + 这个 stack 使用过的原始成员波形”。如果先在主 stack 窗口点击某条 stack，再打开预览，就会优先查看这条 stack；否则默认查看当前顺序里的第一条 stack。预览仍按你打开的 tX 头段对齐，并且会优先使用这条 stack 生成时记录的时间窗，让原始成员波形跟随 stack 的窗口一起显示。默认 Overlay 模式会像 stack 输出包里的 preview.png 一样，把原始成员波形和 stack 波形叠在同一个归一化振幅轴上，stack 用不同颜色显示；切到 TopDist 模式后，才会把 stack 人为设置到最大震中距并显示在成员集合最上方。stack 波形只显示本次用于叠加对齐的那个头段，例如按 t6 叠加就只在 stack 上保留/标记 t6，不会把其他头段一起画上去。主 stack 窗口也会把这个对齐头段换算到 stack SAC 自己的时间轴里显示，例如 sidecar 窗口是 [-30, 20] 而 SAC 显示轴是 0..50 时，t6 会画在 30s。预览里的方位角图只显示原始成员波形，穿透点图默认显示所有 stack 点并高亮当前 stack；打开 SrcPts 后，会额外显示当前 stack 的原始成员穿透点。

如果只想先检查 stack 工作区，不打开 GUI：

python ppk_stack.py EVENT_DIR --health
python ppk_stack.py EVENT_DIR --manifest
python ppk_stack.py EVENT_DIR --index
python ppk_stack.py EVENT_DIR --refresh-index
python ppk_stack.py EVENT_DIR --init
python ppk_stack.py EVENT_DIR --quarantine-invalid --dry-run
python ppk_stack.py EVENT_DIR --repair-metadata --health

其中 --health 只读输出 JSON，会区分坏 SAC、缺 sidecar、孤儿 sidecar、坏 JSON sidecar、以及能自动补齐的旧 sidecar 合约字段；--manifest 会列出当前 stack 工作区里的每条 stack SAC，包括是否可读、sidecar 是否有效/需修复、摘要、成员数、成员清单、跳过原因、结果包路径和平均几何/穿透点信息；--index 会输出工作区索引，--refresh-index 会重写工作区里的 .stack_index.json；--init 会为已有原始事件目录创建空 stack 工作区和 .stack_event.json，但不会伪造 SAC；--repair-metadata 会补齐 marker/sidecar 的可推断字段，无法解析的坏 JSON sidecar 只报告、不覆盖；--quarantine-invalid --dry-run 会报告哪些坏 SAC 会被隔离，但不移动文件；去掉 --dry-run 后才会把无效 stack SAC 和对应 sidecar 移入 _trash_invalid/<timestamp>/。

stack 工作目录里现在有两类工作区级文件，外加若干 stack 子目录：

• .stack_event.json：记录这个 stack 工作区对应哪个原始事件，以及输出包目录在哪里。
• .stack_index.json：记录当前工作区有哪些 stack SAC、哪些可读、sidecar 是否有效/需修复、成员数、成员清单、跳过原因、摘要、输出包和平均几何/穿透点；保存新 stack、初始化工作区或运行维护命令时会刷新。
• <stack_name>/：某一次 stack 的数据目录，里面放这次 stack 的 .sac 和 .stack.json。

打开 stack 窗口后，File 菜单里可以直接使用 Stack Health、Refresh Stack Index、Preview Invalid Stack Quarantine 和 Quarantine Invalid Stack Files 管理当前 stack 工作区。建议先用 Preview Invalid Stack Quarantine 看会处理哪些坏 stack，再决定是否真正隔离。

低层维护脚本 repair_stack_metadata.py 也支持 --health、--index、--refresh-index、--quarantine-invalid，但日常更推荐先用 ppk_stack.py，因为它能同时接受原始事件目录和 stack 工作目录。

用 pip install -e . 安装后会自动生成 dephase 命令。如果想要更短的命令， 可以在 PATH 里放一个 dpk 脚本：

#!/bin/bash
exec /path/to/dephasekit/.venv/bin/python /path/to/dephasekit/ppk.py "$@"

6. 命令行参数

python ppk.py wave_path [-a baz|gcarc|az] [-x xmin xmax] [-t tmarker]
                        [-s .sac] [-p t7,t6,t5,t0,t2,t3]
                        [-x2 x1 x2 x1 x2 ...]

参数说明：

• wave_path
  • 事件波形目录
• -a
  • 排序方式，默认 gcarc
  • 可选：gcarc、baz、az
• -x
  • 主拾取窗时间窗，格式为 xmin xmax
  • 普通事件里如果不写，程序会按当前对齐头段自动给默认窗
  • stack 工作区里如果不写，程序会优先按 stack SAC 自己的 b/e 自动给默认窗
• -t
  • 主拾取窗对齐头段，默认 t0
• -s
  • SAC 文件后缀，默认 .sac
• -p
  • 预览窗列表，多个头段用逗号分隔
  • 默认 t7,t6,t5,t0,t2,t3
• -x2
  • 每个预览窗单独的时间窗
  • 数量必须等于 2 x 预览头段个数

默认时间窗规则：

• t0 / t7 -> [-10, 70]
• t2 / t6 -> [-40, 30]
• t3 / t5 -> [-50, 20]
• 其他 -> [-10, 10]

7. 推荐工作流

如果你第一次用，建议按下面顺序：

1. 用 t0、t2 或 t3 作为主对齐头段打开事件。
2. 在主拾取窗中浏览波形，先把目标观测头段拾出来。
3. 常见做法是：
   • 用理论头段对齐：t0、t2、t3
   • 拾观测头段：t7、t6、t5
4. 打开相应预览窗，比如 Preview t7。
5. 在预览窗里把重点波形打成紫色 user2。
6. 如果想从紫色里再挑一层更可靠波形，就把它们打成绿色 user1。
7. 回到主窗，用 Jump U1 或 Jump U2 在对应集合里快速巡检。
8. 点击 Finish 保存结果。

一句话理解颜色：

• 紫色 user2：预览阶段的重点候选
• 绿色 user1：从重点候选里进一步确认的集合

当前主窗跳转规则是互斥的：

• Jump U1 只在 user1 里跳
• Jump U2 只在“紫色但不属于 user1”的波形里跳

8. 主拾取窗

主拾取窗是你打开程序后看到的主界面。每页显示 5 条波形。

8.1 主拾取窗能做什么

• 翻页看全部波形
• 切换对齐头段
• 切换绝对时间轴 / 相对时间轴
• 调整时间窗
• 输入滤波参数做临时显示
• 直接拾取 t0-t9
• 删除离点击位置最近的头段标记
• 在 user1 或 user2 集合中左右跳转
• 打开各个预览窗

8.2 主拾取窗顶部控件

带编号截图的速查表见 1.6 主拾取窗控件详解，本节是逐项展开。

• Align
  • 选择当前主窗对齐头段
  • 常用头段会排在前面：t0, t2, t3, t7, t6, t5
  • 点击 Apply 后，底部状态栏会提示当前对齐头段还缺多少台站、并列出前几个缺失台站名
• [] []
  • 主窗 x1 / x2 时间窗
• Mode
  • Absolute: 显示绝对时间
  • Relative: 显示相对当前对齐头段的时间
• BP
  • 主窗临时带通滤波显示设置
  • 参数含义：
    • c: 频段范围 freqmin freqmax
    • n: corners
    • p: 相位方式
      • p1: 单程滤波，保留相位延迟，更接近看初动
      • p2: 零相位双向滤波，更接近平滑后的峰值位置
• BP presets
  • 滤波预设下拉框
  • 选中后会自动回填到 BP 输入框
• +
  • 将当前 BP 参数保存为预设
• -
  • 删除当前下拉框选中的预设
• Apply BP
  • 按当前 BP 参数做临时显示滤波（不改原始文件）
• Jump Missing
  • 跳到下一个缺少当前对齐头段的台站
  • 适合沿着遗漏台站逐个补拾
• Reload
  • 丢弃临时滤波，重新读回原始波形

8.3 主拾取窗右上按钮

• Back (b)
  • 上一页
• Next (n)
  • 下一页
• Jump U1
  • 立刻跳到 user1 集合里按页顺序的第一条波形
  • 之后 Left/Right 只在 user1 集合里切换
• Jump U2
  • 立刻跳到 user2 集合里按页顺序的第一条波形
  • 之后 Left/Right 只在“紫色但不属于 user1”的集合里切换
• Jump U5
  • 跳到 user5 集合，之后 Left/Right 在该集合内切换
• Jump Flip
  • 跳到已翻转极性（user4）的集合，之后 Left/Right 在该集合内切换
• Jump Missing (g)
  • 跳到下一个缺少当前对齐头段的台站
• Flip Current
  • 翻转当前波形的极性（写 user4）；若该道已是目标状态，状态栏会提示而不重复写
• Preview tX
  • 打开对应头段的预览窗，括号内字母是快捷键
• Finish
  • 保存 SAC 头段并结束程序

8.4 主拾取窗颜色含义

• 黑色：普通波形
• 紫色：user2 波形
• 绿色：user1 波形

说明：

• 主拾取窗只显示颜色状态
• 不显示预览窗里的“当前选中高亮色”

8.5 主拾取窗拾取方法

先按键，再点击波形：

• 按 0-9
  • 进入对应 t0-t9 的拾取模式
• 在某条波形上点击
  • 在点击位置写入对应头段
• 按 d
  • 进入删除模式
• 再点击波形
  • 删除离点击位置最近的一个头段标记
• 按 s
  • 进入 user1 切换模式
• 再点击波形
  • 切换这条波形是否属于 user1

说明：

• 每次数字键、d 或 s 都是一次性操作
• 拾取后主窗会刷新
• 只有当前时间窗内的头段标签会显示在图上

8.6 主拾取窗状态栏

底部状态栏会显示：

• 当前跳转集合中的位置，比如 U1 3/12
• 当前站名
• 当前所在页码
• 当前对齐头段的完整度提示，比如 Align P missing 12/84 [...] 或 Align P complete 84/84
• 用 Jump Missing 或 g 可以直接跳到下一个缺失当前对齐头段的台站

9. 主拾取窗快捷键

这些键大部分不出现在界面上，只能从这里查。全部为全局快捷键， 焦点在输入框里时不触发（先按 Esc 或点空白处退出输入框）。

9.1 翻页与跳转

键	作用
b	上一页（等同 Back (b) 按钮）
n	下一页（等同 Next (n) 按钮）
g	跳到下一个缺少当前对齐头段的台站
←	在当前跳转集合里向前跳
→	在当前跳转集合里向后跳

跳转集合由 Jump U1 / U2 / U5 / Flip 四个按钮切换，默认是 U2。

9.2 拾取与删除

键	作用
0–9	进入 t0–t9 拾取模式，然后在目标道上左键单击完成拾取
d	进入删除模式，单击某道上已有标记的附近即删除最近的标记
s	进入 user1 切换模式，单击某道即切换其 user1（绿色）状态
q	取消当前拾取模式（解除武装）。误按数字键后用它退出，避免误拾

拾取模式是「一次性」的：完成一次单击后自动解除，需要连续拾取就再按一次数字键。 若在未武装状态下点到另一道，程序只会切换当前道而不写标记，防止误拾。

9.3 预览窗

键	打开的预览窗
u	Preview t7
y	Preview t6
t	Preview t5
p	Preview t0
w	Preview t2
e	Preview t3

9.4 搜索与窗口

键	作用
Ctrl+F	聚焦台站搜索框
/	同上（与 Ctrl+F 等价，单手更快）
Enter	在搜索框内按下时执行跳转
Space	关闭最上层的子窗口（预览窗）。注意：不是打开搜索
Ctrl+S	保存当前图像（只存图，不写 SAC；写 SAC 用 Finish）

9.5 台站搜索用法

1. 按 Ctrl+F 或 /
2. 输入台站名或波形文件名的一部分
3. 按 Enter，主窗跳到匹配的波形

10. 预览窗

预览窗的作用是：只看“某个头段已经被拾过”的波形，方便集中检查。

例如：

• Preview t7 只显示已经有 t7 的波形
• Preview t6 只显示已经有 t6 的波形

10.1 预览窗布局

带编号的控件速查表见 1.8 预览窗控件详解，本节是逐项展开。

预览窗包含：

• 左侧：按波形叠加显示的主预览图
• 右侧：az-gcarc 散点图
• 底部：控制按钮和输入框

10.2 预览窗底部控件

• x1, x2
  • 当前预览窗自己的时间窗
• dx
  • 默认使用 auto，会按当前窗宽自动计算横轴主刻度间隔
  • 也可以手动输入数字覆盖，比如 5
  • 在 x1、x2、dx 或 ph 输入框里按回车后立即生效
  • 底部会显示当前 Window width 和实际生效的 dx
• ph
  • 控制预览震中距图和标准图 Std 要使用哪些震相
  • 输入格式例如 t0,t2,t3
  • 默认留空，表示不显示震相线
  • 改完后在输入框里按回车才会应用
  • 预览震中距图只显示这些震相的线，不显示震相名
  • 导出的标准图会为同一组震相添加线和顶部相位名标注，并自动额外包含当前对齐震相
• 搜索框
  • 输入站名或波形名关键字
  • 在输入框里按回车搜索并跳到匹配波形
• M*
  • 一键选中当前预览里所有紫色波形
  • 只选当前仍可见的紫色波形，不会把已隐藏波形选回来
• G*
  • 一键选中当前预览里所有绿色 user1 波形
  • 只选当前仍可见的绿色波形，不会把已隐藏波形选回来
• A-
  • 略微减小预览波形振幅显示
• A+
  • 略微增大预览波形振幅显示
  • 如果你用 D 隐藏了一部分波形，振幅调节只作用于当前剩余波形
  • 每次执行 R 或 RA 恢复后，振幅会回到对应那一层隐藏前的设置
  • 再次执行 D 进入新的隐藏视图时，振幅会重新从默认值开始
• U1+
  • 把当前选中的波形加入 user1
• U1-
  • 把当前选中的波形从 user1 移除
• U5+
  • 把当前选中的波形加入 user5
• U5-
  • 把当前选中的波形从 user5 移除
• R
  • 只恢复上一轮通过 D 隐藏的波形
• RA
  • 恢复当前所有已隐藏波形
• Even / Real
  • 在真实震中距排布和均匀道集排布之间切换
  • Even 会把波形按当前排序结果等间距展开，方便找出是哪一条波形头段没标好
  • Even 的默认道间距是 1.0
  • 切换后 Std 导出也会沿用同一套排布
• C
  • 保存当前预览窗截图
• Std
  • 导出标准震中距图和方位角图
  • 如果已经隐藏了一部分波形，Std 只会导出当前还可见的剩余波形
  • 导出时的波形振幅倍率会跟随当前预览窗的 Amp
• Overlay / TopDist
  • 只在 stack 预览中出现
  • Overlay 是默认模式，按 preview.png 的方式把成员波形和 stack 波形叠在同一个振幅轴上
  • Overlay 里仍会标出本次 stack 对齐头段的位置，但只标这个头段，不显示其他相位线
  • TopDist 会把 stack 放到最大震中距，方便用 Even / Real 检查它和成员集合的位置关系
• Stack- / Stack+
  • 只在 stack 预览中出现
  • 切换到上一条或下一条 stack，并刷新成“该 stack + 它的原始成员波形”
• SrcPts:on/off
  • 只在 stack 预览中出现
  • 控制穿透点图是否额外显示当前 stack 的原始成员穿透点
• P
  • 进入批量拾取曲线模式
  • 左键连续加点画参考曲线，右键结束
  • 再按一次 P 可以取消当前曲线
  • 画线过程中不能直接执行 pk；必须先右键结束曲线，或者按 P 取消后再走无折线 pk
• A
  • 将当前批量拾取曲线交点附近 -0.5 s 到 +0.5 s 内的最大绝对振幅时间写入当前预览相位
  • 例如 Preview t7 中按 A，只会批量改 t7
  • 有选中波形时只检查选中波形；如果内部选择状态为空，才检查当前预览里所有可见波形
  • 只有和曲线真正相交的显示波形才会被修改，其他波形会跳过
  • A 不会切换到新头段对齐，也不会写 SAC 文件
• pk
  • 批量极值拾取参数输入框
  • 可以直接输入数字，例如 7，表示把极值时间写到 t7
  • 也兼容输入 t7 或 pk 7
  • 默认搜索半窗是 0.5 s
  • 输入 7 0.5 表示在中心时间前后 0.5 s 范围内搜索显示波形的最大绝对振幅
  • 如果已经画完 P 折线，中心时间来自折线和显示波形的真实交点
  • 如果没有画折线，中心时间就是当前预览相位的对齐位置，也就是横轴 0 s
  • 如果正在画折线但还没右键结束，按回车不会退回到横轴 0 s，会提示先结束或取消曲线
  • pk 只改目标头段 marker，不会把预览窗改成按目标头段对齐
  • 改完后直接按回车即可应用；结果会先保存在程序内存里的 self.markers
• K
  • 保留当前选中的波形，临时隐藏当前预览里其余所有仍可见波形
  • 很适合先用 Shift 选出中间一段，再一键去掉上下两端
• D
  • 把当前选中的波形从本次预览列表中临时移出
  • 不区分普通波形、紫色波形还是 user1 波形，只要选中了都可以隐藏
  • 可以连续多轮执行，逐步收缩到你想保留的波形集合
• SaveG
  • 将当前选中的非 user1 波形保存成 groupN
  • 如果选中集合里混有 user1，这些 user1 会被跳过，不计入 group 数量
• LoadG
  • 从 Load 下拉框恢复一个已保存的 group，恢复时只会跳到当前预览里真实存在的波形
• DelG
  • 删除 Load 下拉框当前选中的 group
  • 只删除对应的 groupN.txt 和 groupN.png，不会删除 SAC 波形文件
• 底部状态栏
  • 会显示当前预览窗宽、dx、ph、振幅倍率，以及当前隐藏了多少条波形、共几轮隐藏

说明：

• 预览窗里的 A、pk/peak 和主拾取窗手动点击一样，都会先更新程序内存中的 marker 状态。
• 主窗、预览窗和导出图都会从同一份 marker 状态刷新显示。
• 只有点击主窗 Finish 时，当前 marker 状态才会真正写回 SAC 头段。

10.3 预览窗中的选择方式

• 普通点击
  • 单选
• Shift + 点击
  • 连续范围选择
• Ctrl + 点击
  • 增删式多选
• Up / Down
  • 切换活动波形
• Shift + Up / Down
  • 扩展范围选择
• Ctrl + Up / Down
  • 追加选择
• Left / Right
  • 将当前选中的一条或多条波形的当前预览相位向左或向右微调
  • 按键方向按视觉直觉处理：按 Left 会让波形往左，按 Right 会让波形往右
• Ctrl + Left / Right
  • 对当前选中的一条或多条波形一起微调
  • 使用更小步长，适合精细修正
• Shift + Left / Right
  • 对当前选中的一条或多条波形一起微调
  • 使用更大步长，适合快速挪动

10.4 预览窗快捷键

• m
  • 将当前选中的波形切换成紫色 user2
• d
  • 执行与按钮 D 相同的动作
  • 按钮 D 位于预览图上方的预览控件区
  • 将当前选中的波形从本次预览列表临时移出
  • 普通黑色波形也可以直接隐藏
• r
  • 恢复上一轮预览里临时隐藏的波形
• c
  • 保存预览窗截图
• w / s
  • 只在 stack 预览中生效
  • w 切到上一条 stack，s 切到下一条 stack
• h
  • 切换当前选中波形是否写入绿色 user1
  • 第一次按会加入 user1，再按一次会取消 user1
• n
  • 切换当前选中波形是否写入 user5
  • 第一次按会加入 user5，再按一次会取消 user5
• l / L
  • 根据当前选中波形已有的状态，选中当前预览里同状态的全部波形
  • 例如先选中一个 user1，按 l 会选中全部 user1
  • 如果先选中一个 user1 和一个 user5，按 l 会选中全部 user1 或 user5
  • 只按当前选中波形的主状态扩选；主状态优先级是 user1 > user4 > user2/user5
  • 写入 user1 或 user4 时会自动清掉同一波形上的低层 user2/user5
  • 再按一次 l 会取补集，也就是选中其它状态/普通波形；继续按会反复在两边切换
• K
  • 保留当前选中的波形，隐藏当前预览里其它所有可见波形
• f
  • 执行搜索
• j
  • 把当前活动波形跳回主拾取窗
  • 跳转目标会在主拾取窗里显示成粉红色，方便定位
• p
  • 进入或取消批量拾取曲线模式
• a
  • 将当前批量拾取曲线应用到波形
  • 有选中时优先只作用于选中波形；否则自动检查当前可见波形 补充：以下键在上面的列表里没有，但同样有效（源自预览窗按键处理）。

键	作用
Space	关闭预览窗
x	清除选中波形上「删除标记」输入框所指的头段值
k	与 K 等价（保留选中、隐藏其余）
↑ / ↓	上下移动选中项；Shift 为范围扩选，Ctrl 为增选
← / →	微调对齐（见下）；Ctrl 最细、无修饰中等、Shift 最大

预览窗鼠标：左键单击选中；Shift+左键范围选择；Ctrl+左键增删选择。 在右侧穿透点图上单击也能选中对应波形。

预览窗微调说明：

• 微调的是“当前预览窗对应头段”，比如 Preview t7 里左右移动改的就是 t7
• 步长按当前数据采样间隔 dt 自动换算
• 三种 Left/Right 步长都会移动当前选中的一条或多条波形
• Ctrl 是最细步长，普通 Left/Right 是中等步长，Shift 是更大步长
• 修改后会立即同步刷新预览窗与主拾取窗

预览窗批量重对齐说明：

• 如果你只想改一部分，先选中那批“不太对”的波形
• 如果你不先选中，A 会检查当前预览里所有可见波形
• 按 P 或点 P 进入批量拾取曲线模式
• 在左侧主预览图里用鼠标左键连续画出你认为正确的相位走势
• 鼠标右键结束画线
• A 会以折线交点为中心，在前后 0.5 s 内找最大绝对振幅，并把该时间写入当前预览相位；它只写 marker，不改变当前显示对齐，也不写 SAC 文件

预览窗批量极值拾取说明：

• 如果你没有先画折线，直接在 pk 里输入任意目标头段，例如 t3、t5、t7
• 按回车后，程序会以当前预览对齐时刻为中心，默认在前后 0.5 s 范围内搜索最大绝对振幅
• 找到后会把对应绝对时间写入目标头段，但画面仍保持当前原头段对齐
• 现在默认直接写数字即可，例如 7
• 如果想自己改默认窗口，可以写成 7 0.3、5 0.8、7 0.5
• 先选中你想一起处理的那批波形
• 按 P 画参考折线，右键结束
• 在 pk 里输入任意目标头段，例如 3、5、7
• 如果你只写数字，不写窗口，折线精标默认就在交点前后 0.5 s 内找峰
• 如果想改这个窗口，再写成 3 0.1、6 0.2、7 0.5
• 按回车应用
• 程序会按这个预览窗当前头段去理解折线，例如 Preview t0 里画的折线就是基于 t0 的原始对齐
• 它会先找每条波形与折线的真实交点，再在交点前后窗口内的显示曲线上找最大绝对振幅
• 找到后会把对应绝对时间写入指定 SAC 头段
• 折线精标只做一件事：写 marker，不改当前预览窗或主拾取窗的显示对齐参考
• 这适合你已经能大致看出峰谷位置，只想把少量人工点选变成一批自动拾取

预览窗按钮补充：

• Std
  • 按当前预览状态直接导出两张标准图
  • 一张是震中距剖面图 gcarc_真实时间.png
  • 一张是方位角剖面图 az_真实时间.png
  • 会保留当前预览里的隐藏状态、筛选结果和时间窗
  • 不会把“当前选中”的红色高亮画进标准图
  • 横轴标签会自动写成真实震相名，例如 Time after pP (s)

10.5 预览窗颜色和状态

• 黑色：普通波形
• 紫色：user2
• 绿色：user1
• 红色：当前活动选中

说明：

• 如果一条波形同时属于 user2 和 user1，预览窗会优先以 user1 颜色显示
• 预览窗下方状态行会显示：
  • 台站名
  • 震中距
  • 反方位角
  • 是否是 [purple]
  • 是否是 [user1]
  • 当前选中了几条

10.6 D 和 R 的作用

D 与 R 只影响“当前会话下预览窗是否显示”，不等于删除 SAC 头段。

• D
  • 把当前选中的波形临时隐藏
• R
  • 把上一轮临时隐藏的波形恢复显示

这些隐藏状态只保存在当前程序会话内；退出程序后不会写进 SAC 头段。

这非常适合在预览阶段把当前选中的一批波形临时清掉，不管它们是不是 user1。

11. 滤波预设 BP presets

主拾取窗支持保存常用滤波参数。

使用方法：

1. 在主窗填好 freqmin / freqmax / corners / passes
2. 点击 +
3. 这组参数会加入下拉框
4. 以后只需在下拉框选中，再点 Apply

删除方法：

1. 在下拉框选中某个预设
2. 点击 -

说明：

• 预设保存在 bp_presets.json
• 删除后下次启动不会自动恢复
• 如果全部删空，下拉框只会剩占位项

12. 保存和输出结果

点击 Finish 后，程序会做两件事：

12.1 写回 SAC 头段

会写回：

• t0 ~ t9
• user1
• user2

12.2 移动 user1 波形

凡是 user1 不为空的波形，会被移动到 LowQ 目录。

默认目标目录规则：

• 如果事件目录位于 <PROJECT_ROOT>/data/ 体系下：
  • <PROJECT_ROOT>/data/process/low_waveform/<dataset>/<event_dir>/
• 否则：
  • 当前工作目录下的 LowQ_sac/<event_dir>/

12.3 预览窗截图

截图会保留：

• latest 最新版本
• 带时间戳的历史版本

目录与命名规则：

• lowq_preview_*
  • 直接保存到对应的 LowQ 事件目录
  • 如果事件目录位于 <PROJECT_ROOT>/data/ 体系下： <PROJECT_ROOT>/data/process/low_waveform/<dataset>/<event_dir>/
  • 保存时图片右下角会附带当前 user1 的完整 台网.台站 名单
• gcarc_*.png 和 az_*.png
  • 继续保存到分析输出目录 <PROJECT_ROOT>/data/output/phases/...

常见命名：

• lowq_preview_t7_latest.png

13. 适合新手的最短上手流程

如果你完全第一次用，可以只按下面做：

1. python ppk.py EVENT_DIR -t t0
2. 在主窗按 7，然后在每条波形上点出 t7
3. 打开 Preview t7
4. 在预览窗里用鼠标选中几条想重点检查的波形
5. 按 m，让它们变成紫色
6. 对更可靠的一批按 U1+，让它们变成绿色
7. 回主窗点 Jump U1
8. 用 Left/Right 巡检绿色波形
9. 确认后点击 Finish

14. 常见问题

14.1 为什么我改了 BP，但 SAC 文件没有变？

因为 BP 是“临时显示滤波”，只影响主窗与预览窗的显示，不改原始数据振幅。

14.2 为什么预览窗里有些紫色波形突然不见了？

很可能是你按了 D，把当前选中的波形在本次预览里临时隐藏了。按 R 会恢复上一轮临时隐藏的波形，按 RA 会恢复当前预览里所有临时隐藏的波形。

14.3 普通黑色波形能不能在预览里隐藏？

可以。只要在预览窗里先选中那条波形，不管它是普通黑色、紫色 user2，还是深绿色 user1，然后按 d 或点 D，它就会从当前预览里临时隐藏。按 r 或点 R 会恢复上一轮临时隐藏的波形，按 RA 会恢复当前预览里的全部临时隐藏波形。

14.4 为什么 Jump U2 看不到某些紫色里挑出来的波形？

因为当前规则是：

• U1 = 全部 user1
• U2 = 紫色但不属于 user1

也就是说，从紫色里升级成 user1 的波形，只会在 Jump U1 里出现。

14.5 为什么点击 Jump U1 或 Jump U2 后会立即跳页？

这是刻意设计的。按钮不仅切换模式，还会立刻定位到该集合按页顺序的第一条波形，方便你直接开始巡检。

15. 当前约定和建议

• 推荐用 t0、t2、t3 作为理论对齐头段
• 推荐把观测到时拾在 t7、t6、t5
• user2 更适合表示“候选集合”
• user1 更适合表示“最终保留集合 / LowQ 集合”
• 保存前最好至少巡检一遍 Jump U1

16. 一句话总结

如果只记一件事：

先在主窗拾取头段，再在预览窗筛紫色和绿色，最后回主窗用 Jump U1/U2 巡检，确认后 Finish 保存。