原始 IQ 数据时频图生成

摘要

本文档说明工程中 "原始 IQ → 脉冲检测 → 短时傅里叶变换（STFT）时频图" 流水线的实现方式与物理含义。测试数据来自 generate_pulse_compress_iq.txt：一段用于脉压仿真的零中频复基带 IQ，内含多个线性调频（LFM）脉冲。程序输出两张核心图像：

单脉冲时频图 （single_pulse_from_detected_span.png）：聚焦某一个检测脉冲的脉内时频结构；
多脉冲时频图 （multi_pulse_keep_original_time_axis.png）：在保留原始时间轴与脉间空隙的前提下，展示整段脉冲串的时频演化。

两张图的本质，是把一维复数 IQ 序列映射到 时间---频率---功率 三维可视化空间：横轴为时间，纵轴为频率，颜色表示归一化功率（分贝）。对雷达信号而言，这是观察 脉内调制（如 Chirp 斜率、带宽） 与 脉间重复结构（PRI、脉冲串节律） 最直观的方法之一。

第一章系统定位与总体架构

1.1 工程任务

完成 可视化分析：

输入：文本格式的交替 I/Q 采样序列 + 采样率；
中间：自动检测脉冲位置；
输出：单脉冲与多脉冲 STFT 谱图（PNG），以及检测与绘图元信息（JSON）。

其典型用途包括：

人工核查 IQ 数据是否正常（有无 Chirp、相位跳变、镜像、杂散）；
对比仿真真值与实测/检测结果；
为后续特征提取（瞬时频率、时频脊线）提供直观依据；

1.2 模块组成

模块	职责
主流水线入口脚本	读 IQ、调用检测、调用绘图、写 JSON 摘要
脉冲检测入口	在整段 IQ 上定位每个脉冲的起止采样点
时频图视图模块	STFT 计算、单/多脉冲片段构造、图像保存
核心类型定义	脉冲区间数据结构（起止索引闭区间）

1.3 处理流程

复制代码

文本 IQ 加载（I/Q 交替 → 复数序列）
        ↓
整段 IQ 脉冲检测（默认双阈值包络法）
        ↓
分支 A：取第 N 个检测脉冲 → 截取片段 → STFT → 单脉冲时频图
分支 B：取全部（或前 K 个）检测脉冲 → 连续截取（保留脉间）→ STFT（带时间偏移）→ 多脉冲时频图
        ↓
figures/ 目录 PNG + metrics/ 目录 JSON

第二章输入数据说明

2.1 文件格式

generate_pulse_compress_iq.txt 为纯文本，相邻两行分别为同相分量与正交分量 ，程序按 [I0, Q0, I1, Q1, ...] 合成为复数 IQ。若总样本数为奇数，末尾一个点会被丢弃。

本次运行摘要显示：

复样本数：20 857；
采样率：125 MHz；
总时长约 166.9 μs（20 857 ÷ 125×10⁶）。

2.2 信号来源（脉压仿真）

该文件为 IQ 由 脉压仿真生成器 产生。生成器逻辑如下：

波形类型：零中频 LFM（线性调频） 基带脉冲；
每个脉冲相位为二次函数，对应瞬时频率随时间线性变化；
默认仿真参数（生成器缺省值）：采样率 20 MHz、脉宽 20 μs、PRI 120 μs、8 个脉冲、带宽 4 MHz、信噪比 14 dB 等；
实际 txt 在流水线中以 125 MHz 采样率处理，说明数据可能经重采样或使用了不同生成配置。

2.3 本次检测到的脉冲结构

根据 pipeline_summary.json：

检测到 8 个脉冲，与仿真"8 脉冲串"一致；
首个脉冲：采样点 788～1217 （闭区间），脉宽约 3.44 μs；
多脉冲绘图区间：从首个脉冲起点 788 到最后一个脉冲终点 18056 ，总时长约 138.2 μs；
相邻脉冲起点间隔约 18～19 μs 量级，对应脉冲重复间隔 PRI。

第三章脉冲检测阶段

3.1 为何先检测再画图

STFT 是对整段片段 做时频分析。若不对 IQ 切分，长观测窗会把多个脉冲、脉间噪声和空闲段混在一起，单脉冲 Chirp 结构会被稀释。因此本流水线 先检测、再截取，保证：

单脉冲图只含一个脉冲的脉内信息；
多脉冲图只覆盖"有脉冲的时段"，且可选保留脉间原始样本。

3.2 默认检测方法：双阈值包络

主流水线默认配置要点：

