fabiotosi92/ZipDepth

📦 什麼是 ZipDepth？

ZipDepth 是在 ECCV 2026 上發表的輕量級、零樣本單目深度估計模型。它能在不進行任何任務特定微調的情況下，從單張 RGB 圖像預測密集深度圖。其核心優勢在於 精度-效率的權衡：在模型大小僅約 6 M 參數的同時，達到與大型 Transformer 基礎模型相當的性能，並在現代 GPU 上實現 >1 k FPS 的運行速度（在移動/邊緣硬體上亦表現良好）。

---

🔑 核心概念

組件	功能
編碼器	由 RepVGG 可重參數化卷積構成的四階段層次結構。早期階段使用 條帶池化注意力 取得水平/垂直上下文；後期階段加入 壓縮-及-激發 與 全域上下文區塊。
頸部	多尺度池化（SPPF）與 跨尺度融合 模組，於解碼前融合特徵。
解碼器	緊湊的特徵金字塔網路（FPN），搭配 凸上採樣 頭部，產出亞像素級精度的深度圖。
兩個檢查點	zipdepth_base.pth（GPU 友好，使用 torch.nn.Unfold）與 zipdepth_base_npu.pth（無 Unfold，更易轉換為 ONNX/CoreML/TFLite 用於移動/NPU）。

---

🚀 快速上手

# 克隆並安裝
git clone https://github.com/fabiotosi92/ZipDepth
cd ZipDepth
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt   # 需要 PyTorch ≥2.4
pip install -e .

推理（單張影像、資料夾或影片）

python scripts/infer.py \
  --checkpoint checkpoints/zipdepth_base.pth \
  --input assets/examples/im0.jpg \
  --input-size 384          # 短邊，四捨五入為 32 的倍數

可選參數：--fp16（半精度）、--compile（torch.compile）、--npu（使用 NPU 相容檢查點）、--no-colormap / --save-raw 用於輸出原始 .npy 深度資料。

導出模型

• ONNX（推薦用於移動/邊緣設備）：

  python scripts/export.py \
    --ckpt checkpoints/zipdepth_base_npu.pth \
    --format onnx --height 384 --width 384 --npu
  

• TorchScript（追蹤或凍結）用於純 PyTorch 部署。

---

📊 性能概覽

資料集	參數量	GFLOPs（384×384）	典型延遲（RTX 3090）
NYUv2, KITTI, ETH3D, ScanNet, DIODE	~6.1 M	~0.9 G	0.8 ms（TensorRT FP16）→ ≈1300 FPS

論文中的帕累托圖顯示，ZipDepth 在輕量級模型區域佔據主導地位，同時與最佳大型模型性能僅差幾個百分點。

---

🛠️ 訓練（研究導向）

• 資料：透過從 Depth Anything V2 Large 知識蒸餾，在 17 個公開影像領域（如 COCO、Cityscapes、MegaDepth 等）生成的 1400 萬對 RGB-深度影像。檔案路徑清單以 training_files.txt.gz 提供；實際影像需從原始資料集取得。
• 流程：scripts/prepare_index.py 建立 JSON 索引 → 可選轉換為 NumPy 記憶體映射以實現快速 I/O。
• 啟動（單一 GPU 範例）：

  python scripts/train.py --config configs/default.json
  

  多 GPU 透過 torchrun 與標準 DDP 實現。
• 損失函數：尺度與平移不變深度損失 + 梯度正則化，使用 AdamW 與 One-Cycle 學習率調度進行最佳化。

---

📱 在裝置上部署

1. 選擇 NPU 友好檢查點（zipdepth_base_npu.pth）。
2. 導出為 ONNX（scripts/export.py --format onnx --npu）。
3. 將 ONNX 模型轉換為目標執行時（ONNX Runtime Mobile、CoreML、TFLite、NCNN 等）。
4. 上採樣頭部僅使用移動 NPU 廣泛支援的操作，確保轉換過程乾淨無誤。

---

🙏 致謝與引用

作者感謝 Marigold（提供評估協定）與 Depth Anything V2（提供偽標籤）的創作者。若在研究中使用 ZipDepth，請引用：

@inproceedings{tosi2026zipdepth,
  title     = {ZipDepth: Bringing Lightweight Zero-Shot Monocular Depth Anywhere, on Any Device},
  author    = {Tosi, Fabio and Bartolomei, Luca and Poggi, Matteo and Mattoccia, Stefano},
  booktitle = {European Conference on Computer Vision (ECCV)},
  year      = {2026}
}

---

📧 聯絡方式

如有疑問，請透過 README 中列出的電子郵件聯絡作者。