|
|
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: 三、架构设计
|
|
|
45: 模块采用三层构件化架构，核心算法层完全独立于 ROS，确保可分离、可测试、可移植：
|
|
|
47: ┌─────────────────────────────────────────┐
|
|
|
48: │ ROS 层（acoustic_node / threat_publisher）│ ← 话题订阅/发布
|
|
|
49: ├─────────────────────────────────────────┤
|
|
|
50: │ IO 层（WavFileSource / MobilePhoneSource）│ ← 音频源抽象
|
|
|
51: ├─────────────────────────────────────────┤
|
|
|
52: │ Core 层（Pipeline 编排以下模块） │ ← 零 ROS 依赖
|
|
|
53: │ • FeatureExtractor (Mel Spectrogram) │
|
|
|
54: │ • GunshotClassifier (ONNX Runtime) │
|
|
|
55: │ • GccPhatLocalizer (GCC-PHAT + TDOA) │
|
|
|
56: │ • DistanceEstimator (能量衰减 + 卡尔曼) │
|
|
|
57: │ • ThreatTracker (多帧关联跟踪) │
|
|
|
58: └─────────────────────────────────────────┘
|
|
|
60: 四、当前环境与依赖
|
|
|
61: 4.1 Python 训练环境（Windows 已验证）
|
|
|
63: 4.2 C++ 编译环境（Windows 已配置）
|
|
|
64: • 编译器：g++ (MinGW-W64 15.2.0) 已安装 ✅
|
|
|
65: • CMake：4.1.0 已安装 ✅
|
|
|
66: • Eigen3：bundled third_party/eigen-3.4.0 ✅
|
|
|
67: • ONNX Runtime C++：v1.20.1 已配置（头文件 + DLL + MinGW 导入库）✅
|
|
|
68: • yaml-cpp：conda 0.8.0 已检测，CMake 自动链接 ✅
|
|
|
69: • 构建方式：
|
|
|
70: – 快速命令行：build_core_test.bat（一键编译全部测试）
|
|
|
71: – 标准 CMake：build_cmake_mingw.bat（自动处理中文路径问题）
|
|
|
72: 五、待办事项与下一步计划
|
|
|
74: 六、关键配置参数速查
|
|
|
75: config/acoustic_params.yaml 核心参数：
|
|
|
76: source:
|
|
|
77: type: "mobile_phone" # 临时方案：mobile_phone / wav_file / mic_array
|
|
|
78: audio:
|
|
|
79: sample_rate: 16000
|
|
|
80: chunk_duration: 2.0 # 分析窗口 2 秒
|
|
|
81: hop_duration: 0.5 # 步进 0.5 秒
|
|
|
82: features:
|
|
|
83: n_mels: 64, n_fft: 2048, hop_length: 512
|
|
|
84: mic_array:
|
|
|
85: num_mics: 1 # [TEMP] 1=手机; [FINAL] 4=阵列
|
|
|
86: layout: "cross", spacing: 0.15
|
|
|
87: classifier:
|
|
|
88: model_path: ".../gunshot_classifier.onnx"
|
|
|
89: threshold: 0.7
|
|
|
90: 七、文件路径索引
|
|
|
91: 项目根目录：software/src/drone-software/src/acoustic/
|
|
|
92: • 核心算法：include/acoustic_analyzer/core/ & src/core/
|
|
|
93: • IO 抽象：include/acoustic_analyzer/io/ & src/io/
|
|
|
94: • ROS 封装：include/acoustic_analyzer/ros/ & src/ros/
|
|
|
95: • 训练脚本：scripts/train_classifier.py, export_onnx.py, verify_onnx.py
|
|
|
96: • 手机桥接：scripts/mobile_audio_bridge.py, android_audio_sender.py
|
|
|
97: • 测试程序：tests/test_core_lib.cpp, extract_mel_cpp.cpp, test_classifier_cpp.cpp
|
|
|
98: • 配置文件：config/acoustic_params.yaml
|
|
|
99: • 模型权重：models/gunshot_classifier.onnx, train_output/best_model.pth
|
|
|
100: • 数据集：dataset/{train,val}/{ambient,gunshot,artillery,explosion}/
|
|
|
101: 八、新增构建脚本说明
|
|
|
102: • build_core_test.bat：一键命令行编译，适用于快速验证核心算法和 ONNX 推理
|
|
|
103: 编译目标：test_core_lib.exe / extract_mel_cpp.exe / test_classifier_cpp.exe
|
|
|
104: • build_cmake_mingw.bat：标准 CMake + MinGW Makefiles 构建流程
|
|
|
105: 自动将源码复制到 C:/temp/acoustic_src（规避中文路径问题），在 C:/temp/acoustic_build 构建，
|
|
|
106: 完成后将可执行文件复制回原目录。适用于需要标准 CMake 流程的场景。
|
|
|
108: AI 助手将读取本文档及项目代码，基于当前状态继续推进。
|
