video2threejs — ビデオ → プロシージャルThree.jsシーン
参照ビデオ(Seedance / Sora / Veoの出力、または実写映像)をコードのみ、アセット不要のThree.jsシーンとして再構築します。基準は1:1です:カメラ、すべてのオブジェクトの位置と比率、パレット、照明、キャラクターの外見、そしてキャラクターがたどるモーションタイムライン。
コードによる再構築 — NeRF、ビデオ-to-メッシュ、ダウンロードしたアセットパックではありません。img2threejs(1枚の画像から1つのオブジェクトまたはキャラクター)の姉妹スキルです。このスキルは、人と時間を含む部屋全体をカバーします。
このファイルは常に読み込まれるルーターです。これには、作業の順序、根拠付きの厳格なルール、完了条件、アンチパターンが含まれます。各段階の完全な契約は、ルール名が示す grimoire/ ファイルにあります — その段階に達したときに読み、それより前に読んではいけません。
使用するタイミング
- ユーザーがビデオまたはツイート(ビデオ付き)を共有し、「これをThree.jsで再現して」と依頼した場合。
- ユーザーが特定の柔らかい、または有機的なオブジェクト(掛布団、枕、ぬいぐるみ、アニメの髪、猫)をプロシージャルにモデリングする方法を尋ねた場合。
- 部屋やインテリアを、ゲーム、ジオラマ、インタラクティブなオマージュのために映像から1:1で再構築する必要がある場合。
対象外:1枚の画像からの単一のヒーローオブジェクト(その場合はimg2threejsを使用)、またはGLBアセットのダウンロードが許容されるプロジェクト。
必要な入力
- ビデオ(mp4 URL / ツイート URL / ファイル)。ツイートの場合は、メディアバリアントを取得し、720p mp4をダウンロードします。
- ユーザーの許容範囲:「1:1」(このスキルのデフォルト)または「雰囲気を再現」。
- ユーザーがブラウザで開ける開発サーバーを実行する場所。
厳格なルール
以下の各ルールは、Blue Roomのケーススタディで手戻りを経験して確立されました。これらはスタイル上の好みではありません。
1. 彫刻中のライブプレビュー
何かをモデリングする前に、開発サーバーを起動し、ユーザー用にページを open します。ホットリロードされる段階(壁 → 家具 → 照明 → キャラクター → モーション → イントロカメラ)でシーンを記述します。ページの隅に段階ラベルを配置し、window.onerror をルーティングして、実行時エラーがページ上で表示されるようにします。
理由: フィードバックは、間違った壁が現れた瞬間に最も安価であり、部屋全体が家具で埋め尽くされた後ではありません。
→ grimoire/build/live_preview.md
2. 最初にビデオを複数の角度から分析する
クリップ全体から少なくとも8フレームを抽出します。空間的な事実(どの壁、どの隅、何が何の上にあるか)については、グリッド化されたフレームをセルごとに読みます。2番目のフレームですべての事実を確認します。それでも遠近法が解決しない場合は、ユーザーにスクリーンショットに隅と床の線を描いてもらいます。空間的事実シート、オブジェクトインベントリ、パレット、キャラクターカード、モーションシーンテーブルをコードを書く前に作成します。
各ショットについて、何が動くのか — 被写体かカメラかを明示的に決定します。これを誤るとコストがかかります:ゆっくりとしたプッシュとしてアニメーション化されたショットが、実際は腕が上がるのを見ている静止カメラであり、腕にリグがなかったことが判明します。
理由: 3回の確信的な再構築で窓の位置が間違っていました。1回の赤ペンスケッチで修正されました。
→ grimoire/intake/multi_view_analysis.md、grimoire/intake/frame_extraction.md
3. オブジェクトの前に空間を設定し、カメラを解決する
表示される壁と隅を決定し、座標フレーム(左壁 x = LW、右壁 z = RW)を設定し、次に forge/solve_camera.py を使用してランドマークの割合からカメラを解決します。その後でのみ家具を配置します。
ランドマークのスクリーン位置と見かけのサイズから、forge/solve_camera.mjs を使用して測定値から解決し、ソルバーが間違ったブランチを選択できないように仰角を制約します。フレーミングを追求する前に、それがそもそも可能かどうかを確認します:合成参照の2つのショットは、多くの場合、同じスケールで共存できません(grimoireの三角不等式テスト)。その場合は、最も近い一貫性のあるフレーミングを採用し、先に進みます。
理由: 感覚で配置されたカメラは、後続のすべての比較を嘘にします。不可能なカメラは永遠に嘘をつき続けます。
→ grimoire/space/perspective_solving.md
4. 書面によるレイアウト契約を維持する
オブジェクトごとに1行:壁、位置、サイズ、関係、参照フレーム。すべてのユーザー修正は、最初に契約を編集し、次にコードを編集します。契約は、家具、ポーズ、カメラソルバーで使用される位置の単一の信頼できる情報源です。
→ grimoire/space/layout_contract.md
5. 色はピクセルから取得する
グリッド化されたフレーム上の各オブジェクトの、光が当たっている部分と影になっている部分のパッチをサンプリングします。その中間の、明るめの基本色を選択します。記憶から色を入力しないでください。
→ grimoire/intake/frame_extraction.md
6. 実際の照明、診断、決してペイントしない
実際の窓の開口部がある頑丈な壁。部屋の内部を正確に覆う屋根。下端がゼロのトーンランプ。部屋をカバーするシャドウカメラを備えた1つの暖かい太陽。ペイントされた床のパッチ、ボリューメトリック平面、浮遊パーティクルで照明を偽装しないでください。直接太陽のみのレンダリング(?diag=sun)で診断します:壁と天井は黒くなければならず、パッチはジオメトリが示す場所に配置されなければなりません。
→ grimoire/build/lighting.md
7. オブジェクトごとに8/10まで彫刻する
オブジェクトを構築する前に、その参照特徴(形状、位置、色、付属品)をリストします。構築後、クローズアップカメラからスクリーンショットを撮り、スコアを付けます。8未満で次に進まないでください。テクスチャよりもジオメトリを優先:掛布団はドレープされたシート、本棚は本物の本が入ったオープンなもの、枕は厚く傾いています。
→ grimoire/build/procedural_recipes.md
8. 1つのメッシュ、彫刻 — 決して組み立てない
有機的な形状(頭、耳、胴体、手足、手、ローブ)は、自身の頂点を移動させることで形作られた1つの閉じたサーフェスです:膨らませる、凹ませる、面から手足を押し出す、滑らかなフィールドで変位させる。球体+円錐+カプセルを組み合わせて構築しないでください。組み立てられた有機物は、毎回、次の問題を引き起こします:照明とともに動く明るい継ぎ目、埋め込まれた部分の周りの輪郭リング、関節が回転したときに外れる部品、Zファイティングのきらめき、誤って巻かれたサブメッシュによる「透明」な外観、そしてどのマテリアルチューニングでも除去できないシェーディングの切れ目。
適用される場合: 参照で皮膚を共有するものはすべて、ビルドでもメッシュを共有する必要があります — 鼻は顔が前方に押し出されたもの、耳は頭蓋骨が隆起したものです。明確に分離されたオブジェクト(ランプ、本、ポール、窓枠)は、個別のプリミティブのままです。サーフェス上にあり変形しない小さな剛体の立体(髪のカール、リベット、花びら)は、彫刻された皮膚上のインスタンス化された装飾品です。長く細いランは、1つのスイープチューブであり、カプセルの連鎖ではありません。
2つの基盤: 密に分割されたプリミティブ上の変位フィールド(頭部、球体に近い形状)、またはボックスモデリングケージ+Catmull-Clark、その後ディテールのための変位(身体、手足、手、衣類)。どちらも1つの皮膚を残し、リグがバインドする対象となります。
理由: このプロジェクトの歴史において、組み立てられた有機物はすべて、最終的に1つのメッシュとして再構築されました。継ぎ目がそれぞれレビューラウンドを消費した後です。
→ grimoire/build/one_mesh_sculpting.md、grimoire/build/box_modelling.md
9. 最初に推論し、次に各ステップを完了させながら段階的に彫刻する
ジオメトリに触れる前に、形状を書き留めます:基本ボリューム、どの特徴が隆起し、どの特徴が沈み込み、どの特徴が傾斜の変化か、それらをどの順序で適用する必要があるか — 各ステップは前のステップが残したサーフェス上に構築されます。次に、作業を、それぞれが有効で確認可能なサーフェス(空白のベース → 大きな平面 → 主要な特徴 → 二次 → 微細なディテール)を残すステップに分割し、次のステップを開始する前に各ステップを完了させます:スクリーンショットを撮り、数値プロファイルをダンプし、表示し、承認を得ます。ステップ2で残したぐらつきは、ステップ5では修正できません。なぜなら、その上に5つのフィールドが乗っているからです。後続のステップが完了しなければ結果を判断できないステップは絶対に作らないでください。
理由: 塊ごとに彫刻された頭部は2回破棄されました。同じ頭部を「空白の顔 → くぼみ → 目 → 口 → 鼻」と彫刻し、矢印ごとに1回の承認を得たものは受け入れられました。
→ grimoire/build/one_mesh_sculpting.md
10. サーフェスを目ではなく数値で検証する
サーフェス全体のプロファイル(顔の中心線、手のひらの横断線、関節の周りのリング)をダンプし、必要な場所で単調であることを確認します。2つの隆起の間の台地は、目にはくぼみとして読み取られ、スペキュラーハイライトはその両方を隠します。ケージ操作の後、≠ 2の面で使用されているエッジの数もカウントします:ゼロ以外はTジャンクションを意味し、細分割はそれをハードクリースとしてレンダリングします。
→ grimoire/build/box_modelling.md、grimoire/build/one_mesh_sculpting.md
11. 閉じたソリッド、正しい巻き方向、可能な限り1つのサーフェス
手作業で構築されたスイープチューブには2つの可能な三角形の順序があり、そのうち1つだけが外側を向きます。間違った順序では FrontSide が外側のシェルをカリングするため、オブジェクトの内部が見えます — 図形は透明で「ひどく継ぎ合わされた」ように見え、マテリアルのせいにします。LatheGeometry は開いたチューブです。ジョイントボールは、それらがキャップするチューブの端よりも大きくする必要があります。2つのプリミティブを重ねるよりも、1つの連続したプロファイル(首と胴体を1回のスイープで)を優先します:「内部が十分に離れているため表示されない」という状態は、断面が異なったり関節が回転したりするとすぐに成り立たなくなります。?diag=flat(不透明マテリアル — それでも透過している場合はジオメトリの問題)、?diag=norm、次に ?off=<パーツ> で診断します。
理由: 1行のインデックス順序のバグに対して、いくつかのレビューラウンドがマテリアルチューニングに費やされました。
→ grimoire/build/solid_geometry.md
12. シェーダーは静かに失敗する — 最初にエラーフックを配線する
renderer.debug.onShaderError をページに配置します。カスタムマテリアルを書く前に行います。コンパイルに失敗した ShaderMaterial は何もレンダリングせず、コンソールにのみログを出力します。次に、静かな問題を知っておきます:modelMatrix は頂点ステージにのみ存在します。pow(negative, 2.0) と smoothstep(hi, lo, x) はGLSLでは未定義でNaNを生成します。ビット演算の前に倍精度にオーバーフローする整数ハッシュはバイアスがかかり、シーン内のすべてのテクスチャを平坦化します。フレネルは、カメラが手足をかすめるときに大気を作ることができません。
→ grimoire/build/shader_traps.md
13. 不確かな場合は調査する
構築方法がわからない場合(布、髪、ランプアークなど)、three.jsのサンプル、フォーラム、姉妹スキルを検索し、最大3つのアプローチをリストアップし、最も制御可能なものを選択し、ソースを引用し、調査結果を 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 で解決し、連続性項を持つシーケンスでキーフレームを打ち、ポーズが1つのブランチに留まり、単一の動きとして補間されるようにします。ウェイポイント(via)は、キャラクターを家具の周りにルーティングします。座っている高さと横になっている高さは、掛布団の上面から測定します。消失したキャラクターについては、ジョイントとバウンディングボックスをログに記録します。すべてのシーンのスクリーンショットを撮ります。
スキンは、リジッドセグメントと短いヒンジ(手足の直径1つ分のブレンド、関節のハーフローテーションボーン、関節上に放射状に配置されたケージループ)でバインドし、各関節軸を想定するのではなく導出します — 手首の屈曲軸は 前腕 × 手のひら法線 であり、これを肘のヒンジ軸で構築すると、キーが文字通り何も行いません。キャラクターが引き起こすエフェクトは、ショットのクロックではなく、クリップのクロックに属します。
→ 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 | オブジェクトを1つずつ;有機形状は1つの彫刻メッシュとして段階的に | オブジェクトごとのクローズアップ ≥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 |
完了条件
- 参照フレームと並べて表示:壁、座標、比率が一致していること。
- カメラの位置、FOV、回転が参照と一致していること。
- 照明がシーンに合っており、?diag=sun で診断済みであること。
- すべてのオブジェクトのスコアが8/10以上であること。
- キャラクターのモーションが人間らしく、リグが正しく動作していること。
- ユーザーの「ノー」リストに該当する要素がないこと。
- プロジェクトCLAUDE.md にすべての情報が記録されていること。
アンチパターン
- ダウンロードしたアセットやテクスチャを使用する。
- シェーダーやマテリアルの代わりにペイントされた照明効果を使用する。
- 単一のメッシュで彫刻せずに、プリミティブを組み立てて有機形状を作成する。
- スクリーンショットによる検証なしで作業を進める。
- ユーザーのフィードバックを無視する。
研究リソース
grimoire/research/when_unsure.md:不確かな構築のためのアプローチとソース。- three.jsのサンプル、フォーラム、姉妹スキル。
- 数学の検証にはNodeを使用。