## 托盘位姿检测数据集

已核对 `2026_10_17.zip` 与正式集：193帧重叠（150文件一致、43帧XYZ一致但强度不同）。独立构建154帧检测框＋部分位姿联合数据，原train/val/test=103/2/49；另76帧扩展样本未划分，98条问题记录隔离。监督分为116帧x/y/theta及38帧参考点＋法向量，**不是完整6D位姿**，原检测数据不变。

[下载ZIP（约699 MiB）](outputs/pallet_pose_dataset_v2/pallet_pose_dataset_v2.zip) · [重叠及质量CSV](outputs/pallet_pose_dataset_v2/dataset/overlap_and_quality.csv) · [方法、格式与验收](docs/pallet_pose_dataset_v1.md) · [位姿专用入口](configs/active_pose_dataset.json)。已通过源表重读、点云/图像对应、ZIP完整性及125项相关回归，未启动训练。

## 托盘结构属性：腿数与闭合方式

**人工确认 Web 界面：** 服务端口 `3389`，适配 iPhone；支持逐目标确认/修正、无法判断、进度筛选与审核导出。启动：`.venv/bin/python -m pallet.structure_review --port 3389`。[使用与访问说明](docs/structure_review_web.md)。人工记录单独持久保存，不覆盖算法或原训练标签。

新增独立结构属性流水线：按当前叉取面统计两／三／四腿，以及川字（下部无横梁）／田字（下部有横梁），保留原22大组。采用强度阈值分割和横纵投影；不稳定时回退到未填孔的点云前面板掩膜，仅必要异常做图像复查。未知和部分已知独立保留，机器建议不自动用于训练。

[方法与使用说明](docs/pallet_structure_attributes.md) · [结果图册](outputs/pallet_structure_attributes_v1/gallery.html) · [分类Excel](outputs/pallet_structure_attributes_v1/托盘结构分类结果.xlsx)。全量12,344目标处理完成：5,203完整组合建议、3,521部分属性已知、3,620未知；点云掩膜补充1,172目标，13例助手必要复查。125项相关回归和独立完整性核验通过，原标签不变；未知与机器建议仍须人工复核。

<!-- fork-face-enclosure-v2-complete-20261014 -->
叉取面可编辑凹包已全量交付：[下载ZIP（2.93 GiB）](outputs/pallet_fork_face_anylabeling_enclosure_v2/pallet_fork_face_anylabeling_enclosure_v2.zip) · [操作说明](docs/fork_face_enclosure.md) · [前后对比](outputs/pallet_fork_face_anylabeling_enclosure_v2/delivery/report_zh.html)。每个非空组一片、最多24顶点，原mask全覆盖，内部孔洞填平，取消IoU门槛。推荐打开 `pallets/images/train`；原263负例及41无mask正例身份保留，仍须人工修正。

<!-- fork-face-anylabeling-v1-complete-20261013 -->
叉取面分割的AnyLabeling修正包已交付：[下载ZIP（1.74 GiB）](outputs/pallet_fork_face_anylabeling_v1/pallet_fork_face_anylabeling_v1.zip) · [操作说明](docs/fork_face_anylabeling.md)。逐托盘联合版与逐面片版各覆盖10,374帧；解压后优先打开 `pallets/images/train`。多边形分片保留孔洞，全部新分割仍待人工复核。

<!-- fork-face-masks-v1-complete-20261013 -->
叉取面几何候选已全量交付：10,374帧、12,344个托盘目标均有处理记录；12,303个目标得到候选掩膜，41个未解决目标保留原人工框。原检测标签与划分保持不变。

[下载点云与掩膜 ZIP（2.26 GiB）](outputs/pallet_fork_face_masks_v1/pallet_fork_face_masks_v1.zip) · [中文报告](outputs/pallet_fork_face_masks_v1/delivery/report_zh.html) · [离线可旋转点云图册](outputs/pallet_fork_face_masks_v1/delivery/gallery.html) · [操作与验收说明](docs/pallet_fork_face_masks.md)。新掩膜全部为待复核建议；参数敏感性较高，未测量分割准确率。

<!-- intensity-coverage-audit-20261012-v2 -->
原始强度图覆盖已核验：2,236张PNG与2,375份YAML全部对应正式数据帧，归档4,328条强度数据均有对应，遗漏0。[逐文件覆盖报告](docs/intensity_source_coverage_check.md)。

<!-- baseline-8x4090-single-file-delivery-v1 -->
单文件整体交付：[下载全部迁移材料（3.37 GiB）](outputs/baselines_8x4090_handoff_v1/pallet_baselines_8x4090_all_in_one_v1.zip)。数据、源码、权重、任务/环境说明、验收与校验文件、日志均在包内；解压后阅读 `README_zh.md`。

