context: stroke-deepisles-demo
Disclaimer: This software is for research and demonstration purposes only. Not for clinical use.
overview
This document explains why we're building stroke-deepisles-demo and the architectural context that informs our design decisions.
the problem we're solving
We want to demonstrate an end-to-end neuroimaging inference pipeline:
HuggingFace Hub (ISLES24-MR-Lite)
↓
BIDS/NIfTI loader (datasets fork)
↓
DeepISLES Docker (stroke segmentation)
↓
NiiVue visualization (Gradio Space)
This showcases that:
- Neuroimaging data can be consumed from HF Hub with proper BIDS/NIfTI support
- Clinical-grade models can run via Docker as black boxes
- Results can be visualized interactively in a browser
why we need tobias's datasets fork
As of December 2025, the official huggingface/datasets library has partial NIfTI support but lacks critical features for neuroimaging workflows.
what's merged upstream
| PR | Author | Status | Description |
|---|---|---|---|
| #7874 | CloseChoice (Tobias) | Merged Nov 21 | NIfTI visualization support |
| #7878 | CloseChoice (Tobias) | Merged Nov 27 | Replace papaya with NiiVue |
what's NOT merged (and why we need the fork)
| PR | Author | Status | Description |
|---|---|---|---|
| #7886 | The-Obstacle-Is-The-Way | Open | BIDS dataset loader - load_dataset('bids', ...) |
| #7887 | The-Obstacle-Is-The-Way | Open | NIfTI lazy loading fix - use dataobj not get_fdata() |
| #7892 | CloseChoice (Tobias) | Open | NIfTI encoding for lazy upload - fixes Arrow serialization |
The fork branch bundles all these features:
https://github.com/CloseChoice/datasets/tree/feat/bids-loader-streaming-upload-fix
We pin to this branch until upstream merges the PRs.
key components
1. data source: ISLES24-MR-Lite
- HF Dataset: YongchengYAO/ISLES24-MR-Lite
- Content: 149 acute stroke MRI cases with DWI, ADC, and manual infarct masks
- Origin: Subset of ISLES 2024 challenge data
- Why suitable: DeepISLES was trained on ISLES 2022, so ISLES24 is an external test set (no data leakage)
2. model: DeepISLES
- Paper: Nature Communications 2025 - "DeepISLES: A clinically validated ischemic stroke segmentation model"
- GitHub: ezequieldlrosa/DeepIsles
- Docker:
isleschallenge/deepisles - Inputs: DWI + ADC (required), FLAIR (optional)
- Output: 3D binary lesion mask (NIfTI)
- Mode: We use
fast=True(single model) not the full 3-model ensemble
3. visualization: NiiVue
- Library: niivue/niivue
- Type: WebGL2-based neuroimaging viewer
- Formats: Native NIfTI support, overlays, multiplanar views
- Integration: Via Gradio custom HTML component or iframe
4. UI framework: Gradio 5
- Version: Gradio 5.x (latest as of Dec 2025)
- Features: SSR for fast loading, improved components, WebRTC support
- Deployment: Hugging Face Spaces
architecture diagram
┌─────────────────────────────────────────────────────────────────┐
│ stroke-deepisles-demo │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ data/ │ │ inference/ │ │ ui/ │ │
│ │ │ │ │ │ │ │
│ │ - loader │───▶│ - docker │───▶│ - gradio │ │
│ │ - adapter │ │ - wrapper │ │ - niivue │ │
│ │ - staging │ │ - pipeline │ │ - viewer │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ core/ │ │
│ │ - config (pydantic-settings) │ │
│ │ - types (dataclasses, TypedDicts) │ │
│ │ - exceptions │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ HF Hub │ │ Docker │ │ Browser │
│ datasets │ │ Engine │ │ WebGL2 │
└──────────┘ └──────────┘ └──────────┘
design principles
- Vertical slices: Each phase delivers runnable functionality
- TDD: Tests written before implementation
- Type safety: Full type hints, mypy/pyright strict mode
- Separation of concerns: Data, inference, and UI are independent modules
- Docker as black box: We don't reimplement DeepISLES, we call it
- Graceful degradation: Mock Docker for tests, fallback viewers if NiiVue fails
reference repositories
These are cloned locally (without git linkages) for reference:
| Directory | Source | Purpose |
|---|---|---|
_reference_repos/datasets-tobias-bids-fork/ |
CloseChoice/datasets@feat/bids-loader-streaming-upload-fix | BIDS loader + NIfTI lazy loading |
_reference_repos/arc-aphasia-bids/ |
The-Obstacle-Is-The-Way/arc-aphasia-bids | BIDS upload patterns (reference only) |
_reference_repos/DeepIsles/ |
ezequieldlrosa/DeepIsles | DeepISLES CLI interface reference |
_reference_repos/bids-neuroimaging-space/ |
TobiasPitters/bids-neuroimaging | Working NiiVue + FastAPI implementation |
key reference: tobias's bids-neuroimaging space
This is the most important reference for Phase 4 (UI). It demonstrates:
- NiiVue working in HF Spaces - Proof that WebGL2 viewer works in production
- FastAPI + raw HTML approach - Clean, no Gradio overhead for viewer
- Base64 data URLs for NIfTI -
data:application/octet-stream;base64,{b64} - NiiVue CDN loading -
https://unpkg.com/@niivue/niivue@0.57.0/dist/index.js - Multiplanar + 3D rendering -
setSliceType(sliceTypeMultiplanar)+setMultiplanarLayout(2)
Key file: main.py (~485 lines) - complete working implementation.