TRAINING_GUIDE.md

# 🏥 Medical Image Segmentation - Complete Guide

## 📋 Tổng Quan Dự Án

Dự án này phân đoạn tự động các cơ quan trong ảnh Y tế của đường tiêu hóa sử dụng **SegFormer** model từ HuggingFace Transformers.

### 🎯 Các Cơ Quan Được Phân Đoạn
- **Dạ dày** (Stomach) - 🔵 Xanh dương
- **Ruột non** (Small bowel) - 🟢 Xanh lá
- **Ruột già** (Large bowel) - 🔴 Đỏ

---

## 🚀 Quick Start

### 1. Chạy Ứng Dụng Demo

```bash
# Vào thư mục dự án
cd UWMGI_Medical_Image_Segmentation

# Chạy ứng dụng web
python app.py
```

Mở trình duyệt: **http://127.0.0.1:7860**

### 2. Sử Dụng Ứng Dụng
1. Upload ảnh Y tế hoặc chọn ảnh mẫu
2. Click nút "Generate Predictions"
3. Xem kết quả phân đoạn với màu sắc

---

## 📚 Hướng Dẫn Training (Huấn Luyện Mô Hình Mới)

### Bước 1: Cài Đặt Dependencies

```bash
pip install -r requirements.txt
pip install kaggle pandas scikit-learn matplotlib
```

### Bước 2: Tải Dataset từ Kaggle

```bash
python download_dataset.py
```

