FILE_INDEX.md

# 📚 Medical Image Segmentation - File Index

## 🎯 Quick Navigation

### 🚀 Bắt Đầu Nhanh (3 lệnh)
```bash
# 1. Chạy ứng dụng web
python app.py

# 2. Hoặc chạy Jupyter demo
jupyter notebook demo.ipynb

# 3. Hoặc train model mới
python train.py --data ./prepared_data
```

---

## 📋 Danh Sách File & Công Dụng

### 🔴 **Core Scripts (Chính)**

| File | Mô Tả | Lệnh |
|------|-------|------|
| **app.py** | Web interface (Gradio) | `python app.py` |
| **demo.ipynb** | Interactive Jupyter demo | `jupyter notebook demo.ipynb` |
| **download_dataset.py** | Tải dataset từ Kaggle | `python download_dataset.py` |
| **prepare_dataset.py** | Chuẩn bị data (split, RLE decode) | `python prepare_dataset.py` |
| **train.py** | Train SegFormer model | `python train.py --data ./prepared_data` |
| **test.py** | Test & evaluation | `python test.py --model ./models/best_model` |

### 📚 **Documentation (Tài Liệu)**

| File | Nội Dung |
|------|---------|
| **TRAINING_GUIDE.md** | 📖 Hướng dẫn chi tiết từng bước |
| **IMPLEMENTATION_SUMMARY.md** | 🎉 Tóm tắt triển khai |
| **FILE_INDEX.md** | 📚 File này - danh sách file |
| **README.md** | ℹ️ Info gốc của dự án |

### 🗂️ **Directories (Thư Mục)**

