wsi-toolbox 0.1.1

A comprehensive toolkit for Whole Slide Image processing, feature extraction, and clustering analysis

WSI Toolbox

A comprehensive toolkit for Whole Slide Image (WSI) processing, feature extraction, and clustering analysis.

Installation

From PyPI

pip install wsi-toolbox

For development

# Clone repository
git clone https://github.com/endaaman/WSI-toolbox.git
cd WSI-toolbox

# Install dependencies
uv sync

Note: For gigapath slide-level encoder (CLI only):

# For flash-attn (requires CUDA, takes time to build)
uv sync --extra build
uv sync --extra build --extra compile

# Then install gigapath (uv-only dependency group, not available via PyPI)
uv sync --group gigapath

Quick Start

As a Python Library

import wsi_toolbox as wt

# Basic workflow
wt.set_default_model_preset('uni')
cmd = wt.Wsi2HDF5Command(patch_size=256)
result = cmd('input.ndpi', 'output.h5')

See README_API.md for comprehensive API documentation (detailed examples, command patterns, utilities, etc.)

As a CLI Tool

# Convert WSI to HDF5
wsi-toolbox wsi2h5 --in input.ndpi --out output.h5 --patch-size 256

# Extract features
wsi-toolbox embed --in output.h5 --model uni

# Clustering
wsi-toolbox cluster --in output.h5 --resolution 1.0

# For all commands
wsi-toolbox --help

Streamlit Web Application

uv run task app

HDF5 File Structure

WSI-toolbox stores all data in a single HDF5 file:

# Core data
'patches'                      # Patch images: [N, H, W, 3], e.g., [3237, 256, 256, 3]
'coordinates'                  # Patch pixel coordinates: [N, 2]

# Metadata
'metadata/original_mpp'        # Original microns per pixel
'metadata/original_width'      # Original image width (level=0)
'metadata/original_height'     # Original image height (level=0)
'metadata/image_level'         # Image level used (typically 0)
'metadata/mpp'                 # Output patch MPP
'metadata/scale'               # Scale factor
'metadata/patch_size'          # Patch size (e.g., 256)
'metadata/patch_count'         # Total patch count
'metadata/cols'                # Grid columns
'metadata/rows'                # Grid rows

# Model features (per model: uni, gigapath, virchow2)
'{model}/features'             # Patch features: [N, D]
                               #   uni: [N, 1024]
                               #   gigapath: [N, 1536]
                               #   virchow2: [N, 2560]
'{model}/latent_features'      # Latent features (optional): [N, K, K, D]
'{model}/clusters'             # Cluster labels: [N]

# Gigapath slide-level (CLI only)
'gigapath/slide_feature'       # Slide-level features: [768]

Features

• WSI processing (.ndpi, .svs, .tiff → HDF5)
• Feature extraction (UNI, Gigapath, Virchow2)
• Leiden clustering with UMAP visualization
• Preview generation (cluster overlays, latent PCA)
• Type-safe command pattern with Pydantic results
• CLI, Python API, and Streamlit GUI

Documentation

• API Guide - Comprehensive Python API documentation (日本語)
• CLAUDE.md - Development guidelines

Development

Setup Development Environment

# Clone repository
git clone https://github.com/endaaman/wsi-toolbox.git
cd wsi-toolbox

# Install all dependencies
uv sync

# Install with optional gigapath support (uv-only dependency group)
uv sync --group gigapath

# Install build tools
uv sync --group build

Run Tests and Development Tools

# Run CLI
uv run wsi-toolbox --help

# Run Streamlit app
uv run task app

# Run watcher
uv run task watcher

Code Quality (Linting)

This project uses Ruff for linting and code formatting.

# Install dev dependencies (includes ruff)
uv sync --group dev

# Check code quality
uv run ruff check wsi_toolbox/

# Auto-fix issues where possible
uv run ruff check wsi_toolbox/ --fix

# Format code
uv run ruff format wsi_toolbox/

# Check formatting without modifying files
uv run ruff format --check wsi_toolbox/

Note: Linting runs automatically on every push/PR via GitHub Actions.

Build and Deploy

Build Package

# Clean previous builds
uv run task clean

# Build package
uv run task build
# or
python -m build

# Check package integrity
uv run task check
# or
python -m twine check dist/*

Deploy to PyPI

Prerequisites: Install build tools first

uv sync --group build

Deploy:

# Using deploy script (recommended)
./deploy.sh

# Or manually
python -m build
python -m twine check dist/*
python -m twine upload dist/*

Note: Configure your PyPI credentials before deploying:

# Create ~/.pypirc with your API token
# Or use environment variables
export TWINE_USERNAME=__token__
export TWINE_PASSWORD=<your-pypi-token>

License

MIT