# AtomVision 物理先验融合轨迹恢复项目
目录
- 1. 项目概述
- 2. 核心思路
- 3. 方法流程
- 4. 模型结构
- 5. 最终结果
- 6. 物理约束使用方式
- 7. 运行指南
- 8. 结果展示区
- 9. 环境与复现说明
- 10. 工程实现与落地性
- 11. 项目结构（含用途说明）
- 12. 许可证
- 13. 致谢
1. 项目概述
本项目面向 BPT-V 赛道，目标是在遮挡、缺失和复杂运动条件下恢复小球轨迹。
终结版方案采用“物理先验融合 + 序列残差学习 + 事件与不确定性联合建模”，兼顾精度、稳定性和可复现性。
2. 核心思路
| 模块 | 做法 | 作用 |
|---|---|---|
| 多先验融合 | 融合全局拟合、分段拟合等多路先验并动态加权 | 提升先验质量，降低单一先验偏差 |
| 残差学习 | 预测 pred_xy - fused_prior 的残差项 |
用小模型修正先验误差 |
| 事件分支 | 同步预测关键运动事件概率 | 强化关键时刻的判别能力 |
| 不确定性分支 | 预测 logvar 并进行门控 |
抑制不稳定帧的过激修正 |
| 难样本采样 | 训练阶段启用 hard mining | 提高复杂样本上的鲁棒性 |
3. 方法流程
3.1 端到端流程
- 构建缺失区间的多路物理先验。
- 提取轨迹与运动学特征，送入 GRU+TCN 编码器。
- 输出残差、事件概率和不确定性，得到最终轨迹恢复结果。
- 联合损失训练，并以综合指标选择最优权重。
3.2 最终预测关系
pred_xy = fused_prior + residual * uncertainty_gate
4. 模型结构
| 组件 | 说明 |
|---|---|
| 主干编码器 | 2 层 GRU + 轻量 TCN 融合 |
| 先验融合头 | 学习动态权重并融合多路先验 |
| 残差头 | 预测 2 维坐标残差 |
| 事件头 | 预测逐帧事件 logit |
| 不确定性头 | 预测 logvar 并生成门控系数 |
5. 最终结果
5.1 最终提交配置（final_optimized）
| 项目 | 数值 |
|---|---|
| 运行名称 | final_optimized |
| 训练轮数 | 20 |
| 批大小 | 8 |
| 学习率 | 5e-4 |
| 最优模型选择策略 | hybrid |
5.2 核心评测指标
来源文件：outputs/metrics/model_eval_final_optimized.json
| 指标 | 数值 |
|---|---|
| 模型预测均方误差（MSE） | 1924.18378 |
| 物理先验均方误差（MSE） | 2842.93694 |
| 相对物理先验提升 | 32.32% |
| 事件 F1（固定阈值） | 0.3212 |
| 事件 F1（校准阈值） | 0.3223 |
| 事件最优阈值 | 0.50 |
| 不确定性负对数似然（NLL） | 1785.19803 |
| 样本数 | 18 |
5.3 推理时延（CPU，batch=1，seq_len=21）
| 指标 | 数值 |
|---|---|
| 平均时延 | 2.7468 ms |
| 中位时延（p50） | 2.4404 ms |
| 95 分位时延（p95） | 4.2872 ms |
| 99 分位时延（p99） | 4.9993 ms |
5.4 轻量化信息
| 项目 | 数值 |
|---|---|
| 模型文件 | checkpoints/final_optimized/best_model.pt |
| 文件大小 | 0.31 MB |
| 运行设备 | CPU |
6. 物理约束使用方式
| 环节 | 使用方式 |
|---|---|
| 先验构建 | 全局拟合 + 分段拟合生成多路轨迹先验 |
| 分段依据 | 结合速度变化与接触约束检测关键节点 |
| 运动学特征 | 数值微分得到 vx, vy, ax, ay |
| 最终恢复 | 采用“先验融合 + 残差修正 + 不确定性门控”逐帧恢复 |
7. 运行指南
7.1 环境安装
pip install -r requirements.txt
7.2 一键终端流程（推荐）
py run_final.py --dataset-dir "<训练集目录或评委评测数据目录>" --epochs 20 --run-name final_optimized
7.3 训练模型
py train.py --dataset-dir "<训练集目录>" --epochs 20 --batch-size 8 --lr 5e-4 --run-name final_optimized
7.4 评估模型
py evaluate_physics.py --dataset-dir "<评委评测数据目录或测试集目录>" --ckpt checkpoints/final_optimized/best_model.pt --tag final_optimized
7.5 推理时延测试
py benchmark.py --ckpt checkpoints/final_optimized/best_model.pt --runs 200 --warmup 50
7.6 全数据集批量评测
py batch_evaluate.py --dataset-dir "<评委评测数据目录或测试集目录>"
8. 结果展示区
8.1 原始轨迹
8.2 缺失与恢复对比
8.3 分段拟合结果
8.4 轨迹动画
8.5 端到端自验证截图
以下截图展示了从一键命令启动、训练完成到评估输出的完整自验证链路。
9. 环境与复现说明
- 当前机器由于 CUDA 与本地显卡架构兼容问题，训练与评估默认走 CPU。
- 脚本均可在 CPU 环境完整复现，不影响提交验证流程。
- 评委侧只需保证
--dataset-dir指向有效数据目录即可运行。
10. 工程实现与落地性
| 维度 | 当前实现 |
|---|---|
| 一键可复现 | run_final.py 统一训练与评估入口 |
| 训练可配置 | train.py 支持数据目录、训练轮数、损失权重等参数化 |
| 评估可追溯 | 结果固定输出到 outputs/metrics/ |
| 可视化完整 | 静态图 + 动画 + 终端自验证截图 |
| 部署友好 | 模型体积小、CPU 可运行、目录结构清晰 |
11. 项目结构（含用途说明）
project/
├── LICENSE # 项目使用与分发规则说明文件
├── README.md # 项目说明文档（终结版）
├── requirements.txt # Python 依赖列表
├── main.py # 单视频演示主流程
├── run_final.py # 一键训练 + 评估入口（推荐）
├── train.py # 模型训练脚本
├── evaluate_physics.py # 模型评估脚本
├── benchmark.py # 推理时延测试脚本
├── batch_evaluate.py # 全数据集批量评测脚本
├── models/
│ └── physics_residual_gru.py # 多先验融合残差模型
├── utils/
│ └── dataset_builder.py # 样本构建与特征生成
├── scripts/
│ ├── data_loader.py # 轨迹 JSON 读取
│ ├── physics_fit.py # 全局拟合与先验构建
│ ├── segment_fit.py # 分段拟合与反弹检测
│ ├── evaluate.py # 误差计算工具
│ └── visualize.py # 可视化工具
├── checkpoints/
│ └── final_optimized/ # 终结版权重与训练日志
└── outputs/
├── figures/ # 轨迹静态图
├── animations/ # 轨迹动画
├── submission_screenshots/ # 提交用自验证截图
└── metrics/ # 指标与评测报告文件
12. 许可证
本项目包含开源使用许可，明确了代码使用、修改、再发布与责任边界， 用于保障项目共享协作中的权利与义务清晰一致。
13. 致谢
- 感谢 BPT-V 赛道提供任务与数据支持。
- 感谢 PyTorch、NumPy、Matplotlib 等开源社区提供基础工具。
- 感谢指导老师与比赛组织方的建议与反馈。