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

WSI Reader Base Module.

This module provides the `WSIReader` abstract base class, which standardizes access to Whole Slide Images (WSI). It handles coordinate translations, resolution scaling (Level, Magnification, MPP), and tissue-aware cropping.

Typical usage example: with OpenSlideReader("path/to/slide.svs") as reader:

# Get tissue-only dimensions

dims = reader.dimensions(bounded=True)

# Read a region relative to the slide origin

region = reader.read\_region((0, 0), (512, 512), Level(0), bounded=False)

## WSIReader

```python theme={null}
class WSIReader(ABC)
```

Abstract Base Class for all WSI Backends.

Standardizes the interface for reading digital pathology slides across different vendors. It manages metadata, pyramid levels, and tissue bounding box transformations.

<ParamField body="path">
  Path object pointing to the slide file.
</ParamField>

<ParamField body="props">
  Metadata properties extracted from the slide.
</ParamField>

#### open\_slide

```python theme={null}
@abstractmethod
def open_slide() -> None
```

Opens the file handle for the slide.

**Raises:**

* `NotImplementedError` — If not implemented by subclass.

#### level\_count

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

Number of pyramid levels available in the slide.

<ResponseField name="returns" type="int">
  Number of pyramid levels.
</ResponseField>

**Raises:**

* `NotImplementedError` — If not implemented by subclass.

#### mpp

```python theme={null}
@property
def mpp() -> Union[MPP, None]
```

Native microns per pixel (MPP) value.

<ResponseField name="returns" type="Optional[MPP]">
  The MPP value if found in metadata, else None.
</ResponseField>

**Example**:

```pycon theme={null}
>>> reader.mpp
0.25
```

#### downsample\_dimensions

```python theme={null}
def downsample_dimensions(downsample_factor: float,
                          bounded: bool = True) -> Union[WSIDims, WSIBounds]
```

Calculates slide dimensions at a specific downsample factor.

<ParamField body="downsample_factor" type="float" required>
  The ratio to scale down by.
</ParamField>

<ParamField body="bounded" type="bool">
  Whether to return tissue bounds or full slide size.
</ParamField>

<ResponseField name="returns" type="Union[WSIDims, WSIBounds]">
  Union\[WSIDims, WSIBounds]: Scaled slide dimensions or tissue bounds.
</ResponseField>

**Example**:

```pycon theme={null}
>>> reader.downsample_dimensions(4.0, bounded=False)
WSIDims(width=25000, height=20000)
>>> reader.downsample_dimensions(4.0, bounded=True)
WSIBounds(x=1250, y=500, width=25000, height=20000)
```

#### level\_dimensions

```python theme={null}
def level_dimensions(level: Level,
                     bounded: bool = True) -> Union[WSIDims, WSIBounds]
```

Returns the dimensions of a specific pyramid level.

<ParamField body="level" type="Level" required>
  The target pyramid level (0 is highest resolution).
</ParamField>

<ParamField body="bounded" type="bool">
  If True, returns tissue area at that level.
</ParamField>

<ResponseField name="returns" type="Union[WSIDims, WSIBounds]">
  Union\[WSIDims, WSIBounds]: Dimensions or bounds at specified level.
</ResponseField>

**Raises:**

* `ValueError` — If level is out of range.

**Example**:

```pycon theme={null}
>>> reader.level_dimensions(Level(2), bounded=False)
WSIDims(width=25000, height=20000)
>>> reader.level_dimensions(Level(2), bounded=True)
WSIBounds(x=1250, y=500, width=25000, height=20000)
```

#### magnification\_dimensions

```python theme={null}
def magnification_dimensions(
        magnification: float,
        bounded: bool = True) -> Union[WSIDims, WSIBounds]
```

Returns slide dimensions for a specific optical magnification.

<ParamField body="magnification" type="float" required>
  Target magnification (e.g., 40x, 20x, 10x).
</ParamField>

<ParamField body="bounded" type="bool">
  If True, returns tissue area at that magnification.
</ParamField>

<ResponseField name="returns" type="Union[WSIDims, WSIBounds]">
  Union\[WSIDims, WSIBounds]: Dimensions or bounds at specified magnification.
</ResponseField>

**Example**:

```pycon theme={null}
>>> reader.magnification_dimensions(10.0, bounded=False)
WSIDims(width=25000, height=20000)
>>> reader.magnification_dimensions(10.0, bounded=True)
WSIBounds(x=1250, y=500, width=25000, height=20000)
```

#### mpp\_dimensions

```python theme={null}
def mpp_dimensions(mpp: float,
                   bounded: bool = True) -> Union[WSIDims, WSIBounds]
```

Returns slide dimensions for a specific MPP (microns per pixel).

<ParamField body="mpp" type="float" required>
  Target microns per pixel.
</ParamField>

<ParamField body="bounded" type="bool">
  If True, returns tissue area at that MPP.
</ParamField>

