pjalb

Imported from user-xixiboliya/pjalb (AGENTS.md). Install upstream with npx skills add user-xixiboliya/pjalb. Copyright stays with the author.

Agent Working Notes

General Guidance

你现在应该在C文件夹下进行工作。

/mnt/workspace/Sharpa-HOI/A/HO-Tracker-Baseline-Challenge/data中有数据，但是你尽量不要修改，这是公用的。

你应该充分阅读代码相关接口、了解细节后执行。

不懂的地方请询问用户。

Current Scope

• Primary task: docs/question.md section 3.3, 物体 2D mask subitem.
• Approved approach: Scheme A, SAM2 prompt-based video propagation.
• Mask definition for this repo: visible object region per frame. The mask includes only pixels of the target object that are visible in the image. It excludes hands, background, support surfaces, and occluded object parts. Motion-capture marker geometry does not need to be reconstructed; if a marker is a separable protruding blob, do not deliberately include it as target shape.
• Target objects for 3.3: pipette, bread, drink bottle 1, drink bottle 2.

Reproducibility Rules

• Use the official HO-Tracker-Challenge dataset source from docs/question.md: kelvin34501/HO-Tracker-Challenge. If the mirror is used, record HF_ENDPOINT=https://hf-mirror.com.
• Use the official SAM2 repository or installed package from https://github.com/facebookresearch/sam2.
• Record the exact SAM2 commit, checkpoint filename, model config, dataset source, sequence id, camera/view id, frame range, and prompts for every produced mask set.
• Keep prompts in small JSON files under configs/ or another committed config directory. Do not rely on unrecorded GUI clicks.
• Treat generated datasets, frames, checkpoints, masks, and overlay videos as artifacts. Keep them under data/, outputs/, or an explicitly documented artifact directory.

Expected Layout

All SAM2 object-mask code now lives in one folder: object_mask_sam2/.

• object_mask_sam2/PROMPT.md: goal-aligned execution prompt / handoff brief.
• object_mask_sam2/README.md: runbook for the object-mask workflow.
• object_mask_sam2/setup_sam2.sh: install deps + clone SAM2 + download checkpoint.
• object_mask_sam2/extract_frames.py: ffmpeg .mkv (FFV1) → JPEG frames.
• object_mask_sam2/sam2_object_masks.py: SAM2 mask generation entry point.
• object_mask_sam2/configs/human_demo.json: REAL config wired to A/.../human_demo, prompts grounded on frame 0.
• object_mask_sam2/configs/sam2_object_masks.example.json: generic template.
• object_mask_sam2/outputs/object_masks/sam2/<sequence_id>/: generated frames, masks, overlays, manifest, area summary (gitignored).

The four target objects map to human_demo sessions: Pipette #1, Bread #1, Drink AD, Drink YYKX. Full session table is in object_mask_sam2/PROMPT.md. Videos are FFV1 .mkv, 1280×720, 15 fps, 3 views (camera_side_1/2, camera_top).

SAM2 Mask Workflow

