照片場景重建 是做什麼的?
此方法於 2026 年 11 月在三個專案中開發:一張有電車的街景照片(弗萊堡)、一個有哥德式噴泉的廣場(弗萊堡的 Fischbrunnen)以及三個程式碼生成的城市、商店和海港立體模型。以下範例來自這些專案。通用框架(相機、協調器、渲染與比較工具)位於此檔案旁的 harness/ 資料夾中:將 harness/blender 和 harness/tools 複製到新的運行資料夾。以下提及的不在 harness/ 中的工具名稱(例如 facade_solve.py)是每個領域自行撰寫的探測工具;其用途在命名處有說明。
需求:Blender(針對 5.1 版、Cycles 編寫)、Python 搭配 numpy、opencv 和 pillow 以用於 2D 工具(tools/py.sh 使用 uv 運行它們)、以及一個可以啟動子代理的代理運行環境。
使用者透過肉眼並排與照片比較來判斷保真度。以下所有內容都是為了使這種比較更便宜、更頻繁且更誠實。
0. 主要代理在任何代理啟動前進行設定
主要代理(主會話)獨自完成這些步驟。代理僅在所有設定完成後才啟動。
-
運行資料夾。
<runs>/<scene>/包含ref/photo.jpg、blender/、tools/、layout/、gen/、renders/、work/、final/。從harness/複製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)。 -
求解相機:使用
tools/vp.py。找到垂直消失點和沿主立面的一個水平消失點。然後tools/solve_cam.py會取得:- 焦距,基於兩個方向互相垂直(不要假定鏡頭);
- 俯仰角,來自垂直消失點;
- 偏航角,選擇使立面沿世界 +X 方向。
將結果寫入
layout/camera.json。相機在整個運行期間保持固定。 -
測量錨點:使用
tools/cam.py:on_z碰觸水平面,on_y碰觸垂直面,project給出像素點,而ray給出視線。- 測量地面線、立面平面以及每個地標的距離。
- 將主要代理的初始估計值寫入規則手冊作為起始值。
- 在掠射角度,地面線的一個像素可能對應半米的深度。優先使用已知物體的高度和寬度(門 2.1 米、眼睛 1.6 米、路緣 0.12 米),而不是單一的地面點。
-
物體清單:列出照片中可見的每個物體,並將其標記為 腳本生成 或 網格(第 3 節)。此清單決定領域劃分和資產獲取。
-
撰寫
AGENTS.md以用於本次運行:目標、世界座標系、錨點、領域表格、硬性規則、循環、工作順序、完成規則。
1. 領域所有權(代理如何共享一個場景)
劃分場景
- 一個領域 = 一個帶有
build(L, ctx)的模組 + 一個layout/<domain>.json+ 所有新事物的檔案前綴(tools/<domain>_*.py、tex/<domain>_*、gen/<domain>_*)。 - 根據螢幕區域和工作類型劃分,而不是物體數量。好的劃分會給每個代理一個它可以單獨裁切和判斷的區域。弗萊堡使用了五個:光線、街道、左側建築物、主角立面、道具。
- 光線始終是其自己的領域,並擁有天空、曝光、色彩管理和分級。沒有其他代理可以為了讓自己的材質看起來正確而觸碰曝光。
- 主角元素(眼睛聚焦的東西)會得到一個專屬領域。
- 四到六個領域。太少則代理會在檔案內碰撞;太多則主要代理無法審查它們。
契約
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)必須始終有效。每個代理重建整個場景,因此一個損壞的模組會阻塞所有人。在保存有風險的編輯之前檢查語法。
運行代理
- 每個代理構建到自己的
work/<domain>.blend中;渲染通過work/.gpu_lock序列化(超過 6 分鐘的鎖被視為過期)。only=跳過其他領域以加快速度;在判斷顏色時使用完整場景,因為鄰居會反射光線。 - 同時最多兩到三個渲染的代理。 多個 Blender 進程曾使 Windows 頁面檔案超過 50 GB 並填滿 C:碟。一旦代理完成,立即刪除其
work/<domain>.blend。等待特定的進程 ID,永遠不要等待“沒有 Blender 在運行”。 - 分波運行。 第一波是產生幾何體的領域(例如地面、立面和主角),最多同時三個。第二波是光線和有機或家具領域,它們需要幾何體來進行照明、陰影和生長。在不完整的幾何體上判斷光線是浪費工作。
- 在任何波次之前保持機器清醒(
request_keep_awake)。當電腦閒置休眠時,渲染會凍結九個小時。 - 回合。 在每個波次或回合之後,主要代理構建
main,通過肉眼將渲染與照片進行比較,並將最顯著的差異寫入下一回合的簡報。使用者在發送的比較表上的筆記,例如“紋理更粗糙”或“照明看起來不自然”,會成為一個獨立的回合。 - 每個代理將其最後三個預覽集保留在
renders/中,並刪除其自己前綴的較舊集合。 - 代理永遠不會花費付費積分。他們報告生成的資產會修復什麼,以及要使用的照片裁切;主要代理會將該資訊連同成本一起提供給使用者。
- 代理不提交、不接觸 git,也不在運行資料夾之外寫入。
代理簡報(主要代理發送的內容)
保持簡短;規則手冊承載其餘部分。
- “先閱讀
AGENTS.md。” 然後:你的領域、你的模組和佈局檔案、你的照片區域(以像素為單位)。 - 已經有什麼以及有什麼問題(命名與照片的三個最顯著差異)。
- 該領域的清單中的網格列表,已獲取到
gen/。 - 完成規則和報告格式(如下)。
完成與整合
- 當代理的區域在 960 像素的裁切中與照片相比站得住腳時,或者在大約 12 次迭代後,代理停止。
- 最終報告,少於 250 字:什麼改變了,仍然與照片有什麼不同,生成的資產在哪裡會有幫助,最後一次渲染的標籤。
- 然後,主要代理從所有模組構建
work/main.blend,渲染完整幀,並在不先閱讀代理報告的情況下將其與照片進行比較。報告描述意圖;圖像是證據。差異成為下一回合的簡報。 - 照明氛圍和效果隨後作為非破壞性疊加層應用於
main.blend,因此外觀更改永遠不會干擾已批准的保真度。電車運行在main.blend之上使用了blender/mood.py。Fischbrunnen 在設定FB_MOOD時,將mood/<variant>.json(由tools/mood_make.py編寫)深度合併到佈局之上;它接受一個逗號列表,例如warm_a,film。使用 Fischbrunnen 的形式:氛圍通過相同的模組重建,不需要第二個場景檔案。
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 的測量值放置大型物體。 | 輪廓位於 edg_* 的紅色邊緣上,在 960 寬度下在幾個像素內。 |
| 3. 比例 | 開口、樓層線、開間、重複計數。 | 窗戶和門的邊緣與照片邊緣對齊;計數匹配。 |
| 4. 顏色 | 針對照片測量的材質底色,構建完整場景,光線領域的曝光保持不變。將材質版本作為反照率進行比較(第 4.2 節)。 | tools/stats.py 和該領域的區域檢查接近照片,並且 50% 混合顯示沒有色調斑塊。 |
| 5. 小零件 | 飾邊、固定件、電纜、標誌、排水溝、燈具、街道雜物。根據第 3 節的網格。 | 該區域清單中的每個項目都存在於裁切中。 |
| 6. 變化與磨損 | 倒角、顏色變化、窗台下的污漬、條紋、地面磨損、玻璃波紋和反射。 | 裁切通過了下面的 CG 感檢查,並且紋理能量檢查(第 4.3 節)接近照片。 |
每個階段都適用的規則:
- 真實世界的尺寸,圖案以毫米為單位。使用
cam.py測量;不要猜測。 - 沒有東西漂浮或互相穿透。東西站在地面上或固定在牆上。
- 在追蹤差異時,每次迭代只進行一個更改,以便比較顯示更改的效果。
CG 感檢查(每次渲染後:“還有什麼讓我看起來覺得這是 CG?”)
| CG 感 | 通常的修復方法 |
|---|---|
| 完美銳利的邊緣 | 倒角或斜角,建築部分 2 到 10 毫米 |
| 平坦的單色表面 | 測量的顏色變化、污漬、條紋、真實比例的紋理 |
| 可見的重複 | 每個實例在色調、旋轉、磨損上的變化 |
| 缺少接觸陰影 | 檢查物體是否接觸地面;檢查光線和降噪 |
| 玻璃後面或反射中沒有東西 | 內部平面或色調、真實反射、輕微波紋 |
| 錯誤的紋理比例 | 從照片以毫米為單位重新測量圖案 |
| 原始形狀的物體 | 替換為真實網格(第 3 節) |
| 太乾淨的地面 | 磨損、潮濕斑塊、落葉、接縫 |
在使用者批准保真度之後
只有這樣才能按順序執行以下操作:
- 真實感傳遞: 倒角、玻璃和地面磨損。電車運行將其作為一個模組(一個
weather模組)執行;Fischbrunnen 在每個領域內部執行。兩種方式都可以,但一個領域必須擁有每個表面。 - 渲染品質: 2160 像素超級採樣和準確降噪。
- 感測器效果(第 4.1 節)。
- 其他角度的校樣視圖(一個
proof.py渲染額外相機)。 - 照明氛圍。
- 影片(第 5 節)。
在每個這些檢查點發送一張照片與渲染的對比表,並等待使用者。
3. 網格:複雜物體不使用基本幾何體
規則:複雜物體絕不從簡單的基本幾何體構建。改用現有的真實網格。
什麼算
- 允許使用腳本生成的幾何體來處理建築和基礎設施:牆壁、樓板、屋頂、窗戶和門框、飛簷和型飾線條、路緣、鋪路、欄杆、桿子、電線、平面標誌。
- 需要有真實網格來處理所有有機或物體狀的東西:樹木、灌木、盆栽植物、人物、車輛、自行車、椅子、桌子、長凳、花盆、遮陽傘、具有造型燈體的路燈、雕刻裝飾品、雕像、有褶皺的布料。
- 測試:如果有人將你的構建描述為“棍子上的球體”、“帶四條腿的盒子”或“圓柱體”,那麼它就是基本幾何體的替代品,是不允許的,即使作為發送給使用者的渲染中的佔位符也不允許。
來源階梯(停在第一個合適的)
-
你自己的網格庫。 保留早期項目產生或下載的每個道具網格的索引(類別、大小、三角面數、路徑、許可證),並首先搜索它。重複使用勝過購買。
-
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 用於硬表面主角。通過三個步驟準備和適配網格:
- 清理裁切。 從照片中裁切物體(
gen/meshy_refs/<name>_crop.jpg)。在其上運行一個便宜的圖像編輯通道以移除遮擋物、完成被切斷的部分並提供一個簡單的背景,保存為<name>_clean.png。只有這樣才調用圖像到 3D。在噴泉運行中,這使得所有四個雕像和遮陽篷在第一次嘗試時就可使用。 - 減面一次,離線,放入
gen/<domain>_meshes.blend,使用與 Blender 的 Decimate 修改器相同的目標:對於主角物體約 50k 個三角面,對於較小物體約 10k 個三角面。保留 UV。 - 透過領域適配。 領域的
build函數調用assets.fit來縮放和定位:將物體的高度設為照片測量值,將其最低頂點放到地面上,並以約 0.5 米的公差將其放到照片像素位置。如果適合,設置旋轉以匹配照片。不要在fit之後捏造比例。
[...] 後續內容因原始提示截斷而省略。
- 清理裁切。 從照片中裁切物體(
(注意:由於原始 SKILL.md 內容被截斷,skillMarkdown 的翻譯內容也在此截斷。完整的翻譯應包含原始文件中省略的部分,直至第 11 節。)