> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bioptimus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```python theme={null}
class Level(index: int)
```

Represents a pyramid level index in a WSI.

Level 0 is the highest resolution. Higher indices are lower resolutions.

**index**

The pyramid level index (0-based).

**Raises**:

* `ValueError` - If `index` is negative.

**Example**:

```python theme={null}
>>> 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

```python theme={null}
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).

**value**

The pixel size in microns to represent as MPP.

**Raises**:

* `ValueError` - If `value` is not a finite positive number.

**Example**:

```python theme={null}
>>> 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

```python theme={null}
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

**value**

The objective power.

**Raises**:

* `ValueError` - If `value` is not a finite positive number.

**Example**:

```python theme={null}
>>> 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

```python theme={null}
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**:

```python theme={null}
>>> dims = WSIDims(width=10000, height=20000)
>>> print(dims.width)
10000
```

## WSIBounds

```python theme={null}
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**:

```python theme={null}
>>> bounds = WSIBounds(x=100, y=100, width=500, height=500)
>>> print(bounds.dims)
WSIDims(width=500, height=500)
```

***

#### dims

```python theme={null}
@property
def dims() -> WSIDims
```

Extracts width and height as a WSIDims object.

**Returns**:

* `WSIDims` - The dimensions of the bounding box.

**Example**:

```python theme={null}
>>> bounds = WSIBounds(x=10, y=20, width=100, height=200)
>>> bounds.dims
WSIDims(width=100, height=200)
```

## MeasurementUnit

```python theme={null}
class MeasurementUnit(str, Enum)
```

Enumeration of measurement units for WSI tiles and regions.

***

#### has\_value

```python theme={null}
@classmethod
def has_value(cls, value: str) -> bool
```

Checks if a string is a valid MeasurementUnit.

**value**

The string to check.

**Returns**:

* `bool` - True if valid, False otherwise.

**Example**:

```python theme={null}
>>> MeasurementUnit.has_value("PIXELS")
True
>>> MeasurementUnit.has_value("INCHES")
False
```

## RegionLocation

```python theme={null}
@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**:

```python theme={null}
>>> location = RegionLocation(top=100, left=200)
>>> print(location.top)
100
```

***

#### x

```python theme={null}
@property
def x() -> int
```

Alias for left coordinate.

***

#### y

```python theme={null}
@property
def y() -> int
```

Alias for top coordinate.

## RegionShape

```python theme={null}
@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**:

```python theme={null}
>>> shape = RegionShape(width=500, height=500, unit=MeasurementUnit.PIXELS)
>>> print(shape.unit)
PIXELS
>>> print(shape.width)
500
```

***

#### shape

```python theme={null}
@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

```python theme={null}
def to_um(mpp: MPP) -> "RegionShape"
```

Converts pixels to microns.

**pixels**

The pixel count to convert.

**mpp**

The microns-per-pixel scale.

**Returns**:

* `float` - The length in microns.

**Example**:

```python theme={null}
>>> unit = MeasurementUnit.PIXELS
>>> unit.pixels_to_um(100, MPP(0.5))
50.0
```

***

#### to\_pixels

```python theme={null}
def to_pixels(mpp: MPP) -> "RegionShape"
```

Converts microns to pixels.

**microns**

The length in microns to convert.

**mpp**

The microns-per-pixel scale.

**Returns**:

* `float` - The length in pixels.

**Example**:

```python theme={null}
>>> unit = MeasurementUnit.UM
>>> unit.um_to_pixels(50, MPP(0.5))
100.0
```

## RegionMaskSpec

```python theme={null}
@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

```python theme={null}
@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**:

```python theme={null}
>>> 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

```python theme={null}
@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**:

```python theme={null}
>>> 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

```python theme={null}
@property
def location() -> RegionLocation
```

Convenience property to access the region's location directly.

***

#### shape

```python theme={null}
@property
def shape() -> tuple[int, int]
```

Convenience property to access the region's shape directly.

***

#### resolution

```python theme={null}
@property
def resolution() -> Resolution
```

Convenience property to access the region's resolution directly.

***

#### measurement\_unit

```python theme={null}
@property
def measurement_unit() -> MeasurementUnit
```

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

***

#### mask

```python theme={null}
@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

```python theme={null}
@property
def mask_ratio() -> float
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.