# Acoustic Analyzer Module

无人机声学威胁检测模块，基于深度学习（CNN-GRU）的枪声/爆炸声分类器，结合麦克风阵列 GCC-PHAT 定位与 SPL 衰减模型测距。

## 模块结构

```
acoustic/
├── include/acoustic_analyzer/     # 公共头文件
│   ├── core/                      # 核心算法
│   │   ├── audio_buffer.h         # 音频循环缓冲区
│   │   ├── distance_estimator.h   # SPL 距离估计器
│   │   ├── feature_extractor.h    # Mel 频谱图提取
│   │   ├── fft_utils.h            # FFT 工具
│   │   ├── gcc_phat_localizer.h   # GCC-PHAT 声源定位
│   │   ├── gunshot_classifier.h   # ONNX 分类器
│   │   ├── pipeline.h             # 完整处理流水线
│   │   ├── threat_tracker.h       # 威胁跟踪/去重
│   │   └── types.h                # 公共类型定义
│   ├── io/                        # 音频输入源
│   │   ├── audio_source.h
│   │   ├── mobile_phone_source.h
│   │   └── wav_file_source.h      # WAV 文件读取
│   └── ros/                       # ROS 包装器
│       ├── acoustic_node.h
│       └── threat_publisher.h
├── src/                           # 实现文件
│   ├── core/
│   ├── io/
│   └── ros/
├── tests/                         # 测试程序
│   ├── demo_offline.cpp           # 离线推理演示
│   ├── test_core_lib.cpp
│   ├── test_classifier_cpp.cpp
│   └── extract_mel_cpp.cpp
├── scripts/                       # Python 训练/导出脚本
│   ├── train_binary_classifier.py
│   ├── export_onnx.py
│   ├── generate_dataset.py
│   └── verify_val_accuracy.py
├── models/                        # 模型文件
│   ├── gunshot_classifier.onnx
│   ├── label_map.json
│   └── mel_filter_bank.bin
├── config/
│   └── acoustic_params.yaml       # 流水线配置
├── third_party/                   # 头文件级依赖
│   ├── eigen-3.4.0/               # 矩阵运算
│   └── onnxruntime/               # ONNX Runtime C++ API
├── CMakeLists.txt
├── build_demo.bat                 # Windows 一键编译
├── batch_test.bat                 # Windows 一键测试
└── package.xml                    # ROS 包描述
```

## 快速开始（Windows + MinGW）

### 1. 编译离线演示程序

```bat
build_demo.bat
```

### 2. 运行单文件测试

```bat
build\demo_offline.exe dataset\binary\val\ambient\drone_noise_val_000.wav
build\demo_offline.exe dataset\binary\val\threat\synth_threat_val_000.wav
```

### 3. 批量验证整个数据集

```bat
batch_test.bat
:: 或直接传目录（支持递归子目录）
build\demo_offline.exe dataset\binary\val
```

### 4. 使用自定义模型

```bat
build\demo_offline.exe some_audio.wav --model my_model.onnx --label_map my_labels.json
```

## 模型训练（Python）

```bash
# 1. 生成合成数据集（或准备真实音频）
cd scripts
python generate_dataset.py

# 2. 训练二分类器
python train_binary_classifier.py --data_dir ../dataset/binary --epochs 50

# 3. 导出 ONNX
python export_onnx.py --checkpoint checkpoints/best.pth --output ../models/gunshot_classifier.onnx
```

## ROS 集成（Ubuntu）

```bash
cd ~/catkin_ws/src
git clone <repo_url>
cd ~/catkin_ws
catkin_make -DCMAKE_BUILD_TYPE=Release
source devel/setup.bash
roslaunch acoustic_analyzer acoustic_node.launch
```

## 依赖

| 依赖 | 用途 | 状态 |
|------|------|------|
| Eigen 3.4.0 | 矩阵运算 | Bundled |
| ONNX Runtime 1.17+ | 模型推理 | Bundled headers + DLL/lib |
| yaml-cpp | 配置解析 | Ubuntu: `apt install libyaml-cpp-dev` |
| kiss_fft | ~~FFT~~ | **已移除**，使用内联实现 |

## 已知限制

- 当前分类器基于合成数据集训练，仅用于代码集成验证。实际部署需真实威胁音频重新训练。
- Windows 下完整流水线（Pipeline 类）需要 yaml-cpp，离线 demo 已绕过此依赖。
- 距离估计依赖 SPL 校准，合成音频的归一化幅度会导致距离值偏大。

## 更新日志

详见 [CHANGELOG.md](CHANGELOG.md)。

## 许可证

与父项目保持一致。