**Yêu cầu**: Kaggle API key (từ https://www.kaggle.com/account)

Nếu không có API key:
```bash
# Tạo thư mục Kaggle
mkdir ~/.kaggle

# Tải kaggle.json từ https://www.kaggle.com/account
# Lưu vào ~/.kaggle/kaggle.json

# Set permissions (Linux/Mac)
chmod 600 ~/.kaggle/kaggle.json
```

### Bước 3: Chuẩn Bị Dataset

```bash
python prepare_dataset.py
```

Script này sẽ:
- ✅ Giải mã RLE encoding thành mask images
- ✅ Chia train/val/test sets (80/10/10)
- ✅ Tạo cấu trúc folder chuẩn

**Kết quả**:
```
prepared_data/
├── train_images/     (80% ảnh)
├── train_masks/      (corresponding masks)
├── val_images/       (10% ảnh)
├── val_masks/
├── test_images/      (10% ảnh)
├── test_masks/
└── split.json        (file metadata)
```

### Bước 4: Train Mô Hình

```bash
python train.py \
    --data ./prepared_data \
    --output-dir ./models \
    --epochs 10 \
    --batch-size 8 \
    --learning-rate 1e-4
```

**Các tham số**:
- `--epochs`: Số lần lặp (mặc định: 10)
- `--batch-size`: Kích thước batch (mặc định: 8)
- `--learning-rate`: Tốc độ học (mặc định: 1e-4)
- `--num-workers`: Workers cho DataLoader (mặc định: 4)

**Kết quả**:
```
models/
├── best_model/            (model tốt nhất trên validation)
├── final_model/           (model sau training)
└── training_history.json  (loss history)
```

---

## 🧪 Testing & Evaluation

### 1. Đánh Giá Trên Test Set

```bash
python test.py \
    --model ./models/best_model \
    --test-images ./prepared_data/test_images \
    --test-masks ./prepared_data/test_masks \
    --output-dir ./test_results
```

**Kết quả Metrics**:
- **mIoU** (mean Intersection over Union): 0.0 - 1.0 (cao hơn tốt hơn)
- **Precision**: Độ chính xác
- **Recall**: Độ nhạy
- **Per-class IoU**: Metrics cho từng cơ quan

### 2. Tạo Visualizations

```bash
python test.py \
    --model ./models/best_model \
    --test-images ./prepared_data/test_images \
    --test-masks ./prepared_data/test_masks \
    --output-dir ./test_results \
    --visualize \
    --num-samples 10
```

Sẽ tạo ra visualizations:
- Original image
- Prediction mask
- Confidence map

---

## 💻 Sử Dụng Mô Hình Tùy Chỉnh

### Thay Thế Mô Hình Mặc Định

```python
# Chỉnh sửa app.py
# Thay đổi dòng này:
model_dir = "./models/best_model"  # Thay vào chỗ Configs.MODEL_PATH hoặc W&B artifact
```

Hoặc tạo script custom:

```python
from transformers import SegformerForSemanticSegmentation
import torch
from PIL import Image

# Load model
model = SegformerForSemanticSegmentation.from_pretrained("./models/best_model")
model.eval()

# Load image
image = Image.open("test.png").convert("RGB")

# Predict (xem app.py's predict function để chi tiết)
```

---

## 📊 Cấu Trúc File

```
UWMGI_Medical_Image_Segmentation/
├── app.py                          # Ứng dụng Gradio chính
├── download_dataset.py             # Script tải dataset từ Kaggle
├── prepare_dataset.py              # Script chuẩn bị dataset
├── train.py                        # Script training
├── test.py                         # Script testing & evaluation
├── requirements.txt                # Dependencies
├── segformer_trained_weights/      # Pre-trained weights
├── samples/                        # Ảnh mẫu
│
├── data/                           # Raw dataset từ Kaggle
│   ├── train_images/
│   ├── test_images/
│   └── train_masks.csv
│
├── prepared_data/                  # Processed dataset
│   ├── train_images/
│   ├── train_masks/
│   ├── val_images/
│   ├── val_masks/
│   ├── test_images/
│   ├── test_masks/
│   └── split.json
│
├── models/                         # Trained models
│   ├── best_model/
│   ├── final_model/
│   └── training_history.json
│
└── test_results/                   # Evaluation results
    ├── predictions/                # Predicted masks
    ├── visualizations/             # Visualization images
    └── evaluation_results.json
```

---

## 🔧 Troubleshooting

### Lỗi: "Kaggle API not installed"
```bash
pip install kaggle
```

### Lỗi: "Kaggle credentials not found"
Xem hướng dẫn trong phần "Bước 2: Tải Dataset"

### GPU Memory Error
- Giảm batch-size: `--batch-size 4`
- Sử dụng CPU: Model sẽ tự detect CPU nếu GPU không available

### Dataset Quá Lớn
- Giảm số epochs: `--epochs 5`
- Tăng learning-rate: `--learning-rate 5e-4` (cẩn thận)

---

## 📈 Performance Tips

1. **Tăng chất lượng**:
   - Tăng epochs (20-30)
   - Tăng batch size (nếu GPU cho phép)
   - Dùng augmentation (thêm vào prepare_dataset.py)

2. **Tăng tốc độ**:
   - Giảm epochs
   - Dùng mixed precision training
   - Tăng num_workers (4-8)

3. **Tinh chỉnh hyperparameters**:
   - Learning rate: 1e-5 to 5e-4
   - Batch size: 4-32
   - Warmup epochs: 2-3

---

## 📚 Dataset Format

### Input
- **Định dạng**: PNG, JPEG
- **Kích thước**: Tự động resize về 288x288
- **Channels**: RGB (3 channels)

### Output (Mask)
- **Giá trị pixel**:
  - 0 = Background
  - 1 = Large bowel
  - 2 = Small bowel
  - 3 = Stomach

---

## 🤝 Contributions

Muốn cải thiện dự án? Bạn có thể:
- Thêm augmentation techniques
- Cải tiến model architecture
- Thêm support cho các cơ quan khác
- Tối ưu performance

---

## 📞 Support

Nếu gặp vấn đề:
1. Kiểm tra error message
2. Xem phần Troubleshooting
3. Kiểm tra Kaggle/PyTorch documentation

---

## 📝 References

- **SegFormer**: https://huggingface.co/docs/transformers/model_doc/segformer
- **HuggingFace Transformers**: https://huggingface.co/
- **UW-Madison Challenge**: https://www.kaggle.com/competitions/uw-madison-gi-tract-image-segmentation
- **PyTorch**: https://pytorch.org/
- **Gradio**: https://www.gradio.app/

---

**Created**: January 2026
**License**: MIT
**Framework**: PyTorch + HuggingFace Transformers