方法：双阈值包络检测；
高阈值虚警概率：约 10⁻³；
低阈值比：高阈值的 45%，用于维持脉冲内部连通；
噪声估计 ：滑动窗口内功率的 25% 分位数法；
最小脉宽：2 μs；
合并间隙：0.5 μs 内的断裂会被合并。

检测在 功率包络（模平方）上进行：先估计背景噪声功率，再设高/低门限；超过高门限触发，降至低门限以下结束；最后用原始功率细化边沿。

3.3 检测输出

每个脉冲表示为 起止采样点索引的闭区间。元信息 JSON 记录：噪声功率估计、高/低门限、粗检测数、合并后脉冲数等，便于追溯"为何切在这里"。

第四章 STFT 时频分析原理

4.1 从雷达 IQ 到谱图

雷达接收机输出的零中频 IQ，可写成：

复包络 = 幅度 × exp(j×相位)

瞬时频率 是相位对时间的导数（除以 2π）。LFM 脉冲的相位是时间的二次函数，故瞬时频率随时间线性变化 ，在时频平面上呈现 斜线（脊线）。

STFT 的做法：用长度为窗长的有限窗口（默认 Hann 窗）在时间上滑动，对每个窗口做 FFT，得到"某一时刻、某一频率"的能量。滑动步长由 窗长 − 重叠点数 决定。

4.2 默认 STFT 参数及物理意义

参数	默认值	含义
采样率	125 MHz	频率轴范围 ±62.5 MHz（基带）
窗长	256 点	时间窗约 2.05 μs
重叠	192 点	步进 64 点，时间步长约 0.51 μs
FFT 点数	4096	频率分辨率约 30.5 kHz
窗函数	Hann	降低谱泄漏，牺牲部分频率分辨率
动态范围下限	−40 dB	低于峰值的能量截断为 −40 dB，图面更干净
色图	jet	蓝低红高，传统谱图配色

时间分辨率 ≈ 窗长 / 采样率；频率分辨率 ≈ 采样率 / FFT 点数。二者受不确定性原理约束：窗越长，频率越细、时间越粗。

4.3 复基带与双边谱

程序使用 双边 FFT （非单边），并对频率维做 fftshift ，纵轴从 负频率到正频率 排列。零中频 LFM 的 Chirp 可能从负频率扫到正频率，在图中表现为 穿越零频的斜带，这与上传的单脉冲、多脉冲图一致。

4.4 功率归一化与分贝显示

计算步骤：

对 STFT 复系数取模平方得功率；
整幅图除以全局最大值，峰值归一化为 0 dB；
取 10×log₁₀，并 下限钳位 到 −40 dB；
用 imshow 绘制，色标范围 [−40, 0] dB。

因此色标标注为 "归一化功率(dB)" ：不是绝对功率，而是 相对最强点的分贝。优点是可比较不同时频结构；缺点是无法从颜色直接读出绝对 dBm，需结合原始 IQ 幅度。

4.5 时间轴为何不从零开始（单脉冲图）

SciPy STFT 的时间采样点对应 各分析窗的中心时刻 。对短脉冲片段，第一个有效时间点约在 窗长/(2×采样率) 处。

对 3.44 μs 脉宽、窗长 2.05 μs 的情况，图中时间轴大约从 1.0 μs 到 2.1 μs ，而不是 0～3.44 μs------这不是脉冲起点错了，而是 STFT 有效分析区的定义方式 。读图时应看 斜带形态，而非绝对起止微秒数是否等于脉宽。

第五章单脉冲时频图详解

5.1 生成逻辑

在检测结果中取 第 0 号脉冲（可通过参数改选其他脉冲）；
按检测闭区间 精确截取 IQ（默认不额外加边距，margin_ratio=0）；
对片段做 STFT（无时间偏移，横轴为片段内相对时间）；

5.2 上传图像的含义

单脉冲图主要特征：

视觉元素	物理含义
红色粗斜带（约 −5 MHz → +5 MHz）	LFM 主能量：脉内瞬时频率线性上升，调频带宽约 10 MHz
斜带时间跨度约 1 μs	STFT 窗中心能覆盖的有效脉内时段（小于真实脉宽 3.44 μs）
纵轴 ±60 MHz	显示整个基带 Nyquist 范围（125 MHz 采样）
大量水平浅蓝线	脉内/脉缘恒定频率分量：噪声、窗函数旁瓣、谱泄漏，或 STFT 在 Chirp 较弱处的窄带残留
背景深蓝（−40 dB 附近）	动态范围下限以下的弱能量

5.3 雷达知识：如何从单脉冲图读 LFM

