bioptimus.io.wsi.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(index: int)

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

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, got -1.

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(value: float)

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 a finite number strictly greater than 0 (NaN and infinity are rejected).

The pixel size in microns to represent as MPP.

Raises:

ValueError - If value is not a finite positive number.

Example:

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

Magnification

class Magnification(value: 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 finite positive float (NaN and infinity are rejected). Typical magnifications:

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

The objective power.

Raises:

ValueError - If value is not a finite positive number.

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 a finite positive number, got -10.0.

WSIDims

class WSIDims(NamedTuple)

Dimensions of a slide or level at full resolution. Attributes:

width int - The width of the image in pixels.
height 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. Attributes:

x int - The X coordinate of the top-left corner.
y int - The Y coordinate of the top-left corner.
width int - The width of the bounding box.
height 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. Returns:

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.

The string to check.

Returns:

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

top int - The top coordinate of the top-left corner of the region.
left int - The left coordinate of the top-left corner of the region.
width int - The width of the region in pixels.
height 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. Attributes:

width int - The width of the region in pixels.
height int - The height of the region in pixels.
unit 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. Returns: tuple[int, int]: A tuple containing (width, height).

to_um

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

Converts pixels to microns.

The pixel count to convert.

The microns-per-pixel scale.

Returns:

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.

The length in microns to convert.

The microns-per-pixel scale.

Returns:

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

ratio float - Pixels belonging to the mask relative to the total region area.
mask 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. Attributes:

location RegionLocation - The location of the region within the slide.
shape RegionShape - The shape of the region.
resolution 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. Attributes:

image PIL.Image.Image - The pixel data of the region as a PIL Image.
spec RegionSpec - The specifications of the region, including location, shape, resolution, and mask.

Example:

>>> from PIL import Image
>>> img = Image.new('RGB', (500, 500))  # create a 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. Returns: 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

Troubleshooting

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