README.md

metadata

title: Medical Image Segmentation - GI Tract
emoji: 🏥
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 4.11.0
python_version: '3.9'
app_file: app.py
pinned: false

🏥 Medical Image Segmentation - UW-Madison GI Tract

Automated semantic segmentation of gastrointestinal tract organs in medical CT/MRI images using SegFormer and Gradio web interface.

📋 Table of Contents

• Overview
• Features
• Installation
• Quick Start
• Usage
• Project Structure
• Model Details
• Training
• API Reference
• Contributing
• License

📊 Overview

This project provides an end-to-end solution for segmenting GI tract organs in medical images:

• Stomach
• Large Bowel
• Small Bowel

Built with state-of-the-art SegFormer architecture and trained on the UW-Madison GI Tract Image Segmentation dataset (45K+ images).

Key Achievements

• ✅ 64M parameter efficient model
• ✅ Interactive Gradio web interface
• ✅ Real-time inference on CPU/GPU
• ✅ 40+ pre-loaded sample images
• ✅ Complete training pipeline included
• ✅ Production-ready code

✨ Features

Core Capabilities

• Web Interface: Upload images and get instant segmentation predictions
• Batch Processing: Test on multiple images simultaneously
• Color-Coded Output: Intuitive visual representation of organ locations
• Confidence Scores: Pixel-level confidence metrics for each organ
• Interactive Notebook: Educational Jupyter notebook with step-by-step examples

Development Tools

• Data download automation (Kaggle integration)
• Dataset preparation and preprocessing
• Model training with validation
• Comprehensive evaluation metrics
• Diagnostic system checker
• Simple testing without ground truth

🚀 Installation

Requirements

• Python 3.8 or higher
• CUDA 11.8+ (optional, for GPU acceleration)
• 4GB RAM minimum (8GB recommended)
• 2GB disk space

Step 1: Clone Repository

git clone https://github.com/hung2903/medical-image-segmentation.git
cd UWMGI_Medical_Image_Segmentation

Step 2: Create Virtual Environment

# Using venv
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Or using conda
conda create -n medseg python=3.10
conda activate medseg

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Verify Installation

python diagnose.py

All checks should show ✅ PASSED.

🎯 Quick Start

1. Run Web Interface (Easiest)

python app.py

Then open http://127.0.0.1:7860 in your browser.

2. Test on Sample Images

python test_simple.py \
    --model segformer_trained_weights \
    --images samples \
    --output-dir results

3. Interactive Jupyter Notebook

jupyter notebook demo.ipynb

📖 Usage

Web Interface

1. Launch: python app.py
2. Upload medical image (PNG/JPG)
3. Click "Generate Predictions"
4. View color-coded segmentation with confidence scores
5. Download result image

Supported Formats: PNG, JPG, JPEG, GIF, BMP, WEBP

Command Line

from app import get_model, predict
import torch
from PIL import Image

# Load model
device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
model = get_model(device)

# Load image
image = Image.open('sample.png')

# Get predictions
output_image, confidence_info = predict(image)

Python API

import torch
from transformers import SegformerForSemanticSegmentation, SegformerImageProcessor

device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
model = SegformerForSemanticSegmentation.from_pretrained(
    'segformer_trained_weights'
).to(device)
processor = SegformerImageProcessor()

# Process image
image_input = processor(image, return_tensors='pt').to(device)
outputs = model(**image_input)
logits = outputs.logits

📁 Project Structure

.
├── app.py                      # Gradio web interface
├── train.py                    # Model training script
├── test.py                     # Comprehensive evaluation
├── test_simple.py              # Simple testing without ground truth
├── download_dataset.py         # Kaggle dataset download
├── prepare_dataset.py          # Data preprocessing
├── diagnose.py                 # System diagnostics
├── demo.ipynb                  # Interactive notebook
├── requirements.txt            # Python dependencies
├── LICENSE                     # MIT License
├── README.md                   # This file
├── TRAINING_GUIDE.md           # Detailed training instructions
├── IMPLEMENTATION_SUMMARY.md   # Technical details
├── FILE_INDEX.md               # File navigation guide
├── samples/                    # 40 pre-loaded sample images
├── segformer_trained_weights/  # Pre-trained model
│   ├── config.json
│   └── pytorch_model.bin
└── test_results_simple/        # Test outputs

