# Nerfstudio 本地訓練指南 (Windows + RTX 3080 版)

這份文件記錄了在 Windows 環境下，使用 RTX 3080 進行 Gaussian Splatting (Splatfacto 模型) 訓練的完整流程。

## 📋 1. 環境前置準備 (Prerequisites)

在開始安裝 Python 套件前，必須先確保底層編譯環境與 CUDA 驅動正確。

### A. 安裝 C++ 編譯器

Nerfstudio 依賴 `tiny-cuda-nn`，安裝時需要即時編譯。

1. 下載 **Visual Studio 2022 Community** (免費版)。
2. 安裝時，在「工作負載 (Workloads)」頁籤中，**務必勾選**：
* `[v] 使用 C++ 的桌面開發 (Desktop development with C++)`

3. *注意：如果不裝這個，pip install 時會噴出一大堆紅色錯誤。*

### B. 安裝 CUDA Toolkit

建議使用 **CUDA 11.8** (目前 PyTorch 支援最穩定的版本)。

1. 前往 [NVIDIA CUDA Toolkit Archive](https://developer.nvidia.com/cuda-11-8-0-download-archive) 下載。
2. 安裝完成後，開啟 CMD 輸入以下指令確認：

nvcc --version

*(應顯示 V11.8.x)*

### C. 準備外部工具 (COLMAP & FFmpeg)

這兩個工具負責「影片轉圖片」與「相機位姿解算」。

1. **COLMAP (CUDA版):**
* 下載：[COLMAP GitHub](https://github.com/colmap/colmap/releases) (找 Windows-CUDA-No-Install.zip)
* 解壓至例如 `C:\Tools\colmap`

2. **FFmpeg:**
* 下載：[FFmpeg Build](https://www.gyan.dev/ffmpeg/builds/) (release-essentials.zip 即可)
* 解壓至例如 `C:\Tools\ffmpeg`

3. **設定環境變數 (關鍵步驟):**
* 將包含 `.exe` 的資料夾路徑 (例如 `C:\Tools\colmap` 和 `C:\Tools\ffmpeg\bin`) 加入 Windows 的 **系統環境變數 Path** 中。
* *設定完後請重啟 Terminal 才會生效。*

---

## 🛠️ 2. 安裝 Nerfstudio (Installation)

請開啟 Anaconda Prompt 或支援 Conda 的終端機。

### 步驟 1: 建立虛擬環境

使用 Python 3.10 以獲得最佳相容性。

conda create --name nerfstudio -y python=3.10
conda activate nerfstudio

### 步驟 2: 安裝 PyTorch (CUDA 11.8 版本)

精確指定版本以免裝到 CPU 版或不相容的 CUDA 版。

pip install torch==2.1.2+cu118 torchvision==0.16.2+cu118 --extra-index-url https://download.pytorch.org/whl/cu118

### 步驟 3: 安裝 Nerfstudio 核心

這一步會自動編譯 `tiny-cuda-nn`，依據 CPU 效能可能需要 5-10 分鐘。

pip install nerfstudio

---

## 🎬 3. 標準作業流程 (Pipeline)

假設您的專案資料夾在 `D:\GS_Project`，影片檔名為 `source.mp4`。

### Phase 1: 資料前處理 (Process Data)

將影片轉換為 Nerfstudio 可讀取的訓練資料。此步驟會自動執行：

1. FFmpeg 拆解影格。
2. COLMAP 特徵匹配與相機解算 (SfM)。

# 基本指令
ns-process-data video --data source.mp4 --output-dir processed_data

### Phase 2: 開始訓練 (Train)

使用 Gaussian Splatting 模型 (`splatfacto`)。

ns-train splatfacto --data processed_data

# [針對 RTX 3080 的優化指令]
# 如果影片是 4K，建議降採樣以防顯存爆炸 (OOM)
ns-train splatfacto --data processed_data --downscale-factor 2

* **Viewer:** 訓練開始後，Terminal 會顯示 `Viewer at: https://viewer.nerf.studio/...`。
* **操作:** 按住 `Ctrl` 點擊連結，即可在瀏覽器即時監看訓練成果。
* **時間:** RTX 3080 訓練標準場景約需 15-30 分鐘。

### Phase 3: 匯出模型 (Export)

訓練完成後 (或按 `Ctrl+C` 中止後)，將模型匯出為通用的 `.ply` 格式。

1. **尋找 Config 檔:** 在 `outputs/processed_data/splatfacto/YYYY-MM-DD.../` 資料夾中找到 `config.yml`。
2. **執行匯出:**

# 語法: ns-export gaussian-splat --load-config [Config路徑] --output-dir [輸出路徑]

ns-export gaussian-splat --load-config outputs/processed_data/splatfacto/2026-01-08_12-00-00/config.yml --output-dir exports/

* 結果會在 `exports/splat.ply`，可直接拖入 [Spline](https://spline.design/) 或 [Polycam](https://poly.cam/) 等網頁觀看。

---

## ⚠️ 4. 常見問題與 RTX 3080 優化 (Troubleshooting)

### Q1: 訓練時出現 CUDA Out of Memory (OOM)

* **原因:** 4K 圖片解析度太高，塞滿 3080 的 10GB/12GB 顯存。
* **解法:**
1. 在訓練時使用 `--downscale-factor 2` (推薦)。
2. 或者在訓練時減少 Batch Size (不推薦，會影響品質)。

### Q2: COLMAP 跑很久或失敗

* **檢查:** 拍攝時是否只有純旋轉 (原地轉圈)？這會導致 COLMAP 算不出深度。必須要有位移 (Parallax)。
* **設定:** 確認使用的是 GPU 版 COLMAP。如果不確定，請在 `ns-process-data` 指令後加上 `--verbose` 查看 Log。

### Q3: 匯出的 .ply 檔案極大

* **說明:** 原始的 Splat 模型通常有 300MB - 1GB。
* **解法:** 若要網頁展示，可考慮使用 `ns-export gaussian-splat --format splat` (較新的壓縮格式)，或是使用 [SuperSplat](https://playcanvas.com/supersplat/editor) 進行手動修剪 (Crop) 後再儲存。

### Q4: COLMAP 報錯 `unrecognised option '--SiftExtraction.use_gpu'` 🌟 (新版 COLMAP 必看)

* **現象:** 在執行 `ns-process-data` 時，出現紅字錯誤，指出無法識別 SiftExtraction 參數。
* **原因:** 您安裝的 COLMAP 版本較新 (3.9 或以上)，參數名稱已更改 (`Sift` -> `Feature`)，但 Nerfstudio 舊版代碼仍送出舊參數。
* **解法 (修改原始碼):**
1. 前往您的 Nerfstudio 安裝路徑 (或是您 clone 下來的資料夾)。
2. 找到並編輯檔案：`nerfstudio\process_data\colmap_utils.py`。
3. 搜尋並修改參數名稱 (大約在第 129 行與 143 行)：
* 將 `"SiftExtraction.use_gpu"` 改為 **`"FeatureExtraction.use_gpu"`**
* 將 `"SiftMatching.use_gpu"` 改為 **`"FeatureMatching.use_gpu"`**

4. 存檔後重新執行指令即可正常運作。

## 🔗 常用指令速查表

| 動作 | 指令關鍵字 |
| --- | --- |
| **處理影片** | `ns-process-data video --data [影片] --output-dir [資料夾]` |
| **處理照片集** | `ns-process-data images --data [圖片資料夾] --output-dir [資料夾]` |
| **開始訓練** | `ns-train splatfacto --data [資料夾]` |
| **繼續訓練** | `ns-train splatfacto --load-dir [Checkpoint資料夾]` |
| **匯出 PLY** | `ns-export gaussian-splat --load-config [Config檔]` |
| **開啟 Viewer** | `ns-viewer --load-config [Config檔]` (不訓練純觀看) |