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(path: str)

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

path - Path object pointing to the slide file.
props - 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. Returns:

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

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.

The ratio to scale down by.

Whether to return tissue bounds or full slide size.

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

The target pyramid level (0 is highest resolution).

If True, returns tissue area at that level.

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

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

If True, returns tissue area at that magnification.

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

Target microns per pixel.

If True, returns tissue area at that MPP.

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

Acts as the bounded toggle when a 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.

Target pyramid level.

If True, returns tissue bounds.

dimensions

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

Returns slide dimensions at a magnification.

Target optical magnification.

If True, returns tissue bounds.

dimensions

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

Returns slide dimensions at a target MPP.

Target microns per pixel.

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.

Desired resolution (Level, Magnification, or MPP).

If True, returns tissue area at that resolution.

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

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

Returns:

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.

Pyramid level index.

Returns:

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.

Target microns per pixel.

Returns:

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.

Target magnification power.

Returns:

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

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.

Target scaling factor.

Returns:

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]

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

Desired resolution of the slide. Can be one of:

Level: integer pyramid level
Magnification: desired optical magnification
MPP: microns per pixel

Returns:

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.

(x, y) at Level 0.

(width, height) at target resolution.

Resolution level/mpp/magnification.

Unit for the region shape

pixels).

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

Returns:

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

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.

enter

def __enter__() -> "WSIReader"

Context manager entry. Returns:

WSIReader - The reader instance with slide file open.

Example:

>>> with SomeWSIReader("slide.svs") as reader:
...     dims = reader.dimensions()

exit

def __exit__(exc_type: Any, exc_value: Any, traceback: Any) -> None

Context manager exit.

Exception type.

Exception value.

Exception traceback.

Returns: None Example:

>>> with SomeWSIReader("slide.svs") as reader:
...     pass

get_thumbnail

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

Generates a slide thumbnail.

Max (width, height) for result.

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

Returns:

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

Troubleshooting

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

enter

exit

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

​__enter__

​__exit__

​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

enter

exit

get_thumbnail