黑曜石项目 (Obsidian Project)

超音波空腔检测与生态监测系统 Sonar-based Cavity Detection and Ecological Monitoring System

---

📋 项目概况

黑曜石项目是一个综合的水下/沙地空腔检测系统，专注于：

• 🦐 生物应用: 螺蛄虾（Austinogebia edulis）洞穴识别与族群监测
• 🌍 地理范围: 台湾西部潮间带（王功地区）
• 🔧 核心硬件: Deeper Smart Sonar CHIRP+ 2 (675 kHz)
• 🧠 AI 模型: PointNet++ + Physics-informed GAN
• 📡 传输方案: 协议逆向工程 + 网关中继实时传输

项目愿景

从特定生物种（阿基米德船 → 螺蛄虾）扩展到通用的地下空腔检测平台（一般船艦），支持多物种、多地区、多硬件平台的应用。

---

🏗️ 项目结构

obsidian-project/
├── models/                          # 深度学习模型
│   ├── pointnet_plus_plus.py       # PointNet++ 核心架构
│   ├── geometric_prior.py           # Y型洞穴几何约束
│   └── physics_informed_gan.py      # Physics-informed GAN (待实现)
│
├── data/                            # 数据管理
│   ├── sonar_dataset.py            # 声纳点云数据加载器
│   ├── raw/                         # 原始现场数据
│   └── synthetic/                   # 合成训练数据
│
├── physics/                         # 物理模拟
│   ├── biot_simulator.py           # Biot理论声波传播模拟
│   └── synthetic_data_generator.py # 合成数据生成 (待实现)
│
├── training/                        # 训练脚本
│   ├── train_pointnet.py           # PointNet++ 训练流程
│   └── train_gan.py                # GAN 训练 (待实现)
│
├── analysis/                        # 数据分析
│   ├── penetration_analyzer.py      # 675kHz 穿透力分析
│   ├── signal_processor.py          # 信号处理工具 (待实现)
│   └── sonar_visualizer.py          # 可视化工具 (待实现)
│
├── reports/                         # 报告与评估
│   ├── hardware_evaluation.md       # 硬件方案对比与建议
│   ├── penetration_report.txt       # 穿透力评估报告 (自动生成)
│   └── training_history.json        # 训练历史 (自动生成)
│
└── README.md                        # 本文件

---

🚀 快速开始

1. 环境配置

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装依赖
pip install torch torchvision torchaudio
pip install numpy pandas scipy matplotlib
pip install scikit-learn tensorboard

2. 生成合成训练数据

from physics.biot_simulator import create_synthetic_dataset

# 生成 100 个合成样本
create_synthetic_dataset(
    num_samples=100,
    num_points=512,
    output_dir="E:\\Bally\\obsidian-project\\data\\synthetic"
)

3. 训练 PointNet++ 模型

cd training
python train_pointnet.py

输出：

• checkpoints/pointnet_sonar_v1/best_model.pt - 最佳模型
• checkpoints/pointnet_sonar_v1/training_history.json - 训练历史

4. 分析现场穿透力数据

from analysis.penetration_analyzer import analyze_field_data

# 分析现场 CSV 数据
analyze_field_data(
    csv_file="E:\\Bally\\Downloads\\field_data.csv",
    output_dir="E:\\Bally\\obsidian-project\\analysis_results"
)

输出：

• analysis_results/penetration_report.txt - 穿透力评估
• analysis_results/penetration_analysis.png - 衰减曲线图

---

📊 关键技术模块

PointNet++ 模型 (models/pointnet_plus_plus.py)

特点:

• ✓ 天然处理极坐标稀疏点云
• ✓ 显存效率高，支持 15Hz 实时推理
• ✓ 多尺度特征提取（Set Abstraction + Feature Propagation）
• ✓ 优于 3D U-Net 在稀疏数据上的性能

使用:

from models.pointnet_plus_plus import PointNetPlusPlus
import torch

model = PointNetPlusPlus(in_channels=6, num_classes=2)
xyz = torch.randn(2, 3, 1024)
features = torch.randn(2, 3, 1024)
logits = model(xyz, features)
print(logits.shape)  # (2, 2, 1024) - 分类logits

Biot 理论模拟 (physics/biot_simulator.py)

功能:

• ✓ 模拟声波在多孔隙饱和沙质介质中的传播
• ✓ 计算有效声学参数（P波速、衰减系数）
• ✓ 生成 Physics-informed 合成训练数据
• ✓ 支持空腔（空气/水填充）反射模拟

使用:

from physics.biot_simulator import BiotSimulator