<!-- baseline-8x4090-handoff-v1 -->
8卡4090训练交接已完成：[下载 ZIP（3.37 GiB）](outputs/baselines_8x4090_handoff_v1/pallet_baselines_8x4090_handoff_v1.zip) · [验收与迁移说明](docs/baselines_8x4090_handoff.md) · [完整目标任务](docs/baselines_8x4090_task_zh.md) · [SHA-256](outputs/baselines_8x4090_handoff_v1/pallet_baselines_8x4090_handoff_v1.zip.sha256)。包含正式数据、200份源码快照与官方YOLO初始化权重；八项单seed baseline由目标服务器继续实现并训练。

<!-- formal-dataset-delivered-v1 -->
当前正式数据集已完成：10,374张人工帧，10,111正例/263负例，共12,344个托盘框；原train/val/test=6,552/1,455/2,367，待审0。

[下载正式数据集 ZIP（3.33 GiB）](outputs/pallet_dataset_formal_v1/pallet_dataset_formal_v1.zip) · [数据与验收报告](docs/formal_dataset_v1.md) · [活动入口](configs/active_formal_dataset.json)。含COCO、YOLO、AnyLabeling及原生浮点传感器数据；以下旧修正包和辅助训练进度为历史记录，后续以正式入口为准。

<!-- assistant-delivery:human_correction_manual_8692_v1_4090d -->
最新人工标注交付：[1682帧混合修正包](outputs/human_correction_manual_8692_v1_4090d/human_correction_remaining_1682_mixed_v1.zip)。原分组不变，使用`images/mixed`继续检查。

<!-- mixed-return-start:human_correction_manual_8692_v1_4090d -->
最新任务：mixed.zip的1,606人工帧已合并，累计8,692；已启动4090D重新训练。目标剩余1,682帧混合修正包尚未交付。[本轮实时报告](docs/human_correction_8692_report.md)。

<!-- final-verification:human_correction_manual_7086_v2_4090d -->
最新交付已全量复核：[3,288帧混合AnyLabeling修正包](outputs/human_correction_manual_7086_v2_4090d/human_correction_remaining_3288_mixed_v1.zip)。解压后打开`images/mixed`；排除7,086已人工检查帧，保留原分组，55张零检测仍须检查。[本轮完整报告](docs/human_correction_7086_report.md)。

<!-- assistant-delivery:human_correction_manual_7086_v2_4090d -->
最新人工标注交付：[3288帧混合修正包](outputs/human_correction_manual_7086_v2_4090d/human_correction_remaining_3288_mixed_v1.zip)。原分组不变，使用`images/mixed`继续检查。

<!-- hardware-restart-7086-4090d-20261010 -->
最新任务：3090故障后已改用4090D从官方权重重新训练，固定人工划分6021/1031；新3288帧混合包尚未交付。见[实时报告](docs/human_correction_7086_report.md)。

<!-- test500-prepare-20261010 -->
最新test_500任务已冻结人工标签并启动后台训练流程，新包尚未交付；见[当前任务报告](docs/human_correction_7086_report.md)。

# Pallet detection from ToF depth and intensity

最新修正包：240×96域300帧倒置已校正180°，并更新建议框；其余3,488帧图像/JSON未变。[下载3,788帧方向校正包](outputs/orientation_240x96_v1/human_correction_remaining_3788_rotated180_v2.zip) · [来源与校正说明](docs/orientation_240x96_correction.md)。活动协议已更新为`outputs/protocol_v7_oriented`。


<!-- manual-update-complete:human_correction_manual_6552_v1 -->
## 本轮训练与修正包已完成

本轮6,586张人工检查结果已归档；其中原train的6,552张按组隔离为5,569训练/983验证，原val/test的34张仅保存修正结果并排除交付。新YOLO26s完成93轮，最佳epoch42（从0计），内部人工验证AP50:95=0.91190，建议阈值0.70。未开展最终测试评分。

[下载剩余3,788帧修正包](outputs/human_correction_manual_6552_v1/human_correction_remaining_3788_v1.zip)：val1,439/test2,349，无train帧；已排除全部6,586张人工帧及不可恢复黑图。配对、原生坐标、待审标志、ZIP CRC及逐成员哈希均通过。空预测仍待审，val/test属于模型辅助人工工作版本。

ZIP SHA-256：`61088d81e517d66d7ad25e6ef1deac00f08d28f4d18c1c64540237d5c11dc531`。


