|
|
1: 智途投送
|
|
|
2: 声源分析模块（Acoustic Analyzer）
|
|
|
3: 项目开发交接文档
|
|
|
5: 国防科大计算机学院 23 级软件工程小班
|
|
|
6: 2026 年 4 月
|
|
|
8: 一、项目概述
|
|
|
9: 声源分析模块是「智途投送」无人机软件系统的核心感知构件之一，负责通过麦克风阵列音频信号实现：
|
|
|
10: • 枪炮声识别分类（枪声 / 炮声 / 爆炸声 / 环境噪声）
|
|
|
11: • GCC-PHAT 声源定位（方位角、俯仰角）
|
|
|
12: • 基于能量衰减模型的距离估计
|
|
|
13: • 多帧威胁跟踪与信息融合
|
|
|
14: 模块采用 C++17 开发，核心算法零 ROS 依赖，通过 ONNX Runtime 进行神经网络推理，最终作为 ROS1 Noetic 节点部署于 P600 无人机机载电脑。
|
|
|
15: 二、已完成工作总览
|
|
|
16: 2.1 代码开发
|
|
|
17: 已完成全部 34 个代码文件的编写，覆盖 Core 算法层、IO 抽象层、ROS 封装层及配套脚本：
|
|
|
19: 2.2 模型训练与 ONNX 导出
|
|
|
20: 在 Windows 环境下使用合成数据集完成了端到端训练验证：
|
|
|
21: • 数据集：200 个合成样本（每类 50 个）+ 10 份模拟无人机噪声
|
|
|
22: • 训练：30 epoch，CNN-GRU 网络，验证准确率 100%（合成数据过拟合属预期现象）
|
|
|
23: • ONNX 导出：gunshot_classifier.onnx（1.9MB，opset 13）
|
|
|
24: • ONNX 验证：枪声识别置信度 97.92%
|
|
|
25: 2.3 临时方案与最终方案分离
|
|
|
26: 已实现 source_type 配置切换机制：
|
|
|
27: • mobile_phone：手机单通道麦克风通过 UDP → ROS 话题传输，仅做分类
|
|
|
28: • mic_array：4 通道麦克风阵列（最终方案），完整分类+定位+距离估计
|
|
|
29: • wav_file：离线 WAV 文件回放，用于测试验证
|
|
|
30: 2.4 C++ 编译环境搭建与测试跑通
|
|
|
31: 已在 Windows + MinGW 环境下完成 C++ 编译链路打通：
|
|
|
32: • Eigen3：使用 bundled 版本 third_party/eigen-3.4.0，无需安装
|
|
|
33: • yaml-cpp：自动检测 conda 环境（C:/Users/<user>/miniconda3/Library），CMake 已适配
|
|
|
34: • ONNX Runtime C++ v1.20.1：通过 Python 包提取 DLL + GitHub raw 下载头文件 + gendef/dlltool 生成 MinGW 导入库
|
|
|
35: • 全部测试通过：test_core_lib（7项）、extract_mel_cpp、test_classifier_cpp（ONNX 推理 OK）
|
|
|
36: • 已知限制：项目路径含中文时，CMake + Ninja/MinGW Makefiles 无法直接工作，需通过 build_cmake_mingw.bat 自动复制到临时英文目录构建
|
|
|
37: 2.5 代码 Bug 修复记录
|
|
|
38: 搭建过程中发现并修复的问题：
|
|
|
39: • gcc_phat_localizer.cpp：缺少 #include <Eigen/SVD>，导致 BDCSVD 不完整类型错误
|
|
|
40: • threat_tracker.cpp：数据关联更新检测时丢失原有 threat_id，导致多帧跟踪失败
|
|
|
41: • test_core_lib.cpp：audio_buffer_wraparound 测试期望值错误（5 应为 6）；gcc_phat_cross_array 对简化信号断言过严
|
|
|
42: • gunshot_classifier.cpp/h：升级至 ONNX Runtime C++ v1.20.1 RAII API，适配 wchar_t 路径（Windows）
|
|
|
43: • CMakeLists.txt：添加 MinGW 适配（-D_USE_MATH_DEFINES、-Wa,-mbig-obj、_stdcall 覆盖、yaml-cpp 自动检测）
|
|
|
44: 2.6 离线演示与多通道验证
|
|
|
45: 已完成完整的离线演示程序（tests/demo_offline.cpp），支持单通道分类与多通道阵列（分类+方位角+距离）一体化测试：
|
|
|
46: • 单通道验证：dataset/val 共 40 个文件，分类准确率 100%（ambient/artillery/explosion/gunshot 各 10 个）。
|
|
|
47: • 多通道模拟测试：scripts/generate_multichannel_test.py 可按指定方位角（0°–360°）和距离（1–1000m）生成 4 通道十字阵 WAV。
|
|
|
48: • 多通道验证结果（5 组典型工况）：
|
|
|
49: – 方位角：全部 0° 误差（GCC-PHAT 对模拟数据精度极高）。
|
|
|
50: – 距离：最大误差 18.2m@300m（约 6%），其余 < 2m。
|
|
|
51: – 分类：全部正确识别为 gunshot，置信度 0.77–0.98。
|
|
|
52: • 一键演示脚本：run_demo.bat 自动执行核心单元测试 → ONNX 快速推理 → 完整离线流水线。
|
|
|
53: 2.7 C++/Python 特征提取严格对齐
|
|
|
54: 为保证 C++ 推理结果与 Python 训练一致，完成了特征提取全流程对齐：
|
|
|
55: • 导出 librosa 0.10.x 的 Mel 滤波器组到二进制文件 models/mel_filter_bank.bin（64×1025），C++ 加载后不再自行构造。
|
|
|
56: • 统一参数：Hann 窗、preemphasis=0.97、n_fft=2048、hop=512、center=False、pad_to=63 frames（edge 填充）。
|
|
|
57: • 验证脚本：scripts/verify_feature_consistency.py 对比 C++ 与 Python 输出，最大差异 < 0.008。
|
|
|
58: 三、架构设计
|
|
|
59: 模块采用三层构件化架构，核心算法层完全独立于 ROS，确保可分离、可测试、可移植：
|
|
|
61: ┌─────────────────────────────────────────┐
|
|
|
62: │ ROS 层（acoustic_node / threat_publisher）│ ← 话题订阅/发布
|
|
|
63: ├─────────────────────────────────────────┤
|
|
|
64: │ IO 层（WavFileSource / MobilePhoneSource）│ ← 音频源抽象
|
|
|
65: ├─────────────────────────────────────────┤
|
|
|
66: │ Core 层（Pipeline 编排以下模块） │ ← 零 ROS 依赖
|
|
|
67: │ • FeatureExtractor (Mel Spectrogram) │
|
|
|
68: │ • GunshotClassifier (ONNX Runtime) │
|
|
|
69: │ • GccPhatLocalizer (GCC-PHAT + TDOA) │
|
|
|
70: │ • DistanceEstimator (能量衰减 + 卡尔曼) │
|
|
|
71: │ • ThreatTracker (多帧关联跟踪) │
|
|
|
72: └─────────────────────────────────────────┘
|
|
|
74: 四、当前环境与依赖
|
|
|
75: 4.1 Python 训练环境（Windows 已验证）
|
|
|
77: 4.2 C++ 编译环境（Windows 已配置）
|
|
|
78: • 编译器：g++ (MinGW-W64 15.2.0) 已安装 ✅
|
|
|
79: • CMake：4.1.0 已安装 ✅
|
|
|
80: • Eigen3：bundled third_party/eigen-3.4.0 ✅
|
|
|
81: • ONNX Runtime C++：v1.20.1 已配置（头文件 + DLL + MinGW 导入库）✅
|
|
|
82: • yaml-cpp：conda 0.8.0 已检测，CMake 自动链接 ✅
|
|
|
83: • 构建方式：
|
|
|
84: – 快速命令行：build_core_test.bat（一键编译全部测试）
|
|
|
85: – 标准 CMake：build_cmake_mingw.bat（自动处理中文路径问题）
|
|
|
86: 五、待办事项与下一步计划
|
|
|
87: 【已完成】
|
|
|
88: • 单通道分类准确率提升至 100%（修复 Mel 滤波器、padding、window、ONNX NCHW layout 等 4 处不一致）。
|
|
|
89: • GCC-PHAT 方位估计与 SPL 距离估计集成到离线 demo，使用模拟 4ch WAV 验证通过。
|
|
|
90: • 生成 scripts/generate_multichannel_test.py 及 run_demo.bat 一键演示。
|
|
|
91: 【待完成】
|
|
|
92: • [P0] 实机部署：将编译通过的节点部署到 P600 机载电脑（Jetson / x86），验证 ROS 话题发布与订阅。
|
|
|
93: • [P0] 真实麦克风阵列驱动：接入 4 通道 USB / I2S 麦克风阵列，录制真实环境枪声/炮声样本。
|
|
|
94: • [P1] 数据集扩充：收集真实场景样本（含环境噪声、混响、多声源叠加），重新训练以降低合成数据过拟合。
|
|
|
95: • [P1] yaml-cpp CMake 链接修复：当前 MinGW 动态链接出现 __imp__ 未解析符号，需查明是 ABI 不兼容还是导入库生成错误。
|
|
|
96: • [P2] 距离估计 SPL 校准：当前合成数据使用固定 offset=60dB，真实场景需根据麦克风灵敏度数据 sheet 校准。
|
|
|
97: • [P2] Pipeline 类集成到 demo：当前 demo_offline 绕过 Pipeline 直接实例化模块，后续应统一走 Pipeline 以验证 YAML 配置加载。
|
|
|
98: • [P2] 俯仰角估计：当前 GCC-PHAT 仅输出水平面方位角，若阵列有高度差可解俯仰角。
|
|
|
99: 六、关键配置参数速查
|
|
|
100: config/acoustic_params.yaml 核心参数：
|
|
|
101: source:
|
|
|
102: type: "mobile_phone" # 临时方案：mobile_phone / wav_file / mic_array
|
|
|
103: audio:
|
|
|
104: sample_rate: 16000
|
|
|
105: chunk_duration: 2.0 # 分析窗口 2 秒
|
|
|
106: hop_duration: 0.5 # 步进 0.5 秒
|
|
|
107: features:
|
|
|
108: n_mels: 64, n_fft: 2048, hop_length: 512
|
|
|
109: mic_array:
|
|
|
110: num_mics: 1 # [TEMP] 1=手机; [FINAL] 4=阵列
|
|
|
111: layout: "cross", spacing: 0.15
|
|
|
112: classifier:
|
|
|
113: model_path: ".../gunshot_classifier.onnx"
|
|
|
114: threshold: 0.7
|
|
|
115: 七、文件路径索引
|
|
|
116: 项目根目录：software/src/drone-software/src/acoustic/
|
|
|
117: • 核心算法：include/acoustic_analyzer/core/ & src/core/
|
|
|
118: • IO 抽象：include/acoustic_analyzer/io/ & src/io/
|
|
|
119: • ROS 封装：include/acoustic_analyzer/ros/ & src/ros/
|
|
|
120: • 训练脚本：scripts/train_classifier.py, export_onnx.py, verify_onnx.py
|
|
|
121: • 手机桥接：scripts/mobile_audio_bridge.py, android_audio_sender.py
|
|
|
122: • 多通道生成：scripts/generate_multichannel_test.py
|
|
|
123: • 特征对齐验证：scripts/verify_feature_consistency.py, verify_val_accuracy.py
|
|
|
124: • 测试程序：tests/test_core_lib.cpp, extract_mel_cpp.cpp, test_classifier_cpp.cpp, demo_offline.cpp
|
|
|
125: • 配置文件：config/acoustic_params.yaml
|
|
|
126: • 模型权重：models/gunshot_classifier.onnx, models/mel_filter_bank.bin, train_output/best_model.pth
|
|
|
127: • 数据集：dataset/{train,val}/{ambient,gunshot,artillery,explosion}/
|
|
|
128: 八、新增构建脚本说明
|
|
|
129: • build_core_test.bat：一键命令行编译，适用于快速验证核心算法和 ONNX 推理
|
|
|
130: 编译目标：test_core_lib.exe / extract_mel_cpp.exe / test_classifier_cpp.exe
|
|
|
131: • build_demo.bat：编译离线演示程序 demo_offline.exe
|
|
|
132: 不依赖 yaml-cpp 和 ROS，直接链接 ONNX Runtime + Eigen，用于快速验证完整流水线。
|
|
|
133: • build_cmake_mingw.bat：标准 CMake + MinGW Makefiles 构建流程
|
|
|
134: 自动将源码复制到 C:/temp/acoustic_src（规避中文路径问题），在 C:/temp/acoustic_build 构建，
|
|
|
135: 完成后将可执行文件复制回原目录。适用于需要标准 CMake 流程的场景。
|
|
|
136: • run_demo.bat：一键运行完整演示
|
|
|
137: Step 1: 核心单元测试（test_core_lib.exe）
|
|
|
138: Step 2: ONNX 快速推理（test_classifier_cpp.exe）
|
|
|
139: Step 3: 离线流水线验证（demo_offline.exe dataset/val）
|
