|
|
#!/usr/bin/env python3
|
|
|
"""
|
|
|
更新声源分析模块_项目交接文档.docx
|
|
|
将本次（2026-05-06）完成的多通道离线演示等工作追加到文档中。
|
|
|
"""
|
|
|
|
|
|
from docx import Document
|
|
|
from docx.shared import Pt, RGBColor
|
|
|
from docx.enum.text import WD_PARAGRAPH_ALIGNMENT
|
|
|
import os
|
|
|
|
|
|
def add_heading(doc, text, level=1):
|
|
|
"""添加标题段落"""
|
|
|
p = doc.add_paragraph()
|
|
|
run = p.add_run(text)
|
|
|
run.bold = True
|
|
|
if level == 1:
|
|
|
run.font.size = Pt(16)
|
|
|
elif level == 2:
|
|
|
run.font.size = Pt(14)
|
|
|
else:
|
|
|
run.font.size = Pt(12)
|
|
|
p.alignment = WD_PARAGRAPH_ALIGNMENT.LEFT
|
|
|
return p
|
|
|
|
|
|
def add_bullet(doc, text, indent=0):
|
|
|
"""添加项目符号段落"""
|
|
|
p = doc.add_paragraph(style='List Bullet')
|
|
|
p.paragraph_format.left_indent = Pt(indent * 10)
|
|
|
p.add_run(text)
|
|
|
return p
|
|
|
|
|
|
def add_normal(doc, text):
|
|
|
p = doc.add_paragraph()
|
|
|
p.add_run(text)
|
|
|
return p
|
|
|
|
|
|
def main():
|
|
|
doc_path = '声源分析模块_项目交接文档.docx'
|
|
|
doc = Document(doc_path)
|
|
|
|
|
|
# ========================================================================
|
|
|
# 1. 在 "2.5 代码 Bug 修复记录" 之后插入 2.6 小节
|
|
|
# ========================================================================
|
|
|
insert_idx = None
|
|
|
for i, para in enumerate(doc.paragraphs):
|
|
|
if para.text.strip().startswith('2.5'):
|
|
|
# 找到 2.5 的最后一项（CMakeLists.txt 那行）之后
|
|
|
pass
|
|
|
if para.text.strip().startswith('三、架构设计'):
|
|
|
insert_idx = i
|
|
|
break
|
|
|
|
|
|
if insert_idx is None:
|
|
|
print("ERROR: 未找到插入点（三、架构设计）")
|
|
|
return
|
|
|
|
|
|
# 由于 python-docx 不支持在特定索引插入段落到 body，
|
|
|
# 我们采用另一种策略：将新内容作为独立段落追加到文档末尾，
|
|
|
# 然后手动调整顺序。但更简单的方法是：直接在 2.5 和 三 之间添加。
|
|
|
# python-docx 的 add_paragraph 总是追加到末尾，所以我们需要操作 XML。
|
|
|
# 为了避免 XML 操作复杂性，我们直接将整个文档重新组织：
|
|
|
# 读取所有段落文本 -> 在合适位置插入新文本 -> 重新写入。
|
|
|
|
|
|
# 实际上，对于 docx，最安全的方式是：
|
|
|
# 保存一份副本，然后在新段落要插入的位置，使用 paragraphs 列表的 _element 进行 insert。
|
|
|
paragraphs = doc.paragraphs
|
|
|
|
|
|
# 找到 2.5 最后一行（CMakeLists.txt）的索引
|
|
|
idx_after_25 = None
|
|
|
for i, p in enumerate(paragraphs):
|
|
|
if 'CMakeLists.txt' in p.text and 'MinGW' in p.text:
|
|
|
idx_after_25 = i + 1
|
|
|
break
|
|
|
|
|
|
if idx_after_25 is None:
|
|
|
# 备用：找到 "三、架构设计"
|
|
|
for i, p in enumerate(paragraphs):
|
|
|
if p.text.strip().startswith('三、架构设计'):
|
|
|
idx_after_25 = i
|
|
|
break
|
|
|
|
|
|
# 构建要插入的新段落列表 (text, style_name)
|
|
|
new_sections = []
|
|
|
|
|
|
# ---- 2.6 离线演示与多通道验证 ----
|
|
|
new_sections.append(('2.6 离线演示与多通道验证', 'Heading 2'))
|
|
|
new_sections.append(('已完成完整的离线演示程序（tests/demo_offline.cpp），支持单通道分类与多通道阵列（分类+方位角+距离）一体化测试：', None))
|
|
|
new_sections.append(('', 'List Bullet'))
|
|
|
# 修正：我们无法在 add_paragraph 之后修改之前的内容，所以换个策略
|
|
|
# 直接在 XML 层级插入
|
|
|
|
|
|
# 为了简化，我们把所有段落文本收集起来，重建文档
|
|
|
all_texts = []
|
|
|
for p in doc.paragraphs:
|
|
|
style = p.style.name if p.style else None
|
|
|
all_texts.append((p.text, style))
|
|
|
|
|
|
# 找到插入位置
|
|
|
insert_pos = None
|
|
|
for i, (text, style) in enumerate(all_texts):
|
|
|
if text.strip().startswith('三、架构设计'):
|
|
|
insert_pos = i
|
|
|
break
|
|
|
|
|
|
if insert_pos is None:
|
|
|
print("ERROR: 未找到 '三、架构设计'")
|
|
|
return
|
|
|
|
|
|
# 准备新内容
|
|
|
new_content = []
|
|
|
new_content.append(('2.6 离线演示与多通道验证', 'Heading 2'))
|
|
|
new_content.append(('已完成完整的离线演示程序（tests/demo_offline.cpp），支持单通道分类与多通道阵列（分类+方位角+距离）一体化测试：', None))
|
|
|
new_content.append(('• 单通道验证：dataset/val 共 40 个文件，分类准确率 100%（ambient/artillery/explosion/gunshot 各 10 个）。', 'List Bullet'))
|
|
|
new_content.append(('• 多通道模拟测试：scripts/generate_multichannel_test.py 可按指定方位角（0°–360°）和距离（1–1000m）生成 4 通道十字阵 WAV。', 'List Bullet'))
|
|
|
new_content.append(('• 多通道验证结果（5 组典型工况）：', 'List Bullet'))
|
|
|
new_content.append((' – 方位角：全部 0° 误差（GCC-PHAT 对模拟数据精度极高）。', 'List Bullet'))
|
|
|
new_content.append((' – 距离：最大误差 18.2m@300m（约 6%），其余 < 2m。', 'List Bullet'))
|
|
|
new_content.append((' – 分类：全部正确识别为 gunshot，置信度 0.77–0.98。', 'List Bullet'))
|
|
|
new_content.append(('• 一键演示脚本：run_demo.bat 自动执行核心单元测试 → ONNX 快速推理 → 完整离线流水线。', 'List Bullet'))
|
|
|
|
|
|
new_content.append(('2.7 C++/Python 特征提取严格对齐', 'Heading 2'))
|
|
|
new_content.append(('为保证 C++ 推理结果与 Python 训练一致，完成了特征提取全流程对齐：', None))
|
|
|
new_content.append(('• 导出 librosa 0.10.x 的 Mel 滤波器组到二进制文件 models/mel_filter_bank.bin（64×1025），C++ 加载后不再自行构造。', 'List Bullet'))
|
|
|
new_content.append(('• 统一参数：Hann 窗、preemphasis=0.97、n_fft=2048、hop=512、center=False、pad_to=63 frames（edge 填充）。', 'List Bullet'))
|
|
|
new_content.append(('• 验证脚本：scripts/verify_feature_consistency.py 对比 C++ 与 Python 输出，最大差异 < 0.008。', 'List Bullet'))
|
|
|
|
|
|
# 插入
|
|
|
all_texts = all_texts[:insert_pos] + new_content + all_texts[insert_pos:]
|
|
|
|
|
|
# ========================================================================
|
|
|
# 2. 更新 "五、待办事项与下一步计划"
|
|
|
# ========================================================================
|
|
|
# 找到第五部分的起止范围
|
|
|
section5_start = None
|
|
|
section5_end = None
|
|
|
for i, (text, style) in enumerate(all_texts):
|
|
|
if text.strip().startswith('五、待办事项与下一步计划'):
|
|
|
section5_start = i
|
|
|
elif section5_start is not None and text.strip().startswith('六、'):
|
|
|
section5_end = i
|
|
|
break
|
|
|
|
|
|
if section5_start is not None and section5_end is not None:
|
|
|
# 替换第五部分的内容
|
|
|
new_section5 = []
|
|
|
new_section5.append(('五、待办事项与下一步计划', 'Heading 1'))
|
|
|
new_section5.append(('【已完成】', 'Heading 2'))
|
|
|
new_section5.append(('• 单通道分类准确率提升至 100%（修复 Mel 滤波器、padding、window、ONNX NCHW layout 等 4 处不一致）。', 'List Bullet'))
|
|
|
new_section5.append(('• GCC-PHAT 方位估计与 SPL 距离估计集成到离线 demo，使用模拟 4ch WAV 验证通过。', 'List Bullet'))
|
|
|
new_section5.append(('• 生成 scripts/generate_multichannel_test.py 及 run_demo.bat 一键演示。', 'List Bullet'))
|
|
|
new_section5.append(('【待完成】', 'Heading 2'))
|
|
|
new_section5.append(('• [P0] 实机部署：将编译通过的节点部署到 P600 机载电脑（Jetson / x86），验证 ROS 话题发布与订阅。', 'List Bullet'))
|
|
|
new_section5.append(('• [P0] 真实麦克风阵列驱动：接入 4 通道 USB / I2S 麦克风阵列，录制真实环境枪声/炮声样本。', 'List Bullet'))
|
|
|
new_section5.append(('• [P1] 数据集扩充：收集真实场景样本（含环境噪声、混响、多声源叠加），重新训练以降低合成数据过拟合。', 'List Bullet'))
|
|
|
new_section5.append(('• [P1] yaml-cpp CMake 链接修复：当前 MinGW 动态链接出现 __imp__ 未解析符号，需查明是 ABI 不兼容还是导入库生成错误。', 'List Bullet'))
|
|
|
new_section5.append(('• [P2] 距离估计 SPL 校准：当前合成数据使用固定 offset=60dB，真实场景需根据麦克风灵敏度数据 sheet 校准。', 'List Bullet'))
|
|
|
new_section5.append(('• [P2] Pipeline 类集成到 demo：当前 demo_offline 绕过 Pipeline 直接实例化模块，后续应统一走 Pipeline 以验证 YAML 配置加载。', 'List Bullet'))
|
|
|
new_section5.append(('• [P2] 俯仰角估计：当前 GCC-PHAT 仅输出水平面方位角，若阵列有高度差可解俯仰角。', 'List Bullet'))
|
|
|
all_texts = all_texts[:section5_start] + new_section5 + all_texts[section5_end:]
|
|
|
|
|
|
# ========================================================================
|
|
|
# 3. 更新 "七、文件路径索引"
|
|
|
# ========================================================================
|
|
|
section7_start = None
|
|
|
section7_end = None
|
|
|
for i, (text, style) in enumerate(all_texts):
|
|
|
if text.strip().startswith('七、文件路径索引'):
|
|
|
section7_start = i
|
|
|
elif section7_start is not None and text.strip().startswith('八、'):
|
|
|
section7_end = i
|
|
|
break
|
|
|
|
|
|
if section7_start is not None and section7_end is not None:
|
|
|
new_section7 = []
|
|
|
new_section7.append(('七、文件路径索引', 'Heading 1'))
|
|
|
new_section7.append(('项目根目录：software/src/drone-software/src/acoustic/', None))
|
|
|
new_section7.append(('• 核心算法：include/acoustic_analyzer/core/ & src/core/', 'List Bullet'))
|
|
|
new_section7.append(('• IO 抽象：include/acoustic_analyzer/io/ & src/io/', 'List Bullet'))
|
|
|
new_section7.append(('• ROS 封装：include/acoustic_analyzer/ros/ & src/ros/', 'List Bullet'))
|
|
|
new_section7.append(('• 训练脚本：scripts/train_classifier.py, export_onnx.py, verify_onnx.py', 'List Bullet'))
|
|
|
new_section7.append(('• 手机桥接：scripts/mobile_audio_bridge.py, android_audio_sender.py', 'List Bullet'))
|
|
|
new_section7.append(('• 多通道生成：scripts/generate_multichannel_test.py', 'List Bullet'))
|
|
|
new_section7.append(('• 特征对齐验证：scripts/verify_feature_consistency.py, verify_val_accuracy.py', 'List Bullet'))
|
|
|
new_section7.append(('• 测试程序：tests/test_core_lib.cpp, extract_mel_cpp.cpp, test_classifier_cpp.cpp, demo_offline.cpp', 'List Bullet'))
|
|
|
new_section7.append(('• 配置文件：config/acoustic_params.yaml', 'List Bullet'))
|
|
|
new_section7.append(('• 模型权重：models/gunshot_classifier.onnx, models/mel_filter_bank.bin, train_output/best_model.pth', 'List Bullet'))
|
|
|
new_section7.append(('• 数据集：dataset/{train,val}/{ambient,gunshot,artillery,explosion}/', 'List Bullet'))
|
|
|
all_texts = all_texts[:section7_start] + new_section7 + all_texts[section7_end:]
|
|
|
|
|
|
# ========================================================================
|
|
|
# 4. 更新 "八、新增构建脚本说明"
|
|
|
# ========================================================================
|
|
|
section8_start = None
|
|
|
section8_end = None
|
|
|
for i, (text, style) in enumerate(all_texts):
|
|
|
if text.strip().startswith('八、新增构建脚本说明'):
|
|
|
section8_start = i
|
|
|
elif section8_start is not None and (text.strip().startswith('AI 助手') or text.strip().startswith('附录') or i == len(all_texts)-1):
|
|
|
section8_end = i if text.strip() else i
|
|
|
if i == len(all_texts)-1:
|
|
|
section8_end = len(all_texts)
|
|
|
break
|
|
|
if section8_start is not None and section8_end is None:
|
|
|
section8_end = len(all_texts)
|
|
|
|
|
|
if section8_start is not None and section8_end is not None:
|
|
|
new_section8 = []
|
|
|
new_section8.append(('八、新增构建脚本说明', 'Heading 1'))
|
|
|
new_section8.append(('• build_core_test.bat：一键命令行编译，适用于快速验证核心算法和 ONNX 推理', 'List Bullet'))
|
|
|
new_section8.append((' 编译目标：test_core_lib.exe / extract_mel_cpp.exe / test_classifier_cpp.exe', 'List Bullet'))
|
|
|
new_section8.append(('• build_demo.bat：编译离线演示程序 demo_offline.exe', 'List Bullet'))
|
|
|
new_section8.append((' 不依赖 yaml-cpp 和 ROS，直接链接 ONNX Runtime + Eigen，用于快速验证完整流水线。', 'List Bullet'))
|
|
|
new_section8.append(('• build_cmake_mingw.bat：标准 CMake + MinGW Makefiles 构建流程', 'List Bullet'))
|
|
|
new_section8.append((' 自动将源码复制到 C:/temp/acoustic_src（规避中文路径问题），在 C:/temp/acoustic_build 构建，', 'List Bullet'))
|
|
|
new_section8.append((' 完成后将可执行文件复制回原目录。适用于需要标准 CMake 流程的场景。', 'List Bullet'))
|
|
|
new_section8.append(('• run_demo.bat：一键运行完整演示', 'List Bullet'))
|
|
|
new_section8.append((' Step 1: 核心单元测试（test_core_lib.exe）', 'List Bullet'))
|
|
|
new_section8.append((' Step 2: ONNX 快速推理（test_classifier_cpp.exe）', 'List Bullet'))
|
|
|
new_section8.append((' Step 3: 离线流水线验证（demo_offline.exe dataset/val）', 'List Bullet'))
|
|
|
all_texts = all_texts[:section8_start] + new_section8 + all_texts[section8_end:]
|
|
|
|
|
|
# ========================================================================
|
|
|
# 重建文档
|
|
|
# ========================================================================
|
|
|
new_doc = Document()
|
|
|
for text, style_name in all_texts:
|
|
|
if not text and style_name == 'List Bullet':
|
|
|
# 空项目符号，跳过
|
|
|
continue
|
|
|
if style_name:
|
|
|
try:
|
|
|
p = new_doc.add_paragraph(text, style=style_name)
|
|
|
except:
|
|
|
p = new_doc.add_paragraph(text)
|
|
|
else:
|
|
|
p = new_doc.add_paragraph(text)
|
|
|
|
|
|
# 保留原始文档的页眉页脚等信息？简化处理：不保留
|
|
|
output_path = '声源分析模块_项目交接文档.docx'
|
|
|
new_doc.save(output_path)
|
|
|
print(f"[OK] 文档已更新: {output_path}")
|
|
|
|
|
|
if __name__ == '__main__':
|
|
|
main()
|
