hs2p

hs2p tiles whole-slide images at a requested physical resolution (microns per pixel), including resolutions absent from the image pyramid. Use the Python API in your own pipeline or the CLI for batch preprocessing. Both produce reproducible tile coordinates and can select tiles by tissue or annotation coverage.

Try the interactive demo to adjust tiling parameters and inspect grids and mask previews, including on your own pyramidal WSI (up to 1 GB).

Installation

Python 3.10 or newer is required. For whole-slide images read with OpenSlide:

pip install "hs2p[openslide]"

For flat PNG/JPEG slides, pip install hs2p is sufficient; supply their physical spacing with spacing_at_level_0. Flat masks need no spacing. See the backend guide for other readers, optional JPEG encoding, and SAM2 installation.

Workflows

Tiling computes a grid over tissue, using a supplied mask or segmenting tissue on the fly. Masks can have a different resolution from the slide. To prepare masks in advance, use the tissue-mask generation script.

Annotation sampling selects tiles by label coverage and writes per-class or merged coordinates.

Python quick start

from pathlib import Path

from hs2p import (
    SegmentationConfig,
    SlideSpec,
    TilingConfig,
    save_tiling_result,
    tile_slide,
    write_tiling_preview,
)

result = tile_slide(
    SlideSpec(
        sample_id="slide-1",
        image_path=Path("/data/wsi/slide-1.tif"),
        # Optional: omit to segment tissue on the fly.
        mask_path=Path("/data/mask/slide-1-tissue-mask.tif"),
    ),
    tiling=TilingConfig(
        backend="openslide",
        mask_backend="openslide",
        requested_spacing_um=0.5,
        requested_tile_size_px=224,
        tolerance=0.07,
        overlap=0.0,
        min_coverage={"tissue": 0.1},
    ),
    segmentation=SegmentationConfig(method="hsv", downsample=64),
)

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

if result.x.size:
    print(artifacts.coordinates_npz_path)  # output/tiles/slide-1.coordinates.npz
    write_tiling_preview(result=result, output_dir=Path("output"), downsample=32)

tile_slide() returns an in-memory TilingResult; tile_slides() processes a batch and saves its results. See the API guide for result fields, batch processing, and artifact loading.

CLI quick start

Create slides.csv with a unique sample_id and an image_path for each slide. mask_path is optional for tissue tiling:

sample_id,image_path,mask_path
slide-1,/data/wsi/slide-1.tif,/data/mask/slide-1-tissue-mask.tif
slide-2,/data/wsi/slide-2.tif,

Save this as config.yaml; omitted settings inherit the default config:

csv: slides.csv
output_dir: output
tiling:
  backend: openslide
  params:
    requested_spacing_um: 0.5
    requested_tile_size_px: 224

Run:

hs2p config.yaml

Results go into a dated subdirectory of output. Annotation sampling uses the same command and CSV schema, with a required annotation mask_path and label settings under tiling.masks. See the CLI guide for sampling, previews, tile export, and resume.

Outputs

Each non-empty result saves .coordinates.npz arrays and .coordinates.meta.json metadata. Empty results save metadata only. Coordinates are in level-0 pixels, sorted by numeric x, then y.

Tissue tiling writes under tiles/; annotation sampling can write under tiles/<annotation>/ or merge results under tiles/. Batch runs also write process_list.csv. The artifact reference describes paths, fields, and reuse compatibility.

Docker

Run the CLI in the published container:

docker pull waticlems/hs2p:latest
docker run --rm -v /path/to/your/data:/data \
  waticlems/hs2p:latest hs2p /data/config.yaml

Use paths inside the container in the CSV and config, and set output_dir under /data to retain results on the host. The mounted output directory must be writable by the container user.

Continue with the documentation index for guides, benchmarks, and release notes.

Metadata

Release files for hs2p 5.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hs2p 5.0.0
File	Size	Uploaded
hs2p-5.0.0.tar.gz	217.3 kB	Sep 22, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for hs2p 5.0.0
File	Interpreter	ABI	Platform	Reset
hs2p-5.0.0-py3-none-any.whl 121.7 kB Sep 22, 2026	Python 3	none	any	Details

Total release size: 339.0 kB

Release files / hs2p-5.0.0.tar.gz

Download URL	hs2p-5.0.0.tar.gz
Size	217.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`72874f678bd831fec5128af1b7485355c9851980d6d2fed2f25d447a3e0a5531`
BLAKE2b-256 checksum How to use checksums	`2e6fcf9593d37c7d97a8ee481d417c392980618d8929f3e9a6b2ffe5706e1e67`
Upload date	Sep 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.16`

Release files / hs2p-5.0.0-py3-none-any.whl

Download URL	hs2p-5.0.0-py3-none-any.whl
Size	121.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`eea898168ccb9adbe940b99d8f789437e1ff8bc0dbc7ba0eba2f0a77a4a6ccf7`
BLAKE2b-256 checksum How to use checksums	`53ba36cbd749c98a19faee5d3e2347274536ff6b1abf401d885df6586cb96432`
Upload date	Sep 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.16`