<ResponseField name="returns" type="Union[WSIDims, WSIBounds]">
  Union\[WSIDims, WSIBounds]: Dimensions or bounds at specified MPP.
</ResponseField>

**Example**:

```pycon theme={null}
>>> reader.mpp_dimensions(1.0, bounded=False)
WSIDims(width=25000, height=20000)
>>> reader.mpp_dimensions(1.0, bounded=True)
WSIBounds(x=1250, y=500, width=25000, height=20000)
```

#### dimensions

```python theme={null}
@overload
def dimensions(resolution: bool = True,
               bounded: bool = True) -> Union[WSIDims, WSIBounds]
```

Returns full or bounded slide dimensions at Level 0.

<ParamField body="resolution" type="bool">
  Acts as the `bounded` toggle when a bool.
</ParamField>

<ParamField body="bounded" type="bool">
  If True, returns tissue bounds.
</ParamField>

#### dimensions

```python theme={null}
@overload
def dimensions(resolution: Level,
               bounded: bool = True) -> Union[WSIDims, WSIBounds]
```

Returns slide dimensions at a pyramid level.

<ParamField body="resolution" type="Level" required>
  Target pyramid level.
</ParamField>

<ParamField body="bounded" type="bool">
  If True, returns tissue bounds.
</ParamField>

#### dimensions

```python theme={null}
@overload
def dimensions(resolution: Magnification,
               bounded: bool = True) -> Union[WSIDims, WSIBounds]
```

Returns slide dimensions at a magnification.

<ParamField body="resolution" type="Magnification" required>
  Target optical magnification.
</ParamField>

<ParamField body="bounded" type="bool">
  If True, returns tissue bounds.
</ParamField>

#### dimensions

```python theme={null}
@overload
def dimensions(resolution: MPP,
               bounded: bool = True) -> Union[WSIDims, WSIBounds]
```

Returns slide dimensions at a target MPP.

<ParamField body="resolution" type="MPP" required>
  Target microns per pixel.
</ParamField>

<ParamField body="bounded" type="bool">
  If True, returns tissue bounds.
</ParamField>

#### dimensions

```python theme={null}
def dimensions(resolution: Union[Resolution, bool] = True,
               bounded: bool = True) -> Union[WSIDims, WSIBounds]
```

Returns slide dimensions for a specific resolution.

<ParamField body="resolution" type="Resolution">
  Desired resolution (Level, Magnification, or MPP).
</ParamField>

<ParamField body="bounded" type="bool">
  If True, returns tissue area at that resolution.
</ParamField>

<ResponseField name="returns" type="Union[WSIDims, WSIBounds]">
  Union\[WSIDims, WSIBounds]: Dimensions or bounds at specified resolution.
</ResponseField>

**Example**:

```pycon theme={null}
>>> reader.dimensions(Resolution(level=2), bounded=False)
WSIDims(width=25000, height=20000)
>>> reader.dimensions(Resolution(level=2), bounded=True)
WSIBounds(x=1250, y=500, width=25000, height=20000)
```

```pycon theme={null}
>>> reader.dimensions(Resolution(magnification=10.0), bounded=False)
WSIDims(width=25000, height=20000)
>>> reader.dimensions(Resolution(magnification=10.0), bounded=True)
WSIBounds(x=1250, y=500, width=25000, height=20000)
```

```pycon theme={null}
>>> reader.dimensions(Resolution(mpp=1.0), bounded=False)
WSIDims(width=25000, height=20000)
>>> reader.dimensions(Resolution(mpp=1.0), bounded=True)
WSIBounds(x=1250, y=500, width=25000, height=20000)
```

#### get\_downsample\_factor

```python theme={null}
def get_downsample_factor(resolution: Resolution) -> float
```

Calculates the downsample factor for a given resolution.

<ParamField body="resolution" type="Resolution" required>
  The target resolution (Level, Magnification, or MPP).
</ParamField>

<ResponseField name="returns" type="float">
  Downsample factor for the given resolution.
</ResponseField>

**Example**:

```pycon theme={null}
>>> reader.get_downsample_factor(Resolution(level=2))
4.0
>>> reader.get_downsample_factor(Resolution(magnification=10.0))
4.0
>>> reader.get_downsample_factor(Resolution(mpp=1.0))
4.0
```

#### level\_downsample

```python theme={null}
@abstractmethod
def level_downsample(level: int) -> float
```

Returns downsample factor for a pyramid level.

<ParamField body="level" type="int" required>
  Pyramid level index.
</ParamField>

<ResponseField name="returns" type="float">
  Downsample factor for the given level.
</ResponseField>

**Raises:**

* `NotImplementedError` — If not implemented by subclass.

#### mpp\_downsample

```python theme={null}
def mpp_downsample(mpp: float) -> float
```

Calculates downsample needed for target MPP.

<ParamField body="mpp" type="float" required>
  Target microns per pixel.
</ParamField>

<ResponseField name="returns" type="float">
  Downsample factor for the target MPP.