sim = BiotSimulator(phi=0.4, k=1e-13)
time, amplitude = sim.simulate_pulse_response(
    frequency=675e3,
    distance=1.0,
    cavity_present=True,
    cavity_fill='air'
)

穿透力分析工具 (analysis/penetration_analyzer.py)

功能:

• ✓ 深度-回波强度曲线提取
• ✓ 有效穿透深度估算
• ✓ 指数衰减拟合
• ✓ 自动评估和建议

使用:

from analysis.penetration_analyzer import PenetrationAnalyzer

analyzer = PenetrationAnalyzer("field_data.csv")
depth, intensity = analyzer.extract_depth_profile()
pen_depth = analyzer.estimate_penetration_depth(depth, intensity)
assessment = analyzer.assess_frequency_adequacy(pen_depth, target_depth=1.0)
report = analyzer.generate_report()

---

🔄 工作流程

第一阶段：可行性验证 🔴

目标: 验证 675kHz 在王功泥灘地的穿透能力

现场实测 (675kHz @ 1m)
    ↓
CSV 数据
    ↓
penetration_analyzer.py 分析
    ↓
穿透力评估报告
    ↓
决策：继续用 A / 换 B / 考虑 C

使用工具: analysis/penetration_analyzer.py

第二阶段：算法开发 🟠

目标: 实现 PointNet++ 模型和 Physics-informed GAN

合成数据 (Biot模拟)
    ↓
PointNet++ 训练
    ↓
模型验证 (准确率、推理速度)
    ↓
Physics-informed GAN (领域偏移补偿)
    ↓
现场数据微调

使用工具: models/, training/, physics/

第三阶段：系统集成 🟡

目标: 遠端传输、硬件融合、自动化工作流

协议逆向 (CHIRP+ 2 通讯)
    ↓
网关中继系统 (实时数据流)
    ↓
数据预处理管线 (ToF + 体素化)
    ↓
PointNet++ 推理
    ↓
结果可视化 + GIS 输出

第四阶段：现场部署 🟢

目标: 王功大规模监测与验证

自动化掃描 (无人船)
    ↓
实时数据处理
    ↓
洞穴识别与定位
    ↓
族群密度估算
    ↓
监测数据库 (时间序列)

---

📈 性能指标

PointNet++ 预期性能

指标	目标	说明
准确率	> 85%	孔隙 vs 背景分类
推理时间	< 50ms	单帧 1024 点云
显存占用	< 2GB	GPU (e.g., RTX 3060)
数据吞吐	15 fps	实时处理

硬件穿透力目标

频率	穿透深度	分辨率	应用场景
675 kHz	0.5-0.8m	1cm	表层细节
300 kHz	1.0-1.5m	3cm	深层结构
100 kHz	2.0+ m	10cm	地下调查

---

🛠️ 开发进度

已完成 ✅

• 项目架构设计
• PointNet++ 模型实现
• 声纳数据加载器
• 训练脚本与流程
• Biot 理论模拟器
• 穿透力分析工具
• 硬件评估报告

进行中 🔄

• Physics-informed GAN 实现
• 几何约束编码
• 数据合成与增强
• 现场穿透力验证

待做 📝

• 信号处理优化
• 协议逆向工程
• 网关中继系统
• 可视化工具
• 地理信息系统集成
• 完整工作流自动化

---

📚 参考资料

科学文献

• [1] Das et al. (2018) - Burrow characteristics of mud shrimp Austinogebia edulis
• [2] Biot (1956) - Theory of Propagation of Elastic Waves
• [3] PointNet++ (Qi et al., 2017) - Deep Hierarchical Feature Learning

技术文档

• Deeper Sonar Support: support.deeper.eu
• PyTorch Documentation: pytorch.org
• NVIDIA CUDA Toolkit: developer.nvidia.com/cuda-toolkit

相关项目

• Point Cloud Library (PCL): pointclouds.org
• Open3D: open3d.org

---

🤝 贡献指南

提交改进建议或代码时，请：

1. Fork 项目
2. 创建特性分支 (git checkout -b feature/improvement)
3. 提交更改 (git commit -am 'Add improvement')
4. 推送到分支 (git push origin feature/improvement)
5. 创建 Pull Request

---

📞 联系方式

项目负责: Obsidian Team 技术咨询: Claude Code + Gemini 报告位置: reports/ 目录

---

📄 许可证

本项目采用 MIT License。详见 LICENSE 文件。

---

🎯 致谢

感谢 Gemini 的专业技术评审和建议，使项目避免了多个技术陷阱。

---

最后更新: 2026-03-23 版本: 1.0 状态: 🚀 积极开发中