一張照片變成紅藍深度圖,桌面看起來近、牆壁看起來遠,但畫面裡的「兩公尺」該去哪裡找?這篇 Depth Pro 2 教學帶你從保存原始數值開始,做一份能重新檢查的照片與短片校核紀錄。
本文寫給第一次接觸深度估計的讀者。你不需要先懂神經網路;先學會區分距離、色階與時間變化,再決定要跑哪一條指令。前篇論文解讀介紹模型機制與研究成績,本篇聚焦自己的資料如何留檔、怎麼檢查,以及看到異常後先排哪個原因。
以下依 2026 年 11 月 21 日查閱的官方程式與文件整理。模型權重授權限非商業科學研究與學術開發,並排除商業利用、產品開發及商業產品或服務用途;下面首跑步驟適用於符合該範圍的研究工作。本文提供文件式操作與評估方法,未執行 Depth Pro 2 模型推論,也不提供自有素材的準確率或速度成績。
先說結論:數值看尺度,輪廓看邊界,連續影格看穩定
深度驗收=尺度校核+邊界檢查+時間一致性。可以把彩色深度圖想成天氣圖:顏色是圖例,原始數值才是溫度計的讀數。顏色漂亮,只完成了「方便看」這一關。
- 先拿一張自有照片與一段幾秒的固定鏡頭短片,選一個不反光、輪廓清楚的靜止物體。
- 保留原始影像與 NPZ 深度陣列;NPZ 是把數值陣列打包的檔案。
- 先對固定場景的公尺值與色階,再換模型或模式;每輪只改一項條件。
一、Depth Pro 2 教學先認三種輸出:公尺、逆深度、顏色

單目深度估計,就是模型從普通相機影像推估每個像素離相機的深度。官方定義中的 depth 是沿相機觀看方向的 Z 深度;偏到畫面邊緣的點,到鏡頭的斜線距離與這個值會不同。因此第一輪最好用畫面中央、面向鏡頭的平面作校核,先減少量測幾何的歧義。
逆深度像把尺倒過來讀:若是簡單的 1/深度,1 公尺對應 1,2 公尺對應 0.5,4 公尺對應 0.25。越近,數值差越顯眼。但程式介面的 inverse_depth 還含焦距與影像寬度的正規化;不要把這個欄位直接當成 1/公尺。研究距離時,先讀已換算好的 depth。
官方 CLI 的彩色 PNG/MP4 是觀看版本,--save-png16 保存的是縮放過的逆深度灰階,--save-npz 才保留 depth 與 focallength_px。後者是以像素為單位的焦距。這三種交付物用途不同:拿彩圖看邊界,拿 NPZ 查公尺;灰階合成素材則連同當次轉換尺度保存。
二、六步完成 Depth Pro 2 教學:從首跑到一份可對帳紀錄
第 1 步:「先確認適用範圍」準備小素材與環境
先完成上面的權重用途檢查,再準備自己有權處理的 photo.jpg 與 clip.mp4。短片先用固定相機、固定焦段與靜止場景,讓同一畫面位置對應同一物體。先不用人物臉部、私人室內資訊或別人的社群照片做練習;選一面牆與前方紙箱就能開始。
官方封裝要求 Python 3.11 以上。README給 Linux 與 Apple silicon Mac 的 uv 路徑;uv 是管理 Python 專案與相依套件的工具,安裝方式見官方安裝頁。這裡沿用其命令,不保證你目前電腦已具備相依環境。先確認剩餘空間,尤其逐幀 NPZ 會比一支壓縮影片大得多。
在終端機依序執行 git clone https://github.com/apple-aiml-research/ml-depth-pro-2.git、cd ml-depth-pro-2,再用 git rev-parse HEAD把提交識別碼抄進紀錄。本文核對的提交是 aa389cbb0b74341664ed663a0966c859905cd6c0;若你使用新版,先用下一步的 help 對照選項。把兩份素材放進此資料夾,保留不經通訊軟體轉存的照片原檔。
第 2 步:「只跑一張」明確指定模型並保留數值
先執行 uv run depth-pro-2 predict --help,確認看到 --save-npz。接著執行 uv run depth-pro-2 predict -i photo.jpg -o out-photo -m depthpro2-s --save-npz。這裡主動選 S,避免無意間走到預設 H+;首次執行會下載套件與模型。官方模型頁列出的 S 深度權重約 97 MB,另有共用焦距估計器,下載量不能只看一個權重檔。
成功後檢查 out-photo/photo-depth.png 與 out-photo/photo-depth.npz 是否同時存在。保存終端機顯示的裝置、精度與焦距來源。看到 MPS、CUDA 或 CPU,分別代表 Apple GPU、NVIDIA GPU 或處理器的運算路徑;它們不是模型品質評分。

