Community影像github.com

照片深度

讓單張照片、畫作或 AI 生成圖片在網頁上擁有真實深度。使用 MoGe-2(MIT 授權)估算深度圖,然後讓圖片像 three.js 場景中的窗戶一樣表現(相機移動時產生視差且邊緣無撕裂),或找出圖片中物體的位置以放置 3D 物件。

照片深度 是什麼?

這個技能能將任何二維圖片(照片、畫作或 AI 生成圖)轉變為具有深度感的 2.5D 互動體驗。它使用 MoGe-2 模型(MIT 授權)從單張圖片估計深度圖,然後提供兩種主要應用:一是將圖片變成 three.js 場景中的「窗戶」,利用視差效果讓圖片隨著相機移動產生立體感,邊緣不會撕裂;二是能精確定位圖片中的平面(如牆壁、地面)或特定像素的 3D 座標,讓開發者可以將 3D 物件無縫嵌入圖片場景中。技能內含完整的 Python 腳本和 three.js 示範程式碼,支援 WebP 輸出、16 位元距離圖以及相機參數導出。所有下載(PyTorch、模型權重等)都需要使用者明確同意,且授權條款明確可商用。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/skyeyesec333/photo-depth/tree/main/skills/photo-depth

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

在你喜歡的 AI 中提問

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

說明文件

照片深度:讓圖片像一個真實空間

0. 設定     建立含有 MoGe-2 的 Python 環境(僅一次,下載前會詢問)           scripts/setup.sh
1. 深度     圖片 ➔ 接近度圖(+ 16 位元距離、相機參數、原始 npz)          scripts/depth.py
2a. 窗戶    讓圖片在 three.js 中像窗戶一樣表現                              examples/portal.js
2b. 放置    在圖片自身的 3D 空間中找出平面與點位                            scripts/fit_plane.py
3. 檢查     從你會實際使用的極端視角來檢視效果

scripts/ 和 examples/ 指的是這個技能自身目錄中的資料夾(${CLAUDE_SKILL_DIR},無論是外掛還是複製的技能皆同),而非使用者的專案目錄。請將 S 設為該 scripts/ 資料夾的路徑,並使用完整路徑執行 "$S/depth.py" 及其他腳本。

0. 設定(僅需一次)

首先檢查:如果已有可用的環境(import moge 可正常執行)則可直接重複使用(詢問使用者該環境的位置)。否則在下載前詢問使用者,並說明會下載哪些內容:來自 PyPI 的 PyTorch 及其相關套件(安裝後約 1 GB)、來自 GitHub 的 MoGe 原始碼及兩個小型函式庫(固定提交版本,數 MB),以及後續的模型權重(約 1.3 GB,來自 Hugging Face 上的 Ruicheng/moge-2-vitl)。然後執行:

"$S/setup.sh" <環境目錄> --yes

詳細資訊、GPU 注意事項及其他模型:references/setup.md

1. 深度

<環境>/.venv/bin/python "$S/depth.py" picture.jpg --out public/depth/ [--dist16] [--npz]
  • 一定會輸出 <主檔名>-near.webp:接近度(視差),0 代表天空,1 代表最近的物體,邊緣向外擴張 2 像素以確保物體邊緣能隨之移動。一張 1-2K 的圖片約 10-25 KB。
  • --dist16:輸出 <主檔名>-dist16.webp(以 16 位元儲存的對數距離,R 為高位 G 為低位,無失真)和 <主檔名>-camera.json(估計的相機內參)。用於將圖片重建為曲面。
  • --npz:輸出原始公制深度,供 fit_plane.py 使用。
  • 除非加上 --allow-download,否則腳本會拒絕下載權重:請先詢問使用者。
  • 腳本會輸出有效區域比例、深度百分位數以及估計的視野角度。請注意這些數值:「valid 20%」或視野角度 150° 表示模型無法理解這張圖片。

每當圖片有變更時就必須重新執行:使用舊版圖片產生的深度圖會導致每個邊緣錯位。

2a. 窗戶效果

examples/portal.js 是一個自成一體的 three.js 材質(請將其複製到專案中)。圖片是從休息點(你的預設相機位置)看到的場景。從其他任何位置觀看時,「玻璃」上的每個像素會顯示沿著視線方向看到的內容,這是透過 16 個步驟遍歷接近度圖來達成的,因此近的物體會遮蔽遠的物體,且邊緣不會撕裂。詳細資訊、調整方法及失敗模式請參閱:references/portal.md

import { makePortal } from "./portal.js";
const portal = makePortal({ map, near, width: 4, height: 2.5 });
scene.add(portal.mesh); portal.setRest(defaultCameraPosition);
// 每一影格:portal.update(camera);

examples/portal.html 是一個單檔示範:將圖片、其接近度圖、portal.js 和頁面放在同一個資料夾中,打開 portal.html?pic=<檔案>&near=<檔案> 然後移動滑鼠指標。

以實際觀看方式檢查: 將相機放在網站真正會使用的最左、最右、最高、最低位置(若要自動檢查,示範頁面支援 window.__view = [x, y]),然後檢查每一項:

  • 完全看不出深度?第一個版本在真實網站上的效果太弱,以至於難以察覺:請降低 uQ.y(0.6 → 0.4)。
  • 近物相對於邊框移動最多,或天空在晃動?深度是反向的(距離被當作接近度)。
  • 大幅移動時出現模糊或重影:單張圖片在近物後面沒有資訊。請保持相機移動幅度小,或使用緩動效果(uEase),或繪製背景層(references/placing.md)。

2b. 在圖片中放置物件

<環境>/.venv/bin/python "$S/fit_plane.py" plane out/city-depth.npz --box 410,120,520,260
<環境>/.venv/bin/python "$S/fit_plane.py" plane out/city-depth.npz --box 410,120,520,260 --corners 415,128 515,124 516,250 414,255
<環境>/.venv/bin/python "$S/fit_plane.py" point out/city-depth.npz 640,700

像素座標為圖片本身的座標(加上 --norm 可使用 0..1 範圍)。輸出為 three.js 相機空間的 JSON(相機在原點,朝 -Z 方向看,單位為公尺)。flatness_rms_m 表示該區域的平坦程度:在 40 公尺外的一面牆上,數公分的 RMS 誤差即代表平坦。請在面板邊緣內部選取角落(而不是選取包圍面板的矩形範圍),這樣廣告看板才能貼合面板的真實形狀,而不會看起來歪斜。將整個圖片重建為 3D 曲面、撕裂的邊緣、背景層等相關資訊:references/placing.md

規則

  • 授權條款: MoGe-2 的程式碼與權重均為 MIT 授權。有幾種常見的深度模型未獲商用許可(請見 references/setup.md):在為客戶或販售作品的專案切換模型前請先確認。
  • 圖片本身的授權仍適用於其衍生作品。
  • Alpha 頻道遮罩: 如果圖片在 Alpha 頻道中含有遮罩(例如水、天空),請以無失真方式儲存 WebP 並保留精確 RGB(cwebp -lossless -exact,Pillow 的 exact=True)。有損壓縮的 Alpha 會將透明像素下的顏色歸零並造成顏色擴散。
  • 下載任何內容前都必須詢問(套件、權重),並說明下載內容、來源與大小。

相關技能