🧠 Model Details

Architecture

• Model: SegFormer-B0
• Framework: HuggingFace Transformers
• Pre-training: Cityscapes dataset
• Fine-tuning: UW-Madison GI Tract Dataset

Specifications

Aspect	Value
Input Size	288 × 288 pixels
Output Classes	4 (background + 3 organs)
Parameters	64M
Model Size	256 MB
Inference Time	~500ms (CPU), ~100ms (GPU)

Normalization

Mean: [0.485, 0.456, 0.406]
Std:  [0.229, 0.224, 0.225]

(ImageNet standard)

🎓 Training

Download Full Dataset

# Requires Kaggle API key setup
python download_dataset.py

Prepare Data

python prepare_dataset.py \
    --data-dir /path/to/downloaded/data \
    --output-dir prepared_data

Train Model

python train.py \
    --epochs 20 \
    --batch-size 16 \
    --learning-rate 1e-4 \
    --train-dir prepared_data/train_images \
    --val-dir prepared_data/val_images

Evaluate

python test.py \
    --model models/best_model \
    --test-images prepared_data/test_images \
    --test-masks prepared_data/test_masks \
    --visualize

See TRAINING_GUIDE.md for detailed instructions.

📡 API Reference

app.py

def predict(image: Image.Image) -> Tuple[Image.Image, str]:
    """Perform segmentation on input image."""
    
def get_model(device: torch.device) -> SegformerForSemanticSegmentation:
    """Load pre-trained model."""

test_simple.py

class SimpleSegmentationTester:
    def test_batch(self, image_paths: List[str]) -> Dict:
        """Segment multiple images."""

train.py

class MedicalImageSegmentationTrainer:
    def train(self, num_epochs: int) -> None:
        """Train model with validation."""

🔄 Preprocessing Pipeline

1. Image Resize: 288 × 288
2. Normalization: ImageNet standard (mean/std)
3. Tensor Conversion: Convert to PyTorch tensors
4. Device Transfer: Move to GPU/CPU

📊 Output Format

Web Interface

• Colored overlay image (red/green/blue for organs)
• Confidence percentages per organ
• Downloadable result image

JSON Output (test_simple.py)

{
  "case101_day26": {
    "large_bowel_pixels": 244,
    "small_bowel_pixels": 1901,
    "stomach_pixels": 2979,
    "total_segmented": 5124
  }
}

🐛 Troubleshooting

ModuleNotFoundError

pip install -r requirements.txt --default-timeout=1000

CUDA Out of Memory

# Use CPU instead
device = torch.device('cpu')

# Or reduce batch size
batch_size = 4

Model Loading Issues

python diagnose.py  # Check all requirements

📈 Performance Metrics

Evaluated on validation set:

• mIoU: Intersection over Union
• Precision: Per-class accuracy
• Recall: Organ detection rate
• F1-Score: Harmonic mean

See IMPLEMENTATION_SUMMARY.md for details.

🤝 Contributing

Contributions welcome! Areas for improvement:

• Add more organ classes
• Improve inference speed
• Add DICOM format support
• Deploy to Hugging Face Spaces
• Add multi-modal support (CT/MRI)

📚 References

• UW-Madison GI Tract Dataset
• SegFormer Paper
• HuggingFace Transformers

📝 License

This project is licensed under the MIT License - see LICENSE file for details.

👥 Citation

If you use this project, please cite:

@software{medical_image_seg_2026,
  title={Medical Image Segmentation - UW-Madison GI Tract},
  author={Hungkm},
  year={2026},
  url={https://github.com/hung2903/medical-image-segmentation}
}

📧 Contact

For questions or issues:

• Open a GitHub issue
• Email: kmh2903.dsh@gmail.com

---

Made with ❤️ for medical imaging