# 托盘部分位姿模型：训练结果与使用

已实际完成一轮独立先导实验。方法调研见 [研究与选型](pallet_pose_model_research_v1.md)，数据依据为 [位姿数据集v2](pallet_pose_dataset_v1.md)。本轮没有修改原检测／位姿标签，也没有使用76帧unassigned或98条隔离记录。

[下载模型与推理包](../outputs/pallet_pose_training_v1/pallet_pose_models_v1.zip) · [SHA-256](../outputs/pallet_pose_training_v1/pallet_pose_models_v1.zip.sha256) · [逐帧全流程结果CSV](../outputs/pallet_pose_training_v1/evaluation/pipeline_predictions.csv) · [完整测试JSON](../outputs/pallet_pose_training_v1/evaluation/results.json)。模型包包含检测器、两种部分位姿头、最小推理源码、训练源码快照、调研及训练记录和仅来自原train的可执行示例。

## 模型

- **检测器**：YOLOv8s，官方COCO初始化，原6,552帧train／1,455帧val，640、batch16、AdamW、无Mosaic，固定20轮。选权重只用原val，不使用历史托盘辅助权重。
- **平面位姿**：几何RANSAC/SVD先验＋PointNet风格残差。65帧原train、9组、3折分组交叉验证；几何、岭回归与神经网络共同对照，原val两帧不参与位姿选模。
- **参考点＋法向量**：38帧原train固定200轮，单独网络，没有独立val/test。其结果仅训练集拟合，不是泛化性能。

神经网络三折实际各训练200轮，最佳轮数1／1／175，中位数1轮重拟合平面最终权重。长期训练的明显过拟合已保留在逐轮记录，不用最终训练loss或测试结果重新挑选权重。PointNet内部CV每组等权综合分数略低于几何基线，但不构成显著优势。

## 测试结果

所有选择、权重哈希、置信度=.25、IoU=.5、成功阈值**位置≤50mm且角度≤5°**都在测试前冻结。原test为49帧／3个采集组，43帧集中在同一组；这些帧不曾进入本轮任何训练或选轮。

### 真值框ROI下的位姿回归（不是端到端）

| 方法 | XY位置平均欧氏误差 | θ平均绝对误差 | 50mm/5°通过 |
|---|---:|---:|---:|
| 几何平面代理 | 28.79mm | 0.442° | 43/49（87.76%） |
| 岭回归残差 | 110.50mm | 1.455° | 2/49（4.08%） |
| 冻结PointNet残差 | 28.74mm | 0.519° | 43/49（87.76%） |

深度网络与几何基线非常接近，角度反而略逊。没有根据这张测试表反选几何模型或再调训练轮数；冻结的主模型仍为内部CV选定的PointNet残差。

### 实际检测器→点云→位姿全流程

- 测试49个目标均有IoU≥.5的检测，共输出49个框，无匹配后的点云输入失败。
- XY平均欧氏误差 **28.20mm**，中位数28.68mm，P90 **48.37mm**。
- x／y逐轴平均绝对误差分别 **8.14／26.22mm**。
- θ平均绝对误差 **0.518°**。
- 满足50mm和5°的为 **47/49＝95.92%**，分母始终为49，包括漏检或点云失败时也不缩小。

| 测试采集组 | 帧数 | 全流程通过 |
|---|---:|---:|
| 2024_11_11/scene/2 | 5 | 4/5 |
| 2024_11_29/scene/1000mm/0mm | 43 | 42/43 |
| 2025_4_15/scene/hanlan/2 | 1 | 1/1 |

实际检测框与人工框的覆盖不同，几何取点也随之改变，因此全流程和真值框ROI结果不一定单调。不能据此说“检测误差让位姿模型整体更准确”，也不能将95.92%解释成任意场景叉取成功率。样本和独立组都很少。

检测器完整原val上的 **mAP50约0.963、mAP50–95约0.930** 属于模型选择用验证结果；不是49帧的位姿精度，也不是完整2,367帧检测测试集成绩。

### 法向量网络

