CardiacSeg-HW5: 3D Cardiac Image Segmentation

本專案為 HW5 心臟影像分割作業 的實作儲存庫。我們基於 nnU-Net v2 框架，針對心臟 MRI 影像（左心室、右心室、心肌）開發了一套自動化分割流程。

🏆 最佳成績 (V8): Dice Score 0.7905 🚀 核心策略: 2D + 3D Lowres Ensemble + Soft Voting + Morphological Post-processing

---

📋 目錄

• 快速開始 (Quick Start)
• HW5 專案報告 (Project Report)
• 使用說明 (Usage Guide)
• 專案結構 (Project Structure)
• 常見問題 (FAQ)

---

🚀 快速開始 {#quick-start}

1. 環境安裝

本專案提供一鍵安裝腳本，自動配置 Python 虛擬環境、PyTorch (CUDA/MPS) 及 nnU-Net。

Windows (PowerShell)

# 1. 允許執行腳本
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 2. 執行安裝
.\setup_environment.ps1

# 3. 啟用環境
.\.venv\Scripts\Activate.ps1

macOS / Linux

# 1. 執行安裝
chmod +x setup_environment.sh
./setup_environment.sh

# 2. 啟用環境
source .venv/bin/activate

2. 執行流程

安裝完成後，請依序執行以下指令：

# 1. 資料集標準化 (自動下載或整理格式)
python rename_dataset.py

# 2. 開始訓練 (預設使用 3D Lowres 配置)
python nnunet_train.py --config 3d_lowres --fold 0

# 3. 推論測試集
python nnunet_infer.py

# 4. 評估結果 (需有 Ground Truth)
python nnunet_evaluate.py

---

📝 HW5 專案報告 (Project Report)

0. 團隊成員 (Team Member)

• [學校] [學號] [姓名]
• (請自行填寫)

1. 摘要 (Abstract)

本研究旨在解決心臟 MRI 影像的自動化分割問題，目標是精確分割左心室 (LV)、右心室 (RV) 及心肌 (Myocardium)。我們採用了基於 nnU-Net 框架的集成學習策略。初期實驗顯示單一模型難以同時兼顧所有結構的分割精度，特別是右心室的複雜形狀。因此，我們提出了一種結合 2D nnU-Net 與 3D Low-resolution nnU-Net 的集成方法。

本報告重點描述最終優化版本 (V8) 的策略：採用 Soft Voting (機率加權集成) 取代傳統的硬標籤投票，並結合 Test Time Augmentation (TTA) 與針對性的後處理 (LCC, Fill Holes, Morphological Closing)。實驗結果顯示，此策略能有效結合 2D 模型在平面解析度上的優勢與 3D 模型在空間連續性上的優勢，將 Dice Score 從早期的 0.36 大幅提升至 0.7905。

2. 方法論 (Methodology)

本研究的核心方法為 多視圖集成 (Multi-view Ensemble) 搭配 Soft Voting。

模型架構

我們訓練了兩個獨立的 nnU-Net 模型：

• 2D nnU-Net: 逐層 (Slice-by-slice) 進行分割，輸入尺寸為 $512 \times 512$。此模型對於邊緣細節（特別是右心室）的捕捉能力較強。
• 3D Low-resolution nnU-Net: 將原始影像降採樣後進行 3D 卷積運算。此模型擁有更大的感受野 (Receptive Field)，能有效維持心臟結構的 3D 拓樸正確性（如心肌的環狀結構）。

Soft Voting Ensemble (機率加權集成)

這是 V6 版本的核心改進。不同於之前的 Hard Voting (直接對類別標籤投票)，Soft Voting 是對模型輸出的 Softmax 機率圖 (Probability Maps) 進行加權平均。

假設 $P_{2d}(x)$ 和 $P_{3d}(x)$ 分別為 2D 和 3D 模型在體素 (Voxel) $x$ 處預測某類別的機率，最終機率 $P_{final}(x)$ 定義為：

$$ P_{final}(x) = w_{2d} \cdot P_{2d}(x) + w_{3d} \cdot P_{3d}(x) $$

我們根據驗證集 (Validation Set) 的表現，針對不同解剖結構設計了特定的權重矩陣 $W$：

解剖結構 (Label)	2D 權重 ($w_{2d}$)	3D 權重 ($w_{3d}$)	設計理由
Background (0)	0.5	0.5	中立
Myocardium (1)	0.3	0.7	3D 模型更能維持心肌的環狀連續性
Left Ventricle (2)	0.3	0.7	3D 模型對左心室的整體形狀掌握較佳
Right Ventricle (3)	0.65	0.35	2D 模型對形狀不規則的右心室分割更精準

推論增強與後處理

• TTA (Test Time Augmentation)：推論時開啟多軸向鏡像翻轉，消除隨機誤差。
• LCC (Keep Largest Connected Component)：針對每個類別僅保留最大連通區域，移除雜訊。
• Fill Holes：填補左/右心室內部的孔洞。
• Morphological Closing：使用形態學閉運算平滑邊緣 (V8 新增)。

3. 實驗過程與演進 (Evolution of Approaches)

我們的方法經歷了多次迭代，以下是各階段的關鍵發現與困難解決：

• Phase 1: 初期嘗試 (HW3 原始版本)

  • 結果: Dice Score 0.3635 (Underfitting)。
  • 問題: 模型訓練不足，未處理資料型態與維度問題。

• Phase 2: Baseline 建立

  • 方法: 2D + 3D Lowres Ensemble (Hard Voting)。
  • 結果: Dice Score 0.7829。
  • 發現: 證明了 2D 與 3D Lowres 的互補性。

• Phase 3: 錯誤的優化方向 (V2/V3)

  • 方法: 引入 3D Full-resolution 模型。
  • 結果: 分數下降至 0.77。
  • 困難: 3D Fullres 模型過擬合 (Overfitting)，且發生 float/uint8 型態轉換錯誤。
  • 解決: 放棄 Fullres，專注於優化 Lowres 與 2D 的結合，並修復程式碼 Bug。

• Phase 4 & 5: 回歸與修正 (V4/V5)

  • 方法: 回歸 3D Lowres + TTA + LCC/Fill Holes。
  • 結果: Dice Score 回升至 0.7833。

• Phase 6: Soft Voting 優化 (Current V6)

  • 方法: 改用 Soft Voting (機率加權)。
  • 結果: Dice Score 0.7901。
  • 突破: 成功突破 0.79 瓶頸，證明保留信心資訊比單純投票更有效。

• Phase 7: 過度集成 (V7)

  • 方法: 嘗試加入 3D Fullres (Fold 0 & Fold 1) 進行 4 模型集成。
  • 結果: Dice Score 下降至 0.7898。
  • 分析: 證實 3D Fullres 模型在此資料集上表現不佳，加入後反而引入雜訊，拖累整體表現。

• Phase 8: 形態學優化 (Current V8)

  • 方法: 新增 Morphological Closing。
  • 結果: Dice Score 提升至 0.7905。
  • 結論: 細微的形態學處理能進一步提升邊界品質。

4. 未來展望 (Future Work)

目前的優化已將單一 Fold (Fold 0) 的潛力發揮至極限。為了突破 0.80 的大關，我們已啟動 5-Fold Cross Validation 計畫，預期透過消除資料切分的偏差，能進一步提升模型的泛化能力。

---

📖 使用說明 (Usage Guide)

訓練策略建議

針對有限的運算資源，我們建議以下漸進式策略：

階段	配置 (--config)	Epochs	目的
快速驗證	2d	50-80	確認流程跑通，檢查標籤正確性
主力模型	3d_lowres	150-250	取得不錯的 Baseline，訓練速度適中
追求極致	3d_fullres	300+	提升邊界細節 (需較多時間與顯存)

指令範例:

# 訓練 2D 模型 (快速)
python nnunet_train.py --config 2d --epochs 100

# 訓練 3D Lowres 模型 (推薦)
python nnunet_train.py --config 3d_lowres --epochs 250

監控訓練

專案內建 monitor_training_live.ps1 (Windows) 可即時監控訓練進度與 GPU 使用率。

.\monitor_training_live.ps1

---

📁 專案結構

CardiacSeg/
├── setup_environment.ps1      # Windows 安裝腳本
├── setup_environment.sh       # macOS/Linux 安裝腳本
├── rename_dataset.py          # 資料前處理
├── nnunet_train.py            # 訓練主程式
├── nnunet_infer.py            # 推論主程式
├── nnunet_evaluate.py         # 評估程式
├── run_optimized_submission_v8.py # (V8) 最佳化集成腳本
├── nnUNet_raw/                # 原始資料存放區
├── nnUNet_preprocessed/       # 預處理後資料
└── nnUNet_results/            # 模型權重與預測結果

---

❓ 常見問題 (FAQ)

Q: 遇到 CUDA out of memory 怎麼辦？ A: 請嘗試改用 3d_lowres 或 2d 配置，或在 nnunet_train.py 中減少 batch size。

Q: 如何使用最佳的 V8 集成模型？ A: 請執行 python run_optimized_submission_v8.py，此腳本會自動載入訓練好的 2D 與 3D 模型並進行 Soft Voting 集成。

---

🔗 參考資料

• nnU-Net GitHub
• Isensee, F., et al. "nnU-Net: a self-configuring method for deep learning-based biomedical image segmentation." Nature Methods (2021).