# 托盘位姿模型批量评测 v3

本轮执行用户批准的8类候选评测。实时证据位于
`outputs/pallet_pose_benchmark_v3/`；最终结论以该目录的
`selection_frozen.json`、`final_results.json`、`REPORT_zh.md`为准，
文件尚未生成时表示相应阶段仍未完成。

## 调研范围（2026-10-20）

|模型|官方来源|本次适配|
|---|---|---|
|Utonia-Small，ICML 2026|https://github.com/Pointcept/Utonia |跨域预训练编码器＋位姿头|
|LitePT-S，CVPR 2026|https://github.com/prs-eth/LitePT |ScanNet预训练编码器＋位姿头|
|Concerto-Small，NeurIPS 2025|https://github.com/Pointcept/Concerto |2D–3D预训练编码器＋位姿头|
|Sonata，CVPR 2025|https://github.com/facebookresearch/sonata |自监督预训练编码器＋位姿头|
|PTv3，CVPR 2024|https://github.com/Pointcept/PointTransformerV3 |官方默认编码器，从头训练|
|PointNeXt-S，NeurIPS 2022|https://github.com/guochengqian/PointNeXt |官方分类S配置的编码器，7通道输入，从头训练|
|Point-MAE，ECCV 2022|https://github.com/Pang-Yatian/Point-MAE |ShapeNet预训练编码器＋位姿头|
|DGCNN，TOG 2019|https://github.com/WangYueFt/dgcnn |经典局部图基线，从头训练|

这些是点云骨干及预训练模型，不是已在托盘位姿上证明最优的成品。
统一任务为叉取面宽度中心的平面`x/y/θ`，不是完整6D。
FoundationPose（https://github.com/NVlabs/FoundationPose）需要CAD或带深度的参考视图，
本数据未提供其必要输入，因此没有伪造一个可比得分。

`upstream_manifest.json`固定8个官方Git提交；PointNeXt的OpenPoints子模块固定为
`db31e0d94ede35bc672ef06d1b6e4073a9c269d5`。
`weights_manifest.json`记录5份权重的地址、大小和SHA-256。
Hugging Face直连失败后使用镜像，4份镜像权重均与模型仓库发布的LFS对象哈希一致，
证据为`*_weight_identity.json`及`integrity_audit.json`。

## 冻结数据和选模

- 沿用v2授权快照的1,215条有效研究标签；原train仅860条，米制288／38采集组，未知单位572／51采集组。
- 原val/test与后续新增记录均不进入训练；当前在线草稿状态与确认字段没有升级。
- 同一套3折采集组CV，折分种子42；初筛训练种子42，每折80轮。
- 预训练模型初筛只训练回归头；PTv3、PointNeXt、DGCNN端到端训练。
- 每分支前三名补种子142、242，并比较原自动ROI输入与完整原框ROI输入。
  入围预训练模型另外微调最后编码阶段；Point-MAE微调最后Transformer块及末尾LayerNorm。
- 学习率：头`1e-3`、骨干`1e-4`，AdamW，weight decay `0.005`。
  初筛冻结头batch16、端到端batch8；512个点、三个固定采样变体、训练坐标扰动0.003个自动宽度。
- 每折按训练内验证组选epoch；最终重拟合轮数取三种子九折的已选epoch中位数，固定种子42。
- 主指标：采集组等权平均`位置误差/自动宽度/0.05 + 角度误差/5°`。
- 最佳学习方案按三种子均值选择。相对几何的采集组配对bootstrap（10,000次，种子4242）
  95%区间上界低于0且覆盖率不降低才建议部署。该区间是选模后描述性稳定性分析，
  不代替全新独立盲测或多重比较校正。
- 原test此前已被查看，本轮仅作为冻结后的固定集对照；所有预处理失败计入完整分母。

### 用户授权的加速复测配方

用户随后要求提高batch、优先使用非3090的两块更稳定显卡。先仅用原train测试
batch8/16/32的前向/反向吞吐与显存、验证batch8/32/64的一致性，证据为
`throughput_fast16.json`、`throughput_fast24.json`，不按任何验证/test精度选batch。

- 所有入围模型、两条路线及三个种子统一使用训练最大batch32、验证batch64；冻结编码提取batch32。
- 原始初筛协议、排名和已完成的batch8复测不改写；新实验存于`trials/*/accelerated/`，
  原batch8结果作为补充证据，不混入最终新配方排名。
- 训练batch变化会改变BatchNorm、随机数轨迹和每轮优化器步数，并非数学等价加速。
  新配方仍训练80轮、学习率不变，所有入围模型采用同一预算；末尾batch均衡分组，不丢样本。
- 调度仅使用`GPU-3315c096-fef4-7350-483a-7c5f5ca2b619`和
  `GPU-09ed84c8-4dee-efc0-dc1d-deda5177e4e8`，不再向3090分配任务。
- 原train短测试中，batch32较8的训练样本吞吐提升：PointNeXt约3.7–5.4倍、
  PTv3约2.6–2.7倍、DGCNN约1.6–2.2倍；这不是完整训练管线的加速保证。
- 独立配方及绑定哈希见`configs/pallet_pose_benchmark_v3_acceleration.json`与
  `refinement_protocol.json`，不覆盖原`protocol.json`。

## 输入与实现适配

人工多边形、手动选面、最终标尺、GT、目标ID和采集组ID均不是模型输入。
目标/组ID仅用于数据关联、划分和审计。