第 3 步:「兩公尺在哪裡?」先選區域,再讀中位數
選畫面中央、離物體邊緣一段距離的平面小區域,稱為 ROI(你圈出來要檢查的範圍)。把該平面沿觀看方向的已知距離與量測方式寫下,保留原圖上的位置。不要把桌腳前緣、後方牆面與地板一起圈進去;不同深度混在一起,中位數也回答不了原本的問題。
下面範例讀左上角為原點的 x=300–339、y=200–239 區域;請先依你的原圖改座標。它會剔除非有限與非正值,再印出深度中位數:uv run python -c 'import numpy as np; d=np.load("out-photo/photo-depth.npz", allow_pickle=False)["depth"]; r=d[200:240,300:340]; v=r[np.isfinite(r) & (r>0)]; print("valid_pixels", v.size, "median_m", float(np.median(v)) if v.size else "EMPTY")'。若顯示 EMPTY,回頭查座標、影像尺寸與有效像素,先不計誤差。NumPy 的讀檔說明也交代了 NPZ 與 allow_pickle 的行為。
只做算術示範:已知平面 Z 深度為 2.00 公尺,假設區域中位數為 2.20 公尺,絕對誤差就是 |2.20−2.00|=0.20 公尺,相對誤差是 0.20/2.00=10%。這不是本模型的實測成績。換三個距離、每處留數個不重疊區域,比單挑一個看起來最準的像素更有診斷價值。
如果多個平面都按近似比例偏遠,先檢查焦距與裁切;若只有交界處失真,則回到邊界與遮擋。這是排查順序,不是憑誤差外觀就斷定原因。尤其不要用同一個已知物體調好尺度後,又把它當成獨立驗證資料。
第 4 步:「把影片當影片」保存一整段的逐幀數值
執行 uv run depth-pro-2 predict -i clip.mp4 -o out-video -m depthpro2-s --mode buffered --window 16 --overlap 4 --save-npz。官方 CLI會寫出 out-video/clip-depth.mp4,並在 out-video/clip-depth/ 產生 000000.npz 起的逐幀陣列。資料夾裡的獨立照片與影片輸入採不同處理路徑;想觀察跨幀資訊的效果,就保留影片入口。
buffered 像先讀一小段文章再回答,視窗是一次參考的影格數,overlap 是相鄰片段共用的影格。第一輪把這些值寫死;資源不足時,可先成對縮短為 --window 8 --overlap 2 再重跑到新資料夾,保留原紀錄。這裡的 8/2 是有效選項組合與排查建議,不是經本文驗證的最佳品質配置。
第 5 步:「閃的是數值還是圖例?」固定色階與取樣位置
先看原始畫面:相機移動、物體移動或被遮擋,同一像素的真實深度本來就可能變化。第一輪採固定鏡頭與靜物,才適合沿用同一 ROI 看中位數隨影格怎麼變。遇到手持鏡頭,應追蹤同一實體表面並處理遮擋,不能把畫面固定座標的跳動直接稱為模型抖動。
官方 CLI 的影片色階在第一幀建立並延用,這點已在影片輸出程式核對;因此不要先假設它每幀自動調色。問題常出在你另外把各幀 NPZ 交給繪圖軟體,各張自動挑一套最小值、最大值,或者把兩次不同首幀的執行直接並排比顏色。
自行畫圖時,選定共同的公尺範圍,例如只觀察室內 0–5 公尺,就對所有幀使用同一組 vmin=0, vmax=5 與同一色盤。Matplotlib imshow提供這兩個顯示範圍參數。這個 5 公尺只是本練習選的圖例上限;超出範圍的點會壓到色階端點,仍要回 NPZ 查原值。
要一次匯出所有幀的共同色階圖,可執行 uv run python -c 'import numpy as np, matplotlib.pyplot as plt; from pathlib import Path; p=Path("out-video/clip-depth"); o=Path("fixed-scale"); o.mkdir(exist_ok=True); [plt.imsave(o/(f.stem+".png"), np.load(f,allow_pickle=False)["depth"], cmap="viridis", vmin=0, vmax=5) for f in sorted(p.glob("*.npz"))]'。打開 fixed-scale,依序比對同一物體;此處使用 viridis 色盤,與官方預覽的配色不同,所有幀都固定以 0–5 公尺映射。先確認資料夾內的檔案數與 NPZ 數一致,再讀顏色。
逐幀抄下「影格編號、ROI 有效像素數、深度中位數、焦距」,用同一座標範圍畫折線。再逐格看物體邊緣是否漏進背景,特別留意遮擋發生與片段接縫附近。穩定但整段偏遠,屬於尺度問題;平均接近卻忽近忽遠,屬於另一種時間變化。平線本身也不能證明深度正確。
第 6 步:「只改一個旋鈕」保留品質與成本的成對紀錄
先完成一套基準,再比較另一個模型或改成 --mode unbuffered。後者參考當前與過去影格,適合研究即時輸入的等待取捨。比較時沿用原素材、ROI 與共同色階,另開輸出資料夾,避免把新結果覆蓋舊結果。第一輪只問「這次改動,改善了哪個錯誤,又犧牲什麼?」
每輪用文字紀錄這些欄位:素材檔名/雜湊、提交碼、模型、裝置、精度、寬×高、幀率、mode、window、overlap、焦距來源、ROI、已知 Z、各幀中位數、總耗時、記憶體觀測方式。沒有量到的欄位寫「未量測」。下載與首次初始化另記,重跑時間另記;完整命令耗時包含解碼與存檔,應和純模型推論時間分開命名。
三、三個常見誤判:邊界、焦距與資源
把深度交界當成同一個平面。細線、毛髮、透明物與反光區域可以列為壓力素材,但先用平坦、不透明區域建立尺度基準。檢查邊緣時看原圖與深度圖的同一位置;把平滑背景和細線輪廓分開驗,避免用一個整體平均掩蓋錯誤。
把照片原檔與裁切轉存版混為一談。焦距資料與影像幾何會影響公尺換算。若用 Python 提供像素焦距,縮放影像時也要按同一比例縮放它;影片使用共同焦距,變焦素材應另開測試。先把「保持原檔」做到,再研究改尺寸後的差別。
把權重檔大小當成完整運算需求。影格解析度、視窗與運算精度都會影響資源。這份流程不把某個下載量換算成保證可跑的記憶體門檻;遇到錯誤先保留訊息、縮小工作量,再做可對照的一次改動。論文的高速硬體結果也不能直接當成你的筆電耗時。
四、常見問題:八個先講答案的判斷
1. 深度圖顏色一樣,距離就一樣嗎?
不一定。先確認是不是同一個數值定義、同一色盤與同一範圍;跨影片、跨執行時尤其要對圖例。
2. 16-bit 灰階的 1000,就是 1000 公尺嗎?
不是。這裡的 PNG16 保存縮放過的逆深度,必須連著轉換尺度解讀;公尺校核優先讀 NPZ 的 depth。
3. 手機斜著量出的距離可以直接比嗎?
先對幾何。模型輸出是觀看方向的 Z;第一輪選中央、正對相機的平面,並記錄量測起點與方式。
4. 影片不閃,就代表量準了嗎?
不能這樣推論。穩定與準確是分開的指標;一段始終多估距離的輸出也可能很穩。
5. 空資料夾或 EMPTY 可以填成零公尺嗎?
不要。先查是否成功解碼、是否有 NPZ、ROI 是否在範圍內及有效像素數;零不能代替缺失紀錄。
6. 可以直接拿來做付費剪輯服務嗎?
目前這份公開權重授權排除商業產品或服務用途。符合非商業科學研究範圍的操作,與商業導入是不同的用途判定。
7. 這篇給的是 AlphaLab 的模型實測嗎?
不是。這裡提供經官方文件與原始碼核對的首跑與校核方法;算術例子不代表模型輸出。
8. 完全沒有技術背景,今天先做什麼?
先準備一張自己拍的中央平面照片,寫下已知距離與量法,再學會分辨彩圖和原始公尺值;符合環境與用途條件後才進到指令。
給新手的三個重點
- 每份彩圖都連著原始 NPZ 保存,先確認你正在讀哪一種尺。
- 先用固定相機與靜止場景建立可解釋的基準,再增加移動與遮擋。
- 一次改一項設定;保留失敗案例、缺失欄位與完整配置,才知道改善來自哪裡。
接著閱讀
左右滑動查看更多推薦
下一步:讓第一個數字有一份可回看的依據
拿出一張原圖,標好 ROI、已知 Z 深度與量測方式,再把輸出中位數與當次設定放在一起。回到那個錨點:數值看尺度,輪廓看邊界,連續影格看穩定。先完成這份小紀錄,再決定哪個模型值得繼續研究。想系統整理 AI 工具與評估方法,可接著探索AI 主題專區與AlphaLab 課程。






