img2threejs

img2threejs — 画像からプロシージャルな Three.js を生成

参照画像に写っているオブジェクトを、コードのみでプロシージャルな Three.js モデルとして再構築します。段階的なスカルプトパイプラインと、AI ビジョンによる自己修正ループを通じて進めます。これはコードによる再構築であり、フォトグラメトリ、メッシュ抽出、ダウンロードしたアートパックではありません。この約束が規定するのはモデルの 構築方法 です。その後どのファイル形式に エクスポート できるかについては何も規定しません。明示的に選択した出力先（--target <kind>）は、すでに構築済みのモデル全体に対する最終的な変換であり、定められた範囲で検証されます。モデルを構築するための別の方法では決してありません。

エージェントを問いません。Claude Code、Codex、OpenCode で動作します。このドキュメントで「エージェントのビジョン」や「エージェントのブラウザーツール」とある箇所では、ホストが提供するものを使用してください。ネイティブの画像読み取り、ブラウザー MCP（playwright/chrome-devtools）、プロジェクトのプレビュー、またはユーザー提供のスクリーンショットが該当します。

このファイルは常に読み込まれるルーターです。処理の順序と、すべての厳格なルールを一行ずつ記載しています。各ルールの詳細な契約は、そのルールで指定された grimoire/ または docs/ のファイルにあります。事前ではなく、その段階に到達した時点で指定ファイルを読んでください。

正規の共有チェックアウト

このリポジトリのチェックアウトは一つだけ維持し、各ホストがシンボリックリンクを通じてそこにアクセスするようにしてください。Claude と Codex が別々のコードを実行して乖離するのを防げます。

~/.claude/skills/img2threejs -> <your checkout>
~/.codex/skills/img2threejs  -> <your checkout>

使用する場面

ユーザーがオブジェクトの画像を添付または指定し、プロシージャルな Three.js モデル、再構築・アニメーション・破壊の計画、スカルプト仕様、またはコードを求めている場合に使用します。マテリアルの検討、アクションに対応した小道具、ゲームオブジェクト、植物や機械の部品、スタイライズされた再構築にも使用できます。

中核となる約束

写真から順番にスカルプトし、一度でメッシュを作らないでください。

1. 毎回の開始時、再開時、修正の各反復の前に、まず python3 forge/next.py --state .img2threejs/state.json [<spec>] を実行します。 順序付きチェックリスト、次に実行すべき正確なコマンド、エビデンスの状態、制限付き修正ループの状態が報告されます。仕様やパスのゲートの代わりにはなりません。ハードストップに従い、記憶を頼りに作業を続けないでください。
2. 検証します。画像が適切な 3D ターゲットか確認します（grimoire/intake/validation_rubric.md）。
3. オブジェクトのクラスと複雑さを評価し、コードを書く前に qualityContract を作成します。
4. 仕様を作成します。コンポーネント階層、マテリアル、ライティング、ピボット、ソケット、アクションアンカーを定義します。
5. ブロックアウト → 構造 → 形状 → マテリアル → ライティング → インタラクション → 最適化の順に、パスごとに構築します。
6. 各パスでスクリーンショットを参照画像と比較して検証します。全体スコアに問題がなくても、オブジェクトの識別を決定づける特徴が誤っていれば、そのパスは不合格とします。

出力が近似的、スタイライズ、またはローポリである場合は、その旨を明記してください。一枚の画像では見えない面を確認できず、正確な形状も保証できません。自信があるように装わず、そのことを伝えてください。

必須のローカル状態ゲート

会話コンテキストは破棄される可能性があります。.img2threejs/state.json がローカルチェックリストの権威ある情報源です。 再構築ごとに一度初期化し、その後はすべてのステップでこれをゲートとして使用します。

python3 forge/state.py init --state .img2threejs/state.json --reference <img> --profile <generic|character|installed-domain> --spec object-sculpt-spec.json
python3 forge/next.py --state .img2threejs/state.json [object-sculpt-spec.json]
python3 forge/state.py mark <step-id> --state .img2threejs/state.json --evidence <path>

