blender-asset-validation

Blender アセットの検証

自律的な判断、証拠の確認頻度、長時間タスクの継続方法については、タスクごとに一度、共有実行ガイダンスを読んでください。

提供されたアセットと、依頼されたエクスポート成果物を検証してください。確認のみ、またはレンダリングのみのタスクでは、エクスポートを作成しないでください。エクスポートに問題がないことや三角形数が少ないことは、視覚的または機能的な品質の証明にはなりません。

決定論的な検査を実行する

利用可能な場合は、blender_inspect_asset MCP ツールを優先してください。それ以外の場合は、次を実行します。

$env:BLENDER_EXECUTABLE = "C:\path\to\Blender\blender.exe"
& $env:BLENDER_EXECUTABLE `
  --background --factory-startup `
  --python "<skill-root>\scripts\inspect_asset.py" -- `
  --input "<asset-path>" --output "<output-dir>\metrics.json"

次の項目を検査します。

• 評価後の頂点、辺、ポリゴン、三角形；
• 作成時のジオメトリ密度と細分化モディファイアを、評価後のものと比較；
• スムーズシェーディングとフラットシェーディングのポリゴン比率；
• UV を持つメッシュ、ノードベースのマテリアル、画像テクスチャ、作成済みライト；
• メッシュオブジェクト、マテリアル、アクション、フレーム範囲、階層；
• 寸法とワールド境界；
• 無効な座標、縮退面、孤立要素、境界辺と非多様体辺；
• メッシュごとの連結成分；
• デフォルト以外のトランスフォームと割り当てられていないマテリアル。

メトリクスの解釈には、references/quality-gates.mdを使用してください。印刷専用のトポロジールールを、あらゆるゲームアセットに適用しないでください。

検査で縮退面または長さゼロの辺が見つかった場合は、assetPathと新しいoutputJsonを指定し、必要に応じてobjectNameとlimitも指定して、blender_diagnose_topologyを呼び出してください。このツールは全件数と、上限付きのワールド空間位置を報告します。インデックスは評価後のジオメトリに対応します。該当箇所を特定し、永続化されるソースを修復して、エクスポートを再検査してください。開いた境界だけでは欠陥とはみなされません。

修復を診断する前にシーンを把握する

Rust ランタイムが設定されている場合は、評価後のワールド境界、作成時のbas_roleラベル、親子関係、ページ分割されたオブジェクトの概要を取得するために、blender_describe_sceneを使用してください。正確なobjectIdとincludeDescendantsを指定して対象を絞り、大規模な選択ではnext_offsetをたどってください。アセンブリはコレクション名ではなく、オブジェクトの親子関係に従います。

blender_quality_reportでは、概要から得られたtriangleBudget、requireClosedMesh、または名前付きのgroundObjectsと明示的なgroundZのみを使用してください。距離の単位は Blender のワールド単位です。制約は選択範囲全体を対象とし、空間候補の比較対象は返されたページのみです。AABB の重なりや近接は確認候補であり、メッシュの交差、接触、支持が証明されたわけではありません。特に、展開されていないインスタンスやメッシュ以外の形式など、抽出に関する制限を確認してください。

レポートだけで視覚的な確認が不要になることはありません。review_requiredは合格を意味しません。以下の固定ビューを開き、主要形状、参照、仕上げに関する質問に回答してください。ランタイムが利用できない場合は、そのセットアップメッセージに従うか、既存のインスペクターと視覚的な証拠を使って作業を続けてください。測定していない分析を行ったと主張しないでください。

修復後は、保持しておいた候補と再生成した結果に対してblender_compare_scenesを使用してください。requiredObjectsと、契約で指定された不変条件のみを宣言してください。意図的に編集したパーツを、移動、寸法、階層、ロール、トポロジー保持のゲートから除外するには、invariantObjectsを使用してください。宣言された不変条件に違反がなくても、事実に関わるすべての変更を確認してください。回帰リストが空でも、視覚的な改善が証明されたことにはなりません。修復を保持する前に、同じカメラと設定で両バージョンをレンダリングしてください。

意図された物理的な接合部については、接触させるべき正確なメッシュオブジェクトのペアをcontactPairsとして品質レポートに宣言してください。任意の近くの名前ではなく、構造上の契約に基づいて選んでください。許容値を超える境界間の正の隙間がある場合、オブジェクトが返されたページの外にあっても、分離が証明され、expected_contact_gapが生成されます。contact_unverifiedは、境界ボックスが近いか重なっていることを意味しますが、表面の接触を証明するものではありません。中間コネクターを持つ接合部では、離れた両端同士の接触を要求するのではなく、実際の各接続を確認してください。複数のビューで接合部を確認し、永続化されるソースを修復したうえで、同じ宣言済みペアを再実行してから修復を保持してください。

特定の接続点を確認する

アニメーションポーズを確認する際は、SceneIR の記述、品質、比較ツールに frame を指定します。変更前後のエビデンスには、同じ明示的なフレームを使用してください。ペアのアセット比較では、保存されたフレームや単位スケールが異なると拒否されます。必要な各モーション状態で、コントラクトのチェックを繰り返してください。フレームを設定してもシミュレーションがベイクされるわけではなく、サンプル間の動作が証明されるわけでもありません。

ケーブル端子、ヒンジの支点、パイプの端部では、オブジェクト全体のボックスが重なると、contactPairs では誤った端点を見落とすことがあります。安定した名前、正確な objectA／objectB、オブジェクトローカル座標での pointA／pointB の XYZ、ワールド単位での maxDistance を指定して、blender_quality_report に connectionPoints を追加してください。実際の端点と同じソースパラメーターから配置した Empty は、アンカーとして使用できます。両方のオブジェクトが選択されたアセンブリに属している必要があります。ページ分割によってチェックが隠れることはありません。

connection_checks は、ワールド座標での位置、距離、および delta_world_b_minus_a を返します。connection_point_gap は、ボックスが重なっていても、宣言されたアンカーの位置ずれを特定します。修正は永続的なジオメトリソースに適用してください。ローカル座標を編集する場合は、ワールド空間の差分をそのオブジェクトのローカル空間に変換してください。アンカーはジオメトリから導出した状態に保ち、レンダリングされた接合部を確認してください。マーカーだけを動かしても修正にはなりません。within_tolerance が証明するのはアンカー間の一致のみであり、メッシュの接触、水密性、機械的な妥当性ではありません。

評価済みモーションを検査する

blender_inspect_motion では、assetPath、新しい outputJson、増加する順序で重複のない 2～12 個の frames、および正確なメッシュ objectNames を 1～8 個指定します。このツールは、評価済みジオメトリのローカルハッシュ、ワールド変換、およびネイティブのモディファイア／ベイクメタデータを報告します。必要なのは Blender であり、Rust ではありません。また、ソースをベイクしたり保存したりすることはありません。流体やクロスの既存キャッシュを検査し、アニメーションのエクスポートが必要な場合はエクスポート済みファイルでも繰り返してください。

ローカルハッシュの変化は、単なるルート移動ではなく、サンプリングされた変形を示す根拠になります。ただし、変形の質が良いことを示すものではありません。サンプルが空、または変化がない場合、キャッシュファイルがない場合、未ベイクのモディファイアがある場合は、調査が必要です。ベイクフラグがあっても、キャッシュが完全に網羅されているとは限りません。接触、衝突、タイミング、外観、連続再生については、ドメインのワークフローを使用してください。CLI で代替する場合は、Blender 経由で scripts/inspect_motion.py を実行し、--input、--output、--frames 1,12,24、--targets Body を指定します。

レンダリングのエビデンス

参照画像に基づいてプロポーションを確認する場合は、参照画像に合ったカメラを設定し、blender_compare_reference を使用します。参照画像／シルエット／オーバーレイを並べたボードがインラインで返されます。ジオメトリの編集前後で、カメラ、クロップ、ポーズを固定してください。白い前景と黒い背景の maskPath を指定した場合にのみ、シルエット IoU と不足／過剰な領域の評価が有効になります。通常の写真には視覚的なオーバーレイが表示されますが、数値による類似度は得られません。この機能は、最終的な複数視点の確認とマテリアルの検査を補完します。

向きはすでに妥当で、フレーミングだけが異なる場合は、空間的に離れた既知のランドマークを 3～32 個、referenceWidth／referenceHeight、および新しい outputDir とともに指定して、blender_fit_reference_camera を使用します。各ランドマークには、name、objectName、localPoint（XYZ）、および referenceUv（画像の左上を原点とする正規化済み XY）を指定します。このツールは、ポーズやメッシュを変更せず、候補の .blend 内でスケール／焦点距離とレンズシフトを調整します。候補を blender_compare_reference で確認し、採用したパラメーターを永続的なソースに反映したうえで、ジオメトリの比較中はカメラを固定してください。ランドマーク誤差が小さいほど、フレーミングの適合度が高いことを示しますが、ジオメトリが改善したことを示すものではありません。残差が大きい場合、ポーズまたは対応関係が誤っている可能性があります。残差を減らすためだけにメッシュをゆがめないでください。 対象を絞った修正では、views: ["perspective", "front"]（または有用な固定アングルを2つ）と、素早く確認できるresolution: 256を使用します。CLIでは--views perspective,frontを指定できます。マニフェストではこれをpartial_previewとラベル付けします。これは最終的な6ビューの条件を満たしません。修正前後の確認では、同じビュー選択、解像度、明示的な表示設定を維持してください。修正を採用したら、細かな編集のたびではなく、その時点で全ビューをレンダリングします。

下面の接合部を確認するには、viewsにbottomを追加します（CLIでは--views bottom）。このビューでは生成されたスタジオの床だけが取り除かれ、下面を照らす光が追加されます。作成済みのジオメトリは削除されません。周囲を隠さずに小さな接合部をフレーム内に収めるには、focusObjectsにオブジェクトの正確な名前を指定します（CLIでは--focus-objects '["Leg_FL","Seat"]'）。フォーカスした証拠はdetail_previewとラベル付けされ、アセット全体のビューを補完します。遮蔽するジオメトリは引き続き表示されます。近接した切り抜きや境界ボックスの重なりだけでは、接触している証拠にはなりません。

デフォルトのpresentation: "auto"では、一定のマテリアル輝度のヒントに基づいてスタジオ背景が選択されます。明るいアセットには暗い背景、非常に暗いアセットには明るい背景、それ以外にはニュートラルなスレート色の背景が選ばれます。CLIでは--presentation autoを指定します。上書きするには、neutral、dark、またはlightを使用します。ライトの強さとカメラのフレーミングはアセットの寸法に応じて調整されます。このツールは作成済みのライティングとカラーグレーディングをリセットします。元のライティングが要求された仕上がりの一部である場合は、作成時のライティングを使ったビューティーレンダーを別に保持してください。

表示設定を確定する前に、最初のヒーロー画像を開いてください。マテリアルの色が白っぽくなる、影で形状が見えなくなる、またはシルエットが背景に溶け込む場合は、より適切なプリセットで再レンダリングします。自動選択は出発点にすぎません。テクスチャに左右される色、透明な見た目、アートディレクションまでは推測できません。異なる目的に役立つ場合は、暗いスタジオと明るいカタログのように、2つの有用な選択肢を提示します。すべてのプリセットを常に生成する必要はありません。まず洗練されたヒーロー画像を提示し、確認用のマルチビュー証拠も利用できるようにします。

ベンチマークや修正前後の比較では、比較するアセットすべてで同じプリセットとレンダラーのバージョンを明示的に固定し、条件ごとに個別に調整しないでください。evidence.jsonには、要求されたプリセットと解決後のプリセット、ライトの強さ、フレーミング、カラー管理、エンジン、設定のバージョンが記録されます。バージョン2ではライティングとフレーミングが変更されています。管理された視覚比較を行う前に、古い証拠を再レンダリングしてください。

blender_render_evidenceを優先してください。それ以外の場合は、出力ディレクトリを指定してscripts/render_evidence.pyを実行します。次を必須とします。

• パースペクティブのヒーロービュー
• フロント、バック、左、右、トップの各ビュー
• コンタクトシート1枚
• 該当する場合は、指定されたアニメーションの重要フレーム

画像表示ツールでヒーロー画像とコンタクトシートを開き、次を確認します。

• シルエットとプロポーション
• 必要なパーツと空間的な関係
• 向き
• 浮いている要素や支持されていない要素
• 交差や意図しない隙間
• マテリアルの視認性
• 見て分かる面の粗さ、刃のように鋭いエッジ、ブロックアウトの残り、テクスチャの欠落や破損
• 意図したスケールでディテールを判読できるか

ヒューマノイドでは、キャラクターワークフローの形状とフィットのレビューを適用します。全身のプロポーションに加え、履物、ウエスト／股間、肩、手／親指、顔／鼻／耳／首を拡大して確認します。動作中に評価済みの肌表面を検査してください。骨がつながっていることや、単一のメッシュオブジェクトであることだけでは、衣服が連続している証拠になりません。ニュートラルなライティングと目的の表示設定の両方で、肌の色調とテクスチャの継ぎ目を確認してください。依頼内容と一致しない、ブロック状または過度に大きな形状、説明のない重なり、肌の色調の不連続は、ローポリ最適化の成功ではなく視覚的な欠陥として扱います。普遍的な比率ではなく、参照対象との比較に基づいて判断してください。

エクスポートした成果物を検証する

エクスポートが要求または提供された場合は、このゲートを使用します。.blend のみのタスクでは、代わりにそのシーンを再度開いて検査します。

1. 要求された形式でエクスポートするか、提供されたエクスポート済みの成果物を使用します。
2. 新しい Blender プロセスを起動します。
3. 実際にエクスポートされたファイルを個別にインポート、検査し、レンダリングします。
4. 必須の名前、マテリアル、寸法、アクション、重要なフレームを、作成したシーンと比較します。
5. 作成したシーンと再インポートしたシーンのメトリクスを分けて報告します。

レポート

各所見を次のように分類します。

• gate：成果物が無効、または使用できません。
• defect：要求、ジオメトリ、プレゼンテーション、またはモーションに明らかな不備があります。
• warning：確認が必要となるリスクが見込まれます。
• observation：中立的な測定結果です。
• not_applicable：タスクの意味に基づき、意図的に除外されたチェックです。

正確な証拠のパスを記載します。実際に開いていない画像や動画を、確認したと決して述べないでください。