Interscalene Block Segmentation

A modular pipeline for processing medical images and videos with MedSAM2 for interscalene block segmentation.


Example of YOLOv8 bounding box detection on a DICOM slice

Features

• Multiple Input Formats: MP4/AVI/MOV videos, DICOM medical images, TIF/TIFF images
• MedSAM2 Integration: State-of-the-art medical image segmentation
• Modular Architecture: Clean, extensible class-based design
• Batch Processing: Process single files or entire directories

Quick Start

Installation

1. Clone the repository:

git clone https://github.com/yourusername/interscalene-block-segmentation.git
cd interscalene-block-segmentation

2. Create and activate virtual environment:

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

3. Clone MedSAM2 repository:

git clone https://github.com/bowang-lab/MedSAM2.git MedSAM2

4. Install dependencies:

pip install -r requirements.txt
cd MedSAM2 && pip install -e ".[dev]" && cd ..

5. Download MedSAM2 checkpoints:

cd MedSAM2 && bash download.sh && cd ..

See SETUP.md for detailed installation instructions.

Usage

Main Pipeline (Recommended)

The modular pipeline supports multiple formats:

# Process MP4 video
python process_medsam2.py -i video.mp4 -o results

# Process DICOM directory
python process_medsam2.py -i dicom_folder/ -o results

# Process TIF file
python process_medsam2.py -i image.tif -o results

# Process all supported files in a directory
python process_medsam2.py -i input_dir/ -o results

# With options
python process_medsam2.py \
    -i video.mp4 \
    -o results \
    --frame_interval 5 \
    --max_images 10 \
    --device cuda

Process Multiple Videos

To process all MP4 files in a directory:

# Process all supported files (including MP4) in a directory
python process_medsam2.py -i . -o results --extensions .mp4

# Process all MP4 files recursively
python process_medsam2.py -i video_folder/ -o results --extensions .mp4 --recursive

Supported Formats

MP4/AVI/MOV Videos

• Extracts frames from video files
• Supports: .mp4, .avi, .mov, .mkv, .webm

DICOM Medical Images

• Single DICOM files (.dcm, .dicom)
• DICOM series (directories)
• Automatic windowing and normalization
• Requires: pydicom, SimpleITK

TIF/TIFF Images

• Single and multi-page TIF files
• Multi-channel support
• Requires: tifffile

Output Structure

Results are saved in the following structure:

output_dir/
├── file_name/
│   ├── frames/              # Extracted images
│   │   ├── file_name_frame_000000.jpg
│   │   └── ...
│   └── visualizations/      # Mask visualizations
│       ├── file_name_frame_000000_masked.jpg
│       └── ...

Visualizations show the original frame with a green overlay (50% transparency) indicating the segmentation mask generated by MedSAM2.

Architecture

The pipeline consists of modular components:

• Input Handlers (medsam2_pipeline/input_handlers.py): Support for MP4, DICOM, and TIF formats
• MedSAM2 Processor (medsam2_pipeline/processor.py): Model loading and mask generation
• Pipeline (medsam2_pipeline/pipeline.py): Main orchestration class

Python API

from medsam2_pipeline import MedSAM2Pipeline

# Initialize pipeline
pipeline = MedSAM2Pipeline(
    checkpoint_path="MedSAM2/checkpoints/MedSAM2_latest.pt",
    config_path="configs/sam2.1_hiera_t512.yaml",
    device="cuda"  # or "mps", "cpu", or None for auto-detect
)

# Process a single file
result = pipeline.process_file(
    file_path="video.mp4",
    output_dir="results",
    frame_interval=1,
    max_images=None
)

# Process a directory
results = pipeline.process_directory(
    input_dir="input_folder/",
    output_dir="results"
)

Project Structure

.
├── src/                        # Source code directory
│   ├── medsam2_pipeline/       # Modular pipeline package
│   │   ├── __init__.py
│   │   ├── input_handlers.py   # Input format handlers (MP4, DICOM, TIF)
│   │   ├── processor.py        # MedSAM2 model processor
│   │   └── pipeline.py         # Main pipeline orchestration
│   └── process_medsam2.py      # Main processing script
├── tests/                      # Unit tests
│   └── test_pipeline.py
├── MedSAM2/                    # MedSAM2 model code (cloned repository)
├── process_medsam2.py          # Entry point script (calls src/process_medsam2.py)
├── requirements.txt            # Python dependencies
├── pyproject.toml              # Package configuration
├── README.md                   # This file
├── SETUP.md                    # Detailed installation guide
└── TROUBLESHOOTING.md          # Troubleshooting guide

Note: The entry point script in the root directory (process_medsam2.py) is a thin wrapper that calls the actual script in the src/ directory. This keeps the codebase organized while maintaining an easy-to-use command-line interface.

Requirements

• Python 3.8+
• PyTorch
• OpenCV
• pydicom, SimpleITK (for DICOM)
• tifffile (for TIF)

See requirements.txt for complete list.

Command Line Options

Command Line Options

• --input, -i: Input file or directory (required)
• --output, -o: Output directory (default: medsam2_results)
• --checkpoint: Path to MedSAM2 checkpoint
• --config: Path to MedSAM2 config (relative to sam2 package)
• --frame_interval: Process every Nth image (default: 1)
• --max_images: Maximum images per file (default: all)
• --device: Device to use (cuda, mps, cpu, or auto-detect)
• --recursive: Process files recursively in directories
• --extensions: Specific file extensions to process (e.g., --extensions .mp4 .avi)
• --alpha: Mask overlay transparency (0.0-1.0, default: 0.5)
• --mask_color: Mask color in RGB (default: 0 255 0)

Testing

# Run unit tests
pytest tests/test_pipeline.py -v
pytest tests/test_video_processing.py -v

# Run with coverage
pytest tests/ --cov=medsam2_pipeline

Documentation

• SETUP.md - Detailed installation and setup guide
• TROUBLESHOOTING.md - Common issues and solutions

License

[Add your license here]

Citation

If you use this code, please cite:

• MedSAM2 paper
• SAM2 paper
• This repository

Contributing

[Add contribution guidelines]