README.md

---
title: Coronary Artery Segmentation
emoji: 🫀
colorFrom: red
colorTo: pink
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false
license: mit
---

# 🫀 Coronary Artery Segmentation with Fine-tuned SAM2

An interactive tool for segmenting coronary arteries in X-ray angiography images using fine-tuned Segment Anything Model 2 (SAM2). This Space provides an easy-to-use interface for medical image segmentation with point-based prompting.

---

## 🎯 How to Use This Space

### Step 1: Upload Your Image
- Click on the image upload area or drag and drop your coronary X-ray angiography image
- Supported formats: JPG, PNG, and other common image formats
- The image will be displayed in the interface for annotation

### Step 2: Select a Model
Choose from four fine-tuned SAM2 variants optimized for coronary artery segmentation:
- **SAM2 Hiera Tiny** - Fastest inference, good for quick results
- **SAM2 Hiera Small** - Balanced speed and accuracy
- **SAM2 Hiera Base Plus** - Higher accuracy, moderate speed
- **SAM2 Hiera Large** - Best accuracy, slower inference

### Step 3: Add Point Prompts

#### 🟢 Positive Points (Green)  
- Click on areas you **want to include** in the segmentation
- Use positive points to mark the coronary arteries you want to segment
- Multiple positive points help the model understand the full extent of the artery
- **Tip**: Add points along the length of the artery for better coverage

#### 🔴 Negative Points (Red)
- Click on areas you **want to exclude** from the segmentation
- Use negative points to refine the segmentation and remove unwanted regions
- Helpful for separating overlapping vessels or removing background
- **Tip**: Add negative points near the artery boundaries to improve precision

#### 🎨 How to Add Points
1. The first click adds a **positive point** (green)
2. Hold **Shift** while clicking to add a **negative point** (red)
3. You can add multiple points of each type
4. Points are displayed as colored dots on your image

### Step 4: Generate Segmentation
- Click the **"Segment"** button to process your annotations
- The model will generate a segmentation mask based on your point prompts
- The result shows the segmented coronary artery highlighted on the original image

### Step 5: Refine (Optional)
- If the segmentation isn't perfect, add more points:
  - Add positive points to include missing artery sections
  - Add negative points to exclude over-segmented regions
- Click **"Segment"** again to update the result
- Repeat until you're satisfied with the segmentation

### Step 6: Clear and Start Over
- Use the **"Clear"** button to remove all points and start fresh
- Upload a new image to segment a different case

---

## 💡 Tips for Best Results

1. **Start Simple**: Begin with 1-2 positive points on the main artery structure
2. **Be Strategic**: Place positive points at key locations (branches, endpoints, curves)
3. **Refine Gradually**: Add negative points only where the model over-segments
4. **Model Selection**: Start with Tiny or Small models for faster iteration, then use larger models for final results
5. **Multiple Vessels**: For multiple arteries, focus on one at a time with clear positive points
6. **Contrast Matters**: Images with good contrast between vessels and background work best

---

## 🔬 Model Architecture

![Coronary Artery Segmentation Workflow](ICARp_Updated.svg)

The workflow consists of several key stages:
1. **Image Preprocessing** - Normalization and enhancement for optimal model input
2. **Point Prompt Encoding** - Your positive/negative clicks are encoded as spatial prompts
3. **SAM2 Processing** - Fine-tuned encoder-decoder processes the image with prompts
4. **Mask Generation** - High-quality segmentation mask output
5. **Visualization** - Segmented artery overlaid on the original image

---

## 📊 Model Variants

| Model | Parameters | Speed | Accuracy | Best For |
|-------|-----------|-------|----------|----------|
| Hiera Tiny | ~38M | ⚡⚡⚡ | ⭐⭐⭐ | Quick experiments, real-time feedback |
| Hiera Small | ~46M | ⚡⚡ | ⭐⭐⭐⭐ | Balanced performance, general use |
| Hiera Base Plus | ~80M | ⚡ | ⭐⭐⭐⭐⭐ | High-quality results, clinical evaluation |
| Hiera Large | ~224M | ⚡ | ⭐⭐⭐⭐⭐ | Best possible accuracy, research |

All models have been fine-tuned specifically for coronary artery segmentation on X-ray angiography images.

---

## ⚠️ Disclaimer

This tool is intended for **research and educational purposes only**. It is not approved for clinical diagnosis or treatment decisions. Always consult qualified healthcare professionals for medical image interpretation.

---

## 🚀 Local Installation

If you want to run this application locally, follow these setup instructions:

### 1. Create Conda Environment

```bash
# Create a new conda environment named sam2_FT_env with Python 3.10
conda create -n sam2_FT_env python=3.10.0 -y

# Activate the environment
conda activate sam2_FT_env
```

### 2. Install SAM2 Library

```bash
# Clone the official repository
git clone https://github.com/facebookresearch/segment-anything-2.git
cd segment-anything-2

# Install the package in editable mode
pip install -e .
cd ..
```

### 3. Install Dependencies

```bash
pip install uv
uv pip install gradio opencv-python-headless torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu130
```

### 4. Run the Application

```bash
# Ensure model checkpoints are in the correct directories
python app.py
```

Open `http://127.0.0.1:7860` in your browser.

---

## 📚 Citation

If you use this tool in your research, please cite:

```bibtex
@article{ravi2024sam2,
  title={SAM 2: Segment Anything in Images and Videos},
  author={Ravi, Nikhila and others},
  journal={arXiv preprint arXiv:2408.00714},
  year={2024}
}
```

---

## 📧 Contact & Support

For questions, issues, or feedback, please open an issue on the GitHub repository or contact the developers.

**Built with ❤️ using SAM2 and Gradio**