• next.py は、現在のステップ、パス、未完了の必須ステップ、次に実行する正確なコマンド、および loop/max を出力します。終了コード 3 または status=stopped は強制停止を意味します。その理由を報告し、入力を求めてください。 チャット履歴から進捗を再構築して、このゲートを回避してはいけません。
• 完了した各ステップには証拠が必要です。該当しないステップを skipped にするには、--reason を指定してください — 理由のない省略は禁止です。ループ回数はエージェントの記憶ではなく、reviewHistory のアクション （refine-spec／refine-code）から算出されます。デフォルトは、パスごとに修正 3 回、合計 6 回です。
• ドメインプロファイルのステップ、ゲート、参考資料はレジストリから取得されます。同一の方法で登録されるのは、リポジトリ内のモジュール（character）とインストール済みプラグイン（plugin-character の cs2、animated-character）です。また、 forge/state.py init は利用可能な項目を表示します。プロファイルはコアの順序を変えずに必須ゲートを追加します。通常、ドメインプラグインは AI レビューの前に、信頼できる分類、インテークマニフェスト、および機械可読なドメインレビューを必須とします。character はキャラクターの契約とランドマークの証拠を必須とします。animated-character（plugin-character のインストールが必要）は character の全項目に加えて、9 つの Stage R ステップ（grimoire/readiness/animation_contract.md）を追加します。リグを動かす必要がある場合は、必ずこれを選んでください — character では Stage R ゲートがなく、実行されないままビルドが完了するため、以前はアニメーションが壊れた状態でリリースされていました。順序は重要です。メッシュを修復し、固定してから、加算的にバインドし、最後にパリティを検証します。すべてのプロファイルで、適合性、投影の適用可否、およびマテリアル証拠の適用可否を記録します。状態ファイルは再開用のインデックスであり、視覚的な証拠ではありません。レンダー、仕様、レビュー履歴、および決定論的ゲートが、引き続き権威ある成果物です。

必要な入力

• 画像のパス／スクリーンショット／URL／添付画像を 1 つ（ない場合、または読み取れない場合は、確認してください）
• 用途：小道具、ゲームオブジェクト、ヒーローレンダー、プレイ可能／破壊可能なオブジェクト、アニメーションリグ （デフォルト：インタラクティブ性能を備えたリアルタイムのブラウザー用小道具）
• ドメインプラグインが対象に適用される場合、そのインテークステップで要求される信頼できる記録、またはユーザー／ビジョンプロバイダーにその提供を明示的に依頼すること。ヒューリスティックな検出だけでは、ジオメトリアダプターを選択するには不十分です。

ループ（スクリプトが実行を強制し、エージェントのビジョンが判断します）

スキルのルート（forge/...）からスクリプトを実行します。pip のインストールは不要で、Python 3.10 以降の標準ライブラリのみを使用します。 すべてのフラグについては grimoire/scripts.md を参照してください。ビジュアルの採点をスクリプトに任せてはいけません — それはエージェントの役割です。