斜率 ∝ 调频率（Chirp rate）：越陡，单位时间内频率变化越快；
纵跨幅度 ∝ 脉内调制带宽：关系脉压分辨率（约 c/(2B)）；
斜线是否直：LFM 应为直线；弯曲则可能是 NLFM；
0 dB 红色区域宽度：主瓣能量集中程度；旁瓣表现为斜线两侧的弱平行纹。

本图清晰斜带，说明：该脉冲是典型上行 Chirp（频率随时间增加），与脉压仿真 LFM 一致。

5.4 水平"条纹"是不是故障？

不一定是。常见来源：

加窗 STFT 的谱泄漏：Chirp 能量泄漏到邻近频率 bin；
复高斯白噪声：在各频率均匀贡献，形成底噪纹理；
Hann 窗旁瓣：强 Chirp 会在固定频率上出现弱水平结构；
若脉宽很短而窗相对较长，边缘效应也会表现为水平杂散。

当 主 Chirp 脊线清晰、信噪比足够 时，这些水平线通常不影响对调制类型的判断。

第六章多脉冲时频图详解

6.1 生成逻辑与"保留原始时间轴"

多脉冲图的关键设计：

对所有检测脉冲按起始点排序，可选只取前 K 个；
从 第一个脉冲起点 到 最后一个脉冲终点 ，截取原始 IQ 的 连续片段；
keep_gaps=True ：脉间样本 原样保留，不置零、不拼接压缩；
STFT 时传入 时间偏移 = 片段起点 ÷ 采样率，使横轴对齐 整段 IQ 的绝对时间；

与旧行为（把各脉冲 IQ 首尾拼接）相比，保留空隙能 真实反映 PRI：脉间只有噪声时，时频图在对应时段呈现低能量水平背景，而非人为消除时间间隔。

6.2 上传图像的含义

多脉冲图主要特征：

视觉元素	物理含义
8 条平行红色斜带	8 个 LFM 脉冲，脉内调制一致（同类型 Chirp）
斜带在 −20 MHz～+20 MHz 间扫描	每个脉冲调制带宽约 40 MHz（较单脉冲图更宽，因截取/检测区间与 STFT 覆盖整段脉内主能量有关）
斜带在时间上周期性出现	固定 PRI 的脉冲串
相邻斜带起点间隔约 18～20 μs	与检测 JSON 中 PRI 量级一致
单条斜带持续时间约 5～7 μs（视觉）	与 STFT 时间分辨率及脉宽有关；检测脉宽约 3.4 μs，图上看更宽因脊线能量扩散
贯穿全图的水平青色线	脉间噪声底 + 连续波式窄带干扰/泄漏；在 PRI 空隙段尤其明显
脉冲间无斜带的暗蓝区域	脉间无发射，仅噪声（`keep_gaps` 的效果）

6.3 雷达知识：多脉冲图能回答什么

波形是否稳定：8 条斜线平行 → 脉内调制一致，适合脉压处理；
PRI 是否固定：间距均匀 → 恒定 PRI 雷达；
是否存在杂散/干扰：水平线若固定在某频率，可能是连续波干扰或本振泄漏；
检测是否完整：少数缺失斜带 → 漏检；多余短斜带 → 虚警；
Agility / 步进频 ：若各脉冲斜线 纵向位置不同 而斜率相同，可能是载频步进；本图各脉冲频率范围相似，更像 固定载频 LFM 串。

6.4 单脉冲图与多脉冲图的对比

维度	单脉冲图	多脉冲图
时间轴	片段内相对时间	原始 IQ 绝对时间（微秒）
覆盖范围	1 个脉冲	首脉冲～末脉冲整段（含脉间）
主要用途	细看脉内调制、带宽、旁瓣	看 PRI、脉冲数、串稳定性

第七章代码实现要点

7.1 主流水线入口

入口函数接收：IQ 路径、采样率、输出目录、检测配置、STFT 配置、单脉冲索引、最大多脉冲数。流程为：创建输出子目录 → 加载 IQ → 检测 → 条件绘图 → 写三份 JSON（输入摘要、检测结果、流水线摘要）→ 返回路径与元信息字典。

7.2 时频配置对象

不可变数据类封装 STFT 参数，含合法性校验：采样率为正、重叠小于窗长、FFT 点数不小于窗长、动态范围上限为负等。

7.3 STFT 计算核心

调用科学计算库的 STFT 接口，参数包括：采样率、窗型、窗长、重叠、FFT 点数、双边谱、不补零边界。输出经频率维 fftshift 后，算功率、归一化、转 dB、钳位下限，封装为 谱图结果对象（时间轴、频率轴、分贝矩阵、复 STFT 矩阵）。

多脉冲场景传入 时间偏移量，使时间轴加上片段在原始序列中的起始时刻。

7.4 片段截取

