README.md

metadata

title: Stroke DeepISLES Demo
emoji: 🧠
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
suggested_hardware: t4-small
pinned: false
license: apache-2.0
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.

Requirements

Hardware

• GPU Required: This demo requires a T4 GPU (t4-small hardware on HF Spaces)
• Free tier (cpu-basic) will NOT work - DeepISLES requires CUDA for inference
• Recommended: t4-small or better

Browser

• WebGL2 support required (Chrome 56+, Firefox 51+, Safari 15+, Edge 79+)
• Check compatibility: https://get.webgl.org/webgl2/

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

Apache License 2.0. See LICENSE for details.

Acknowledgements

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