| Thư Mục | Nội Dung |
|---------|---------|
| **segformer_trained_weights/** | Pre-trained model weights |
| **samples/** | Sample images để test |
| **data/** | Raw dataset (sau tải) |
| **prepared_data/** | Processed dataset (sau chuẩn bị) |
| **models/** | Trained models (sau training) |
| **test_results/** | Test predictions (sau test) |

---

## 🎯 Hướng Dẫn Sử Dụng Theo Mục Đích

### 📥 **Chỉ muốn test demo**
```bash
# 1. Chạy app web
python app.py
# Truy cập: http://127.0.0.1:7860

# 2. Hoặc dùng notebook
jupyter notebook demo.ipynb
```
**File:** `app.py`, `demo.ipynb`, `segformer_trained_weights/`

---

### 📖 **Muốn hiểu cách hoạt động**
**Đọc các file tài liệu theo thứ tự:**
1. Bắt đầu: `IMPLEMENTATION_SUMMARY.md`
2. Chi tiết: `TRAINING_GUIDE.md`
3. Code: `app.py` hoặc `demo.ipynb`

---

### 🏋️ **Muốn train model mới**
```bash
# Step 1: Tải dataset (yêu cầu Kaggle API)
python download_dataset.py

# Step 2: Chuẩn bị dữ liệu
python prepare_dataset.py

# Step 3: Train model
python train.py --epochs 20 --batch-size 8

# Step 4: Test model
python test.py --model ./models/best_model --visualize
```
**Files:** `download_dataset.py`, `prepare_dataset.py`, `train.py`, `test.py`

---

### 🧪 **Chỉ muốn test model hiện có**
```bash
python test.py \
    --model ./segformer_trained_weights \
    --test-images ./samples \
    --visualize
```
**File:** `test.py`

---

## 🔧 Script Chi Tiết

### **download_dataset.py**
Tải UW-Madison GI Tract dataset từ Kaggle
- ✅ Kiểm tra Kaggle API
- ✅ Tải ~10GB data
- ✅ Giải nén
- ✅ Verify structure

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

```bash
python download_dataset.py
```

---

### **prepare_dataset.py**
Xử lý RLE encoding thành image masks
- ✅ Giải mã RLE
- ✅ Chia train/val/test (80/10/10)
- ✅ Tạo folder structure
- ✅ Thống kê data

```bash
python prepare_dataset.py
```

**Đầu vào:** `data/` (từ Kaggle)  
**Đầu ra:** `prepared_data/`

---

### **train.py**
Train SegFormer model mới
- ✅ Load pre-trained SegFormer-b0
- ✅ Custom training loop
- ✅ Validation mỗi epoch
- ✅ Save best model
- ✅ Loss history

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

**Tham số:**
- `--data`: Path to prepared_data
- `--output-dir`: Model output (mặc định: `./models`)
- `--epochs`: Số epoch (mặc định: 10)
- `--batch-size`: Batch size (mặc định: 8)
- `--learning-rate`: Learning rate (mặc định: 1e-4)
- `--num-workers`: DataLoader workers (mặc định: 4)

**Đầu ra:** `models/best_model/`, `models/final_model/`

---

### **test.py**
Test model & tính metrics
- ✅ Evaluate trên test set
- ✅ Tính mIoU, Precision, Recall
- ✅ Per-class metrics
- ✅ Tạo visualizations
- ✅ Export JSON results

```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
```

**Tham số:**
- `--model`: Path to model (bắt buộc)
- `--test-images`: Test images folder (bắt buộc)
- `--test-masks`: Test masks folder (bắt buộc)
- `--output-dir`: Output folder (mặc định: `./test_results`)
- `--visualize`: Tạo visualizations (flag)
- `--num-samples`: Số samples visualize (mặc định: 5)

**Đầu ra:** `test_results/evaluation_results.json`, visualizations

---

### **app.py**
Web interface sử dụng Gradio
- ✅ Upload ảnh
- ✅ Real-time prediction
- ✅ Color-coded segmentation
- ✅ Confidence scores
- ✅ Sample images

```bash
python app.py
```

**Truy cập:** http://127.0.0.1:7860

**Cộn:** 🔵 Blue = Stomach, 🟢 Green = Small bowel, 🔴 Red = Large bowel

---

### **demo.ipynb**
Jupyter notebook interactive
- Section 1: Imports & Config
- Section 2: Load model
- Section 3: Preprocessing
- Section 4: Prediction function
- Section 5: Load samples
- Section 6: Visualize results
- Section 7: Create overlays
- Section 8: Batch evaluation

```bash
jupyter notebook demo.ipynb
```

---

## 📚 Tài Liệu

### **TRAINING_GUIDE.md**
Hướng dẫn hoàn chỉnh:
- 📖 Tổng quan dự án
- 🚀 Quick start
- 📚 Step-by-step guide
- 🧪 Testing & evaluation
- 💻 Custom model usage
- 📊 Dataset format
- 🔧 Troubleshooting
- 📈 Performance tips

### **IMPLEMENTATION_SUMMARY.md**
Tóm tắt triển khai:
- ✅ Những gì đã triển khai
- 🚀 Full workflow
- 📊 Feature table
- 💡 Quick examples
- ✨ Highlights

---

## 🎓 Learning Path

### **Beginner (Bắt đầu):**
1. Đọc: `IMPLEMENTATION_SUMMARY.md`
2. Chạy: `python app.py`
3. Thử: `jupyter notebook demo.ipynb`

### **Intermediate (Trung bình):**
1. Đọc: `TRAINING_GUIDE.md`
2. Chạy: `python download_dataset.py` → `prepare_dataset.py`
3. Understand: Code trong `train.py`

### **Advanced (Nâng cao):**
1. Sửa hyperparameters trong `train.py`
2. Thêm data augmentation
3. Thử architectures khác
4. Fine-tune cho use case của bạn

---

## 🎯 Cheat Sheet

| Mục đích | Lệnh |
|---------|------|
| Demo web | `python app.py` |
| Jupyter | `jupyter notebook demo.ipynb` |
| Tải data | `python download_dataset.py` |
| Prep data | `python prepare_dataset.py` |
| Train | `python train.py --epochs 20` |
| Test | `python test.py --model ./models/best_model --visualize` |
| Help | Xem `--help`: `python train.py --help` |

---

## 📞 Troubleshooting

**Nếu gặp lỗi:**
1. Xem error message chi tiết
2. Check `TRAINING_GUIDE.md` phần Troubleshooting
3. Verify folders & permissions
4. Kiểm tra Python version (3.8+)

**Common issues:**
- GPU not found? → Model sẽ auto switch sang CPU
- Kaggle error? → Xem hướng dẫn setup API key
- Out of memory? → Giảm `--batch-size`
- Slow? → Tăng `--num-workers`

---

## 📊 Model Info

**Kiến trúc:** SegFormer-B0 (HuggingFace)
**Classes:** 4 (Background + 3 organs)
**Input:** 288x288 RGB images
**Normalization:** ImageNet (mean, std)
**Framework:** PyTorch
**Inference:** ~100ms per image (CPU)

---

## 🎨 Color Legend

```
🔴 Red (#FF0000)     = Large bowel
🟢 Green (#009A17)   = Small bowel
🔵 Blue (#007fff)    = Stomach
⚪ White (0)          = Background
```

---

## 📈 Expected Results

- **mIoU:** 0.60-0.75 (depending on training)
- **Precision:** 0.70-0.85
- **Recall:** 0.60-0.80
- **Inference time:** 0.1-0.5s per image

---

## 🔗 Links

- 📚 HuggingFace SegFormer: https://huggingface.co/docs/transformers/model_doc/segformer
- 🔗 Gradio: https://www.gradio.app/
- 🔬 PyTorch: https://pytorch.org/
- 🏆 Kaggle Challenge: https://www.kaggle.com/competitions/uw-madison-gi-tract-image-segmentation

---

## ✨ Features Checklist

- ✅ Web interface (Gradio)
- ✅ Jupyter notebook
- ✅ Dataset download (Kaggle)
- ✅ Data preparation (RLE decode)
- ✅ Model training (SegFormer)
- ✅ Model testing & evaluation
- ✅ Confidence scores
- ✅ Visualizations
- ✅ Batch processing
- ✅ Complete documentation
- ✅ Error handling
- ✅ GPU/CPU support

---

**Ready to go! 🚀**

Chọn một script ở trên và bắt đầu!