1. Data is already local under A/.../human_demo/<session>/video/*.mkv (read-only).
2. cd object_mask_sam2 && bash setup_sam2.sh (proxy on).
3. python3 extract_frames.py --config configs/human_demo.json to make JPEG frames.
4. configs/human_demo.json already has box + point prompts on frame 0 for each object; add positive/negative points when the bbox includes hand/rack/scale pixels.
5. Run sam2_object_masks.py (see README/PROMPT for the exact command).
6. Inspect overlays (begin/middle/end + occlusion frames). Add refinement prompts for drift, severe occlusion, or object identity switches.
7. Commit only code/config/docs; generated frames/masks/overlays are gitignored artifacts.

Run Status (2026-07-04)

物体 2D mask 已生成 — 3 视角全覆盖 for all 4 objects with SAM 2.1 large (commit 2b90b9f, SAM2_BUILD_CUDA=0). Outputs in object_mask_sam2/outputs/object_masks/sam2/<seq>/ — per-frame binary masks (masks/object_1/*.png), overlays (overlays/all/*.jpg + all.mp4), manifest.json, mask_area.csv.

12 sequences = 4 objects × 3 synchronized camera views (__side1, __top, __side2), each the full clip of one session. Same frame count across the 3 views of an object → temporally-aligned multi-view masks (usable for visual hull / scale alignment → 「几何一致性 4 分」).

3-view consistency montages (frame 0): outputs/object_masks/sam2/_multiview/<obj>_f0_3views.jpg.

To extend to more sessions: copy a sequence in configs/human_demo.json, point source_video/frame_dir at another mkv (see PROMPT.md session table), re-run extract_frames.py + sam2_object_masks.py --sequence <new_id>.

Quality Bar

• The submitted report must state the mask definition above.
• Each target object needs inspectable masks and overlay visualizations.
• Failed or ambiguous frames should be listed in the per-sequence notes or report.
• Do not claim completed/full-shape masks unless a separate completion method is implemented and documented.

物体 pose 追踪

2026-07-04 工作记录

• 赛题对应 docs/question.md 3.3 的 物体 pose 追踪 | 5：目标是获取物体运动轨迹；已有准确物体轨迹的数据，在与重建物体模型配准后可直接使用 GT 轨迹；其余数据需要从视频恢复。
• 当前 C 工作区路径：/mnt/workspace/Sharpa-HOI/C/.dmux/worktrees/dmux-2026-07-04-222754。
• 公共 HO-Tracker 数据位置来自上层 AGENTS.md，只读使用，不要修改：/mnt/workspace/Sharpa-HOI/A/HO-Tracker-Baseline-Challenge/data/HO-Tracker。
• 当前可见的完整 HuggingFace 本地缓存不存在：/root/.cache/huggingface/hub/datasets--kelvin34501--HO-Tracker-Challenge 只有很小的缓存元数据；若要从视频恢复 pose，需要先下载/解压官方 kelvin34501/HO-Tracker-Challenge 的 RGB 视频、相机参数等原始数据。

已完成的 FoundationPose 准备

• 已克隆 FoundationPose 到当前 C 工作区：third_party/FoundationPose。
• 克隆来源：https://github.com/NVlabs/FoundationPose.git。
• 当前 commit：a1b694b83e633c2cb6115b9063d940a687759392。
• 该仓库官方说明在 third_party/FoundationPose/readme.md；模型权重需放在 third_party/FoundationPose/weights/ 下：
  • refiner：weights/2023-10-28-18-33-37/model_best.pth 和 config.yml
  • scorer：weights/2024-01-11-20-02-45/model_best.pth 和 config.yml
• 已运行基础环境检查：
  • 当前 Python：3.12.12
  • PyTorch：2.9.1+cu128
  • CUDA 可用，GPU：NVIDIA GeForce RTX 4090
  • nvcc：CUDA 12.8
  • 本机没有 conda
  • 缺少 FoundationPose 运行依赖：pytorch3d、nvdiffrast、trimesh、open3d、cv2、warp
  • 缺少 FoundationPose 权重；mycpp native extension 也尚未构建
• 因为缺依赖、缺权重、缺输入数据，本次没有运行 FoundationPose 推理。

当前数据判断

• A 目录样例数据中已有部分 GT 物体轨迹，例如：
  • .../data/test_sample/h1o1/0f900@0/left_obj.pkl
  • .../data/test_sample/h2o2/d6fe3@0/right_obj.pkl
• 这些 *_obj.pkl 是 dict，核心键为 obj_trajectory，形状为 T x 4 x 4，dtype 为 float32。
• 同一目录下存在对应物体 mesh/URDF，如 left_urdf/scan.ply、left_urdf/scan.urdf、right_urdf/scan.ply、right_urdf/scan.urdf。
• A baseline 的 main/dataset/ho_tracker.py 会读取 side_obj.pkl、side_urdf 下的 mesh/URDF；main/dataset/base.py 中还会对 obj_trajectory 应用 mujoco2gym_transf。因此：不要把 pkl 里的原始 4x4 轨迹直接当作 IsaacGym/评分坐标；接入 tracking 前应复用 baseline 的坐标变换逻辑或明确记录转换。

建议路线

• 对已有 *_obj.pkl 的序列：优先把用户正在做的重建物体模型配准到数据中提供的 scan.ply 或官方 mesh 坐标系；配准完成后直接继承 obj_trajectory 作为 GT 轨迹，避免从视频重复估计。
• 对没有 GT 轨迹的序列：再使用 FoundationPose 或同类 6D pose tracker 从视频恢复。FoundationPose 当前 demo/reader 需要至少：
  • 物体 CAD/mesh，尺度和坐标原点已确定；
  • 每帧 RGB；
  • 每帧 depth 或可替代的深度来源；
  • 相机内参 K；
  • 第一帧或关键帧物体 mask 用于注册；
  • FoundationPose scorer/refiner 权重和已安装依赖。
• FoundationPose 输出通常是每帧 ob_in_cam 4x4 pose；后续还需要把它和 HO-Tracker/IsaacGym 使用的世界坐标、物体 mesh 坐标、时间采样率对齐，才能交给 3.4 tracking。

当前阻塞与停止点

• 用户说明物体 2D mask、物体 3D 模型与可视化仍在制作中；当前 C 工作区没有这些最终输入。
• 当前也没有完整的 HO-Tracker 原始 RGB/depth/相机参数数据，只有 A 目录中的 pkl/URDF/mesh 样例和不完整 HF 缓存。
• 因缺少上述数据，不能继续实际恢复物体 pose 或验证 FoundationPose 轨迹质量；后续需要用户或对应 agent 提供：
  • 每个目标物体/序列的 RGB 视频或帧目录；
  • 相机内参，若有多视角还需外参/同步信息；
  • 物体 2D mask，至少第一帧或关键帧；
  • 已定尺度、朝向和原点的物体 3D mesh；
  • 若用 FoundationPose，补齐权重和 Python/CUDA 依赖环境。

Hunyuan 物体 3D 模型与大文件本地目录

2026-07-05 工作记录

• 赛题对应 docs/question.md 3.3 的 物体 3D 模型与可视化 | 6：当前采用 Hunyuan3D 作为物体 mesh 生成与可视化路线，代码入口放在当前 worktree 的 Hunyuan/ 目录。
• Hunyuan/ 下应提交到 master 的内容仅包括轻量 wrapper、配置样例、脚本和运行文档：
  • Hunyuan/.gitignore
  • Hunyuan/README.md
  • Hunyuan/requirements-hunyuan-object3d.txt
  • Hunyuan/configs/hunyuan_object3d.example.json
  • Hunyuan/docs/hunyuan_object3d.md
  • Hunyuan/scripts/*.py
• 不要提交 Hunyuan 官方仓库、模型权重、生成 mesh、渲染图、视频和中间帧；这些内容体积较大，只保存在本地 Git 忽略目录。

当前 master 大文件位置

• 已按用户要求把 Hunyuan 大文件从旧 artifact 目录移动到 master checkout 的真实目录，不再使用软链接：
  • /mnt/workspace/Sharpa-HOI/C/Hunyuan/third_party
  • /mnt/workspace/Sharpa-HOI/C/Hunyuan/checkpoints
• 旧目录 /mnt/workspace/Sharpa-HOI/C/object_3d_hunyuan/ 已清空并删除。
• 当前 Hunyuan/ 大文件总体积约 17G，其中：
  • third_party/ 约 471M
  • checkpoints/ 约 17G
• 子 worktree 中不要再保留 Hunyuan 权重副本；若发现 .dmux/worktrees/*/Hunyuan/checkpoints 或 .dmux/worktrees/*/Hunyuan/third_party 占用空间，应优先删除重复副本。
• Hunyuan/.gitignore 必须忽略 third_party 和 checkpoints，不要进入提交。清理 C 工作区或迁移机器前必须单独保留/备份这些本地目录。

Hunyuan 官方仓库记录

• Hunyuan/third_party/Hunyuan3D-2
  • 来源：https://github.com/Tencent-Hunyuan/Hunyuan3D-2.git
  • commit：f8db63096c8282cb27354314d896feba5ba6ff8a
• Hunyuan/third_party/Hunyuan3D-2.1
  • 来源：https://github.com/Tencent-Hunyuan/Hunyuan3D-2.1.git
  • commit：82920d643c0dc2f7bfd7255f45f62d386edfe60c

Hunyuan 模型权重记录

• Hunyuan/checkpoints/hf/tencent/Hunyuan3D-2mv/hunyuan3d-dit-v2-mv/config.yaml：1608 bytes
• Hunyuan/checkpoints/hf/tencent/Hunyuan3D-2mv/hunyuan3d-dit-v2-mv/model.fp16.ckpt：4928618068 bytes
• Hunyuan/checkpoints/hf/tencent/Hunyuan3D-2mv/hunyuan3d-dit-v2-mv/model.fp16.safetensors：4928151562 bytes
• Hunyuan/checkpoints/hf/tencent/Hunyuan3D-2.1/hunyuan3d-dit-v2-1/config.yaml：2078 bytes
• Hunyuan/checkpoints/hf/tencent/Hunyuan3D-2.1/hunyuan3d-dit-v2-1/model.fp16.ckpt：7366389768 bytes
• 下载记录：
  • Hunyuan3D-2mv 使用过 HF_ENDPOINT=https://hf-mirror.com。
  • Hunyuan3D-2.1 的大权重来自 mirror 下载尝试，小型 config.yaml 后续从官方 HuggingFace endpoint 补齐。

从 master 本地目录恢复 Hunyuan 大文件

• 如果要把 Hunyuan 大文件恢复到另一个 checkout/worktree，优先从 master 的真实目录移动或复制；同一文件系统内需要转移所有权时用 mv，需要保留 master 可运行状态时用 rsync：

mkdir -p Hunyuan
rsync -a /mnt/workspace/Sharpa-HOI/C/Hunyuan/third_party Hunyuan/
rsync -a /mnt/workspace/Sharpa-HOI/C/Hunyuan/checkpoints Hunyuan/

• 恢复后应存在：
  • Hunyuan/third_party/Hunyuan3D-2
  • Hunyuan/third_party/Hunyuan3D-2.1
  • Hunyuan/checkpoints/hf/tencent/...

提交 master 前的大文件规则

• Hunyuan/.gitignore 已忽略 third_party、checkpoints、data/、outputs/、生成的 mesh/纹理/视频和本地 config。
• 提交前运行：

git status --short --untracked-files=all
find Hunyuan -type f -size +50M -printf '%s %p\n' | sort -nr

• git status 中不应出现 Hunyuan/third_party/、Hunyuan/checkpoints/ 或生成结果目录。
• find 若列出大文件，必须确认它们已经被 .gitignore 忽略，或者移动/复制到 Hunyuan/checkpoints、Hunyuan/third_party 这类被 Git 忽略的本地目录。
• master 中只保留可复现流程：脚本、配置样例、文档、commit/hash/权重文件名记录；不要把大权重和官方 repo 历史直接塞进 Git。