drug-discovery-prompts/upstream/K-Dense-AI-scientific-agent-skills/skills/histolab/references/slide_management.md

title, task, lineage_type, upstream_source, upstream_sha, imported_at, prompt_class, upstream_changes, author, validated

title	task	lineage_type	upstream_source	upstream_sha	imported_at	prompt_class	upstream_changes	author	validated
Slide Management		import	https://github.com/K-Dense-AI/scientific-agent-skills/blob/9c9bd2e9/skills/histolab/references/slide_management.md	9c9bd2e9	2026-06-27	prompt	accepted	upstream	false

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

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:

uv pip install pooch

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

# 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

# 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

# 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

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

# 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

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

# 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

# Get slide filename without extension
slide_name = slide.name

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

Best Practices

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

Common Workflows

Slide Inspection Workflow

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

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}")