README.md

metadata

title: Stroke DeepISLES Demo
emoji: 🧠
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
suggested_hardware: t4-small
pinned: false
license: mit
short_description: Ischemic stroke lesion segmentation using DeepISLES
models:
  - isleschallenge/deepisles
datasets:
  - hugging-science/isles24-stroke
tags:
  - medical-imaging
  - stroke
  - segmentation
  - neuroimaging
  - niivue
  - nnunet

Stroke DeepISLES Demo

A demonstration pipeline and UI for ischemic stroke lesion segmentation using DeepISLES and ISLES'24 data.

This project provides a complete end-to-end workflow:

1. Data Loading: Lazy-loading of NIfTI neuroimaging data from HuggingFace.
2. Inference: Running DeepISLES segmentation (SEALS or Ensemble) via Docker.
3. Visualization: Interactive 3D and multi-planar viewing with NiiVue in Gradio.

Disclaimer: This software is for research and demonstration purposes only. It is not intended for clinical use.

Features

• 🧠 State-of-the-Art Segmentation: Uses DeepISLES (ISLES'22 winner) for accurate lesion segmentation.
• ☁️ Cloud-Native Data: Streams data directly from HuggingFace Datasets (no massive downloads).
• 🐳 Dockerized Inference: Encapsulates complex deep learning dependencies in a reproducible container.
• 🖥️ Interactive UI: Gradio-based web interface with 3D rendering (NiiVue).
• ⚙️ Production Ready: Type-safe, tested, and configurable via environment variables.

Quickstart

Prerequisites

• Python 3.11+
• Docker (for inference)
• uv (recommended) or pip

Installation

# Clone the repository
git clone https://github.com/The-Obstacle-Is-The-Way/stroke-deepisles-demo.git
cd stroke-deepisles-demo

# Install dependencies
uv sync

Running the Demo

1. Pull the Docker image (first time only):

   docker pull isleschallenge/deepisles
   

2. Launch the UI:

   uv run python -m stroke_deepisles_demo.ui.app
   

   Open http://localhost:7860 in your browser.

3. Run via CLI:

   # List cases
   uv run stroke-demo list
   
   # Run segmentation on a specific case
   uv run stroke-demo run --case sub-stroke0001
   

Documentation

• Quickstart Guide
• Configuration
• Deployment
• Contributing

Architecture

graph TD
    HF[HuggingFace Hub] -->|Stream NIfTI| Loader[Data Loader]
    Loader -->|Stage Files| Staging[Staging Dir]
    Staging -->|Mount Volume| Docker[DeepISLES Container]
    Docker -->|Inference| Results[Prediction Mask]
    Results -->|Load| Metrics[Metrics (Dice)]
    Results -->|Render| UI[Gradio UI / NiiVue]

License

MIT License. See LICENSE for details.

Acknowledgements

• DeepISLES team for the segmentation model.
• ISLES24 challenge for the dataset.
• NiiVue for the web-based neuroimaging viewer.