WSI Reader Base Module. This module provides the WSIReader abstract base class, which standardizes access to Whole Slide Images (WSI). It handles coordinate translations, resolution scaling (Level, Magnification, MPP), and tissue-aware cropping. Typical usage example: with OpenSlideReader(“path/to/slide.svs”) as reader:

Get tissue-only dimensions

dims = reader.dimensions(bounded=True)

Read a region relative to the slide origin

region = reader.read_region((0, 0), (512, 512), Level(0), bounded=False)

WSIReader

class WSIReader(ABC)

Abstract Base Class for all WSI Backends. Standardizes the interface for reading digital pathology slides across different vendors. It manages metadata, pyramid levels, and tissue bounding box transformations.

Path object pointing to the slide file.

Metadata properties extracted from the slide.

open_slide

@abstractmethod
def open_slide() -> None

Opens the file handle for the slide. Raises:

NotImplementedError — If not implemented by subclass.

level_count

@property
@abstractmethod
def level_count() -> int

Number of pyramid levels available in the slide.

int

Number of pyramid levels.

Raises:

NotImplementedError — If not implemented by subclass.

mpp

@property
def mpp() -> Union[MPP, None]

Native microns per pixel (MPP) value.

Optional[MPP]

The MPP value if found in metadata, else None.

Example:

>>> reader.mpp
0.25

downsample_dimensions

def downsample_dimensions(downsample_factor: float,
                          bounded: bool = True) -> Union[WSIDims, WSIBounds]

Calculates slide dimensions at a specific downsample factor.

float

required

The ratio to scale down by.

bool

Whether to return tissue bounds or full slide size.

Union[WSIDims, WSIBounds]

Union[WSIDims, WSIBounds]: Scaled slide dimensions or tissue bounds.

Example:

>>> reader.downsample_dimensions(4.0, bounded=False)
WSIDims(width=25000, height=20000)
>>> reader.downsample_dimensions(4.0, bounded=True)
WSIBounds(x=1250, y=500, width=25000, height=20000)

level_dimensions

def level_dimensions(level: Level,
                     bounded: bool = True) -> Union[WSIDims, WSIBounds]

Returns the dimensions of a specific pyramid level.

Level

required

The target pyramid level (0 is highest resolution).

bool

If True, returns tissue area at that level.

Union[WSIDims, WSIBounds]

Union[WSIDims, WSIBounds]: Dimensions or bounds at specified level.

Raises:

ValueError — If level is out of range.

Example:

>>> reader.level_dimensions(Level(2), bounded=False)
WSIDims(width=25000, height=20000)
>>> reader.level_dimensions(Level(2), bounded=True)
WSIBounds(x=1250, y=500, width=25000, height=20000)

magnification_dimensions

def magnification_dimensions(
        magnification: float,
        bounded: bool = True) -> Union[WSIDims, WSIBounds]

Returns slide dimensions for a specific optical magnification.

float

required

Target magnification (e.g., 40x, 20x, 10x).

bool

If True, returns tissue area at that magnification.

Union[WSIDims, WSIBounds]

Union[WSIDims, WSIBounds]: Dimensions or bounds at specified magnification.

Example:

>>> reader.magnification_dimensions(10.0, bounded=False)
WSIDims(width=25000, height=20000)
>>> reader.magnification_dimensions(10.0, bounded=True)
WSIBounds(x=1250, y=500, width=25000, height=20000)

mpp_dimensions

def mpp_dimensions(mpp: float,
                   bounded: bool = True) -> Union[WSIDims, WSIBounds]

Returns slide dimensions for a specific MPP (microns per pixel).

float

required

Target microns per pixel.

bool

If True, returns tissue area at that MPP.

Union[WSIDims, WSIBounds]

Union[WSIDims, WSIBounds]: Dimensions or bounds at specified MPP.

Example:

>>> reader.mpp_dimensions(1.0, bounded=False)
WSIDims(width=25000, height=20000)
>>> reader.mpp_dimensions(1.0, bounded=True)
WSIBounds(x=1250, y=500, width=25000, height=20000)