1. 最初に画像を分析する（スクリプトより先に、エージェントの視覚機能を使用）：grimoire/intake/image_analysis.md の多層観察プロトコルに従ってください。識別・分類、マクロ→メソ→ミクロの分解、パーツ間の関係のマッピング、PBR 用語での素材の記述、アイデンティティを決定づける特徴の列挙、単一視点では見えない部分の明示を行います。推論より観察を優先し、3D の用語を一貫して使い、2D 画像空間ではなく 3D オブジェクト空間で捉えてください。その後、ローカル画像を調べます： forge/stage1_intake/probe_image.py <image>（メタデータのみ。視覚的な確認は行いません）。 1a. ローカル仕様検索 — 画像分析後、仕様の作成または改良前に、独自に考案するのではなく、ローカルのドメイン情報（解剖学／PBR／摩耗／ジオメトリ／ランタイム／物理）を取得してください： python3 forge/stage2_spec/new_pre_spec_assessment.py "Name" --image <img> --out assessment.json （core_3d コレクション、または宣言されたドメインが提供するコレクションに対して BM25 を自動実行します。コレクションを対象名から推測することは決してありません。new_sculpt_spec.py --assessment が仕様に取り込む localSpecSearch バンドルを書き込みます）。クエリ拡張の全手順（2 言語での用語、search_specs.py による絞り込み検索、キャッシュ規則）： grimoire/intake/local_spec_search.md。不完全なクエリやドメイン固有のクエリを再試行する前に、必ず読んでください。 1b. ドメインのインテーク — ドメインプラグインが対象アイテムに対応している場合、プリスペック作成前にそのインテーク手順（受け入れ判定、ヒューリスティック信号、分類、ファミリー／ルートの解決）を完了してください。マニフェストを作成したり、プリスペック評価を実行したりする前に、その手順で指定された契約書を必ず最後まで読んでください。 1c. 任意の忠実度証拠アダプター — 観察された弱点の改善に役立つ場合に限り使用してください。標準ライブラリのコアが引き続き権威ある情報源です。細い／複雑なマスクにはローカル SAM2、キャラクターの顔／ポーズには MediaPipe、前後の手掛かりが弱い場合は Depth Anything V2 を使用します （forge/stage1_intake/run_vision_adapter.py <segment|landmarks|depth> ...。各アダプターは出所情報を出力します。単眼深度は相対値のみです）。MCP のみで行ったシーンの変更は実装とは見なしません。実証された変更を仕様または TypeScript に反映し、再ビルドして再キャプチャしてください。アダプターと MCP のルーティング、および権限境界の詳細： docs/integrations/reference_fidelity_tooling.md。
2. プリスペック評価ゲート — 分類、複雑さのスコアリング、品質契約の作成を行います： forge/stage2_spec/new_pre_spec_assessment.py "Name" --image <img> --complexity <simple|moderate|complex|ultra-complex> --out assessment.json。ルール：grimoire/intake/quality_contract.md。 objectClass.primaryDomain（object | character | hybrid）を設定し、初期値が設定された detailInventory を埋めてください（targetMinDetails は複雑さに応じて変わります）。ドメインプラグインは拡張によってこの下限を引き上げることができます。マージ処理で下限が適用されるため、プラグインが引き下げることはできません（スキンでは仕上げ／摩耗／ハードウェアがアイテムそのものなので、最上位の忠実度基準が適用されます。プロシージャルなジオメトリを作成しつつ、仕上げは手順 2c の投影経路を通してください。パターン付きスキン（Doppler/Gamma/Marble/Fade）にプロシージャルな仕上げを施すと、参照画像と明らかに異なって見えます。ドメインプラグインには専用の仕上げルールブックとテクスチャ取得ガイドが含まれています。チェックリストの手順で指定されたものを読んでください）。 2b. ディテール一覧（詳細な被写体では省略しないでください） — ゾーンを走査し、アイデンティティを決定づける細部（光沢、ベベル、留め具、線画、輪郭、汚れ）をすべて列挙します： forge/stage1_intake/build_detail_inventory.py <image> --mode grid-3x3 --out-dir <dir> --out di.json。 各ディテールは必ず component.localFeatures または material.localOverrides の項目に対応付けてください。説明文だけに記載することはできません。分類体系と 3D 用語の使用例：grimoire/intake/detail_inventory.md。 2c. 投影優先の忠実度（キャラクターおよび参照画像に一致させる表面 — 塗装済みスキン、デカール、塗装パターン） — 特定の参照画像の表面に一致させることが目的なら、プロシージャルに近似するのではなく、写真そのもののピクセルをメッシュに配置してください。これは忠実度を高める最大の要因であり、パターン付き表面にプロシージャルマテリアルを使うことは、再構築で最も多い失敗です。手順（grimoire/character/likeness_maximization.md — 2 つの手法はキャラクター以外にも応用できます）：カメラを解決し（stage1_intake/solve_camera_pose.py → referenceCamera）、参照画像を除光し（stage1_intake/delight_albedo.py。必須です。投影を安全にするには除光が必要です）、その後、除光したクロップを投影して UV にベイクします（stage3_build/bake_projected_texture.py --mesh-id <id>）。塗装済みスキンでは、投影した除光済みクロップが仕上げそのものとなるため、プロシージャルな Doppler マテリアルは使いません。キャラクターの場合は、まずランドマークをキャプチャし（stage1_intake/extract_landmarks.py --out anatomy.json）、preSpecAssessment.anatomy を埋めて、grimoire/character/reconstruction.md のルートに進んでください。単一視点では見えない面があります。領域ごとの信頼度を報告し、重要な場合は追加の視点を求めてください。 キャラクターのサブルートは次の順で進めます。パーツを形状化する前にどのパーツが存在するかを決め、髪を形状化する前に頭部を形状化してください。
   • パーツ — grimoire/character/structure_decomposition.md
   • 頭部 — grimoire/character/head_construction.md（類似度ゲートの比較対象となる部分）
   • 髪 — grimoire/character/stylized_hair_threejs.md およびパラメーター契約 grimoire/character/threejs_hair_parameter_contract.json。シルエットレビューに合格してからトポロジーを確定してください。マテリアル調整では誤った束のトポロジーを修正できません。 2d. 参照画像のないヒューマノイド — 参照画像のない一般的な人物モデルには測定対象がないため、公開されている標準データから解剖学的情報を補完してください： forge/stage2_spec/humanoid_proportions.py <spec> --style-heads 8 --in-place。anatomy.source: "canon-table" と記録されるため、標準データが測定値と誤認されることはありません。仕様に参照画像が指定されている場合は実行を拒否し、データコーパスにない項目は補間せずに明示します。
