Communitygithub.com

video2threejs

从参考视频(AI生成或实拍)重建房间/场景,生成纯代码的过程化Three.js立体模型,布局、色彩、光照、物体、角色及其运动时间线保持1:1还原。

video2threejs 是什么?

video2threejs 是一个高级 AI 智能体技能,旨在从参考视频(如 Seedance、Sora、Veo 或实拍素材)重建出纯代码、零外部资源的 Three.js 立体场景。它严格遵循 1:1 还原原则,精确匹配视频中的相机、物体的位置与比例、调色板、光照、角色外观以及完整的运动时间线。该技能的核心是通过代码进行重建,而非 NeRF、视频转网格或下载资产包;它专注于包含人物和时间的完整房间重建,是 img2threejs(针对单张图片的单物体或角色)的姊妹技能。文档中规定了严格的规则和流水线,包括实时预览、多帧分析、透视求解、逐个物体精细雕刻、对不确定项进行专门研究,以及通过截图验证的迭代过程,最终生成一个可在浏览器中查看的交互式 Three.js 场景。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/pacb9148/Video2ThreeJS/tree/HEAD

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

video2threejs — 视频 → 程序化 Three.js 场景

从参考视频(Seedance / Sora / Veo 输出,或实拍素材)重建出一个纯代码、零资产的 Three.js 场景。标准是 1:1:相机、每个物体的位置和比例、调色板、光照、角色外观,以及角色遵循的运动时间线。

通过代码重建——不是 NeRF,不是视频转网格,也不是下载的资产包。这是 img2threejs(从单张图片重建单个物体或角色)的姊妹技能;本技能覆盖包含人物和时间的完整房间。

本文件是始终加载的路由器。它包含了操作顺序、带有理由的硬性规则、完成标准以及反模式。每个阶段的完整合约都存储在规则名称对应的 grimoire/ 文件中——在到达该阶段时再阅读它,而不是之前。

何时使用

  • 用户分享了一个视频或带视频的推文,并要求重建/复制/"用 three.js 实现这个"。
  • 用户询问如何程序化地建模一个特定的软性或有机构体(如羽绒被、枕头、毛绒玩具、动漫头发、猫)。
  • 需要从素材中 1:1 重建一个房间或室内场景,用于游戏、立体模型或交互式致敬。

不适用于:从单张图片重建单个主角物体(请使用 img2threejs),或接受下载 GLB 资产的项目。

必需输入

  • 视频(mp4 URL / 推文 URL / 文件)。如果是推文,获取媒体变体并下载 720p mp4。
  • 用户的容忍度:"1:1"(本技能默认值)或"神似即可"。
  • 一个可供用户通过浏览器打开的开发服务器运行环境。

硬性规则

以下每条规则都是 Blue Room 案例研究中付出的返工代价换来的。它们不是风格偏好。

1. 雕刻时实时预览

在建模任何东西之前,启动开发服务器并为用户 open 页面。编写可以热重载的阶段场景(墙壁 → 家具 → 光照 → 角色 → 运动 → 介绍相机)。在页面角落放置阶段标签;将 window.onerror 路由到其中,使运行时错误在页面上可见。 原因: 反馈成本最低的时候是在错误的墙壁出现的那一刻,而不是在整间房间围绕它布置完毕之后。 → grimoire/build/live_preview.md

2. 先分析视频,从多个角度

在整个片段中提取至少 8 帧。对于空间事实(哪面墙、哪个角落、什么上面放着什么),逐格读取加网格的帧;在第二帧中确认每个事实;如果透视仍然无法解析,请用户在截图上的角上和地板上画线。在编写代码之前,生成空间事实表、物体清单、调色板、角色卡片和运动场景表。 明确决定每个镜头中——是什么在移动:主体还是相机。搞反了代价很高:一个被做成缓慢推进的镜头,结果发现是静态相机看着一只手臂举起,而手臂还没有绑骨骼。 原因: 三个自信的重建都把窗户放在了错误的位置;一个红色笔画的草图就解决了问题。 → grimoire/intake/multi_view_analysis.md,grimoire/intake/frame_extraction.md

3. 空间先于物体;解析相机

决定可见的墙壁和角落,设置坐标框架(左墙 x = LW,右墙 z = RW),然后使用 forge/solve_camera.py 解析相机(基于地标分数)。之后才放置家具。 使用 forge/solve_camera.mjs 从测量数据(地标屏幕位置和表观大小)进行解析,并限制仰角,这样求解器就不会选错分支。在追求一个构图之前,检查它是否可能实现:一个综合参考的两个镜头通常无法在同一个尺度下共存(grimoire 中的三角不等式测试)。如实告知,采用最接近的连贯构图,然后继续。 原因: 凭感觉放置的相机使后续的每个比较都失真;一个不可能的相机会使其永远失真。 → grimoire/space/perspective_solving.md

4. 保留书面的布局合约

每个物体一行:墙面、位置、大小、关系、参考帧。每次用户修改,先编辑合约,再修改代码。合约是所有位置(家具、姿势和相机求解器使用)的单一事实来源。 → grimoire/space/layout_contract.md

