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

# 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(int)
```

Represents a pyramid level index in a WSI.

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

<ParamField body="index" type="int">
  The pyramid level index (0-based).
</ParamField>

**Raises:**

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

**Example**:

```pycon 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
```

**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(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.

<ParamField body="value" type="float">
  The pixel size in microns to represent as MPP.
</ParamField>

**Raises:**

* `ValueError` — If `value` is not positive.

**Example**:

```pycon 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 positive, got -1
```

## Magnification

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

<ParamField body="value" type="float">
  The objective power.
</ParamField>

**Raises:**

* `ValueError` — If `value` is not positive.

**Example**:

```pycon 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 positive
```

## WSIDims

```python theme={null}
class WSIDims(NamedTuple)
```

Dimensions of a slide or level at full resolution.

<ParamField body="width" type="int">
  The width of the image in pixels.
</ParamField>

<ParamField body="height" type="int">
  The height of the image in pixels.
</ParamField>

**Example**:

```pycon 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.

<ParamField body="x" type="int">
  The X coordinate of the top-left corner.
</ParamField>

<ParamField body="y" type="int">
  The Y coordinate of the top-left corner.
</ParamField>

<ParamField body="width" type="int">
  The width of the bounding box.
</ParamField>

<ParamField body="height" type="int">
  The height of the bounding box.
</ParamField>

**Example**:

```pycon 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.

<ResponseField name="returns" type="WSIDims">
  The dimensions of the bounding box.
</ResponseField>

**Example**:

```pycon 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.

<ParamField body="value" type="str" required>
  The string to check.
</ParamField>

<ResponseField name="returns" type="bool">
  True if valid, False otherwise.
</ResponseField>

**Example**:

```pycon 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.

<ParamField body="top" type="int">
  The top coordinate of the top-left corner of the region.
</ParamField>

<ParamField body="left" type="int">
  The left coordinate of the top-left corner of the region.
</ParamField>

<ParamField body="width" type="int">
  The width of the region in pixels.
</ParamField>

<ParamField body="height" type="int">
  The height of the region in pixels.
</ParamField>

**Example**:

```pycon 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.

<ParamField body="width" type="int">
  The width of the region in pixels.
</ParamField>

<ParamField body="height" type="int">
  The height of the region in pixels.
</ParamField>

<ParamField body="unit" type="MeasurementUnit">
  The unit of measurement for the shape dimensions (e.g., PIXELS, UM).
</ParamField>

**Example**:

```pycon 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.

<ResponseField name="returns" type="tuple[int, int]">
  tuple\[int, int]: A tuple containing (width, height).
</ResponseField>

#### to\_um

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

Converts pixels to microns.

<ParamField body="pixels" type="float">
  The pixel count to convert.
</ParamField>

<ParamField body="mpp" type="MPP" required>
  The microns-per-pixel scale.
</ParamField>

<ResponseField name="returns" type="float">
  The length in microns.
</ResponseField>

**Example**:

```pycon 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.

<ParamField body="microns" type="float">
  The length in microns to convert.
</ParamField>

<ParamField body="mpp" type="MPP" required>
  The microns-per-pixel scale.
</ParamField>

<ResponseField name="returns" type="float">
  The length in pixels.
</ResponseField>

**Example**:

```pycon 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.

<ParamField body="ratio" type="float">
  Pixels belonging to the mask relative to the total region area.
</ParamField>

<ParamField body="mask" type="np.ndarray | None">
  The mask applied to the region, or `None` if mask storage was not requested.
</ParamField>

## RegionSpec

```python theme={null}
@dataclass(frozen=True)
class RegionSpec()
```

Defines the specifications of a region within a WSI.

<ParamField body="location" type="RegionLocation">
  The location of the region within the slide.
</ParamField>

<ParamField body="shape" type="RegionShape">
  The shape of the region.
</ParamField>

<ParamField body="resolution" type="Resolution">
  The resolution at which the region is defined (Level, MPP, or Magnification).
</ParamField>

**Example**:

```pycon 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.

<ParamField body="image" type="PIL.Image.Image">
  The pixel data of the region as a PIL Image.
</ParamField>

<ParamField body="spec" type="RegionSpec">
  The specifications of the region, including location, shape, resolution, and mask.
</ParamField>

**Example**:

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

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

<ResponseField name="returns" type="Union[np.ndarray, None]">
  np.ndarray | None: The mask array, or `None` if mask storage was not requested during extraction.
</ResponseField>

#### mask\_ratio

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

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