D3D-HOI Contact 标注与人工校准指南¶

1. 开发/人工校准协议（不是 formal automatic-test 协议）¶

每个 case 的 contact 目录只包含两份权威语义标注：

<case>/recon/preprocess/contact/
├── contact_labels_raw.npz
└── contact_labels.npz

contact_labels_raw.npz 是 VLM 原始结果，HTML 不修改它。
contact_labels.npz 是当前开发 HOI-align 读取的人工确认结果；因此相关现有产物只能标 manual-assisted pilot/historical，不能作 automatic formal main row。
final 是否存在直接表示该 case 是否完成确认。
两个 NPZ 都只包含一个 labels 数组，不包含 MANO 顶点、采样参数、模型响应或审核状态。

论文 provisional 选择 automatic main (A)：private test 上 Ours 必须使用 test 解封前冻结的 automatic predictor/raw VLM provider，不允许 case-level 人工查看、编辑、重试或选择。人工 contact_labels.npz 只可用于 visible calibration/evaluator repeatability 与单列 manual-assisted/oracle diagnostic，不与 automatic methods 排名。若 automatic provider 在 freeze 前无法闭环，不默认改用人工 label；而是把 task 收缩为 video + provided contact intent，给所有 row 相同 label 权限并删除 automatic end-to-end claim。

当前 VLM 和 HTML 的 labels 固定为 bool[T,2]：

labels[:,0] = left hand active
labels[:,1] = right hand active

四种人工选择对应：

none  = [0,0]
left  = [1,0]
right = [0,1]
both  = [1,1]

2. Batch VLM¶

统一使用 arthoi4d 环境：

/DATA/intern/hoi4d/miniconda3/envs/arthoi4d/bin/python \
  scripts/run/d3dhoi/infer_contact_labels_batch.py \
  --cases-root output/runs/<run>/cases \
  --config configs/methods/recon/<contact-config>.yaml

常用 case 选择：

--case-list b001-0010_cad12561,b004-0013_cad7221
--case-list-file configs/case_lists/my_cases.txt

不传 case selector 时扫描全部 case。脚本不包含 failure5/full20 等实验集合硬编码，也不绑定默认 config；--config 必须显式传入。raw 已存在时跳过；显式 --overwrite 才重新调用 VLM。如果 final 已存在，overwrite 会拒绝执行，避免 raw 和人工确认结果失配。

VLM 使用固定的 red/blue object-hand crop 和生产 causal prompt，只判断左右手。模型响应、crop 和 overlay 写到 recon/preprocess/visualizations/，属于非权威 debug/review media，不能被优化 loader 消费。

3. 启动 HTML sidecar¶

/DATA/intern/hoi4d/miniconda3/envs/arthoi4d/bin/python \
  scripts/run/d3dhoi/serve_contact_review_editor.py \
  --cases-root output/runs/<run>/cases \
  --host 0.0.0.0 \
  --port 8035

打开：

http://<server>:8035/

页面行为：

未确认 case 从 raw 开始编辑。
已确认 case 从 final 开始编辑。
每个 interval 点击 left/right/both/none。
点击只修改浏览器状态，不立即写磁盘。
“恢复 VLM 原始结果”恢复到 raw。
“确认该 case”原子写入 final。
没有修改的 case 也必须点击确认。
页面离开时如有未保存修改，会显示浏览器警告。
全部 case 都有 final 后显示“全部完成”；不再运行 materialize、conversion 或 install。

interval 边界严格读取每个 case 的 recon/runtime/pipeline_config.yaml 中的 reconstruction.preprocess.contact.interval_frames，不会写入 NPZ，也没有 sidecar 级默认 fallback。

不要同时让两个人编辑同一个 case。多人标注时将 case 列表拆成互不重叠的 batch。

4. HOI-align 消费方式¶

HOI-align 只读取：

<case>/recon/preprocess/contact/contact_labels.npz

final 缺失时立即报错，不回退到 raw 或旧 contact_ref_*.npz。

R66 默认优化配置：

reconstruction:
  optimization:
    contact:
      mode: mano_fingertip10
      surface_side: palmar
      vertices_per_label: 16

loader 在内存中把 [T,2] 左右手标签展开为同侧五指 [T,10]，再使用优化阶段共享的 SMPL-X runtime 构造 palmar k16 顶点。改变 k 或 surface 不需要重新生成标注，也不会重复构建 SMPL-X model。

5. 扩展到数百视频¶

建议每批 20–50 个 case：

准备完整 preprocess case 目录。
batch VLM 生成 raw。
检查失败列表并仅重跑失败 case。
启动 sidecar，逐 case 确认。
验证每个 case 都有 final。
才允许启动 HOI-align。

批量 preflight：

/DATA/intern/hoi4d/miniconda3/envs/arthoi4d/bin/python - <<'PY'
from pathlib import Path
import numpy as np

root = Path("output/runs/<run>/cases")
for case in sorted(path for path in root.iterdir() if path.is_dir()):
    contact = case / "recon/preprocess/contact"
    for name in ("contact_labels_raw.npz", "contact_labels.npz"):
        path = contact / name
        assert path.is_file(), path
        with np.load(path, allow_pickle=False) as payload:
            assert payload.files == ["labels"], (path, payload.files)
            labels = payload["labels"]
            assert labels.ndim == 2 and labels.shape[1] == 2 and labels.dtype == np.bool_, path
print("contact labels preflight passed")
PY

重点人工检查：遮挡、动作开始/结束、support hand、左右手 bbox 重叠、none 与 both，以及 articulated part 已停止后仍搭在物体上的手。

6. Canonical contact 结果¶

production contact 目录只接受 contact_labels_raw.npz 和 contact_labels.npz。旧格式迁移工具已经删除；旧结果应重新生成 canonical preprocess，而不是在运行时或离线保留兼容路径。