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

# 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

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

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

python download_dataset.py

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

Nếu không có API key:

# 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

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

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

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

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

# 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:

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"

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