agenticSTAR：从单目视频进行智能体式形状追踪与三维重建

Agentic STAR：单目视频中的形状跟踪与重建（Shape Tracking and Reconstruction from Monocular Videos）

Kirill Mazur、 Nikita Karaev、 Matthew Chang、 Jitendra Malik、 Nur Muhammad "Mahi" Shafiullah
Amazon FAR（Frontier AI and Robotics，前沿 AI 与机器人）

项目主页见 agenticstar.github.io。

概览

这是一个用于关节物体（articulated objects）智能体形状跟踪（agentic shape tracking）的脚手架。一个编程智能体（coding agent，如 Codex 或 Claude Code）会查看单目视频的各帧，编写一段 Blender 脚本，利用基元（primitives）构建物体，逐帧在已知相机前对其进行摆姿，并声明其关节，然后进行渲染、与原帧对比并迭代。输出是一个带有命名部件的 GLB 文件，以及一个包含每帧位姿与关节状态的 pose.json。

智能体所使用的两个主要组件是位姿搜索视图（sweep/apply，扫描/应用）以及时间工具（temporal tool）。智能体读取的任务文件是 AGENT_TASK.md；scene.py 的契约位于 conventions/。

本仓库基于 GPT-5.6-Sol 与 Claude Fable 5 设计并测试（译注：原文中的这两个名称疑为内部玩笑/化名，并非公开存在的真实模型版本号）。论文中的结果是在开启 mechanism 模块（--enable mechanism；默认关闭）下获得的；较新的模型在关闭该模块时往往表现更好。GPT-5.6-Sol 的相关结果是在 critic 分支下获得的，该分支会引入第二个 VLM（Vision Language Model，视觉语言模型）作为评论者；较新的模型应当无需该分支也能正常工作。

安装

Linux x86_64，需配 NVIDIA GPU。主机上需要预先安装 micromamba、git、curl、tar、xz、python3、tmux、bubblewrap、iproute2 和 ffmpeg。

沙箱（sandbox）的网络命名空间需要 root 权限（或 CAP_NET_ADMIN 能力）。

./install.sh
# artscript env、Blender 4.2.5、pi3x env

export ANTHROPIC_API_KEY=sk-ant-...
# 用于 Claude Code

tools/install_claude_bwrap.sh
# 只需执行一次；密钥存放在 checkout 之外的 state 目录中

export OPENAI_API_KEY=sk-...
# 用于 Codex

tools/install_codex_bwrap.sh

claude 和/或 codex 必须位于 PATH 中。

运行

在已提交的 garden-shears 示例上执行一次有监督的运行，使用 GPU 0：

tools/run_kf.sh --agent claude --timeout-hours 4 examples/garden_shears/capture:0

tools/claude-supervisor attach --run-dir runs/capture_kf_<stamp>
# 观察运行情况

使用 --agent codex 与 tools/agent-supervisor 即可改为 Codex。添加 --enable mechanism 可复现论文中的设置。输出落在 runs/<name>/ 下：scene.py、mesh/object.glb、mesh/pose.json，以及每次迭代的渲染图与对比图，存放在 iterations/ 子目录中。一次运行会持续数小时，并消耗大量 token；--timeout-hours 用于限定其时长。

智能体运行在 Bubblewrap 沙箱内，对网络的访问被限制为模型提供商的 API 主机。

SANDBOX_NET=open 可关闭该限制以便调试。

./run.sh --help 列出其余选项（GPU 钉扎、帧选择、断点续传、--prompt-only）。

输入格式

一个 capture 是一个目录，包含：

frames/000000.jpg, 000005.jpg, ...           # 视频帧
mask_object/<stem>.png                       # 每帧的物体二值掩码，与帧同尺寸
mask_hand/<stem>.png                         # 可选；遮挡物掩码，按 don't-care 处理
tracking/cameras.npz                         # 每帧的 camera-to-world 与相机内参
tracking/keyframes.json                      # 拥有相机参数的帧

掩码可由任意分割器生成。相机参数来自 Pi3X，tools/make_capture.py 会针对关键帧联合运行它：

tools/video_to_frames.sh clip.mov my_input --every 5
# 为上述各帧添加 my_input/mask_object/<stem>.png

micromamba run -n pi3x python tools/make_capture.py --src my_input --out captures/my_object

tools/run_kf.sh --agent claude captures/my_object:0 --depth

--depth 还会额外保留 Pi3X 的逐帧点图（pointmaps），存放在 depth/ 中，供深度打分器使用。

examples/garden_shears/input/ 即是这样的一个输入目录，而 examples/garden_shears/capture/ 是转换器从该输入生成的产物。模式定义、读取器与校验器位于 datasets/common/。

致谢

感谢 Pi3 的作者公开发布他们的模型与代码。

引用

@misc{mazur2026agenticstar,
  title={Agentic STAR: Shape Tracking and Reconstruction from Monocular Videos},
  author={Mazur, Kirill and Karaev, Nikita and Chang, Matthew and Malik, Jitendra and Shafiullah, Nur Muhammad},
  year={},
  howpublished={项目主页见 agenticstar.github.io},
  note={Project page}
}

许可证

MIT，详见 LICENSE。

harness/views/sweeps/lib/_vendor/ 包含两段改编自 SciPy 的优化器例程，沿用其 BSD-3-Clause 许可证（SCIPY_LICENSE.txt）。