Slide Management

Overview

The Slide class is the primary interface for working with whole slide images (WSI) in histolab. It provides methods to load, inspect, and process large histopathology images stored in various formats.

Initialization

python

from histolab.slide import Slide

# Initialize a slide with a WSI file and output directory
slide = Slide("path/to/slide.svs", processed_path="path/to/processed/output")

Parameters:

path: Path to the whole slide image file (supports multiple formats: SVS, TIFF, NDPI, etc.)
processed_path: Directory where processed outputs (tiles, thumbnails, etc.) will be saved
use_largeimage (optional): Use large_image for multi-format backends and mpp-based extraction

Loading Sample Data

Histolab provides built-in sample datasets from TCGA for testing and demonstration. Install pooch to download them:

bash

uv pip install pooch

python

from histolab.data import prostate_tissue, ovarian_tissue, breast_tissue, heart_tissue, kidney_tissue

# Load prostate tissue sample
prostate_svs, prostate_path = prostate_tissue()
slide = Slide(prostate_path, processed_path="output/")

Available sample datasets:

prostate_tissue(): Prostate tissue sample
ovarian_tissue(): Ovarian tissue sample
breast_tissue(): Breast tissue sample
heart_tissue(): Heart tissue sample
kidney_tissue(): Kidney tissue sample

Key Properties

Slide Dimensions

python

# Get slide dimensions at level 0 (highest resolution)
width, height = slide.dimensions

# Get dimensions at specific pyramid level
level_dimensions = slide.level_dimensions
# Returns tuple of (width, height) for each level

Magnification Information

python

# Get base magnification (e.g., 40x, 20x)
base_mag = slide.base_mpp  # Microns per pixel at level 0

# Get all available levels
num_levels = slide.levels  # Number of pyramid levels

Slide Properties

python

# Access OpenSlide properties dictionary
properties = slide.properties

# Common properties include:
# - slide.properties['openslide.objective-power']: Objective power
# - slide.properties['openslide.mpp-x']: Microns per pixel in X
# - slide.properties['openslide.mpp-y']: Microns per pixel in Y
# - slide.properties['openslide.vendor']: Scanner vendor

Thumbnail Generation

python

from pathlib import Path

# Get thumbnail at default size
thumbnail = slide.thumbnail

# Save thumbnail to processed_path
Path(slide.processed_path).mkdir(parents=True, exist_ok=True)
slide.thumbnail.save(Path(slide.processed_path) / f"{slide.name}_thumbnail.png")

# Get scaled thumbnail
scaled_thumbnail = slide.scaled_image(scale_factor=32)

Slide Visualization

python

# Display slide thumbnail with matplotlib
import matplotlib.pyplot as plt

plt.figure(figsize=(10, 10))
plt.imshow(slide.thumbnail)
plt.title(f"Slide: {slide.name}")
plt.axis('off')
plt.show()

Extracting Regions

python

from histolab.types import CoordinatePair

# Extract a tile at specific coordinates and level
tile = slide.extract_tile(
    coords=CoordinatePair(x_ul=x, y_ul=y, x_br=x + width, y_br=y + height),
    tile_size=(width, height),
    level=0,
)
region = tile.image

Working with Pyramid Levels

WSI files use a pyramidal structure with multiple resolution levels:

Level 0: Highest resolution (native scan resolution)
Level 1+: Progressively lower resolutions for faster access

python

# Check available levels
for level in range(slide.levels):
    dims = slide.level_dimensions[level]
    downsample = slide.level_downsamples[level]
    print(f"Level {level}: {dims}, downsample: {downsample}x")

Slide Name and Path

python

# Get slide filename without extension
slide_name = slide.name

# Get output directory for processed artifacts
output_dir = slide.processed_path

Best Practices

Always specify processed_path: Organize outputs in dedicated directories
Check dimensions before processing: Large slides can exceed memory limits
Use appropriate pyramid levels: Extract tiles at levels matching your analysis resolution
Preview with thumbnails: Use thumbnails for quick visualization before heavy processing
Monitor memory usage: Level 0 operations on large slides require significant RAM

Common Workflows

Slide Inspection Workflow

python

from histolab.slide import Slide

# Load slide
slide = Slide("slide.svs", processed_path="output/")

# Inspect properties
print(f"Dimensions: {slide.dimensions}")
print(f"Levels: {slide.levels}")
print(f"Magnification: {slide.properties.get('openslide.objective-power', 'N/A')}")

# Save thumbnail for review
from pathlib import Path
Path(slide.processed_path).mkdir(parents=True, exist_ok=True)
slide.thumbnail.save(Path(slide.processed_path) / f"{slide.name}_thumbnail.png")

Multi-Slide Processing

python

import os
from pathlib import Path

slide_dir = Path("slides/")
output_dir = Path("processed/")

for slide_path in slide_dir.glob("*.svs"):
    slide = Slide(slide_path, processed_path=output_dir / slide_path.stem)
    # Process each slide
    print(f"Processing: {slide.name}")