</ResponseField>

**Raises:**

* `ValueError` — If metadata is missing or target is too high-res.

**Example**:

```pycon theme={null}
>>> reader.mpp_downsample(1.0)
4.0
```

#### magnification\_downsample

```python theme={null}
def magnification_downsample(magnification: float) -> float
```

Calculates downsample needed for target magnification.

<ParamField body="magnification" type="float" required>
  Target magnification power.
</ParamField>

<ResponseField name="returns" type="float">
  Downsample factor for the target magnification.
</ResponseField>

**Raises:**

* `ValueError` — If metadata is missing or target is out of range.

**Example**:

```pycon theme={null}
>>> reader.magnification_downsample(10.0)
4.0
```

#### props

```python theme={null}
@property
def props() -> WSIProps
```

Slide metadata properties.

<ResponseField name="returns" type="WSIProps">
  Metadata extracted from the slide.
</ResponseField>

**Example**:

```pycon theme={null}
>>> reader.props.OBJECTIVE_POWER
40
```

#### get\_best\_level\_for\_downsample

```python theme={null}
def get_best_level_for_downsample(downsample: float) -> int
```

Finds highest pyramid level smaller than target downsample factor.

<ParamField body="downsample" type="float" required>
  Target scaling factor.
</ParamField>

<ResponseField name="returns" type="int">
  Best pyramid level index for the downsample.
</ResponseField>

**Raises:**

* `ValueError` — If downsample is too small.

**Example**:

```pycon theme={null}
>>> reader.get_best_level_for_downsample(4.0)
2
```

#### get\_downsample\_scaling\_and\_level

```python theme={null}
def get_downsample_scaling_and_level(
        resolution: Resolution) -> tuple[float, float, int]
```

Determine the downsample factor, scaling factor, and best pyramid level for a given resolution.

<ParamField body="resolution" type="Resolution" required>
  Desired resolution of the slide. Can be one of: - Level: integer pyramid level - Magnification: desired optical magnification - MPP: microns per pixel
</ParamField>

<ResponseField name="returns" type="tuple">
  (downsample\_factor (float), scaling\_factor (float), best\_level (int)) - downsample\_factor: Factor by which the base level is downsampled. - scaling\_factor: Additional scaling needed at the chosen level. - best\_level: Pyramid level that best matches the resolution.
</ResponseField>

**Raises:**

* `ValueError` — If required slide properties (objective power or MPP) are unavailable.
* `TypeError` — If the resolution type is unsupported.

**Example**:

```pycon theme={null}
>>> reader.get_downsample_scaling_and_level(Level(2))
(4.0, 1.0, 2)
```

#### read\_region

```python theme={null}
def read_region(location: tuple[int, int],
                size: tuple[int, int],
                resolution: Resolution,
                measurement_unit: MeasurementUnit = MeasurementUnit.PIXELS,
                bounded: bool = True) -> Region
```

Reads a region from the slide.

<ParamField body="location" type="tuple[int, int]" required>
  (x, y) at Level 0.
</ParamField>

<ParamField body="size" type="tuple[int, int]" required>
  (width, height) at target resolution.
</ParamField>

<ParamField body="resolution" type="Resolution" required>
  Resolution level/mpp/magnification.
</ParamField>

<ParamField body="measurement_unit" type="MeasurementUnit">
  Unit for the region shape (default pixels).
</ParamField>

<ParamField body="bounded" type="bool">
  If True, (0,0) is tissue top-left. Else slide top-left.
</ParamField>

<ResponseField name="returns" type="Region">
  Object containing the image and metadata for the requested area.
</ResponseField>

**Example**:

```pycon theme={null}
>>> region = reader.read_region((0, 0), (512, 512), Level(0), bounded=False)
>>> region = reader.read_region((0, 0), (512, 512), Level(0), bounded=True)
```

#### is\_supported\_file

```python theme={null}
@abstractmethod
def is_supported_file() -> bool
```

Checks if backend supports this file extension.

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

**Raises:**

* `NotImplementedError` — If not implemented by subclass.

#### close

```python theme={null}
@abstractmethod
def close() -> None
```

Closes slide file handle.

**Returns**:

None

**Raises:**

* `NotImplementedError` — If not implemented by subclass.

#### get\_thumbnail

```python theme={null}
def get_thumbnail(size: tuple[int, int], bounded: bool = True) -> Image.Image
```

Generates a slide thumbnail.

<ParamField body="size" type="tuple[int, int]" required>
  Max (width, height) for result.
</ParamField>

<ParamField body="bounded" type="bool">
  If True, crop to tissue. Else show full slide (incl. white space).
</ParamField>

<ResponseField name="returns" type="Image.Image">
  RGB thumbnail image.
</ResponseField>

**Example**:

```pycon theme={null}
>>> reader.get_thumbnail((1024, 1024), bounded=False)
>>> reader.get_thumbnail((1024, 1024), bounded=True)
```