照片深度:讓圖片像一個真實空間
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 會將透明像素下的顏色歸零並造成顏色擴散。 - 下載任何內容前都必須詢問(套件、權重),並說明下載內容、來源與大小。