最新拡散モデルDepthMasterのローカル環境導入ガイド

# はじめに

こんにちは、しゅんです！
まず一言、**RealSense RealSense RealSense RealSense RealSense RealSense RealSense RealSense** が欲しい！！！！！
冗談はさておき、今回はDepthMasterを使用して、深度推定を行う方法について紹介します。
自分は手順をまとめたのでぜひ見て試してください！いつも見てくれてありがとうございます。

[論文](https://arxiv.org/pdf/2501.02576)
[公式Github](https://github.com/indu1ge/DepthMaster/tree/main)
[公式huggingface](https://github.com/indu1ge/DepthMaster/tree/main)
[公式install手順Doc](https://github.com/indu1ge/DepthMaster/blob/main/docs/installation.md)

---
---
# 説明見たくない方は手順まで飛んでください

#### 目次

1. [DepthMasterとは](#depthmasterとは)
2. [手順](#手順)

---
---

# 以下は、GPTが論文を読んで書いてた説明

## DepthMasterとは？

**DepthMaster**は、単眼画像からの深度推定を目的とした最新の拡散（diffusion）モデルです。本モデルは、**拡散-ノイズ除去の枠組み**を活用し、高い汎化性能を実現しながら、従来の拡散ベースの手法と比較して**高速な推論**を可能にします。

従来の単眼深度推定手法では、テクスチャへの過度な依存や高精度な推定のために繰り返しの推論が必要でしたが、DepthMasterは新たに設計された「**単一ステップ拡散モデル**」を採用し、これらの課題を克服しています。

## DepthMasterの特徴

### 1. **単一ステップ拡散モデルの採用**
通常の拡散モデルは逐次的なノイズ除去プロセスを経るため、推論速度が遅くなる傾向があります。DepthMasterでは、**単一ステップの決定論的推論**を導入することで、**従来手法よりも高速**に深度マップを生成可能です。

### 2. **特徴整合（Feature Alignment）モジュール**
拡散モデル特有の**テクスチャ依存による過学習**を軽減するため、外部の高品質な視覚特徴を利用し、モデルの表現能力を向上させています。これにより、**意味的な特徴の整合性**を確保し、深度推定の精度を向上させています。

### 3. **フーリエ強化（Fourier Enhancement）モジュール**
単一ステップ推論では詳細な情報を捉えにくいため、周波数領域での情報バランスを取る「フーリエ強化モジュール」を採用。これにより、**低周波の構造情報**と**高周波のディテール**を適切に組み合わせ、よりリアルな深度マップを生成します。

### 4. **2段階のトレーニング戦略**
DepthMasterは、以下の2段階に分けて学習を進めます：

1. **第1段階**：特徴整合モジュールを利用し、グローバルなシーン構造を学習  
2. **第2段階**：フーリエ強化モジュールを適用し、詳細な視覚品質を向上

これにより、深度推定の一般化性能と詳細な構造の両方を兼ね備えたモデルを実現しています。

---

## DepthMasterの応用分野

DepthMasterの高い汎化性能と高速推論を活かして、以下の分野での活用が期待されています：

- **自動運転**：カメラベースの環境認識におけるリアルタイム深度推定  
- **仮想・拡張現実（VR/AR）**：深度情報を活用したリアルタイム3Dマッピング  
- **ロボティクス**：単眼カメラによる障害物検知やSLAM技術への応用  
- **画像合成・編集**：背景の分離やシーンのリアルな合成  

---

## DepthMasterの利点

| 項目                 | DepthMaster                  | 従来の拡散モデル              |
|---------------------|-----------------------------|-----------------------------|
| 推論速度             | 高速 (単一ステップ推論)        | 遅い (多段階ノイズ除去)       |
| 詳細表現の精度         | 高 (フーリエ強化モジュール)    | やや低 (多段階に依存)         |
| 過学習耐性             | 高 (特徴整合モジュール)        | 低 (テクスチャ依存)           |
| 学習戦略の最適化       | 2段階のアプローチ              | 単一トレーニングプロセス       |
| モデルの汎化性能       | 優秀                          | データセット依存度が高い       |

---

## DepthMasterの開発者・研究機関

DepthMasterは、**中国科学技術大学（USTC）**と**vivo Mobile Communication Co., Ltd.**の共同研究プロジェクトとして開発されました。本研究は、単眼深度推定分野における拡散モデルの適用可能性を広げることを目的とし、特に実用的な推論速度と高精度な推定を両立させることに重点を置いています。


## 手順

### 1. リポジトリのクローン
```bash
git clone https://github.com/indu1ge/DepthMaster.git
cd DepthMaster
```

**注意:** クローン直後には `in_the_wild_example/input` フォルダが存在しません。手動で作成する必要があります。

```bash
mkdir -p in_the_wild_example/input
```
そして、`input`フォルダ　に　画像を入れてください

---

### 2. インストール
仮想環境セットアップ
```bash
python3 -m venv .venv
source .venv/bin/activate 
```

**PyTorch のインストールは割愛します**

PyTorchのxformersをCUDA 11.8環境に合わせてインストール：
```bash
pip3 install -U xformers --index-url https://download.pytorch.org/whl/cu118
```
```bash
pip install opencv-python transformers matplotlib safetensors accelerate tensorboard datasets scipy einops pytorch_lightning omegaconf diffusers peft
```
```bash
pip3 install h5py scikit-image tqdm bitsandbytes wandb tabulate
```
---

### 3. チェックポイントのダウンロード

公式の手順通り、Hugging Faceから学習済みモデルをダウンロードします。

1. **DepthMasterのチェックポイントを取得：**  
   Hugging Faceのリンクから直接ダウンロード:

   **リンク:**  
   [DepthMaster Checkpoints](https://huggingface.co/zysong212/DepthMaster/tree/main)

   以下のコマンドを使用してダウンロード：
   ```bash
   git lfs install
   git clone https://huggingface.co/zysong212/DepthMaster ckpt
   ```

2. **Stable Diffusion v2のモデルダウンロード:**  
   公式のStable Diffusion v2のモデルをダウンロード：

   **リンク:**  
   [Stable Diffusion v2](https://huggingface.co/stabilityai/stable-diffusion-2/tree/main)

   以下のコマンドを使用して取得：
   ```bash
   cd ckpt
   git clone https://huggingface.co/stabilityai/stable-diffusion-2
   ```

---

### 4. 実行前の確認

`ckpt`ディレクトリが正しく作成され、次のような構成になっているか確認してください：

```
(.venv) syun@syun:/media/syun/ssd02/python_learning/depth_master/DepthMaster$ tree ckpt/
ckpt/
├── README.md
├── assets
│   └── framework.png
├── model_index.json
├── stable-diffusion-2
│   ├── 768-v-ema.ckpt
│   ├── 768-v-ema.safetensors
│   ├── LICENSE-MODEL
│   ├── README.md
│   ├── feature_extractor
│   │   └── preprocessor_config.json
│   ├── model-variants.jpg
│   ├── model_index.json
│   ├── scheduler
│   │   └── scheduler_config.json
│   ├── text_encoder
│   │   ├── config.json
│   │   ├── model.fp16.safetensors
│   │   ├── model.safetensors
│   │   ├── pytorch_model.bin
│   │   └── pytorch_model.fp16.bin
│   ├── tokenizer
│   │   ├── merges.txt
│   │   ├── special_tokens_map.json
│   │   ├── tokenizer_config.json
│   │   └── vocab.json
│   ├── unet
│   │   ├── config.json
│   │   ├── diffusion_pytorch_model.bin
│   │   ├── diffusion_pytorch_model.fp16.bin
│   │   ├── diffusion_pytorch_model.fp16.safetensors
│   │   └── diffusion_pytorch_model.safetensors
│   └── vae
│       ├── config.json
│       ├── diffusion_pytorch_model.bin
│       ├── diffusion_pytorch_model.fp16.bin
│       ├── diffusion_pytorch_model.fp16.safetensors
│       └── diffusion_pytorch_model.safetensors
├── text_encoder
│   ├── config.json
│   └── model.safetensors
├── tokenizer
│   ├── merges.txt
│   ├── special_tokens_map.json
│   ├── tokenizer_config.json
│   └── vocab.json
├── unet
│   ├── config.json
│   └── diffusion_pytorch_model.bin
└── vae
    ├── config.json
    └── diffusion_pytorch_model.safetensors

13 directories, 40 files
```

---

### 5. DepthMasterの推論実行

チェックポイントが正しく配置されたら、以下のコマンドで推論を実行します：

```bash
python run.py \
    --checkpoint ckpt \
    --input_rgb_dir in_the_wild_example/input \
    --output_dir in_the_wild_example/output/final \
    --processing_res 768
```

# 結果
`input`に置いてた画像

![back.jpg](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3506235/3d3d87d9-2eda-a0f8-eaf5-10ec1df431c6.jpeg)

`/output/final/depth_bw/back_pred.png` の予測結果の画像

![back_pred.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3506235/95d1b220-d0c1-f78c-dfe8-062eb190ab47.png)
`/output/final/depth_colored
/depth_colored.png` の予測結果の画像

![back_pred_colored.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3506235/9084e0db-1af4-9341-b39e-20a9cbb053f7.png)

```bash
(.venv) syun@syun:/media/syun/ssd02/python_learning/depth_master/DepthMaster$ python run.py     --checkpoint ckpt     --input_rgb_dir in_the_wild_example/input     --output_dir in_the_wild_example/output/final     --processing_res 768
INFO:root:output dir = in_the_wild_example/output/final
INFO:root:device = cuda
INFO:root:Found 1 images
The config attributes {'default_denoising_steps': 10, 'scheduler': ['diffusers', 'DDIMScheduler']} were passed to DepthMasterPipeline, but are not expected and will be ignored. Please verify your model_index.json configuration file.
Keyword arguments {'default_denoising_steps': 10, 'scheduler': ['diffusers', 'DDIMScheduler']} are not expected by DepthMasterPipeline and will be ignored.
Loading pipeline components...:  50%|████████████████████████████████████                                    | 2/4 [00:00<00:00, 11.60it/s]An error occurred while trying to fetch ckpt/unet: Error no file named diffusion_pytorch_model.safetensors found in directory ckpt/unet.
Defaulting to unsafe serialization. Pass `allow_pickle=False` to raise an error instead.
Some weights of the model checkpoint were not used when initializing UNet2DConditionModel: 
 ['fftblock.norm.weight, fftblock.norm.bias, fftblock.conv_f1.weight, fftblock.conv_f1.bias, fftblock.conv_f2.weight, fftblock.conv_f2.bias, fftblock.conv_f4.weight, fftblock.conv_f4.bias, fftblock.conv_f3.weight, fftblock.conv_f3.bias, fftblock.conv_s1.weight, fftblock.conv_s1.bias, fftblock.conv_s2.weight, fftblock.conv_s2.bias, fftblock.fuse.weight, fftblock.fuse.bias']
Loading pipeline components...: 100%|████████████████████████████████████████████████████████████████████████| 4/4 [00:01<00:00,  2.38it/s]
An error occurred while trying to fetch ckpt/unet: Error no file named diffusion_pytorch_model.safetensors found in directory ckpt/unet.
Defaulting to unsafe serialization. Pass `allow_pickle=False` to raise an error instead.
INFO:root:scale_invariant: True, shift_invariant: True
INFO:root:Inference settings: checkpoint = `ckpt`, processing resolution = 768, color_map = Spectral.
Estimating depth:   0%|                                                                                              | 0/1 [00:00<?, ?it/sWARNING:root:Existing file: 'in_the_wild_example/output/final/depth_bw/back_pred.png' will be overwritten                                   
WARNING:root:Existing file: 'in_the_wild_example/output/final/depth_colored/back_pred_colored.png' will be overwritten
Estimating depth: 100%|██████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:01<00:00,  1.73s/it]
(.venv) syun@syun:/media/syun/ssd02/python_learning/depth_master/DepthMaster$ 
```
---


# まとめ

最後まで見てくれてありがとうございます
次はWEBカメラで動けたらいいと思います。
でも1.7秒の予測は多分まだまだ低いFPSだと思います。どうなんだろう。調節してmsいったら嬉しいですね。
ありがとうございます