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