3. 評価結果から仕様を作成します： forge/stage2_spec/new_sculpt_spec.py "Name" --image <img> --assessment assessment.json --augmentation spec-augmentation.json --domain <profile> --out object-sculpt-spec.json（チェックリストの手順に解決済みフラグが含まれます）。 汎用の初期値である featureReviewTargets を、対象のアイデンティティを決定づける実際のシステムに置き換えてください（1 回のパスにつき重要項目は最大 5 件、最優先項目は最大 3 件）。キャラクターでは anatomy-proportion、face-landmark-placement、pose-silhouette、outfit-and-palette を追加してください。3D グラフィックスの用語のみを使い（grimoire/glossary/3d_vocabulary.md）、「いい感じ／滑らか／光沢」といった表現は使わないでください。プリミティブを選ぶ前に、grimoire/intake/surface_topology.md に従って各コンポーネントの topologyClass／topologyRationale を分類してください。これにより、連続した有機形状をボックスとして選んでしまうことを防げます。
4. マテリアルの忠実度が重要で、ソース画像がある場合は、各マテリアルの仕上げを分析してから、参照 PBR の情報を抽出してください。どちらもクロップ単位で行い（クロップが意図したパーツのものか確認してください）：
   • forge/stage1_intake/analyze_texture.py <crop> --spec spec.json --material-id <id> --in-place 仕上げを分類し、グラデーションのカラーパレットを抽出して、根拠となるドキュメントに基づく MeshPhysicalMaterial のスカラー値をマテリアルに書き込みます。手順と Three.js のテクスチャ／PBR ルール： grimoire/build/threejs_texture_reference.md。目安：平坦な塗装には単色のアルベド、パターン付きの仕上げには実際の参照画像のクロップを使用します。
   • forge/stage1_intake/extract_pbr_evidence.py <crop> --out-dir <dir> --material-id <id> --target-threshold 0.7。 信頼度が 0.7 未満の場合は、合格ではなく停止して入力を改善すべきことを示します。これは推論であり、逆レンダリングではありません。
   • 名前付き領域が複数ある場合：forge/stage1_intake/material_region_analysis.py --manifest regions.json --out-dir material-evidence --out material-analysis.json を実行し、 docs/materials/material-reference.json から各割り当てを解決して、 forge/stage2_spec/apply_material_analysis.py で適用します。
   • 制御されたマテリアル用カメラ／クロップの契約を出力し（forge/stage4_review/material_views.py）、表示範囲のクロップを比較し（material_comparator.py）、範囲を限定したマテリアル単位の修正のみを適用し（material_feedback.py）、ブロック結果を記録します（material_gate.py）。