dimensions

@overload
def dimensions(resolution: bool = True,
               bounded: bool = True) -> Union[WSIDims, WSIBounds]

Returns full or bounded slide dimensions at Level 0.

bool

Acts as the bounded toggle when a bool.

bool

If True, returns tissue bounds.

dimensions

@overload
def dimensions(resolution: Level,
               bounded: bool = True) -> Union[WSIDims, WSIBounds]

Returns slide dimensions at a pyramid level.

Level

required

Target pyramid level.

bool

If True, returns tissue bounds.

dimensions

@overload
def dimensions(resolution: Magnification,
               bounded: bool = True) -> Union[WSIDims, WSIBounds]

Returns slide dimensions at a magnification.

Magnification

required

Target optical magnification.

bool

If True, returns tissue bounds.

dimensions

@overload
def dimensions(resolution: MPP,
               bounded: bool = True) -> Union[WSIDims, WSIBounds]

Returns slide dimensions at a target MPP.

MPP

required

Target microns per pixel.

bool

If True, returns tissue bounds.

dimensions

def dimensions(resolution: Union[Resolution, bool] = True,
               bounded: bool = True) -> Union[WSIDims, WSIBounds]

Returns slide dimensions for a specific resolution.

Resolution

Desired resolution (Level, Magnification, or MPP).

bool

If True, returns tissue area at that resolution.

Union[WSIDims, WSIBounds]

Union[WSIDims, WSIBounds]: Dimensions or bounds at specified resolution.

Example:

>>> reader.dimensions(Resolution(level=2), bounded=False)
WSIDims(width=25000, height=20000)
>>> reader.dimensions(Resolution(level=2), bounded=True)
WSIBounds(x=1250, y=500, width=25000, height=20000)

>>> reader.dimensions(Resolution(magnification=10.0), bounded=False)
WSIDims(width=25000, height=20000)
>>> reader.dimensions(Resolution(magnification=10.0), bounded=True)
WSIBounds(x=1250, y=500, width=25000, height=20000)

>>> reader.dimensions(Resolution(mpp=1.0), bounded=False)
WSIDims(width=25000, height=20000)
>>> reader.dimensions(Resolution(mpp=1.0), bounded=True)
WSIBounds(x=1250, y=500, width=25000, height=20000)

get_downsample_factor

def get_downsample_factor(resolution: Resolution) -> float

Calculates the downsample factor for a given resolution.

Resolution

required

The target resolution (Level, Magnification, or MPP).

float

Downsample factor for the given resolution.

Example:

>>> reader.get_downsample_factor(Resolution(level=2))
4.0
>>> reader.get_downsample_factor(Resolution(magnification=10.0))
4.0
>>> reader.get_downsample_factor(Resolution(mpp=1.0))
4.0

level_downsample

@abstractmethod
def level_downsample(level: int) -> float

Returns downsample factor for a pyramid level.

int

required

Pyramid level index.

float

Downsample factor for the given level.

Raises:

NotImplementedError — If not implemented by subclass.

mpp_downsample

def mpp_downsample(mpp: float) -> float

Calculates downsample needed for target MPP.

float

required

Target microns per pixel.

float

Downsample factor for the target MPP.

Raises:

ValueError — If metadata is missing or target is too high-res.

Example:

>>> reader.mpp_downsample(1.0)
4.0

magnification_downsample

def magnification_downsample(magnification: float) -> float

Calculates downsample needed for target magnification.

float

required

Target magnification power.

float

Downsample factor for the target magnification.

Raises:

ValueError — If metadata is missing or target is out of range.

Example:

>>> reader.magnification_downsample(10.0)
4.0

props

@property
def props() -> WSIProps

Slide metadata properties.

WSIProps

Metadata extracted from the slide.

Example:

>>> reader.props.OBJECTIVE_POWER
40

get_best_level_for_downsample

def get_best_level_for_downsample(downsample: float) -> int

Finds highest pyramid level smaller than target downsample factor.

float

required

Target scaling factor.

int

Best pyramid level index for the downsample.

Raises:

ValueError — If downsample is too small.

