# 托盘位姿检测数据集（最新修订 v2）

输入为 `2026_10_17.zip`，最新修订独立输出到 `outputs/pallet_pose_dataset_v2/`。不替换 `configs/active_formal_dataset.json`，不修改正式检测图像、框、划分、结构属性或正在使用的人工审核库；不启动模型训练。最初保守版 `..._v1/` 保留供追溯；v2补回一条从权威Excel可客观恢复的索引错误，仍属于同一部分位姿数据格式。

## 已完成交付

[下载数据集ZIP（约699 MiB）](../outputs/pallet_pose_dataset_v2/pallet_pose_dataset_v2.zip) · [完整重叠及质量CSV](../outputs/pallet_pose_dataset_v2/dataset/overlap_and_quality.csv) · [独立验收](../outputs/pallet_pose_dataset_v2/independent_verification.json) · [位姿专用入口](../configs/active_pose_dataset.json)。

包内点云与当前检测集共核实 **193帧重叠**：150帧文件完全相同，另43帧XYZ/点序/VIEWPOINT完全相同但强度不同。主索引本身可直接对应190帧；另外3帧的原始PCD在包中，但主索引选到裁剪版，未直接转移其标签。

| 最终联合监督类型 | train | val | test | 合计 |
|---|---:|---:|---:|---:|
| x/y/theta部分位姿 | 65 | 2 | 49 | 116 |
| 参考点XYZ＋法向量 | 38 | 0 | 0 | 38 |
| 合计 | **103** | **2** | **49** | **154** |

另保留 **76帧**有GT的非重叠扩展样本（尚无现有检测框，未划分），主索引中 **98条**问题记录隔离。全包导出230帧监督样本；训练联合检测位姿时应使用 `indices/overlap/`，不能把76个unassigned样本当作已经核验划分的联合检测数据。

验证集仅2帧，法向量子集尚无val/test，不能声称已具备充分的位姿泛化评估集。没有为增加验证量而移动原测试数据或拆分原采集组。

两路核验通过：743个输入成员CRC/哈希、34份原表重读、328条主索引覆盖、230例PCD/NPZ和154例图像像素对应、1,056份输出文件与ZIP逐成员核验；原20,768份检测标签/元数据与193份使用的原始PCD哈希不变。新包内有序XYZ重复组0，跨划分采集组/源文件/有序XYZ重复均0。125项相关回归通过，日志见 `outputs/pallet_pose_dataset_validation_v1/`。

ZIP SHA-256：`f41ef34345985cb50fd03a36e61e05838c38ac500cf0003f5e054796500d8928`。

首次预发布构建曾因120秒工具超时中断、留下不完整NPZ，恢复安全检查将其拒绝；中间目录原样保留在 `outputs/pallet_pose_dataset_interrupted_v1/`。现已改为NPZ编码完成后原子写入，交付版在独立目录全量重建并通过验证，未将不完整文件用作成功结果。

## 位姿标注口径

这不是完整六自由度位姿数据。必须分开使用两种监督：

1. **平面部分位姿**：`x_gt`、`y_gt`、`theta_d_gt`，按来源包使用米、度，保留符号与取值。不采用存在180°写法差异的 `theta_d_convert_gt`，也不把 `x/y/theta`、`trans_*`、`icp_*` 等算法输出当真值。
2. **参考点＋法向量**：从权威 `ground_truth.xlsx` 的按列排布标签读取 `X:/Y:/Z:` 及法向量。主索引只收录法向量、漏掉XYZ，因此恢复值同时绑定原表、工作表与列号。法向量无法确定绕法线旋转，不能据此虚构完整姿态矩阵、四元数或6D标签。

未知分量保留 `null`，并提供 `supervision_mask`；不能当作0。没有物体尺寸真值，不构造3D框。不默认标注参考点就是托盘几何中心，也不假设所有来源表具有相同机器人坐标系。点云保持原坐标与单位，只有原正式传感器政策已有核验时才给 `pointcloud_scale_to_m`。统一坐标系、物理参考点和传感器到机器人外参仍须进一步确认。

## 重叠核验

- 包含705份点云，不等于705个带位姿样本。主索引为328个采集时间身份，源表34份；点云包含多种裁剪、分割、法向量和强度处理版本。
- 首先用文件SHA-256对应当前正式集原始PCD来源哈希；同时间戳仅用于候选检索，不凭名字认定重复。
- 文件哈希不同的主索引点云与候选PCD逐点核验：解码后float32 XYZ数组、点序、点数与PCD VIEWPOINT必须完全相同。强度不同单独记录，保留原正式集强度，不覆盖图像或传感器数据。
- 主索引选到裁剪/变换版的，即使包中另有原始PCD与现有数据完全一致，也不直接把这份位姿GT跨版本转移。原始文件重叠与GT能否安全关联分开报告。
- 原始PCD与正式显示图像的像素方向可能不同。输出 `pixel_to_source_index` 显式恢复对应关系，不旋转点云坐标或擅改GT角度。

补充点集诊断证实3份裁剪PCD的3,365、2,996、6,574个有效XYZ均可在各自正式原始点云中逐点找到（100%），但它们不是同一个完整有序输入；仍不据此豁免GT缺失、表内冲突或目标关联要求。诊断见 `outputs/pallet_pose_identity_audit_v1/cropped_cloud_comparison.json`。

## 纳入与隔离

源主索引实际为 **208条x/y/theta、45条法向量、75条没有可用GT数值**，不是253条完整平面位姿。原说明中的253是208＋45的合计；75条在主索引中均没有权威来源表引用，不能直接用“相对位移样本”的描述代替缺失数值。12条有真值冲突、2条主索引缺PCD，均单列隔离。