5. 検証後、コードを生成する前に厳密検証を実行します： forge/stage2_spec/validate_sculpt_spec.py object-sculpt-spec.json、続けて --strict-quality。 厳密検証では、内容の浅い仕様はブロックされます（複雑なオブジェクトにルートが 1 つだけあり、繰り返しシステム、ローカルオーバーライド、ミクログループがない場合、JSON の検証に通っても実装の準備ができていません）。
6. ロックされたビルドパス — 現在ロック解除されているパスのみを変更してください： forge/stage3_build/orchestrate_passes.py status object-sculpt-spec.json forge/stage3_build/generate_threejs_factory.py object-sculpt-spec.json --out src/createObjectModel.ts ジェネレーターはフェイルクローズ方式です。ファクトリーの書き込み前に strict-quality を通過する必要があり、前のパスがレビューで continue と判定されるまで、後続の --pass-id は失敗します。ブロックされた場合は BLOCKED アーティファクトを保持し、汎用テンプレートで代替せず、対象固有の仕様を改良してください。ローカル状態では、新しいパスまたは refine-spec に限り --force が追加されます。refine-code は再生成せずに現在のアーティファクトを編集します。上書き前に、有効な手動修正を仕様に反映してください。再構築の判断が生成コードにしか残っていない状態にしてはいけません。 6a. 三角形数の上限に達した場合。 performanceBudget.targetTriangles は、セグメント数を持つ各プリミティブのテセレーション段階（low ≤6k、standard ≤60k、それ以外は hero）を選択し、陰関数曲面のサンプリンググリッドに上限を設定します。段階の精度が不十分な場合、そのコンポーネントに geometryDescriptor.decimate: {"targetRatio": 0.4} を追加してください。生成ファクトリー内で二次誤差縮小を行い、スキンのバインド前に実行します。これにより、生き残る頂点に対してウェイトが計算されます。position のみが保持され（法線は再計算）、作成済みの／展開済みの uvStrategy では拒否されます。オフラインの LOD 段階： forge/stage3_build/decimate.py <mesh.json> --ratio <r> --json。
7. ブラウザー／プレビューで現在のパスをレンダリングし、レビュー用の視点からスクリーンショットをキャプチャします。 7a. オフ軸および配置ゲート — 単一のレビュービューではモデルの証拠になりません。 1 フレームだけでなくターンテーブルをキャプチャし、次の 3 つをすべて実行してください。旧ゲートを構造上すり抜けていた欠陥（頭蓋骨の貫通穴、腰の高さにある帽子、浮いたチャームなど）を、それぞれ別の欠陥クラスとして検出します。これらは正面のみのレビューを 8 回行っても残っていました。 forge/stage4_review/turntable_gate.py --capture 0=front.png --capture 90=right.png --capture 180=rear.png --capture 270=left.png --json node runtime/scripts/export_mesh_geometry.mjs --url <preview> --out meshes.json を実行してから、 forge/stage4_review/self_intersection.py meshes.json --json forge/stage4_review/attachment_anchor.py object-sculpt-spec.json --measured measured.json --json 3 つのすべてで、終了コード 0 は問題なし、1 はゲート失敗、2 はエラーを示します。失敗がある場合、全体の忠実度スコアに合格していても continue はブロックされます。問題なしの判定を信頼する前に、sampledVertexCount／unmeasuredAttachments／missingAzimuths を確認してください。それぞれ、ゲートが確認していない内容を示しています。
8. AI ビジョンを使う前に決定論的ゲートを実行します。 grimoire/review/gates_reference.md と grimoire/review/self_correction.md を必ず最後まで読んでください。forge/stage4_review/diagnose_render.py を実行し、--spec object-sculpt-spec.json --pass-id <pass> --in-place で合格した Tier 1 の結果を記録します。平面でない形状では、固定ビューと、意味のあるオービットビューを少なくとも 2 つ使って forge/stage4_review/diagnose_render_multi_angle.py も実行してください。その後、 forge/stage3_build/orchestrate_passes.py check object-sculpt-spec.json --pass-id <pass> を実行します。
9. 参照画像とレンダリングを並べたシートを 1 枚作成し、エージェントの視覚機能で確認します： forge/stage4_review/make_comparison_sheet.py --reference <img> --render <shot> --out cmp.png --json。
10. レビューを記録します（全体、レイヤー別、特徴別のスコア、および判定）： forge/stage4_review/append_review.py object-sculpt-spec.json --pass-id <pass> --fidelity <0-1> --action <continue|refine-spec|refine-code|request-input|stop> --summary "..." --render-screenshot <shot> --comparison-image cmp.png --ai-vision-score <0-1> --layer-scores-json '{...}' --feature-reviews-json <f.json> --in-place。 ドメインプラグインがレビューゲートを提供する場合は、まず、そのプラグインのレビュー手順で指定されたコマンドを使ってバージョン付きレポートを作成し、 --domain-review-json <report>.json --review-scene-json <the plugin's scene fixture> を指定して添付します。チェックリストの手順に解決済みのパスが含まれます。 ファミリー、塗装領域、投影範囲、重要ディテール、またはオービットのいずれかのゲートに失敗した場合、全体スコアに合格していても continue はブロックされます。詳細はプラグイン独自のレビューゲートのドキュメントを参照してください。
11. 手動レビューによる編集後にパイプラインの状態を同期し、チェックリストの証拠を記録してから、別の修正またはパスに進む前にローカル状態ゲートを再実行します： forge/stage3_build/orchestrate_passes.py sync object-sculpt-spec.json --in-place python3 forge/next.py --state .img2threejs/state.json object-sculpt-spec.json。
12. 完了を宣言する前に、forge/stage4_review/check_part_coverage.py --spec object-sculpt-spec.json --manifest parts.json を実行し、アクション可能な階層を確認してください。part-coverage と action-ready は、証拠がある場合に限り記録します。

GLB を介した v2 レンダリング忠実度トラック（1.5 alpha）

ユーザーが中間参照として GLB を提供した場合、ブラウザーでレンダリングした GLB を、独自に作成するプロシージャルなファクトリーの構造的および視覚的なベースラインとします。元の GLB はピクセルの証拠として使用せず、そのトポロジーやマテリアルをファクトリーにコピーすることもありません。ファクトリーを編集する前に、grimoire/build/python_threejs_render_bridge.md に記載された完全な契約と、機械可読スキーマ docs/specs/render-profile.v2.schema.json（およびその例。検証はフェイルクローズ）に従って、次を行います。

1. まず forge/stage1_intake/probe_glb.py を実行します。1 ノード／1 メッシュに統合されたアセットは、セマンティックラベル付けには「不十分」です。正確な領域を主張する前に、複数パーツの GLB を要求するか、ブラウザーでセマンティック ID パスを実行してください。
2. GLB とプロシージャルの両方の経路で使用する、共通の render-profile.v2 を 1 つ作成します（forge/stage4_review/validate_render_profile.py）。領域 ID は対象固有のものであり、サンプルプロファイルから引き継いではなりません。extensions.requiredSemanticRegions で必須セットを宣言し、省略時に検証エラーとなるようにしてください。
3. 許可されたビューごとに 6 つのパス（beauty、alpha-silhouette、semantic-id、depth、normal、roughness-material-id）をキャプチャし、forge/stage4_review/compare_region_passes.py でスコアを算出します。セマンティック ID データがない場合、画像全体のスコアにフォールバックせず、領域ごとの信頼度を算出できないものとします。
4. 領域固有の連続したジオメトリを使用します。領域のシルエットが連続したサーフェスを必要とする場合、顔／頭部のボリューム、布のシェル、尾を浮遊するプリミティブに置き換えてはなりません。
5. ループごとに修正グループを 1 つだけ、次の順序で実行します。camera → silhouette → face → clothing → accessory → materials → lighting。各グループの後にすべてのパスを再キャプチャし、変更したグループ、ハッシュ、スコアを記録します。改善の診断時に複数のグループをまとめて変更してはなりません。

