types

Core types for representing resolutions and regions in Whole Slide Images (WSIs). This module defines lightweight, immutable classes for commonly used WSI attributes such as pyramid levels, physical pixel size (MPP), and objective magnification. Classes:

Level — Pyramid level index (0 = highest resolution).
MPP — Microns per pixel (µm/pixel).
Magnification — Objective power (e.g., 20x).
WSIDims — Width and height dimensions.
WSIBounds — A bounding box for tissue regions.
MeasurementUnit — Enum for pixels or microns.
RegionLocation — X/Y coordinates of a region.
RegionShape — Dimensions and units of a region.
RegionSpec — Full specification (Location + Shape + Resolution).
Region — Container for PIL image data and its RegionSpec.

Level

class Level(int)

Represents a pyramid level index in a WSI. Level 0 is the highest resolution. Higher indices are lower resolutions.

int

The pyramid level index (0-based).

Raises:

ValueError — If index is negative.

Example:

>>> level = Level(0)   # highest resolution
>>> int(level)
0
>>> level
Level 0
>>> Level(-1)
Traceback (most recent call last):
    ...
ValueError: Level index must be >= 0

Notes:

Level 0 is the highest resolution.
Higher indices correspond to lower resolution levels in the pyramid.
This class stores the level index as a primitive integer and is immutable.

MPP

class MPP(float)

A positive float representing the physical size of a pixel in microns per pixel (µm/pixel) in a whole slide image (WSI). MPP values indicate the real-world size of one image pixel and must be strictly greater than 0.

float

The pixel size in microns to represent as MPP.

Raises:

ValueError — If value is not positive.

Example:

>>> mpp = MPP(0.25)  # 0.25 µm/pixel
>>> float(mpp)
0.25
>>> MPP(-1)
Traceback (most recent call last):
    ...
ValueError: MPP must be positive, got -1

Magnification

class Magnification(float)

Objective power of a microscope used to acquire a whole slide image (WSI). Magnification indicates the target resolution (e.g., 20x, 40x). It is always stored as a positive float. Typical magnifications:

10x: low-resolution overview
20x: standard diagnostic resolution
40x: high-resolution for detailed analysis

float

The objective power.

Raises:

ValueError — If value is not positive.

Example:

>>> mag = Magnification(40)  # 40x objective
>>> float(mag)
40.0
>>> mag
40.00x
>>> Magnification(20.0)
20.00x
>>> Magnification(-10)
Traceback (most recent call last):
    ...
ValueError: Magnification must be positive

WSIDims

class WSIDims(NamedTuple)

Dimensions of a slide or level at full resolution.

int

The width of the image in pixels.

int

The height of the image in pixels.

Example:

>>> dims = WSIDims(width=10000, height=20000)
>>> print(dims.width)
10000

WSIBounds

class WSIBounds(NamedTuple)

The non-empty region (Bounding Box) of the slide in pixels. This represents the “tissue-containing” area of a slide, allowing users to ignore large background areas.

int

The X coordinate of the top-left corner.

int

The Y coordinate of the top-left corner.

int

The width of the bounding box.

int

The height of the bounding box.

Example:

>>> bounds = WSIBounds(x=100, y=100, width=500, height=500)
>>> print(bounds.dims)
WSIDims(width=500, height=500)

dims

@property
def dims() -> WSIDims

Extracts width and height as a WSIDims object.

WSIDims

The dimensions of the bounding box.

Example:

>>> bounds = WSIBounds(x=10, y=20, width=100, height=200)
>>> bounds.dims
WSIDims(width=100, height=200)

MeasurementUnit

class MeasurementUnit(str, Enum)

Enumeration of measurement units for WSI tiles and regions.

has_value

@classmethod
def has_value(cls, value: str) -> bool

Checks if a string is a valid MeasurementUnit.

str

required

The string to check.

bool

True if valid, False otherwise.

Example:

>>> MeasurementUnit.has_value("PIXELS")
True
>>> MeasurementUnit.has_value("INCHES")
False

RegionLocation

@dataclass(frozen=True)
class RegionLocation()

Defines the location of a region within a WSI.

int

The top coordinate of the top-left corner of the region.

int

The left coordinate of the top-left corner of the region.

int

The width of the region in pixels.

int

The height of the region in pixels.

Example:

>>> location = RegionLocation(top=100, left=200)
>>> print(location.top)
100

x

@property
def x() -> int

Alias for left coordinate.

y

@property
def y() -> int

Alias for top coordinate.

RegionShape

@dataclass(frozen=True)
class RegionShape()

Defines the shape of a region within a WSI.

int

The width of the region in pixels.

int

The height of the region in pixels.

