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

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.

downsample_factor

float

required

The ratio to scale down by.

bounded

bool

Whether to return tissue bounds or full slide size.

returns

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

Level

required

The target pyramid level (0 is highest resolution).

bounded

bool

If True, returns tissue area at that level.

returns

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.

magnification

float

required

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

bounded

bool

If True, returns tissue area at that magnification.

returns

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

mpp

float

required

Target microns per pixel.

bounded

bool

If True, returns tissue area at that MPP.

returns

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.

resolution

bool

Acts as the bounded toggle when a bool.

bounded

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.

resolution

Level

required

Target pyramid level.

bounded

bool

If True, returns tissue bounds.

dimensions

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

Returns slide dimensions at a magnification.

resolution

Magnification

required

Target optical magnification.

bounded

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.

resolution

MPP

required

Target microns per pixel.

bounded

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

Resolution

Desired resolution (Level, Magnification, or MPP).

bounded

bool

If True, returns tissue area at that resolution.

returns

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

Resolution

required

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.

level

int

required

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.

mpp

float

required

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.

magnification

float

required

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.

downsample

float

required

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]

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

resolution

Resolution

required

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.

location

tuple[int, int]

required

(x, y) at Level 0.

size

tuple[int, int]

required

(width, height) at target resolution.

resolution

Resolution

required

Resolution level/mpp/magnification.

measurement_unit

MeasurementUnit

Unit for the region shape (default pixels).

bounded

bool

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.

get_thumbnail

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

Generates a slide thumbnail.

size

tuple[int, int]

required

Max (width, height) for result.

bounded

bool

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)

​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