Example:

>>> reader.get_best_level_for_downsample(4.0)
2

get_downsample_scaling_and_level

def get_downsample_scaling_and_level(
        resolution: Resolution) -> tuple[float, float, int]

Determine the downsample factor, scaling factor, and best pyramid level for a given resolution.

Resolution

required

Desired resolution of the slide. Can be one of: - Level: integer pyramid level - Magnification: desired optical magnification - MPP: microns per pixel

tuple

(downsample_factor (float), scaling_factor (float), best_level (int)) - downsample_factor: Factor by which the base level is downsampled. - scaling_factor: Additional scaling needed at the chosen level. - best_level: Pyramid level that best matches the resolution.

Raises:

ValueError — If required slide properties (objective power or MPP) are unavailable.
TypeError — If the resolution type is unsupported.

Example:

>>> reader.get_downsample_scaling_and_level(Level(2))
(4.0, 1.0, 2)

read_region

def read_region(location: tuple[int, int],
                size: tuple[int, int],
                resolution: Resolution,
                measurement_unit: MeasurementUnit = MeasurementUnit.PIXELS,
                bounded: bool = True) -> Region

Reads a region from the slide.

tuple[int, int]

required

(x, y) at Level 0.

tuple[int, int]

required

(width, height) at target resolution.

Resolution

required

Resolution level/mpp/magnification.

MeasurementUnit

Unit for the region shape (default pixels).

bool

If True, (0,0) is tissue top-left. Else slide top-left.

Region

Object containing the image and metadata for the requested area.

Example:

>>> region = reader.read_region((0, 0), (512, 512), Level(0), bounded=False)
>>> region = reader.read_region((0, 0), (512, 512), Level(0), bounded=True)

is_supported_file

@abstractmethod
def is_supported_file() -> bool

Checks if backend supports this file extension.

bool

True if supported, False otherwise.

Raises:

NotImplementedError — If not implemented by subclass.

close

@abstractmethod
def close() -> None

Closes slide file handle. Returns: None Raises:

NotImplementedError — If not implemented by subclass.

get_thumbnail

def get_thumbnail(size: tuple[int, int], bounded: bool = True) -> Image.Image

Generates a slide thumbnail.

tuple[int, int]

required

Max (width, height) for result.

bool

If True, crop to tissue. Else show full slide (incl. white space).

Image.Image

RGB thumbnail image.

Example:

>>> reader.get_thumbnail((1024, 1024), bounded=False)
>>> reader.get_thumbnail((1024, 1024), bounded=True)

Overview

Get Started

Preprocessing

Workflows

Reference

bioptimus.io.wsi.interface

Get tissue-only dimensions

Read a region relative to the slide origin

WSIReader

open_slide

level_count

mpp

downsample_dimensions

level_dimensions

magnification_dimensions

mpp_dimensions

dimensions

dimensions

dimensions

dimensions

dimensions

get_downsample_factor

level_downsample

mpp_downsample

magnification_downsample

props

get_best_level_for_downsample

get_downsample_scaling_and_level

read_region

is_supported_file

close

get_thumbnail

​Get tissue-only dimensions

​Read a region relative to the slide origin

​WSIReader

​open_slide

​level_count

​mpp

​downsample_dimensions

​level_dimensions

​magnification_dimensions

​mpp_dimensions

​dimensions

​dimensions

​dimensions

​dimensions

​dimensions

​get_downsample_factor

​level_downsample

​mpp_downsample

​magnification_downsample

​props

​get_best_level_for_downsample

​get_downsample_scaling_and_level

​read_region

​is_supported_file

​close

​get_thumbnail

Get tissue-only dimensions

Read a region relative to the slide origin

WSIReader

open_slide

level_count

mpp

downsample_dimensions

level_dimensions

magnification_dimensions

mpp_dimensions

dimensions

dimensions

dimensions

dimensions

dimensions

get_downsample_factor

level_downsample

mpp_downsample

magnification_downsample

props

get_best_level_for_downsample

get_downsample_scaling_and_level

read_region

is_supported_file

close

get_thumbnail