hs2p

A Python package for preprocessing whole-slide images into reproducible grids of tile coordinates. Handles any requested spacing, even when it doesn’t natively exist in the image pyramid.

Installation

pip install hs2p

Quick start

from pathlib import Path
from hs2p import (
    FilterConfig, SegmentationConfig, TilingConfig,
    WholeSlide, save_tiling_result, tile_slide,
)

result = tile_slide(
    WholeSlide(
        sample_id="slide-1",
        image_path=Path("/data/wsi/slide-1.tif"),
        mask_path=Path("/data/mask/slide-1.tif"),
    ),
    tiling=TilingConfig(
        target_spacing_um=0.5,
        target_tile_size_px=224,
        tissue_threshold=0.1,
    ),
    segmentation=SegmentationConfig(downsample=64),
    filtering=FilterConfig(ref_tile_size=224, a_t=4, a_h=2),
)

artifacts = save_tiling_result(result, output_dir=Path("output"))
print(artifacts.tiles_npz_path)   # coordinates/slide-1.tiles.npz
print(artifacts.tiles_meta_path)  # coordinates/slide-1.tiles.meta.json

Outputs

• coordinates/{sample_id}.tiles.npz — tile coordinate array (deterministic column-major order)
• coordinates/{sample_id}.tiles.meta.json — extraction metadata
• process_list.csv on batch runs — tracks per-slide processing status (success, failure, skip) for easy auditing
• optional tiling preview and tissue mask overlay images for visual QC

Features

• Reproducible coordinate grids at any spacing, including non-native resolutions
• Built-in tissue segmentation or pre-extracted mask support
• Tile filtering and partitioning based on annotation or tissue coverage
• Docker support