写真シーン再構築 は何をしますか?
この手法は、2026年11月の3つのプロジェクトで開発されました。路面電車のある通り(フライブルク)、ゴシック様式の噴水のある広場(フィッシュブルンネン、フライブルク)、そしてコード生成された都市、ショップ、港湾のジオラマです。以下の例はこれらに基づいています。汎用ハーネス(カメラ、オーケストレーター、レンダリングおよび比較ツール)は、このファイルの隣の harness/ にあります。harness/blender と harness/tools を新しい実行フォルダにコピーしてください。以下に記載されているツール名で harness/ にないもの(例:facade_solve.py)は、各実行が自身で作成するドメイン固有のプローブです。それらの目的は、名前が記載されている場所で説明されています。
要件: Blender(5.1、Cyclesに対して記述)、Python(2Dツール用にnumpy、opencv、pillow)(tools/py.sh は uv で実行)、サブエージェントを起動できるエージェントランタイム。
ユーザーは、写真と並べて目視で忠実度を判断します。以下のすべては、その比較を安価で頻繁かつ正直に行うために存在します。
0. リードがエージェント開始前にセットアップ
リード(メインセッション)がこれらを単独で行います。エージェントはこれらがすべて完了した後にのみ開始します。
-
実行フォルダ。
<runs>/<scene>/にref/photo.jpg、blender/、tools/、layout/、gen/、renders/、work/、final/を作成。lib.py、arch.py、assets.py、render.py、build_scene.pyと汎用ツール(cam.py、vp.py、solve_cam.py、iterate.sh、overlay.py、edges.py、pair.py、crop.py、stats.py、py.sh、fetch_polyhaven.py、fetch_ph_model.py)をharness/からコピー。 -
カメラをソルブ するには
tools/vp.pyを使用。垂直消失点と、主要ファサードに沿った1つの水平消失点を見つけます。次にtools/solve_cam.pyで以下を取得:- 焦点距離(2方向が直角であることから、レンズは仮定しない)
- ピッチ(垂直消失点から)
- ヨー(ファサードがワールド+X軸に沿うように選択)
結果を
layout/camera.jsonに書き込みます。その後、カメラは実行全体を通じて固定されます。 -
アンカーを測定 するには
tools/cam.pyを使用:on_zは水平面にヒットし、on_yは垂直面にヒットし、projectはピクセルを返し、rayはビューレイを返します。- 地面のライン、ファサード平面、各ランドマークの距離を測定します。
- リードの最初の推定値をルールブックに初期値として書き込みます。
- かすめ角では、地面ラインの1ピクセルが奥行きの0.5メートルになり得ます。単一の地面ポイントよりも、既知のものの高さと幅(ドア2.1m、目線1.6m、縁石0.12m)を優先します。
-
オブジェクトインベントリ。 写真に表示されているすべてのオブジェクトをリストし、それぞれを スクリプト または メッシュ(セクション3)としてマークします。このリストがドメイン分割とアセットフェッチを決定します。
-
AGENTS.mdを書き込む:目標、ワールドフレーム、アンカー、ドメインテーブル、ハードルール、ループ、作業順序、完了ルール。
1. ドメインユーザーシップ(エージェントが1つのシーンを共有する方法)
シーンの分割
- 1つのドメイン = 1つの
build(L, ctx)を持つモジュール + 1つのlayout/<domain>.json+ 新しいものすべてに対する1つのファイルプレフィックス(tools/<domain>_*.py、tex/<domain>_*、gen/<domain>_*)。 - オブジェクト数ではなく、画面領域と作業の種類で分割します。適切な分割により、各エージェントはクロップして単独で判断できる領域を得られます。フライブルクでは5つを使用:ライト、ストリート、左側の建物、ヒーローファサード、プロップス。
- ライトは常に独自のドメインであり、空、露出、カラーマネジメント、グレーディングを所有します。他のエージェントが自身のマテリアルを良く見せるために露出に触れることはありません。
- ヒーロー要素(目が留まるもの)は、それ自体でドメインを取得します。
- 4〜6のドメイン。それより少ないとエージェントがファイル内で衝突し、多いとリードがレビューできません。
契約
build_scene.pyはオーケストレーションのみを行います:layout/*.jsonをLにマージし、カメラを作成し、固定順序で各モジュールを呼び出し、保存します。ジオメトリはそこには存在しません。- すべてのエージェントは任意のレイアウトキーを読み取り可能であり、自身のレイアウトファイルとモジュールのみに書き込み可能です。
- 共有ヘルパー(
lib.py、arch.py、assets.py、cam.py、iterate.sh)は固定されています。変更が必要なエージェントは、変更したヘルパーを新しい名前で自身のモジュールにコピーします。assets.pyはメッシュフィッティング手順を保持するため、すべてのドメインが同じ方法でメッシュをフィットします:import_gltfはインポートしてXYZ回転を設定world_boundsは頂点から境界を計算fitは測定された高さまたは幅にスケーリングし、ヨーを適用し、最下頂点をそのサポート上にドロップ
- アンカーを測定したドメインがそれを所有します。 リードのアンカーは開始値です。所有ドメインがそれを洗練し、その結果を自身のレイアウトファイルに公開します(例:
L['facade']['plane_y']またはL['fountain']['centre'])。他のすべてのドメインはLから値を読み取り、その数値を自身のコードにコピーすることはありません。これにより、洗練が次のビルドですべてに反映されます。 - 派生したワールド値の横に写真ピクセルでの測定値を保存します(例:
facade.pxとfacade.sec)。ソルバースクリプト(tools/facade_solve.py)がピクセルをワールド数値に変換し、レイアウトに書き込みます。その後、再測定はピクセルを編集してソルバーを再実行することを意味し、座標を手動編集する必要はありません。 - 他のモジュールがインポートする名前はルールブックに「新しい関数を追加し、これらは変更しない」というルールでリストされます。クロスドメイン値は
ctxを介して渡され(例:ctx['track_x'])、編集によって渡されることはありません。 build(L, ctx)は常に動作する必要があります。すべてのエージェントがシーン全体を再構築するため、1つのモジュールが壊れると全員がブロックされます。リスクのある編集を保存する前に構文を確認してください。
エージェントの実行
- 各エージェントは自身の
work/<domain>.blendにビルドします。レンダリングはwork/.gpu_lock(6分以上経過したロックは古いと見なす)によってシリアル化されます。only=で他のドメインをスキップして高速化できます。色を判断するときはフルシーンを使用してください。隣接オブジェクトが光を反射するためです。 - 同時にレンダリングするエージェントは最大2〜3。 複数のBlenderプロセスがWindowsのページファイルを50 GB以上に増やし、C:ドライブを満たす可能性があります。エージェントの
work/<domain>.blendは、終了次第すぐに削除してください。特定のプロセスIDを待機し、「実行中のBlenderがない」状態を待たないでください。 - ウェーブで実行。 ウェーブ1はジオメトリを作成するドメイン(例:地面、ファサード、ヒーロー)で、同時に最大3つ。ウェーブ2はライトと有機的または家具のドメインで、照明、陰影、成長のためにジオメトリが必要です。未完成のジオメトリで判断されたライトは無駄な作業です。
- マシンを起動状態に保つ(
request_keep_awake)ことを任意のウェーブの前に行います。PCがアイドルスリープすると、レンダリングが9時間フリーズしました。 - ラウンド。 各ウェーブまたはラウンドの後、リードは
mainをビルドし、レンダリングを写真と目視でレビューし、最悪の差異を次のラウンドのブリーフとして書き込みます。送信された比較シートに対するユーザーのメモ(例:「より粗いテクスチャ」や「照明が人工的に見える」)は、それ自体がラウンドになります。 - 各エージェントは、最新の3つのプレビューセットを
renders/に保持し、自身のプレフィックスの古いものを削除します。 - エージェントは有料クレジットを使用しません。生成されたアセットが何を修正するかを、使用する写真クロップとともに報告します。リードはそれをコストとともにユーザーに提示します。
- エージェントはコミットせず、gitに触れず、実行フォルダ外に書き込みません。
エージェントブリーフ(リードが送信するもの)
簡潔に保ちます。ルールブックが残りを担います。
- 「最初に
AGENTS.mdを読んでください。」その後:あなたのドメイン、あなたのモジュールとレイアウトファイル、あなたの写真領域(ピクセル単位)。 - 既に存在するものと、それの何が問題か(写真との最悪の差異3つを挙げる)。
- インベントリからのそのドメインのメッシュリスト(既に
gen/にフェッチ済み)。 - 完了ルールとレポート形式(以下)。
完了と統合
- エージェントは、その領域が960pxクロップで写真と並べて遜色なくなった時点、または約12回の反復後に停止します。
- 最終レポート(250ワード未満):何が変わったか、まだ写真と異なる点、生成アセットが役立つ場所、最後のレンダリングのタグ。
- その後、リードはすべてのモジュールから
work/main.blendをビルドし、フルフレームをレンダリングし、最初にエージェントのレポートを読まずに写真とレビューします。レポートは意図を説明しますが、画像が証拠です。差異は次のラウンドのブリーフになります。 - 照明のムードとエフェクトは、その後、
main.blendに対する非破壊オーバーレイとして適用されるため、ルックの変更が承認された忠実度を妨げることはありません。路面電車の実行ではmain.blendの上にblender/mood.pyを使用しました。フィッシュブルンネンは、FB_MOODが設定されている場合、mood/<variant>.json(tools/mood_make.pyによって書き込まれる)をレイアウトにディープマージします。FB_MOODはカンマ区切りリストを受け取ります(例:warm_a,film)。フィッシュブルンネンの形式を使用します。ムードは同じモジュールを通じて再構築され、2番目のシーンファイルは必要ありません。
2. 忠実度の順序とループ
ループ、すべての変更時
tools/iterate.sh <domain> <n> [width=480] [spp=24] [only=a,b] [x0 y0 x1 y1]
ビルド、レンダリング、ovl_*(写真 | レンダリング | 50%ブレンド)と edg_*(レンダリング上にピクセルグリッド付きの赤い写真エッジ)を書き出します。写真ピクセルでボックスを指定すると、その領域のみをレンダリングし、crop_*(写真クロップ | レンダリングクロップ、拡大)を書き出します。幅960で約25秒かかります。画像を開いて確認してください。比較画像を見ずに、変更を改善として報告しないでください。
この順序で作業し、先に進まない
各ステージにはゲートがあります。以前のゲートが通過する前に追加された詳細は無駄になります。なぜなら、以前のエラーが修正されたときにその詳細が移動するからです。
| ステージ | 作業内容 | 次に進む前のゲート |
|---|---|---|
| 1. 読み取り | 自分の領域の写真クロップを拡大します。実際に何があるかを書き留めます:カウント、マテリアル、何が何に触れているか。 | 書き留めたリストが存在し、すべてのアイテムがインベントリにある。 |
| 2. シルエット | cam.py の測定からマスを配置します。 | 輪郭が、960幅で edg_* の赤いエッジ上に数ピクセル以内で収まる。 |
| 3. プロポーション | 開口部、フロアライン、ベイ、繰り返し数。 | 窓とドアのエッジが写真のエッジに一致し、数が一致する。 |
| 4. 色 | 写真に対して測定されたマテリアルベースカラー、フルシーンビルド、ライトドメインの露出はそのまま。マテリアルバージョンをアルベドとして比較(セクション4.2)。 | tools/stats.py とドメインの領域チェックが写真に近く、50%ブレンドに色味のあるパッチが見られない。 |
| 5. 小さな部品 | トリム、金具、ケーブル、看板、雨どい、ランプ、街路備品。セクション3に従ったメッシュ。 | その領域のすべてのインベントリアイテムがクロップ内に存在する。 |
| 6. バリエーションと経年劣化 | ベベル、色のバリエーション、窓台の下のシミ、筋、地面の摩耗、ガラスのリップルと反射。 | クロップが以下のCG判定チェックに合格し、テクスチャエネルギー検査(セクション4.3)が写真に近い。 |
すべてのステージで保持するルール:
- 現実世界の寸法(パターンはミリメートル単位)。
cam.pyで測定し、推測しない。 - 何も浮いたり、相互貫入したりしない。ものは地面に立つか、壁に固定されている。
- 差異を追跡する際は1回の反復につき1つの変更。これにより、比較が変更の効果を示す。
CG判定チェック(各レンダリング後:「まだCGだと分かる点は何か?」)
| 判定点 | 通常の修正 |
|---|---|
| 完全にシャープなエッジ | ベベルまたは面取り、ビルド部分に2〜10mm |
| 平坦な単色表面 | 測定された色のバリエーション、シミ、筋、実際のスケールのテクスチャ |
| 目に見える繰り返し | トーン、回転、摩耗のインスタンスごとのバリエーション |
| 接触影の欠如 | オブジェクトが地面に触れているか確認。ライトとデノイズを確認 |
| 背後または反射がないガラス | 内部平面またはテクスチャ、実際の反射、わずかなリップル |
| 間違ったテクスチャスケール | 写真からパターンをミリメートル単位で再測定 |
| プリミティブ形状のオブジェクト | 実際のメッシュに置き換え(セクション3) |
| 清潔すぎる地面 | 摩耗、湿ったパッチ、葉、継ぎ目 |
ユーザーが忠実度を承認した後
この時点でのみ、順番に以下を行います:
- リアリズムパス: ベベル、ガラス、地面の摩耗。路面電車の実行ではこれを1つのモジュール(
weatherモジュール)として行い、フィッシュブルンネンでは各ドメイン内で行いました。どちらでも機能しますが、1つのドメインが各サーフェスを所有する必要があります。 - レンダリング品質: 2160pxスーパーサンプルと正確なデノイズ。
- センサーフィニッシュ(セクション4.1)。
- 他のアングルからのプルーフビュー(追加カメラをレンダリングする
proof.py)。 - 照明ムード。
- フィルム(セクション5)。
これらの各チェックポイントで写真とレンダリングの比較シートを送信し、ユーザーを待ちます。
3. メッシュ:複雑なオブジェクトにプリミティブは禁止
ルール:複雑なオブジェクトは、単純なプリミティブジオメトリから構築されることはありません。代わりに既存の実際のメッシュを使用します。
該当するもの
- スクリプトジオメトリは許可:壁、スラブ、屋根、窓とドアのフレーム、コーニスとプロファイルトリム、縁石、舗装、レール、ポール、ワイヤー、平面看板など、建築およびインフラストラクチャ。
- 実際のメッシュが必要:木、低木、鉢植え、人、乗り物、自転車、椅子、テーブル、ベンチ、プランター、パラソル、成形体のあるランプ、彫刻装飾、彫像、ひだのある布など、有機的またはオブジェクト的なものすべて。
- テスト:もし誰かがあなたのビルドを「棒の上の球」「4本足の箱」「円柱」と表現するなら、それはプリミティブの代用であり、ユーザーに送信するレンダリングのプレースホルダーとしても許可されません。
調達ラダー(最初に適合するもので停止)
- 自身のメッシュライブラリ。 以前のプロジェクトで作成またはダウンロードしたすべてのプロップメッシュのインデックス(カテゴリ、サイズ、トライアングル数、パス、ライセンス)を保持し、最初に検索します。再利用は購入に勝ります。
- Poly Haven CC0(無料):
tools/fetch_ph_model.py <id>(glTF 2kをgen/ph/<id>/に)、テクスチャと空はtools/fetch_polyhaven.py <id>を使用。エージェントあたり約150 MB以下にダウンロードを抑えます。 - 生成メッシュ(有料、リードを通じてのみ、ユーザーがコストを確認した後にのみ):ソフトまたは有機的なプロップや装飾にはMeshy、ハードサーフェスのヒーローにはTripo H3.1 Detailed。メッシュの準備とフィッティングは3つのステップで行います:
- クロップをクリーンアップ。 写真からオブジェクトをクロップ(
gen/meshy_refs/<name>_crop.jpg)。安価な画像編集パスを1回実行してオクルーダーを除去し、切り取られた部分を仕上げ、無地の背景を与え、<name>_clean.pngとして保存します。その後でのみ画像から3Dを呼び出します。噴水の実行では、これにより4つの彫像すべてと天蓋が初回で使用可能になりました。 - 一度だけデシメート(オフライン)、
gen/<domain>_meshes.blendに。 - フィット(
assets.fit)を使用してメッシュを配置し、高さまたは幅にスケーリングし、ヨーを適用し、最下頂点をそのサポート上にドロップします。
- クロップをクリーンアップ。 写真からオブジェクトをクロップ(
- 手動モデリング: 上記のすべてが失敗した場合の最後の手段。リードが、生成されたメッシュでカバーできないジオメトリを構築するための予算を割り当てます。
メッシュの配置ルール
- 各メッシュは
gen/<domain>_meshes.blendまたは外部ファイルから1回インポートされ、変数に格納され、コピーされません。 - プロップは
assets.pyのfit関数を使用して配置されます。fitはメッシュをスケーリングしてワールド単位の測定値に一致させ、ヨーを適用し(0の場合スキップ)、最下頂点をベース平面にドロップします。 - リグやアーマチュアは不要です。メッシュはそのまま使用されるか、
bpyで単純に変形されます。 - すべてのメッシュは
build(L, ctx)内で、モジュールトップレベルではなく、遅延ロードされます。これにより、build_scene.pyは未使用のメッシュでメモリを消費することなく全モジュールをインポートできます。
4. 写真からの測定
4.1 センサーフィニッシュ
写真の露出は、カメラのセンサーフィニッシュを反映しています。忠実なシーンは、これをレンダリング出力に適用する必要があります。
- フィルムルック(カラープロファイルとトーンカーブ)は、忠実度が承認された後でのみ、レンダリング後に適用できます。
- 実際のセンサー応答が必要な場合:
tools/sensor_finish.pyは、写真のグレースケールパッチからトーンカーブを抽出し、レンダリングに適用します。 - 簡単な方法:露出とホワイトバランスを写真に一致させ、その後、写真のヒストグラムに一致するようにわずかなカラーグレーディングを適用します。
4.2 アルベドチェック
写真の照明が複雑な場合、アルベド(拡散反射率)を分離することが重要です。
tools/albedo_check.pyは、選択した領域の平均色を写真からサンプリングし、既知の照明条件下での予想アルベドと比較します。- 屋外シーン:日向の平均RGBを日陰の平均RGBで割ると、大まかなアルベド比が得られます。
- 材料データベース(
arch.py内)には、一般的な建築材料(レンガ、石、漆喰、金属、木材)のアルベド値が含まれています。
4.3 テクスチャエネルギー検査
テクスチャの周波数分布は写真と一致する必要があります。
tools/stats.pyは、写真とレンダリングの領域のフーリエパワースペクトルを計算します。- 低周波エネルギーは全体的な照明と色の変化を捉え、高周波エネルギーは詳細とテクスチャを捉えます。
- 各オクターブのエネルギー差が10%未満である必要があります。差が大きい場合、テクスチャが粗すぎるか(高周波エネルギーが低い)、細かすぎるか(高周波エネルギーが高い)です。
5. フィルム
忠実なシーンが完成したら、フィルムルックを適用できます。
blender/mood.pyは、露出、ホワイトバランス、トーンカーブ、被写界深度、グレインを調整するノンリニアオーバーレイをmain.blendに追加します。tools/mood_make.pyは、写真からムードパラメータを抽出するか(参照写真が利用可能な場合)、または手動で設定できます。- フィルムバリアント(例:
warm_a、film、cold_b)はmood/<variant>.jsonに保存され、環境変数FB_MOODを介して適用されます。
6. コード生成とスクリプト
6.1 ファサード生成
複雑なファサード(歴史的な建物、装飾的なファサード)には、スクリプトによる生成が推奨されます。
tools/facade_gen.pyは、測定されたプロポーションと写真から抽出されたテクスチャを使用して、建築要素(窓、ドア、コーニス、欄干)を生成します。tools/facade_solve.pyは、ピクセル測定値をワールド単位のパラメータに変換します。gen/facade_meshes.blendには、複雑な要素の事前モデリングされたコンポーネントが含まれています。
6.2 有機的生成
樹木、植生、人物などの有機的要素には、実際のメッシュ(セクション3)を使用するか、tools/vegetation_gen.py を使用してスクリプトで生成します。
tools/vegetation_gen.pyは、写真から抽出された配置ルール(密度、高さ分布、種の混合)を使用して植生を分布させます。- 各樹木または低木は、事前モデリングされたメッシュからインスタンス化され、ランダムなサイズと回転が適用されます。
6.3 インテリア生成
屋内シーンには、tools/interior_gen.py を使用して家具と装飾を生成します。
- レイアウトルール(壁からの距離、通路の幅)は写真から測定されます。
- 家具はメッシュライブラリから選択されるか(セクション3)、スクリプトで生成されます(単純な形状の場合)。
7. コード生成技術のランク付けリスト
ユーザーがコードで生成された建物を要求した場合、または参照写真を3Dで再現するよう要求した場合、以下のランク付けされた技術を順に試します:
- ファサードソルバーを使用したプロシージャル生成:
tools/facade_solve.pyとtools/facade_gen.pyを使用して、写真から直接測定されたパラメータに基づいてファサードを生成します。これにより、最高の忠実度が得られます。 - 測定値と写真テクスチャに基づくスクリプト生成: 建築要素を構築するために
arch.pyとlib.pyの関数を使用します。窓、ドア、コーニス、その他の詳細は、測定値から計算されたパラメータで生成されます。 - 生成されたメッシュのインポート(セクション3.3): 複雑な有機的要素の場合、写真からクロップをクリーンアップし、MeshyまたはTripoを使用して3Dメッシュを生成します。
- 手動モデリング: 上記のすべてが失敗した場合、または特定の詳細が必要な場合の最後の手段。
このランク付けにより、最も効率的で高品質な方法が最初に試され、自動化できない場合にのみ手動介入にフォールバックします。
8. ワークフローの概要
- セットアップ: 実行フォルダを作成し、ハーネスをコピーし、カメラをソルブし、アンカーを測定し、オブジェクトインベントリを作成し、
AGENTS.mdを書き込みます。 - ドメイン分割: シーンを4〜6のドメインに分割し、各ドメインにモジュールとレイアウトファイルを割り当てます。
- ウェーブ1: ジオメトリドメイン(例:地面、ファサード、ヒーロー要素)を並行して実行します。
- ウェーブ2: ライトと有機的/家具のドメインを、ウェーブ1のジオメトリに対して実行します。
- 反復ループ: 各ドメインは、セクション2の固定順序(読み取り→シルエット→プロポーション→色→小さな部品→バリエーションと経年劣化)で作業します。各変更後、
iterate.shを使用してレンダリングを写真と比較します。 - ラウンド: リードは各ラウンド後に
main.blendをビルドし、写真とレビューし、差異に基づいて次のブリーフを発行します。 - 完了: エージェントが完了したら、リードは統合されたシーンをビルドし、レンダリングし、ユーザーに承認を求めます。
- リアリズムパス: ベベル、摩耗、ガラスのリップル、その他のリアリズムの詳細を追加します。
- レンダリング品質: スーパーサンプリング、デノイズ、センサーフィニッシュ。
- ムードとフィルム: 非破壊的なムードオーバーレイを適用します。
- プルーフビュー: 複数のカメラアングルからレンダリングします。
このワークフローにより、写真とほぼ区別がつかないほど忠実度の高いBlenderシーンが体系的に構築され、ユーザーは各段階で品質を検証できます。