ゲート（省略禁止）

ビジュアルレビューまたは continue の判断を行う前に、必ず grimoire/review/gates_reference.md のゲートごとの契約全体（Divine Eye、VLM rescue、multi-angle、interior difference、 chirality、hair、domain review、bounded correction、Divine Eye fitting、screenshot feedback、assembly、 attachment、material、detail inventory、rig payload、character track）を読んでください。要点は次のとおりです。

• まず参照資料を検証します（grimoire/intake/validation_rubric.md、check_reference_admission.py）。
• divine_eye.py は決定論的な処理を優先します。VLM（vlm_gate.py）は条件付きの最終レイヤーであり、ハードゲートの失敗時には決して参照しません。
• 非平面形状は、2 つ以上の角度で成立する必要があります（diagnose_render_multi_angle.py）。
• ビジュアルパスごとにシルエットの内側を測定します（interior_difference.py）。シルエット IoU が読み取る図形のセルは約 11% です。顔を削除したモデルでも、完成した顔と同じ 0.8803 を記録しました。
• すべての -l／-r ペアは回転ではなく鏡像です。仕様策定時に必ず確認します（validate_chirality）。両側が同じ誤り方をしていてもペアは合格するため、参照資料と照合して medial_lateral_bias を確認する必要があります。
• 髪を扱う場合、scalp_exposure.py はハードゲートであり、レンダリング前にジオメトリに対して実行します。hair_gate.py はソフトゲートであり、scalp_exposure.py に従属します。カバレッジ不足を理由に、かたまりを広げることは決して認められません。
• はっきりした境界を持つ単色領域（ブレーズ／ビブ／ソックス、カラーリングのストライプ、ペイントされたマーキング）はアイデンティティの特徴であるため、その境界はジオメトリでゲートします（vertex_region_gate.py）。テクスチャは決して使いません。このパイプラインが出力するのはコードであり、形状述語は _shared/vertex_paint.py にあります。
• 曲線に関する主張（「まっすぐな円錐ではなく、フック状にカールしている」）には swept_arc_gate.py が必要です。おおむね適切なセルを占める直線的な円錐でも、シルエット IoU は合格します。
• キャラクタービルドでは、THREE.Skeleton をバインドする前にリグペイロードを検証します（stage5_rig/validate_rig_payload.py）。これはペイロードの整合性だけを証明し、ポーズの負荷テストや類似性は検証しません。
• 動作する必要があるリグでは、アニメーションゲートも実行します（grimoire/readiness/animation_contract.md。チェックリストの手順とゲートはインストール済みの plugin-character から取得します。stage5_rig/ はこのリポジトリにエミッターのライブラリとして残っていますが、チェックリストの正式な参照元ではありません）。クリップが存在することと、クリップが再生されることは同じではありません。両者を区別するのは G1（maxSampledBindingDelta <= 2^-23）だけです。入力が欠落しているゲートは合格ではなく、unevaluated と報告します。アタッチモードで IDENTITY にバインドし、表示オフセットはメッシュのバウンディングボックスのみから取得します。ループの判定には移動距離ではなく poseReturn を使います。
• ドメインプラグインのレビュ​​ーゲートも、バージョン管理されたシーンフィクスチャに対して実行します。
• ローカル状態では、デフォルトでパスごとに 3 回、合計 6 回の修正が強制されます。いずれかの上限に達したら、ハードストップです。correction_loop.py は、欠陥の反復、振動、または停滞があれば、それより早く停止することがあります。
• continue には、レンダリング、比較シート、しきい値以上の AI ビジョンスコア、および各重要な特徴についてそれぞれのしきい値以上のスコアが必要です（grimoire/feedback/render_capture.md）。
• すべてのモデルは、分解可能かつクリック可能な状態で出荷します。これはピクセルではなく、構造のゲートです （check_part_coverage.py、grimoire/build/geometry_patterns.md）。
• アクション対応、アタッチメント、マテリアル／ライティング、詳細インベントリ、キャラクタートラックの要件： grimoire/readiness/action_rigging.md、grimoire/readiness/joint_attachment.md、 grimoire/feedback/shading_realism.md、grimoire/intake/quality_contract.md、 grimoire/intake/validation_rubric.md。