5. 颜色来自像素

在网格帧上对每个物体的受光面和阴影面进行采样;在它们之间选择基色,偏向亮色。永远不要凭记忆输入颜色。 → grimoire/intake/frame_extraction.md

6. 真实光照,诊断而来,非绘制得来

带真实窗户开口的实体墙壁;正好覆盖室内空间的屋顶;底部阶梯为零的卡通渐变;一个覆盖房间的带阴影相机的温暖太阳。切勿使用绘制的地板补丁、体积平面或浮动粒子来伪造光照。使用纯直射光渲染(?diag=sun)进行诊断:墙壁和天花板必须是黑色,光斑必须落在几何体指示的位置。 → grimoire/build/lighting.md

7. 逐个物体雕刻至 8/10 分

在构建一个物体之前,列出其参考特征(形状、位置、颜色、附件)。构建后,从近摄相机进行截图并评分。未达到 8 分之前不要继续。几何优于纹理:羽绒被是一块垂坠的布料,书架是敞开的并放有真实书籍,枕头是厚实的并倾向于一边。 → grimoire/build/procedural_recipes.md

8. 一个网格,雕刻而成——绝非拼装而成

一个有机形态(头部、耳朵、躯干、肢体、手、长袍)是一个封闭的表面,通过移动其自身的顶点来塑造形状:凸起、凹陷、从某一个面挤出一个肢体,或使用平滑场进行置换。不要将球体、圆锥体和胶囊体拼装在一起。拼装的有机体每次都会产生:发光的接缝随光移动、埋入部分周围有轮廓环、关节旋转时零件分离、深度冲突闪烁、因一个子网格缠绕方向错误而导致的“透明”外观,以及任何材质调整都无法消除的着色断裂。

适用场景: 参考中共享皮肤的任何部分在构建中也必须共享一个网格——鼻子是面部向前推的结果,耳朵是颅骨隆起的结果。真正独立的物体(灯、书、柱子、窗框)保持独立的几何体元;位于表面上且永不形变的小型刚性固体(发卷、铆钉、花朵)是雕刻皮肤上的实例化装饰品;细长的部分是一根扫描管,而非一连串胶囊体。

两种基板: 致密细分几何体元上的置换场(头部、近球形形态),或箱式建模笼 + Catmull-Clark,然后对细节进行置换(身体、四肢、手、衣物)。两者都只产生一个皮肤,骨骼绑定的就是这个皮肤。

原因: 本项目中每个拼装的有机体最终都还是作为一个网格重建了,在接缝问题耗尽了每次审查回合之后。 → grimoire/build/one_mesh_sculpting.md,grimoire/build/box_modelling.md

9. 先推理,然后逐步雕刻,每步完成

在接触几何体之前,先书面描述其形态:基础体积、哪些特征是凸起的、哪些是凹陷的、哪些是斜面变化,以及它们必须按什么顺序应用——每一步都建立在上一步留下的表面之上。然后将工作分解为每一步都留下一个有效的、可检查的表面的步骤(空白基础 → 大平面 → 主要特征 → 次要特征 → 精细细节),并在开始下一步之前完成每一步:截图、输出其数值特征、展示它、获得认可。第 2 步留下的一个摇摆不定的问题在第 5 步无法修复,因为现在有五个场叠加在它上面。绝不要有结果只能在后续步骤完成之后才能判断的步骤。

原因: 那个一团一团雕刻出来的脑袋被扔掉了两次;而同一个脑袋按照“空白脸 → 凹陷 → 眼睛 → 嘴 → 鼻子”雕刻,每步签收一次,就被接受了。 → grimoire/build/one_mesh_sculpting.md

10. 用数字验证表面,而不是用眼睛

在表面上输出一个剖面——脸部的中线、手掌的横线、关节周围的环——并检查它是否在应该单调的地方保持单调。两个凸起之间的平台在眼睛里看起来像凹陷,而镜面高光会同时隐藏两者。在任何笼状操作后,同时统计被不等于 2 个面使用的边数:非零意味着一个 T 形连接,细分会将其渲染成一条硬性折痕。 → grimoire/build/box_modelling.md,grimoire/build/one_mesh_sculpting.md

11. 封闭实体、正确的缠绕方向、尽可能保持单一表面

一个手工制作的扫描管有两种可能的三角形顺序,只有一种朝外;错误的一种会导致 FrontSide 剔除外壳,你看到的将是物体的内部——图形看起来是透明的和“缝合不良”,而你会归咎于材质。LatheGeometry 是一个开放管。关节球必须比它们覆盖的管端大。倾向于一个连续的轮廓(颈和躯干在一个扫描中完成)而不是两个拼装在一起的几何体元:一旦它们的横截面不同或关节旋转,“足够深入以至于不会显示出来”的说法就不再成立。使用 ?diag=flat(不透明材质——仍然透明意味着几何问题),?diag=norm,然后 ?off=<部分> 进行诊断。 原因: 几个审查回合浪费在了为一行索引顺序错误的 bug 进行材质调整上。 → grimoire/build/solid_geometry.md

12. Shader 静默失败——先连接错误钩子