带保护边距截取：在起止索引外各扩展若干样点，用于观察脉冲边沿；单脉冲默认可设脉宽比例边距，多脉冲默认可设最小脉宽比例边距。

多脉冲序列构造：

保留空隙模式：一次截取 [首脉冲起点, 末脉冲终点] 连续 IQ；
拼接模式：各脉冲片段首尾相连，破坏 PRI 时间关系。

第九章参数调优

9.1 窗长

增大窗长：频率分辨率提高，Chirp 斜线更 sharp，但时间分辨率下降，短脉冲可能只得到很少时间帧；
减小窗长：时间分辨率提高，适合窄脉冲或快速相位跳变，但频率方向更模糊，Chirp 变"粗"。

经验：窗长宜为脉宽样点数的 1/5～1/2。本例脉宽约 430 点，窗长 256 点属合理范围。

9.2 重叠

重叠越大，时间方向采样越密，图更平滑，计算量增大。默认 256 窗、192 重叠（75%）是偏平滑的配置。

9.3 FFT 点数

大于窗长时可零填充，插值频率轴，不增加真实分辨率，但使斜线视觉更连续。4096 点对 125 MHz 采样足够细。

9.4 动态范围下限

−40 dB（默认）：突出主 Chirp，抑制弱泄漏（当前图较干净）；
−60 dB：可见更多旁瓣、弱干扰（图更"花"）；
−80 dB：接近噪声底，适合诊断杂散。

9.5 检测参数

脉宽、PRI 与 SNR 变化时，需同步调整最小脉宽、合并间隙、噪声分位数，否则截取区间不准，时频图会 切掉 Chirp 头尾 或 带入相邻脉冲。

第十章与雷达脉压理论的联系

10.1 LFM 与 Chirp 斜线

线性调频脉冲：

瞬时频率 = 中心频率 + 调频率 × 时间

调频率 = 带宽 / 脉宽。时频图斜率即调频率。脉压匹配滤波器与发射 Chirp 共轭匹配，压缩后获得 c/(2B) 量级距离分辨率。本数据 Chirp 清晰，说明 适合作为脉压算法验证的输入。

10.2 PRI 与多脉冲图

脉冲重复间隔决定：

最大无模糊距离；
多普勒采样（PRF）；
时频图上斜线 水平间距。

本图 PRI ≈ 19 μs，PRF ≈ 52 kHz，属中等 PRF 量级（具体模糊距离需结合波长）。

10.3 零中频基带表示

IQ 为 复基带 ，负频率并非"物理负射频"，而是 基带频偏。Chirp 从 −20 MHz 到 +20 MHz 表示相对载波频率偏移在该范围扫描，总占用约 40 MHz 基带带宽，小于 Nyquist（62.5 MHz），无混叠。

第十一章局限性与注意事项

非绝对功率：归一化 dB 只能做相对比较；
STFT 固有模糊：无法同时达到极窄时间、极窄频率；极短脉冲需减小窗长；
水平条纹：需结合 SNR、窗函数、是否 CW 干扰综合判断；
采样率必须正确：125 MHz 误设为其他值会导致频率轴整体缩放错误；
仅 STFT：未使用 Wigner-Ville、小波等；交叉项、高阶调制可能需要别的方法；

第十二章两张上传图的综合结论

针对 generate_pulse_compress_iq.txt 在 125 MHz、双阈值检测、默认 STFT 下生成的结果：

单脉冲时频图 表明：所选脉冲为 上行线性调频，主能量脊线约跨越 10 MHz 基带带宽，形态符合 LFM 脉压波形；水平弱线为噪声与 STFT 旁瓣的正常表现。

多脉冲时频图 表明：全段共 8 个同型 LFM 脉冲 ，PRI 基本恒定，脉内调制稳定；脉间空隙在时频平面上为低能量区，证明 保留原始时间轴 策略有效；贯穿的水平结构以噪声底和可能的窄带干扰为主，不影响对主 Chirp 串的识别。

两张图Together 完整回答了雷达分析中的两个基本问题："一个脉冲里频率怎么变？" 以及 "一串脉冲在时间上如何重复？" ------这正是 pipeline_time_frequency_from_iq.py 的设计目标。

结论

本流水线实现了 可复现、可配置、可审计 的 IQ 时频可视化链路：脉冲检测解决"看哪一段"，STFT 解决"怎么显示频率随时间变化"，双图策略分别服务 脉内微观 与 脉间宏观 分析。结合雷达 LFM 脉压理论，两张谱图清晰展示了一条 8 脉冲、恒定 PRI、线性调频 的仿真雷达信号。

原始 IQ 数据时频图生成