wsi_dataset

WSI Data & Dataset Module. Provides WSIData (single-slide wrapper) and WSIDataset (multi-slide collection) that bridge the bioptimus I/O + extraction layers into structures ready for feature extraction or training. Typical usage:

from bioptimus.data.wsi import WSIData, WSIDataset
from bioptimus.extraction.wsi.tile_extraction import TileExtractor
from bioptimus.extraction.wsi.types import TileSpec
from bioptimus.io.wsi.types import Level, MeasurementUnit

spec = TileSpec(size=(256, 256), stride=(256, 256), resolution=Level(0), unit=MeasurementUnit.PIXELS)
extractor = TileExtractor(tile_spec=spec, mask_threshold=0.5)

dataset = WSIDataset.from_paths(
    paths=["slide_1.svs", "slide_2.svs"],
    extractor=extractor,
)

# Iterate over all patches (flat indexing across slides)
for i in range(len(dataset)):
    patch, meta = dataset[i]  # np.ndarray (H, W, C), dict

WSIData

class WSIData()

Wraps a single Whole Slide Image with its extraction plan. On construction the slide is opened via WSI and the extractor is fitted + executed to produce a list of RegionSpec. Each spec describes one tile/patch location. Patches are read lazily via get_patch.

Path to the WSI file (any format supported by WSI).

A configured TileExtractor. A fresh fit_extract is called for every slide so the same extractor object can be reused across slides.

Optional callable applied to the raw np.ndarray patch before it is returned. Receives (H, W, C) uint8 and should return a transformed array (or tensor).

Path

Resolved slide path.

WSIReader

Open reader for the slide.

List[RegionSpec]

Extraction plan (one entry per patch).

str

Stem of the slide filename.

Example:

wsi = WSIData("tissue.svs", extractor)
patch, meta = wsi.get_patch(0)

get_patch

def get_patch(idx: int) -> Tuple[Any, Dict[str, Any]]

Reads a single patch from the slide.

int

required

Index into specs.

Tuple[Any, Dict[str, Any]]

A tuple (patch, metadata) where patch is an np.ndarray of shape (H, W, C) (or whatever the transform returns), and metadata is a dict with at minimum source, x, y, width, height, slide_name, and tissue_ratio.

Raises:

IndexError — If idx is out of range.

close

def close() -> None

Closes the underlying WSI reader and releases resources. Example:

>>> wsi.close()

WSIDataset

class WSIDataset()

A collection of WSIData wrappers with flat patch indexing. Supports two access patterns:

Slide-level — dataset.slides[i] returns a WSIData.
Patch-level (flat) — dataset[k] maps a global patch index across all slides and returns (patch, metadata).

The flat indexing uses a cumulative-sum lookup (O(log N) via bisect) so random access is fast regardless of how many slides are loaded.

Pre-built WSIData instances.

Example:

dataset = WSIDataset.from_paths(paths, extractor)
len(dataset)            # total patch count across all slides
patch, meta = dataset[42]
slide = dataset.slides[0]

from_paths

@classmethod
def from_paths(
        cls,
        paths: Sequence[Union[str, Path]],
        extractor: TileExtractor,
        transform: Optional[Callable[[np.ndarray], Any]] = None) -> WSIDataset

Creates a dataset by opening and extracting every slide.

Sequence[Union[str, Path]]

required

Iterable of WSI file paths.

TileExtractor

required

Shared TileExtractor (re-fitted per slide).

Optional[Callable[[np.ndarray], Any]]

Optional callable applied to each extracted tile array.

WSIDataset

A new WSIDataset.

Example:

dataset = WSIDataset.from_paths(glob.glob("slides/*.svs"), extractor)

num_slides

@property
def num_slides() -> int

Returns the number of loaded slides.

int

Slide count.

Example:

>>> dataset.num_slides
3

slide_patch_counts

def slide_patch_counts() -> Dict[str, int]

Returns a mapping of slide names to their patch counts.

Dict[str, int]

Dict[str, int]: {slide_name: patch_count} for every slide.

Example:

>>> dataset.slide_patch_counts()
{'slide_001': 150, 'slide_002': 350}

close

def close() -> None

Closes all underlying WSI readers. Example:

>>> dataset.close()

Overview

Get Started

Preprocessing

Workflows

Reference

WSIData

get_patch

close

WSIDataset

from_paths

num_slides

slide_patch_counts

close

​WSIData

​get_patch

​close

​WSIDataset

​from_paths

​num_slides

​slide_patch_counts

​close

WSIData

get_patch

close

WSIDataset

from_paths

num_slides

slide_patch_counts

close