自己修正

各パスの後に、次のいずれかを必ず1つ選んでください：continue | refine-spec | refine-code | request-input | stop。 refine-spec は、誤りや不足、または浅い仕様を修正します（コードでつじつまを合わせず、再検証してください）。 refine-code は、妥当な仕様に合っていない形状、マテリアル、ライティングを修正します。判断する前に、必ず grimoire/review/self_correction.md の根本原因ガイドと忠実度スケールを読み、判断を記録し、 ローカル状態ゲートを再実行してください。

小さな特徴には別の計測器が必要です。 Divine Eye の SSIM、トーン、エッジの各信号は 64×64 の輝度グリッドで動作するため、数ピクセル幅の細部は比較を行う前に失われます。忠実度が個々の涙、スポーク、牙、目に左右される場合は、4段階の顕微鏡を使用してください： grimoire/review/divine_eye_microscope.md。そこから実証的に確立されたルールが2つあります。忠実度はコンポーネント単体のレンダリングではなく、コンポーネントが隠れているフレームを全体フレームから差し引いた可視フットプリントで測定すること。また、凹状の特徴では、暗部の比率がマテリアルではなく空洞の陰影を捉えるため、色による判定を行わないこと。

透明性とプロセスのデバッグ

各パスで何が変わったかを、正確な値や座標などの根拠とともに報告し、まだ一致していない点を明示してください。「改善した」だけの状態で「完了」と主張してはいけません。ゲートを通過しても、3D のリアリズムが証明されたわけではありません。 完全なルールと例については、grimoire/review/self_correction.md を参照してください。

左右

左右のペアは回転ではなく鏡映です。横軸だけを反転し、それ以外は何も変えません： (x, y, z) → (-x, y, z)。forward: +Z、Y 軸を上、右手座標系の場合、キャラクター自身の 左側は +X です。この規約はコードとして forge/_shared/chirality.py （CHARACTER_LEFT_SIGN）に定義されています。これを誤ることで生じる、すでに発生した2種類の不具合には、それぞれ異なるゲートがあります。validate_chirality は仕様作成時に回転と鏡映の取り違えを検出し、 medial_lateral_bias は参照画像と比較して、左右両側が同じように誤っているペアを検出します。 鏡映すると三角形の頂点順序も反転するため、鏡映した側では頂点順序を元に戻してください。そうしないと、 flatShading によって、手足が背後から照らされているかのように見えます。測定された不具合を含む詳細は、 grimoire/scripts.md（「Left and right」）を参照してください。

髪

髪には、ほかのどのゲートでも検出できない失敗モードがあるため、独自のサブシステムがあります。完全な仕様、 測定方法、対象外事項については、docs/HAIR_PIPELINE.md を参照してください。厳守するルールは次のとおりです。

• 根元は絶対位置ではなく (u, v) として頭皮にバインドします（違反するとハード検証エラーになります）。
• standProud はジェネレーターが適用します。単なる推奨ではありません。
• scalp_exposure.py は、レンダリング前のジオメトリに対するハードゲートです。カバー率の不足だけを理由に、ボリュームを広げてはいけません。
• デフォルトの表現レベルはロックではなく shell です。このスキルはテクスチャを出力しないため、髪束らしさはファセット加工とマテリアル（hair.human.code-only）で表現します。
• 髪には plane-card を使用できません（このスキルでは出力できないアルファテクスチャが必要です）。
• 髪は親に剛体的に接続し、滑らかにスキニングしてはいけません（測地場が頭蓋骨を通過します）。

ドメインプラグイン

ドメインプラグインを使うと、このパイプラインでは通常推論に頼る部分を正確に処理できます。プラグインは独自のチェックリスト手順とゲートを追加し、spec-augmentation.json を公開します。このパイプラインはそれを spec-authoring の段階で取り込みます。対象項目に対応するプラグインがない場合、ここでの動作は変わりません。ほかのオブジェクトと同様に、スケルトンを作成し、参照画像から形状を推論してください。

• プラグインが追加する手順は、独自の ID と解決済みパスとともにチェックリストに表示されます。各手順が指定する内容を確認してください。プラグインには独自の仕様があり、そのドメインにはその仕様が適用されます。
• プラグインは、このパイプラインの品質下限を引き上げることはできますが、引き下げることはできません。マージ時に下限値で制限されます。
• 対象項目に対応していないプラグインは、拡張仕様を公開しません。これはエラーでも実行の妨げでもありません。汎用経路となり、推論によって再構築が進みます。
• このパイプラインは特定のドメインを想定しません。ドメイン固有のルールは、そのドメインのプラグインに記述します。

img2 ハーネス