MeasurementUnit

The unit of measurement for the shape dimensions (e.g., PIXELS, UM).

Example:

>>> shape = RegionShape(width=500, height=500, unit=MeasurementUnit.PIXELS)
>>> print(shape.unit)
PIXELS
>>> print(shape.width)
500

shape

@property
def shape() -> tuple[int, int]

Returns the width and height as a tuple.

tuple[int, int]

tuple[int, int]: A tuple containing (width, height).

to_um

def to_um(mpp: MPP) -> "RegionShape"

Converts pixels to microns.

float

The pixel count to convert.

MPP

required

The microns-per-pixel scale.

float

The length in microns.

Example:

>>> unit = MeasurementUnit.PIXELS
>>> unit.pixels_to_um(100, MPP(0.5))
50.0

to_pixels

def to_pixels(mpp: MPP) -> "RegionShape"

Converts microns to pixels.

float

The length in microns to convert.

MPP

required

The microns-per-pixel scale.

float

The length in pixels.

Example:

>>> unit = MeasurementUnit.UM
>>> unit.um_to_pixels(50, MPP(0.5))
100.0

RegionMaskSpec

@dataclass(frozen=True)
class RegionMaskSpec()

Defines the mask applied/corresponding to the region e.g., during extraction can be binary or multiclass mask.

float

Pixels belonging to the mask relative to the total region area.

np.ndarray | None

The mask applied to the region, or None if mask storage was not requested.

RegionSpec

@dataclass(frozen=True)
class RegionSpec()

Defines the specifications of a region within a WSI.

RegionLocation

The location of the region within the slide.

RegionShape

The shape of the region.

Resolution

The resolution at which the region is defined (Level, MPP, or Magnification).

Example:

>>> location = RegionLocation(top=100, left=200)
>>> spec = RegionSpec(
...     location=location,
...     shape=RegionShape(width=500, height=500, unit=MeasurementUnit.PIXELS),
...     resolution=Level(0),
... )
>>> print(spec.location.left)
200

Region

@dataclass(frozen=True)
class Region()

Defines a region of interest within a WSI, including its image data and specifications. This class encapsulates both the pixel data of a region and its metadata, such as location, shape, and resolution.

PIL.Image.Image

The pixel data of the region as a PIL Image.

RegionSpec

The specifications of the region, including location, shape, resolution, and mask.

Example:

>>> from PIL import Image
>>> img = Image.new('RGB', (500, 500))  # blank image for demonstration
>>> location = RegionLocation(top=100, left=200)
>>> shape = RegionShape(width=500, height=500, unit=MeasurementUnit.PIXELS)
>>> mask_spec = RegionMaskSpec(mask=np.zeros((500, 500)), ratio=0.0)
>>> spec = RegionSpec(location=location, shape=shape, resolution=Level(0), mask_spec=mask_spec)
>>> region = Region(image=img, spec=spec)
>>> print(region.spec.location.left)
200

location

@property
def location() -> RegionLocation

Convenience property to access the region’s location directly.

shape

@property
def shape() -> tuple[int, int]

Convenience property to access the region’s shape directly.

resolution

@property
def resolution() -> Resolution

Convenience property to access the region’s resolution directly.

measurement_unit

@property
def measurement_unit() -> MeasurementUnit

Convenience property to access the region’s measurement unit directly.

mask

@property
def mask() -> Union[np.ndarray, None]

Convenience property to access the region’s mask directly.

Union[np.ndarray, None]

np.ndarray | None: The mask array, or None if mask storage was not requested during extraction.

mask_ratio

@property
def mask_ratio() -> float

Convenience property to access the region’s mask ratio directly.

Overview

Get Started

Preprocessing

Workflows

Reference

Level

MPP

Magnification

WSIDims

WSIBounds

dims

MeasurementUnit

has_value

RegionLocation

x

y

RegionShape

shape

to_um

to_pixels

RegionMaskSpec

RegionSpec

Region

location

shape

resolution

measurement_unit

mask

mask_ratio

​Level

​MPP

​Magnification

​WSIDims

​WSIBounds

​dims

​MeasurementUnit

​has_value

​RegionLocation

​x

​y

​RegionShape

​shape

​to_um

​to_pixels

​RegionMaskSpec

​RegionSpec

​Region

​location

​shape

​resolution

​measurement_unit

​mask

​mask_ratio

Level

MPP

Magnification

WSIDims

WSIBounds

dims

MeasurementUnit

has_value

RegionLocation

x

y

RegionShape

shape

to_um

to_pixels

RegionMaskSpec

RegionSpec

Region

location

shape

resolution

measurement_unit

mask

mask_ratio