`residual`沿用v2缓存：原检测框、自动分解ROI保留点、自动叉取面参考中心和宽度。
注意缓存包含自动ROI保留点，并非只包含被选叉取面的点。
`roi`使用原框内全部有效注册点（按同一1%分位去极端点），自动面只作为可选归一化/解码参考；
没有可用叉取面时采用原框点云中位数、Y跨度与登记的X前向作回退参考。
训练标签坐标不会用于构造回退参考。

模型通道：Point-MAE/DGCNN读XYZ；PointNeXt/PTv3读XYZ、强度及有效标志、相对像素位置；
Utonia/Sonata/Concerto用XYZ＋缺失RGB/法向零通道；LitePT采用缺失颜色/法向零通道，
几何由稀疏坐标输入。所有模型另接同一16维自动全局特征。缺失颜色迁移是本次实验条件，
不是这些预训练模型的官方最佳条件；ToF强度未冒充RGB。

预训练冻结头的特征标准化仅拟合当前折的fit部分；端到端的全局特征标准化亦如此。
未知原始单位始终独立，体素0.02是自动宽度归一化单位，不是米。

- 固定官方架构类及权重；Point-MAE/PointNeXt使用AST仅加载所需架构定义，避开无关训练扩展导入。
- FPS、KNN、球查询以PyTorch适配，并测试采样、源点顺序、重复填充与梯度语义。
- LitePT使用其官方PointROPE PyTorch回退。
- 稀疏输入每个体素保留第一个测量点，避免spconv重复坐标的不确定结果。
- 各级序列shuffle关闭；使用官方FlashAttention变长序列路径。
  非Flash路径曾出现批次长度耦合，其试跑已放入`compatibility_aborted_nonflash/`，不参与排行榜。
- `compatibility/`记录每个模型前向、反向、重复推理检查；
  `input_parity.json`记录12个原train目标的两路线共24项离线输入等价检查。

## 环境与复现

宿主glibc 2.27，PyTorch 2.6.0+cu124。依赖只装入独立目录，在线标注环境未更换：

```bash
export PYTHONPATH=/tmp/opencode/pose_benchmark_small_deps:/tmp/opencode/pose_benchmark_deps
export OPENBLAS_NUM_THREADS=1
export OMP_NUM_THREADS=2
export CUDA_VISIBLE_DEVICES=GPU-3315c096-fef4-7350-483a-7c5f5ca2b619

.venv/bin/python -m pallet.pose_benchmark --stage smoke --family pointnext
.venv/bin/python -m pallet.pose_benchmark --stage trial --family pointnext --branch metric
.venv/bin/python -m pallet.pose_benchmark_roi --split train
.venv/bin/python -m pallet.pose_benchmark_results --stage shortlist
.venv/bin/python scripts/run_pose_benchmark.py --stage refine
.venv/bin/python -m pallet.pose_benchmark_results --stage select
.venv/bin/python -m pallet.pose_benchmark_results --stage evaluate --branch metric
.venv/bin/python -m pallet.pose_benchmark_results --stage evaluate --branch native_unknown
.venv/bin/python -m pallet.pose_benchmark_results --stage report
.venv/bin/python scripts/verify_pose_benchmark.py
```

已有训练仍在运行时可用单一续跑器接管后续阶段，无须反复人工启动：

```bash
.venv/bin/python scripts/complete_pose_benchmark.py --wait-pids <已有训练PID...>
```

续跑器通过Linux进程退出通知等待已有任务（不轮询），然后补齐复测、冻结选模、
重拟合、固定集评估、打包、隔离目录推理及数据保护核验。当前阶段写入
`pipeline_state.json`；任一步失败会停止并记录日志，不自动发布机器标签。
加速复测单独复现：`python -m pallet.pose_benchmark --stage trial --family pointnext --branch metric --recipe accelerated`。

核心额外依赖：`spconv-cu120==2.3.6`、`cumm-cu120==0.4.11`、
`torch-scatter==2.1.2+pt26cu124`、`flash-attn==2.7.4.post1`、
`addict==2.4.0`、`easydict==1.13`、`colorhash==2.3.0`。
FlashAttention轮包匹配Python3.11、torch2.6、CUDA12、cxx11abiFALSE。
其余环境版本最终记录在`environment.json`。

## 数据保护与限制

`integrity_audit.json`重新核对10,374帧原PCD/图像、20,768份正式标签/元数据、
原1,216个人工目标与2,541条历史事件；允许用户同时增加人工记录。
原入口与v2交付包哈希另行记录，不由训练脚本改写。

草稿经用户授权用于研究，仍可能带有几何初值偏差。未知单位、机器人外参和完整旋转缺失问题
不会因为模型训练而消失；所有预测仍是待审核建议，`robot_command_eligible=false`。

每折验证既用于选epoch也用于模型比较，因此CV属于模型开发指标，存在选择乐观偏差；
bootstrap区间仅描述本轮组间/种子稳定性，不可当作独立检验的显著性或商业部署保证。

训练标签分布审计（`training_label_distribution.json`）显示：米制101/288、未知单位347/572
与几何初值之差同时小于0.1%宽度及0.01°；未知单位的位置误差中位数为0。
另有米制1条、未知单位12条偏移超过20%宽度，集中于少数采集组。
这些记录仍全部保留在预先冻结的评测中，未因为模型成绩而删除或改标签。