38帧**训练集拟合**：参考点3D平均欧氏误差14.45mm，法向量平均夹角1.99°。这是重代入结果，不能当作新场景验证或完整6D姿态精度；本轮没有法向量测试成绩。

### 单位／坐标限制

49帧测试中43帧有点云单位比例登记，6帧没有。后6帧仅按显式“原数值按米的研究假设”计算，分层结果在原始JSON报告中；统一机器人坐标系与参考点语义仍待核验。预测不包含缺失的z、roll/pitch/yaw、四元数或刚体变换，`robot_command_eligible=false`。

## 产物与审计

训练目录：`outputs/pallet_pose_training_v1/`。

```text
detector/weights/best.pt          # 20轮COCO初始化检测器
detector/results.csv             # 每轮完整原val指标
detector_run.json                # 数据、初始化权重、GPU UUID与保护快照
detector_completed.json
pose/cv_0|cv_1|cv_2/             # 各折逐轮记录、best、last及RNG
pose/cv_results.json
pose/planar_final/final.pt
pose/normal_final/final.pt
pose/normal_training_fit_only.json
pose/original_val_diagnostic.json
pose/frozen_evaluation_plan.json # 测试前模型／阈值／哈希冻结
pose/completed.json
deployment/                     # 精简权重、只需原图和注册点云的推理入口
evaluation/results.json         # 所有方法、单位分层、逐组及全流程结果
evaluation/predictions.jsonl     # 全部实际检测框、预测、后置匹配与GT对照
evaluation/pipeline_predictions.csv
```

检测与位姿训练分别固定GPU硬件UUID，实际GPU／源码／数据／初始化和最终权重哈希均记录，不凭显示名称猜测型号；未改用历史污染测试集的辅助模型。完整研究尚未完成，本轮是单seed、固定预算的可复现初模。

## 复现

训练需按本机实际GPU UUID配置，换设备或配方请使用新配置和新输出目录，不覆盖原实验。

```bash
env CUDA_VISIBLE_DEVICES=GPU-09ed84c8-4dee-efc0-dc1d-deda5177e4e8 \
  YOLO_CONFIG_DIR=/tmp/opencode/pallet_pose_yolo_settings \
  OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=4 \
  .venv/bin/python -m pallet.pose_detector_training --config configs/pallet_pose_training_v1.json

env CUDA_VISIBLE_DEVICES=GPU-3315c096-fef4-7350-483a-7c5f5ca2b619 \
  CUBLAS_WORKSPACE_CONFIG=:4096:8 OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=2 \
  .venv/bin/python -m pallet.pose_training --config configs/pallet_pose_training_v1.json

# 仅在两阶段训练完成、评估计划冻结后执行；结果存在则复核绑定后返回，不重新调参
env CUDA_VISIBLE_DEVICES=GPU-3315c096-fef4-7350-483a-7c5f5ca2b619 \
  OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=2 \
  .venv/bin/python -m pallet.pose_evaluation --device cuda:0
```

新输入推理（不读取GT或人工框）：

```bash
OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=2 .venv/bin/python -m pallet.pose_inference \
  --bundle outputs/pallet_pose_training_v1/deployment \
  --image 原生强度图.png --cloud 已注册点云.npz \
  --scale-to-m 1 --output 预测.json
```

点云NPZ需含 `points_xyzi` 与 `pixel_to_source_index`，映射网格必须与图像一致。`--scale-to-m` 必须来自实际单位标定；未知时默认只保留检测而拒绝位姿估计，确需研究试验可显式加 `--allow-unverified-units`。法向量任务使用 `--task reference_xyz_normal`，不声称具备独立泛化验证。

## 下一步优先级

1. 统一托盘物理参考点、theta定义、单位与传感器→机器人外参；复核跨日期表格可能继承的参考值。
2. 新采集独立组的法向量／参考点val/test，增加目前只有2帧的平面val，不拆同一采集序列充数。
3. 若要求完整6D，补齐可观测的旋转约束和相应标签／CAD或标定角点；法向量本身不能决定绕法线旋转。
4. 在新冻结协议下再比较PointNet++／预训练PTv3／模板注册与不同种子，不能回头针对这49帧继续选优。