当前任务（2026-10-09）：剩余train和118帧专题修正已合并，累计6,586张有效人工帧；新模型已完成93轮训练，3,788帧剩余修正包已交付并复核。见[本轮说明](docs/human_correction_6552_report.md)和[实时进度](outputs/human_correction_manual_6552_v1/workflow_status.json)。

This repository contains a reproducible sensor-data pipeline and a four-channel
YOLO26s detector for single-class pallet detection. The input order is depth,
intensity, valid-depth mask, valid-intensity mask. P2 features receive a
validity-gated two-branch fusion and an optional depth-edge feature. A label is
eligible for training only after two distinct reviewers have recorded decisions.

## 历史强度重建与清理包（2026-10-08）

118帧全零原始强度已从PCD重建，148帧不可恢复黑图已剔除。活动协议为 `outputs/protocol_v6_clean`，入口为 `configs/active_dataset.json`。

- [118帧重建图及模型建议复查包](outputs/pallet_clean_intensity_v1/reconstructed_intensity_118_review_v1.zip)
- [剩余8,693帧AnyLabeling修正包](outputs/pallet_clean_intensity_v1/human_correction_remaining_8693_clean_v1.zip)
- [使用说明、计数及核验记录](docs/clean_intensity_review.md)

旧v5协议及8,806/8,693帧包为历史版本；后续人工检查使用本轮3,788帧包，底层协议仍使用v6清理版本。118帧专题包与剩余包重叠100帧，专题包另包含18帧再次复查的历史人工帧。

## Current status

全对话累计总结与日志：

- [全会话训练、测试进度](docs/session_summary.md)
- [训练与验证日志](docs/training_log.md)
- [调试、失败与待处理问题](docs/debug_log.md)
- [修改日志](docs/change_log.md)

已核验25条运行记录：22条完成、3条未完成；正式全量三种子与留域研究仍未完成。
训练教师和先导验证指标不代表最终测试结果。日志刷新命令：

```bash
PYTHONPATH=. .venv/bin/python -m pallet.research_log --refresh-progress
```

该命令核对配置、权重和独立参考哈希，保存UTC命名的证据快照并更新训练日志。
当前快照入口为 `outputs/session_logs/latest.json`；调试和修改日志按事件追加。

The historical `outputs/protocol_v5` indexes **10,522 usable unique capture
frames** in 433 conservative collection groups. Four malformed ASCII PCD
payloads and structurally unverified archive/undated items are recorded
separately in `outputs/reconciliation_v5.json`. A content-addressed floating
sensor cache is sealed at `outputs/cache_v5/sealed_index.json`.

## 人工修正导出

最初完整 AnyLabeling 历史数据包为 `outputs/anylabeling/pallet_v5_20260930.zip`，解压后
打开 `images/train`、`images/val` 或 `images/test`。全部 10,522 张可用唯一帧
保持原生坐标，同名 PNG/JSON 可直接编辑，附配准深度与有效掩码。
未审、ignore、训练建议和参考冲突分别标记；空框不代表负例。
操作方法和重建命令见 [AnyLabeling 人工修正说明](docs/anylabeling_export.md)。
人工完成后勾选 `human_reviewed` 并保存；数据包不自动回写冻结参考。

The frozen 600/150/150 pilot is in `outputs/stages/pilot600_v5` and
`outputs/protocol_v5/pilot.json`. Independent reviews are ingested into
`outputs/review_v3/labels`; `outputs/review_v3/latest.json` identifies the
current snapshot. The validation reference is frozen in
`outputs/protocol_v5/references/pilot_val.jsonl`. Of 600 requested training
frames, 282 have scored positive/negative labels and 318 are explicitly
ignored; 106 of 150 validation frames are scored. The 150-frame blind test
reference is frozen, with 92 scorable frames and only one confirmed negative.
Pilot model scores are validation-only workflow checks, not
final cross-configuration results. See `docs/experiment_status.md` and
`outputs/progress_v5.json` for measured progress. The fourth review round uses
`docs/annotation_policy_v4.md`, whose examples exclude the training audit reserve.
The paired 200/50/50 train/validation/test panel is frozen in
`outputs/protocol_v5/references`; the full study still lacks most labels and
complete validation/test references. Eight same-snapshot pilot comparisons,
trained-weight latency measurements and their limitations are recorded in
`docs/pilot_validation_v5.md`. The small verified-depth input check and its
domain imbalance are documented in `docs/paired_modality_pilot_v5.md`.

## Runtime