在编写任何自定义材质之前,将 renderer.debug.onShaderError 连接到页面上。一个编译失败的 ShaderMaterial 不渲染任何东西,并且只在控制台中记录日志。然后了解那些静默的问题:modelMatrix 只存在于顶点阶段;pow(负值, 2.0) 和 smoothstep(高值, 低值, x) 在 GLSL 中是未定义的,会产生 NaN;一个整数哈希在位操作之前溢出为 double,会产生偏差并抹平场景中的每个纹理;当相机扫过肢体边缘时,菲涅耳效应无法制造出大气效果。 → grimoire/build/shader_traps.md

13. 不确定时进行研究

如果某个构建方法未知(布料、头发、灯具弧线),搜索 three.js 示例、论坛和姊妹技能,列出至多三种方案,选择最可控的一种,引用来源,并将发现记录在 grimoire/research/when_unsure.md 中。使用节点验证数学(欧拉顺序、几何体 φ 原点),而不是推理。 → grimoire/research/when_unsure.md

14. 运动必须看起来像人类

根关节欧拉顺序 YZX;大腿负值 = 前进,小腿正值 = 向后折叠;仰卧时 rx=-π/2,俯卧时加上 rz=π,侧卧时加上 rz=±π/2。头部的 rotation.x 与直觉相反——Rx(+t) 看起来是向下看。将戏剧性手势指定为手掌在这里,朝向那里,手指向那里,并使用 forge/solve_ik_arm.mjs 求解,按顺序为它们设置关键帧并带有连续性项,这样姿势保持在同一个分支上,并内插为单一动作。航点(via)引导角色绕过家具。坐姿和躺姿的高度是从羽绒被顶部测量的。为任何“消失”的角色记录关节和边界盒。对每个场景截图。

使用刚性分段和短铰链(一个肢体直径的混合范围,关节处的半旋转骨骼,集中在关节上的笼状循环)绑定皮肤,并推导每个关节轴而不是假设它——手腕的屈曲轴是 前臂 × 手掌法线,如果建立在肘部的铰链轴上,关键帧将完全不起作用。角色引起的效果属于片段的时钟,而非镜头的。 → grimoire/build/characters.md,grimoire/build/motion_timeline.md,grimoire/build/skinning_rig.md

15. 截图一切,然后自我审查

使用 GPU 路径的无头 Chrome(几秒钟),视口采用视频的宽高比,与参考帧进行 hstack。在移交之前,编写一个有评分的自我审查表格并附带差距列表,让用户选择下一批。"改进了"不等同于"完成了"。 → grimoire/review/verification.md,grimoire/review/self_review.md

16. 用户的“禁止”列表是永久的

用户拒绝的所有内容都进入 grimoire/feedback/user_signals.md,并且永不再引入(浮动粒子、绘制的光照、乐高式床上用品、丝状头发、狗一样的腿、墙上的灯光……)。 → grimoire/feedback/user_signals.md

17. 从项目根目录部署

vercel --prod(或任何部署)只能在项目目录中执行。编写项目 CLAUDE.md,包含坐标框架、相机、调色板、光照、物体事实、调试参数以及用户的列表。 → grimoire/review/handoff.md

流水线

阶段操作输出阅读文档
0获取视频,提取帧和网格图像frame_*.jpg,grid_01.jpgintake/frame_extraction.md
1多角度分析事实表、清单、调色板、角色卡片、场景表intake/multi_view_analysis.md
2空间:墙壁 → 框架 → 相机求解 → 布局合约landmarks.json,CAM/LOOK/fov,合约space/*
3使用实时预览搭建脚手架;从模板生成分段骨架用户观看的运行中页面build/live_preview.md
4光照窗户开口、屋顶、渐变、太阳;?diag=sun 干净build/lighting.md
5逐一处理物体;有机形态作为单个雕刻网格,逐步完成每个物体近摄 ≥8/10 分,剖面数据输出build/one_mesh_sculpting.md,build/box_modelling.md,build/procedural_recipes.md,build/solid_geometry.md,build/shader_traps.md
6角色:雕刻 → 绑定 → 权重 → 手势关键帧 → 运动时间线每个场景截图、权重图、IK 日志build/characters.md,build/skinning_rig.md,build/motion_timeline.md
6b体积特效(火、风暴、爆炸),与片段同步轨道截图 + 镜头内截图build/volumetrics.md
7相机 UX:轨道、复制/持久化、介绍C/R,验证过的介绍镜头build/camera_ux.md
8验证和自我审查;与用户循环并排比较、评分表review/*
9部署和移交URL、项目 CLAUDE.mdreview/handoff.md

完成标准

  • 与参考帧并排比对:墙壁、角落、每个物体的位置、大小和颜色、光照方向、角色姿态以及运动序列在空间和时序上都匹配。
  • 场景是独立的(零外部纹理、零下载的 GLTF),只需一个 npm install && npm run dev 即可运行。
  • CLAUDE.md 文件已编写,包含完整的布局合约、相机矩阵、调色板、光照参数以及用户的“禁止”列表。
  • 用户已确认场景在视觉上令人满意,或者提供了具体的修改请求。

相关技能