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
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).
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
- 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
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.
The pixel size in microns to represent as MPP.
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)
- 10x: low-resolution overview
- 20x: standard diagnostic resolution
- 40x: high-resolution for detailed analysis
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)
The width of the image in pixels.
The height of the image in pixels.
>>> dims = WSIDims(width=10000, height=20000)
>>> print(dims.width)
10000
WSIBounds
class WSIBounds(NamedTuple)
The X coordinate of the top-left corner.
The Y coordinate of the top-left corner.
The width of the bounding box.
The height of the bounding box.
>>> bounds = WSIBounds(x=100, y=100, width=500, height=500)
>>> print(bounds.dims)
WSIDims(width=500, height=500)
dims
@property
def dims() -> WSIDims
The dimensions of the bounding box.
>>> bounds = WSIBounds(x=10, y=20, width=100, height=200)
>>> bounds.dims
WSIDims(width=100, height=200)
MeasurementUnit
class MeasurementUnit(str, Enum)
has_value
@classmethod
def has_value(cls, value: str) -> bool
True if valid, False otherwise.
>>> MeasurementUnit.has_value("PIXELS")
True
>>> MeasurementUnit.has_value("INCHES")
False
RegionLocation
@dataclass(frozen=True)
class RegionLocation()
The top coordinate of the top-left corner of the region.
The left coordinate of the top-left corner of the region.
The width of the region in pixels.
The height of the region in pixels.
>>> location = RegionLocation(top=100, left=200)
>>> print(location.top)
100
RegionShape
@dataclass(frozen=True)
class RegionShape()
The width of the region in pixels.
The height of the region in pixels.
The unit of measurement for the shape dimensions (e.g., PIXELS, UM).
>>> shape = RegionShape(width=500, height=500, unit=MeasurementUnit.PIXELS)
>>> print(shape.unit)
PIXELS
>>> print(shape.width)
500
shape
@property
def shape() -> tuple[int, int]
tuple[int, int]: A tuple containing (width, height).
to_um
def to_um(mpp: MPP) -> "RegionShape"
The pixel count to convert.
The microns-per-pixel scale.
>>> unit = MeasurementUnit.PIXELS
>>> unit.pixels_to_um(100, MPP(0.5))
50.0
to_pixels
def to_pixels(mpp: MPP) -> "RegionShape"
The length in microns to convert.
The microns-per-pixel scale.
>>> unit = MeasurementUnit.UM
>>> unit.um_to_pixels(50, MPP(0.5))
100.0
RegionMaskSpec
@dataclass(frozen=True)
class RegionMaskSpec()
Pixels belonging to the mask relative to the total region area.
The mask applied to the region, or None if mask storage was not requested.
RegionSpec
@dataclass(frozen=True)
class RegionSpec()
The location of the region within the slide.
The resolution at which the region is defined (Level, MPP, or Magnification).
>>> 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()
The pixel data of the region as a PIL Image.
The specifications of the region, including location, shape, resolution, and mask.
>>> 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
shape
@property
def shape() -> tuple[int, int]
resolution
@property
def resolution() -> Resolution
measurement_unit
@property
def measurement_unit() -> MeasurementUnit
mask
@property
def mask() -> 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
