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 助手将读取本文档及项目代码，基于当前状态继续推进。