bioptimus.data.wsi.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(path: Union[str, Path],
              extractor: TileExtractor,
              transform: Optional[Callable[[np.ndarray], Any]] = None)

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).

Attributes:

path Path - Resolved slide path.
reader WSIReader - Open reader for the slide.
specs List[RegionSpec] - Extraction plan (one entry per patch).
slide_name str - Stem of the slide filename.

Example:

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

len

def __len__() -> int

Returns the number of patches in the extraction plan. Returns:

int - Total patch count for this slide.

Example:

>>> wsi = WSIData("slide.svs", extractor)
>>> len(wsi)
150

get_patch

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

Reads a single patch from the slide.

Index into specs.

Returns: 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(data_list: List[WSIData])

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.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.

Iterable of WSI file paths.

Shared TileExtractor (re-fitted per slide).

Optional callable applied to each extracted tile array.

Returns: A new WSIDataset. Example:

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

len

def __len__() -> int

Returns the total number of patches across all slides. Returns:

int - Global patch count.

Example:

>>> len(dataset)
500

getitem

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

Returns (patch, metadata) for a global patch index.

Global patch index (0-based).

Raises:

IndexError - If idx is out of range.

num_slides

@property
def num_slides() -> int

Returns the number of loaded slides. Returns:

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. Returns: 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

Troubleshooting

Reference

WSIData

len

get_patch

close

WSIDataset

from_paths

len

getitem

num_slides

slide_patch_counts

close

​WSIData

​__len__

​get_patch

​close

​WSIDataset

​from_paths

​__len__

​__getitem__

​num_slides

​slide_patch_counts

​close

WSIData

len

get_patch

close

WSIDataset

from_paths

len

getitem

num_slides

slide_patch_counts

close