纯黑图来源已逐帧核验：剩余包113张黑色主图来自恒定强度显示退化，均有可用深度；建议同时复核34张相同来源的人工负例。证据和名单见[纯黑图来源分析](docs/black_image_source_analysis.md)，本次未修改冻结数据及ZIP。

历史1,716帧分支的修正包及三轮比较已完成：排除累计1,716张人工检查帧，原剩余8,806帧预测、文件配对、坐标和ZIP CRC全部通过。相邻轮次实质变化率由47.46%降至24.07%，仍未达到候选收敛标准。详见[最新运行报告](docs/human_correction_latest_report.md)、[修正ZIP](outputs/human_correction_manual_1716_v2/human_correction_remaining_8806_v1.zip)及[完整三轮报告](outputs/human_correction_stability_1716_v2/report_zh.md)。

最新1,716帧人工修正辅助分支已完成训练和8,806帧候选包全量审计。当前为v2加速分支（actual batch16/effective16/workers4，约31–33秒/epoch）；配置见 `configs/human_correction_1716_accelerated.json`，恢复入口 `bash scripts/run_human_correction_1716.sh`，详细状态见[辅助模型任务说明](docs/human_correction_assistant.md)。

人工修正辅助模型的执行状态、训练数据哈希和命令见
[辅助模型任务说明](docs/human_correction_assistant.md)。manual1330分支合并两批共1,330张用户确认帧，按采集组划为1,130训练、200验证；YOLO26s已完成训练、阈值校准和剩余9,192帧候选预测，AnyLabeling ZIP已通过全量配对、坐标、待审标志及CRC审计。验证指标仅用于本分支选轮和操作性阈值校准，不代表正式泛化或最终测试结论。

Use Python 3.11 and the local `.venv`. The environment reuses the existing
CUDA-enabled PyTorch 2.6 installation, and has Ultralytics 8.4.163,
RF-DETR 1.11.0 and its `torch-hungarian` training solver installed.
The Python package paths can be inspected with `.venv/bin/python -m pip list`.
Source images remain in `/root/private/data/pallet`; indexing does not copy
the 84 GiB data tree.

```bash
.venv/bin/python -m pytest -q
.venv/bin/python -m pallet.cli audit
.venv/bin/python -m pallet.cli dedup
.venv/bin/python -m pallet.cli prepare
.venv/bin/python -m pallet.cli export --annotations outputs/annotations_pilot.jsonl
.venv/bin/python -m pallet.progress_v5
```

`prepare` starts a new unreviewed annotation snapshot. Preserve existing
annotated JSONL files before invoking it with the same output path. Exact
duplicate grouping is loaded from `outputs/content_hashes.json`; run `dedup`
after adding raw files.

`outputs/progress_v5.json` shows current split-level review coverage and
completed runs. `outputs/review_v3/tasks` contains native-coordinate blind
review batches; `outputs/review_v3/adjudication_tasks` contains disagreements.
Every unresolved or ignored frame is kept distinct from a true negative.
`outputs/stages/full_review_queue_v5i` partitions the remaining work into
frozen batches of at most 1,024 frames per split. Its manifest records resolved,
in-flight and waiting frames separately. Round six is awaiting review completion;
raw review submissions can lead the ingested label snapshot. Frozen reference
versions also contain nine overlapping test frames with differing box content;
the session summary records this unresolved reference conflict.

`configs/experiment_matrix.json` is the candidate full-study matrix. Its
execution is gated on source labels and independent references. The smaller
`configs/pilot600_v5.json` has completed YOLO26s and the proposed model;
YOLOv8, RF-DETR and P2 structure ablations are separate completed pilot runs.
Reported pilot scores use only the frozen validation reference.

The optional SAM3 proposer reads the checkpoint in the neighboring
`zero_shot_segmentation` project. Proposals stay unreviewed and cannot be used
as reference labels. A pilot found no SAM3 boxes on two sensor visualizations;
its useful RGB result cannot be transferred without registration.

```bash
.venv/bin/python -m pallet.cli propose --annotations outputs/annotations.jsonl --limit 8
.venv/bin/python -m pallet.fewshot \
  --annotations outputs/annotations_reviewed_v2.jsonl \
  --reference-id '2024_11_29/29-11-2024_07-00-28#all' \
  --output outputs/more_candidates.jsonl
```

For a reviewed snapshot, the guarded trainer and evaluator are:

