Community影像github.com

照片場景重建

透過多代理協作框架,將參考照片重建為 Blender 場景,使其從相同相機視角觀看時如同一張照片。使用渲染比較循環、固定保真度順序、從照片測量光源與材質、真實網格來源規則,以及針對有機建築的程式碼生成技術排名清單。

照片場景重建 是什麼?

照片場景重建是一個專為 AI 代理設計的專業技能,用於從單張參考照片重建高保真度的 Blender 三維場景。此技能的核心在於使用多代理協作框架,將場景拆分為多個領域(如光線、街道、建築物等),每個領域由一個獨立代理負責。代理之間通過共享的佈局檔案(layout JSON)和上下文(ctx)進行協作,並遵循嚴格的「相同相機」原則:首先透過消失點求解器鎖定相機參數(焦距、俯仰角、偏航角),然後所有代理都基於此固定相機進行工作。 為了確保重建的保真度,此技能定義了一個嚴格的六階段工作順序(讀取、輪廓、比例、顏色、小零件、變化與磨損),每個階段都有明確的通過標準,必須依次完成,不得跳過。代理之間透過「渲染比較循環」進行迭代:每次變更後,工具 `iterate.sh` 會自動渲染場景並生成與照片的疊加比較圖(包括混合圖和邊緣對齊圖),代理必須查看這些圖像來驗證改進。 此技能明確禁止使用基本幾何體(如球體、立方體)來替代複雜物體(如樹木、人物、雕像),而是要求從真實網格庫(如 Poly Haven)或生成式模型(如 Meshy、Tripo)中獲取真實網格。對於建築物和基礎設施,則允許使用腳本生成的幾何體(如牆壁、窗戶、路面)。最後,在用戶批准保真度後,才會添加真實感細節(倒角、玻璃、地面磨損)、感測器效果和燈光氛圍。 支援的平台包括 Blender 5.1(Cycles 渲染器)、Python(搭配 numpy、opencv、pillow)以及可啟動子代理的代理運行環境。此技能特別適合用於重建街景、建築物、廣場等複雜場景,或提升現有生成場景的真實感。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/liangjunglj-cpu/ginkgo-skills/tree/main/skills/photo-scene-reconstruction

Installed? Explore more 影像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

照片場景重建 是做什麼的?

此方法於 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. 主要代理在任何代理啟動前進行設定

主要代理(主會話)獨自完成這些步驟。代理僅在所有設定完成後才啟動。

  1. 運行資料夾。 <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)。

  2. 求解相機:使用 tools/vp.py。找到垂直消失點和沿主立面的一個水平消失點。然後 tools/solve_cam.py 會取得:

    • 焦距,基於兩個方向互相垂直(不要假定鏡頭);
    • 俯仰角,來自垂直消失點;
    • 偏航角,選擇使立面沿世界 +X 方向。

    將結果寫入 layout/camera.json。相機在整個運行期間保持固定。

  3. 測量錨點:使用 tools/cam.py:

    • on_z 碰觸水平面,on_y 碰觸垂直面,project 給出像素點,而 ray 給出視線。
    • 測量地面線、立面平面以及每個地標的距離。
    • 將主要代理的初始估計值寫入規則手冊作為起始值。
    • 在掠射角度,地面線的一個像素可能對應半米的深度。優先使用已知物體的高度和寬度(門 2.1 米、眼睛 1.6 米、路緣 0.12 米),而不是單一的地面點。
  4. 物體清單:列出照片中可見的每個物體,並將其標記為 腳本生成 或 網格(第 3 節)。此清單決定領域劃分和資產獲取。

  5. 撰寫 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 節)
太乾淨的地面磨損、潮濕斑塊、落葉、接縫

在使用者批准保真度之後

只有這樣才能按順序執行以下操作:

  1. 真實感傳遞: 倒角、玻璃和地面磨損。電車運行將其作為一個模組(一個 weather 模組)執行;Fischbrunnen 在每個領域內部執行。兩種方式都可以,但一個領域必須擁有每個表面。
  2. 渲染品質: 2160 像素超級採樣和準確降噪。
  3. 感測器效果(第 4.1 節)。
  4. 其他角度的校樣視圖(一個 proof.py 渲染額外相機)。
  5. 照明氛圍。
  6. 影片(第 5 節)。

在每個這些檢查點發送一張照片與渲染的對比表,並等待使用者。

3. 網格:複雜物體不使用基本幾何體

規則:複雜物體絕不從簡單的基本幾何體構建。改用現有的真實網格。

什麼算

  • 允許使用腳本生成的幾何體來處理建築和基礎設施:牆壁、樓板、屋頂、窗戶和門框、飛簷和型飾線條、路緣、鋪路、欄杆、桿子、電線、平面標誌。
  • 需要有真實網格來處理所有有機或物體狀的東西:樹木、灌木、盆栽植物、人物、車輛、自行車、椅子、桌子、長凳、花盆、遮陽傘、具有造型燈體的路燈、雕刻裝飾品、雕像、有褶皺的布料。
  • 測試:如果有人將你的構建描述為“棍子上的球體”、“帶四條腿的盒子”或“圓柱體”,那麼它就是基本幾何體的替代品,是不允許的,即使作為發送給使用者的渲染中的佔位符也不允許。

來源階梯(停在第一個合適的)

  1. 你自己的網格庫。 保留早期項目產生或下載的每個道具網格的索引(類別、大小、三角面數、路徑、許可證),並首先搜索它。重複使用勝過購買。

  2. Poly Haven CC0,免費:tools/fetch_ph_model.py <id>(glTF 2k 到 gen/ph/<id>/),使用 tools/fetch_polyhaven.py <id> 獲取紋理和天空。每個代理的下載量保持在約 150 MB 以下。

  3. 生成的網格,付費,僅通過主要代理並且僅在使用者看到成本之後: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 節。)

相關技能