プラグインは、別個の依存関係不要な CLI（Node ランチャー、Python コア）である img2 ハーネス （img2threejs/img2）によってインストールおよび管理されます。このスキルは 何もインストールしません。state.py init でプロファイルが利用不可と表示された場合は、そのプロファイルを インストールする img2 add コマンドを提示して停止してください。ドメインロジックを独自に組み込んではいけません。

img2 add img2threejs/plugin-<id> --ref <tag>      # install a plugin at a tag (e.g. plugin-cs2)
img2 doctor                                       # what each host resolves: base-skill path + version, plugin gates
img2 capabilities --from-kind image --to-kind glb # which installed plugin serves an edge

セットアップと CLI の完全なリファレンスは、README のクイックスタートとハーネスリポジトリのドキュメントにあります。

Forge ランタイムの契約

細分割のランタイムテストでは、生成された TypeScript を showcase のチェックアウトに対してコンパイルします。 IMG2THREEJS_SHOWCASE_ROOT にそのチェックアウトを設定してください。設定されていない場合、ローカルのランタイム専用テストは 対処方法を示すメッセージとともにスキップされますが、静的な契約テストは引き続き実行されます。CI では IMG2THREEJS_REQUIRE_SHOWCASE=1 を設定して、showcase のチェックアウトがない場合にテストを失敗させてください。

IMG2THREEJS_SHOWCASE_ROOT=/path/to/img2threejs-showcase python3 forge/tests/test_subdivision.py
IMG2THREEJS_SHOWCASE_ROOT=/path/to/img2threejs-showcase python3 -m unittest discover -s forge/tests
IMG2THREEJS_SHOWCASE_ROOT=/path/to/img2threejs-showcase python3 forge/tests/test_showcase_tsc_smoke.py

実装ルール（概要）

プロジェクトでラッパーを使用していない限り、TypeScript と標準の Three.js を使用してください。Group ファクトリー createObjectNameModel(spec, options) を使用し、再構築データはレンダラーオブジェクトとは分けて保持し、 プロシージャルノイズにはすべて決定論的なシードを使用してください。外部アートを使う前に、プリミティブ、 Shape の押し出し、カーブ＋チューブ、インスタンシング、ディスプレースメント、生成したキャンバステクスチャを優先してください。 ジオメトリとマテリアルの詳細なレシピ、および実証済みの失敗パターンについては、grimoire/build/geometry_patterns.md を参照してください。

Python ↔ Three.js の任意レンダリングブリッジ

キャラクターのレンダリングに Python が要求された場合は、ブラウザーの Three.js ランタイムを中心とする決定論的なジョブ／証跡レイヤーとして使用してください。これには、カメラバッチのマニフェスト、ソース／出力ハッシュ、準備完了と静定のチェック、スクリーンショットの保存、マスク、診断、比較用パッケージ化が含まれます。レンダリングの権威となるのは、引き続き対象の Three.js ブラウザールートです。プロシージャルな TypeScript ファクトリーを Blender／VRM／GLB の出力に暗黙に置き換えてはいけません。ルーティング、マニフェストのフィールド、失敗時のルールの詳細については、grimoire/build/python_threejs_render_bridge.md を参照してください。

標準キャラクターパイプライン（1.5 ベータ版＋アルファ版を統合）

キャラクターの作業では、grimoire/readiness/standard_character_pipeline.md を使用してください。ベータ版では厳格なスカルプト／ビルド／レビューのゲートを担当し、アルファ版では決定論的なカメラマニフェスト、ブラウザーのスクリーンショット証跡、UniRig 形式のリグ検証を担当します。CharacterGen、Tripo、VRM などのニューラル／アセットシステムは、ソース、チェックポイント、ライセンス、座標変換、出力ハッシュを含むオプトインアダプターです。これらがプロシージャルな TypeScript ファクトリーを暗黙に置き換えることはありません。画像からメッシュを生成するシステムが出力するのはスケルトンのない静的メッシュであるため、見た目がどれほど優れていても、アニメーションに対応した状態にはなりません。実行可能なエントリーポイントは forge/stage4_review/render_bridge.py と scripts/capture_threejs_playwright.py です（init → browser capture → validate → diagnose。キャプチャは実際の showcase／ブラウザールートで実行し、ワークスペースに読み取り可能な PNG を保存する必要があります）。

出力

• 分析のみ：適合性の判定とスコア、オブジェクトの抽出、マクロからミクロへの階層、ジオメトリ戦略、マテリアル／ライティングのレシピ、アニメーション／破壊の実現可能性、計画とリスク。
• 実装：上記を簡潔に示してからコードを編集し、型チェック／ビルドとスクリーンショットで検証します。
• 実現不可能：障害要因を示し、別の視点の画像、より鮮明な画像、許容可能な様式化、または対象範囲の縮小を求めてください。「この画像から、要求された忠実度を実現することはできません」は妥当な結果です。