独立重读还发现 `ground_truth.xlsx` 含46列样本，其中 `27-03-2024_05-43-28` 未进入主索引，压缩包也没有它的点云；当前检测集中虽存在同时间戳候选，缺少归档内容证据，未凭同名强行纳入。原表内容完整保留，具体证据见 `independent_verification.json`。

### 索引转换错误与真实GT冲突分开处理

`27-03-2024_05-42-16` 的原Excel法向量为 `(0.999178; -4.90068e-05; -0.0405457)`，CSV却记录为 `(0.999178; -4.900680; -0.040546)`，第二分量丢失了指数。v1因索引与原表不一致而隔离；v2只对这种“权威表明确有值、同一样本各列一致”的情况读取原表值，同时恢复其原表XYZ，逐例记录 `index_correction`、CSV原值、工作表与列号。这不是估算新GT，也不为任何真实冲突自动选边。

另发现 `09-01-2025_13-51-03` 虽在manifest中标为无冲突，权威表内部实际有不同的GT记录，并且主索引选到分割PCD，继续隔离。`05-03-2025_10-19-28` 有位姿数值但当前正式检测标签为确认负例，也不擅自推翻旧标签。

| 子集 | 条件 | 用法 |
|---|---|---|
| `overlap` | PCD身份核验通过，权威GT可追溯且无冲突，现有人工检测框恰为1个 | 联合检测框和部分位姿监督，完整继承原train/val/test与采集组 |
| `archive_only` | 有点云及可追溯无冲突GT，但未证实属于当前正式集 | 扩展样本保留，`split=unassigned`、无伪造检测框；不自动进入训练/测试 |
| `quarantine` | GT冲突、无可用GT、缺PCD、主索引几何不同，或多框无法确定GT对应目标 | 全量审计保留原因及原值，不作为负例、不自动选最像的一框 |

原表或manifest给出的冲突不会因为“权威表”或同日规则就被自动裁决；权威表内部出现多种取值也会隔离。只有一个人工框的关联仍是帧级唯一目标假设，并不解决物理参考点定义。

## 目录与读取

```text
outputs/pallet_pose_dataset_v2/
  inputs/2026_10_17/              # 原归档逐成员CRC、MD5、SHA-256核验后的提取副本
  dataset/
    overlap/train|val|test/       # PCD、点云NPZ、原PNG、原四通道sensor NPZ、逐例JSON
    archive_only/unassigned/      # PCD、点云NPZ及逐例JSON
    annotations.jsonl            # 所有已导出的监督样本
    indices/overlap/planar_xy_theta/{train,val,test}.jsonl
    indices/overlap/reference_xyz_normal/{train,val,test}.jsonl
    indices/archive_only/        # 两种任务各自的unassigned索引
    overlap_and_quality.csv       # Excel可读取的全部328行重叠与质量清单
    audit/                       # 全量样本、705份PCD、隔离样本、原表逐行证据
    provenance/                  # 原始34份表、三份CSV、源说明、输入与保护哈希绑定
    statistics.json
    manifest.json
    checksums.sha256
  pallet_pose_dataset_v2.zip
  run_manifest.json
  delivery_manifest.json
  verification.json
  independent_verification.json  # 重新读取原ZIP与原表的第二路语义验收
```

点云NPZ的 `points_xyzi` 是原始有序四列浮点值（未去除NaN/无效点），`valid_xyz` 与 `valid_intensity` 分别标明有效性；`source_point_index` 保留点序。重叠例额外含 `pixel_to_source_index`。`*.sensor.npz` 保留旧正式数据的深度/强度/有效掩码四通道，不应和XYZI数组混淆。

```python
from pathlib import Path
import json
import numpy as np

root = Path('outputs/pallet_pose_dataset_v2/dataset')
rows = [json.loads(line) for line in
        (root/'indices/overlap/planar_xy_theta/train.jsonl').read_text().splitlines()]
for sample in rows:
    with np.load(root/sample['points'], allow_pickle=False) as cloud:
        xyz = cloud['points_xyzi'][cloud['valid_xyz'], :3]
    target = sample['pose']['values']
    # 对应x_gt/y_gt/theta_d_gt的来源任务；不能为缺失6D分量补0。
    box_xywh = sample['box_xywh']
```

## 复现与验证

安装可选表格读取依赖：`pip install -e '.[pose-data]'`。本机实际使用隔离目录 `/tmp/opencode/pallet_pose_tables`，不升级现有训练环境。

```bash
PYTHONPATH=/tmp/opencode/pallet_pose_tables OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=1 \
  .venv/bin/python -m pallet.pose_dataset build --config configs/pallet_pose_dataset_v2.json

# 完全相同的输入/源码才能恢复；异内容输出拒绝覆盖
PYTHONPATH=/tmp/opencode/pallet_pose_tables OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=1 \
  .venv/bin/python -m pallet.pose_dataset build --config configs/pallet_pose_dataset_v2.json --resume

.venv/bin/python -m pallet.pose_dataset verify \
  --dataset outputs/pallet_pose_dataset_v2/dataset \
  --archive outputs/pallet_pose_dataset_v2/pallet_pose_dataset_v2.zip

PYTHONPATH=/tmp/opencode/pallet_pose_tables OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=1 \
  .venv/bin/python scripts/verify_pose_dataset.py
```

解压后可运行 `sha256sum -c checksums.sha256`。构建、源PCD及正式标签前后哈希核验、逐点/像素映射复核、ZIP精确成员/CRC/SHA核验和独立原表重读的最终结果，以交付清单为准。

历史辅助模型曾使用部分原val/test标签，沿用划分不意味着历史模型突然具有独立测试资格；本次不计算任何模型精度。