```bash
.venv/bin/python -m pallet.cli train --protocol outputs/protocol_v5 \
  --subset outputs/stages/pilot600_v5/subset.json \
  --cache-index outputs/cache_v5/sealed_index.json \
  --annotations outputs/stages/pilot600_v5/annotations.jsonl --output outputs/run
.venv/bin/python -m pallet.cli evaluate --protocol outputs/protocol_v5 \
  --annotations outputs/stages/pilot600_v5/annotations.jsonl \
  --checkpoint outputs/run/best.pt --split val --output outputs/run/val.json
.venv/bin/python -m pallet.cli train --family rfdetr-small \
  --annotations /path/to/frozen.jsonl --output outputs/rfdetr
.venv/bin/python -m pallet.cli predict --frame-id '2024_11_29/29-11-2024_07-00-28#all' \
  --checkpoint outputs/run/best.pt --roi-out outputs/pallet_roi.npz
.venv/bin/python -m pallet.cli export-model --checkpoint outputs/run/best.pt \
  --output outputs/run/pallet.onnx
```

`train` rejects missing reviewed training or validation labels. `evaluate`
checks the training snapshot hash and requires a separate frozen independent
reference snapshot for final held-out test scoring.
The default `--recipe project_adamw_pilot` is an engineering pilot.
`--recipe official_research_constrained` runs the locked YOLO or RF-DETR
numerical recipe with explicit sensor-data deviations; `official_default`
remains gated. See `docs/official_recipe_gap.md` for validation and limitations.
`--holdout-domain` removes the chosen configuration from source training,
and source normalization is fitted afresh. Configurations here are sensor-grid
and batch-projection evidence, not confirmed physical camera identities.

Data coordinates and annotations are in the native depth grid. RGB pictures
are side evidence only; their boxes are not projected onto depth. `ignore`
and unreviewed frames are excluded from training/evaluation. The exported
COCO file retains explicit frame status and provenance; YOLO labels are
emitted for reviewed positive and negative frames only.

ONNX output is fixed at the checkpoint input size and contains raw predictions;
box thresholding, native sensor coordinate restoration and optional PCD ROI
extraction are handled by the inference pipeline. The 64-pixel ONNX artifacts
in `outputs/` are synthetic smoke tests, not deployable pallet weights.


<!-- manual-proposal-stability:human_correction_stability_1716_v2 -->
## 2026-10-08：剩余修正包及三轮建议稳定性

历史版本已排除累计1716人工检查帧，原剩余8806帧修正包全量审计通过（已由清理后的8693帧包替代）。历史ZIP：`outputs/human_correction_manual_1716_v2/human_correction_remaining_8806_v1.zip`；SHA-256 `49fd66302b974f29ee913f924985cecec953950ac9734d2e69bff26c8a6e823b`。固定同一未检查范围完成三轮建议差异比较，结论：未达到操作性候选收敛标准。稳定性不代表正确，仍需人工检查。报告：`outputs/human_correction_stability_1716_v2/report_zh.md`；优先检查CSV与报告同目录。


<!-- assistant-delivery:human_correction_manual_6552_v1 -->
## 2026-10-09：累计人工标签辅助分支完成

6552张人工帧按组隔离为5569训练、983验证。YOLO26s实际93个epoch，因patience停止；最佳epoch42，内部人工验证AP50/AP75/AP50:95=0.98832/0.96557/0.91190。阈值0.70，校准召回0.97331。该验证集参与选轮与校准，指标不作为独立泛化结果；未进行测试标签评分。

剩余3788帧预测全部成功、0错误，人工帧重叠0，全量配对/尺寸/坐标/待审状态与ZIP CRC审计通过。包：`outputs/human_correction_manual_6552_v1/human_correction_remaining_3788_v1.zip`；SHA-256 `61088d81e517d66d7ad25e6ef1deac00f08d28f4d18c1c64540237d5c11dc531`。零检测仍待审，val/test候选仅用于人工修正。完整结果见 `outputs/human_correction_manual_6552_v1/delivery_manifest.json`。

## 2026-10-12：托盘目标多属性聚类

新增 `python -m pallet.cluster_targets`，完成正式数据集12,344个目标的外观与点云分析。结果为44个外观簇、23个可见几何簇，提出五组可见结构家族候选；材质与完整规格保留未知。正式标签与划分保持原样。[交付说明与报告入口](docs/pallet_target_clustering_report.md)。

## 2026-10-14：按A类的最小逐面标注种子集

新增 `python -m pallet.cluster_annotation_seed`，按A00–A43各选10个托盘，导出440张不同原尺寸帧及逐面AnyLabeling建议。统一类别为 `pallet_fork_face`，同帧其它托盘区域明确忽略，人工复核后另建分割训练快照。[标注包与使用说明](docs/cluster_annotation_seed.md)。
