A modern, web-based whole-slide image (WSI) viewer for digital pathology and medical imaging, built with FastAPI, Vue.js, OpenSeadragon, and VTK.js. View pathology slides and NIfTI medical images directly in your browser!
- 🔬 High-Performance Viewing: Smooth pan/zoom of gigapixel pathology images using OpenSeadragon
- 📏 Smart Scale Bar: Automatic scale bar with µm/mm measurements based on slide metadata
- 🖼️ Thumbnails: Fast preview generation with viewport-aware lazy loading and concurrency limits
- 📊 Metadata Display: View slide properties, scanner info, resolution, and associated images
- 🧠 3D Visualization: Browser-based NIfTI file viewing with VTK.js
- 🔄 Multi-Planar Reconstruction: Axial, Coronal, and Sagittal views
- 🎨 Window/Level Adjustment: Real-time brightness and contrast control
- 🖱️ Interactive Navigation: Zoom, pan, and slice browsing
- 📥 Download & Integration: Direct download or open in ITK-SNAP/3D Slicer
- 🗂️ File Browser: Hierarchical folder navigation with search and filtering
- 🚀 Redis Caching: Shared Redis backend for tiles, thumbnails, directory trees, and path resolution across workers
- 💾 Fallback Cache: Local pickle-based LRU path cache if Redis is disabled
- 🎯 Modern Stack: Python 3.13, FastAPI, Vue.js 3, VTK.js, and containerized deployment
- 🔒 Production Ready: Docker setup with health checks, non-root user, and optimized builds
Click to view screenshots
Browse slides and medical images with thumbnails and file information
Pan/zoom with scale bar, metadata panel, and associated images
Browser-based 3D medical image visualization with multi-planar reconstruction
🚀 5-Minute Quick Start: See DOCKER_QUICKSTART.md
- Clone the repository
git clone https://github.com/KatherLab/wsi-browser.git
cd wsi-browser- Configure your slide directories
Edit docker-compose.yml to mount your slide directories:
volumes:
- /path/to/your/slides:/path/to/your/slides:ro
- /path/to/your/nifti:/path/to/your/nifti:roCreate a config.yml file (you can copy config.example.yml) to reference the mounted paths:
roots:
- path: "/path/to/your/slides"
label: "My Slides"
- path: "/path/to/your/nifti"
label: "Medical Images"
extensions:
- ".svs"
- ".nii"
- ".nii.gz"- Build and run
docker-compose build
docker-compose up -d-
Access the application Open your browser to:
http://localhost:8010 -
View NIfTI files Click on any
.niior.nii.gzfile to open the VTK.js 3D viewer in a new tab.
📚 Full Deployment Guide: See DEPLOYMENT.md and DEPLOYMENT_CHECKLIST.md
⚡ Quick Test: Run ./test_vtk_quick.ps1 (Windows) for automated testing.
- Install dependencies with uv
pip install uv
uv sync- Configure
config.yml
roots:
- path: "/path/to/slides"
label: "Slide Collection"
- path: "/path/to/nifti"
label: "Medical Images"
cache:
enabled: true
redis_url: "redis://localhost:6379/0"
extensions:
- ".svs"
- ".nii"
- ".nii.gz"- Run the application
# Development mode (auto-reload)
uv run uvicorn app.main:app --host 0.0.0.0 --port 8010 --reload
# Production mode (multiple workers)
uv run uvicorn app.main:app --host 0.0.0.0 --port 8010 --workers 4- Test NIfTI viewer
uv run python test_vtk_viewer.py# Slide directories to expose in the UI
roots:
- path: "/data/slides"
label: "Research Slides"
- path: "/data/clinical"
label: "Clinical Cases"
# Files/folders to exclude
exclude:
- "__pycache__"
- "*.tmp"
- ".git"
# Supported slide formats
extensions:
- ".svs" # Aperio
- ".tif" # Generic TIFF
- ".tiff"
- ".ndpi" # Hamamatsu
- ".scn" # Leica
- ".mrxs" # Mirax (includes .mrxs sidecar directory)
- ".bif" # Ventana
# Redis caching configuration
cache:
enabled: true
redis_url: "redis://redis:6379/0" # Use "redis" hostname in Docker
ttl_seconds:
tree: 60 # Directory tree cache
thumb: 86400 # Thumbnail cache (24h)
tile: 3600 # Tile cache (1h)
# Thumbnail generation
thumbnails:
max_px: 512 # Maximum thumbnail dimension
prefer_associated: true # Use embedded thumbnails when available
# CORS settings
cors_allow_origins: ["*"] # Restrict in productionwsi-browser/
├── app/
│ ├── __init__.py
│ ├── main.py # FastAPI application
│ ├── cache.py # Redis caching layer
│ ├── config.py # Configuration management
│ ├── dz.py # Deep Zoom tile generation
│ ├── fs_index.py # File system indexing
│ ├── models.py # Pydantic models
│ ├── thumbs.py # Thumbnail generation
│ ├── path_cache.py # Redis + LRU path cache
│ ├── templates/
│ │ ├── index.html # Vue.js frontend
│ │ ├── nifti_viewer_vtk.html # VTK.js 3D NIfTI viewer
│ │ └── nifti_viewer_simple.html # Simple NIfTI metadata viewer
│ └── static/
│ ├── logo.svg # Optional branding
│ └── logo.png
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
├── config.yml
├── test_vtk_viewer.py # VTK.js viewer tests
├── test_nifti_integration.py # NIfTI integration tests
├── VTK_VIEWER_README.md # VTK.js viewer documentation
├── NIFTI_INTEGRATION.md # NIfTI integration guide
└── README.md
| Endpoint | Description |
|---|---|
GET / |
Web UI |
GET /api/tree |
Directory tree structure |
GET /api/expand?path=... |
Expand a directory shallowly |
GET /api/dir?path=... |
List slides in directory |
GET /api/thumb/{slide_id} |
Slide thumbnail (with ETag caching) |
GET /api/meta/{slide_id} |
Slide metadata (with MIRAX sidecar size support) |
GET /api/associated/{slide_id} |
List associated images |
GET /api/associated/{slide_id}/{name} |
Get associated image |
GET /dzi/{slide_id}.dzi |
Deep Zoom descriptor (with ETag) |
GET /dzi/{slide_id}_files/{z}/{x}_{y}.jpeg |
Deep Zoom tiles (with ETag) |
GET /nifti-viewer?path=...&mode=vtk |
VTK.js 3D NIfTI viewer |
GET /api/nifti/file?path=... |
Serve NIfTI file as binary data |
GET /api/nifti/meta?path=... |
Get NIfTI file metadata |
GET /api/nifti/download?path=... |
Download NIfTI file |
GET /health |
Health check (reports Redis status) |
The application supports all formats readable by OpenSlide:
- Aperio (.svs, .tif)
- Hamamatsu (.ndpi, .vms, .vmu)
- Leica (.scn)
- MIRAX (.mrxs + sidecar directory)
- Philips (.tiff)
- Sakura (.svslide)
- Trestle (.tif)
- Ventana (.bif, .tif)
- Generic tiled TIFF (.tif, .tiff)
- NIfTI-1 (.nii) - Full 3D visualization support
- NIfTI-1 Gzip (.nii.gz) - Compressed format support
- DICOM (.dcm) - Metadata and download (OHIF integration planned)
- ✅ Browser-based 3D visualization (no software installation required)
- ✅ Multi-planar reconstruction (Axial/Coronal/Sagittal)
- ✅ Window/Level adjustment for optimal display
- ✅ Interactive zoom, pan, and slice navigation
- ✅ Fullscreen mode for detailed examination
- ✅ Direct download or open in desktop applications (ITK-SNAP, 3D Slicer)
For more details, see NIFTI_INTEGRATION.md and VTK_VIEWER_README.md.
- Redis: Stores tiles, thumbnails, directory trees, and path lookups (shared across workers)
- LRU Fallback: Local pickle cache if Redis is disabled
- TTL Configuration: Customizable expiration times for tiles and thumbnails
- On-demand validation: Path entries checked for existence on access; stale entries evicted
- Multiple Workers: 4+ Uvicorn workers recommended
- Read-only Mounts: Slide directories mounted read-only
- Health Checks:
/healthendpoint for container monitoring - Non-root User: Enhanced security in containers
-
Set
maxmemoryandmaxmemory-policy allkeys-lruin your Redis config to prevent out-of-memory errors:maxmemory 2gb maxmemory-policy allkeys-lru
-
Mount slides with
:roto enforce read-only access -
Tune NFS mount options for throughput:
nfsvers=3,rsize=262144,wsize=262144,hard,noatime
Slides not appearing
- Check file extensions in
config.yml - Verify directory permissions
- Confirm Docker volume mounts
Performance issues
- Increase Redis memory limit in
docker-compose.yml - Adjust worker count based on CPU cores
- Ensure NFS mount options are tuned (
noatime, largerrsize/wsize)
Connection errors
docker-compose ps
docker-compose logs -f
docker-compose exec redis redis-cli ping
curl http://localhost:8010/health- Backend: modify
app/Python modules - Frontend: edit
app/templates/index.html - Rebuild:
docker-compose build && docker-compose up -d
uv sync --dev
uv run pytest
uv run ruff check app/
uv run mypy app/- Restrict CORS origins in
config.yml - Set up SSL/TLS termination (nginx/traefik)
- Configure monitoring (Prometheus/Grafana)
- Use log aggregation
- Add authentication if needed
- Set up Redis persistence/backups if required
- External Redis cluster for large deployments
- Multiple app instances behind load balancer
- CDN for static assets
- Distributed file system (NFS/GlusterFS) for slides
This project is licensed under the MIT License - see the LICENSE file for details.
- OpenSlide - C library for reading WSI files
- OpenSeadragon - Deep zoom image viewer
- VTK.js - 3D visualization library
- ITK-WASM - Medical image format parsing
- FastAPI - Modern Python web framework
- Vue.js - Progressive JavaScript framework
- ITK-SNAP - Medical image segmentation tool
- 3D Slicer - Medical image analysis platform
For issues and questions:
- Open an issue on GitHub
- Check existing issues for solutions
- Provide logs and configuration when reporting bugs
📑 Complete Index: See DOCUMENTATION_INDEX.md for a searchable documentation index.
- DOCKER_QUICKSTART.md - 5-minute Docker deployment guide
- DEPLOYMENT.md - Complete deployment guide (local, Docker, production)
- DEPLOYMENT_CHECKLIST.md - Pre-deployment checklist
- NIFTI_INTEGRATION.md - NIfTI file integration guide
- VTK_VIEWER_README.md - VTK.js 3D viewer documentation
- VTK_VIEWER_TEST_GUIDE.md - Testing guide for VTK.js viewer
- IMPLEMENTATION_SUMMARY.md - Technical implementation details
- SDK_USAGE.md - SDK usage guide
- ACCESS_GUIDE.html - Access guide
- RUNNING_GUIDE.md - Running guide