> ## 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(path: str)
```

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.

**Attributes**:

* `path` - Path object pointing to the slide file.
* `props` - Metadata properties extracted from the slide.

***

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

**Returns**:

* `int` - Number of pyramid levels.

**Raises**:

* `NotImplementedError` - If not implemented by subclass.

***

#### mpp

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

Native microns per pixel (MPP) value.

**Returns**:

* `Optional[MPP]` - The MPP value if found in metadata, else None.

**Example**:

```python 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">
  The ratio to scale down by.
</ParamField>

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

**Returns**:

Union\[WSIDims, WSIBounds]: Scaled slide dimensions or tissue bounds.

**Example**:

```python 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">
  The target pyramid level (0 is highest resolution).
</ParamField>

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

**Returns**:

Union\[WSIDims, WSIBounds]: Dimensions or bounds at specified level.

**Raises**:

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

**Example**:

```python 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">
  Target magnification (e.g., 40x, 20x, 10x).
</ParamField>

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

**Returns**:

Union\[WSIDims, WSIBounds]: Dimensions or bounds at specified magnification.

**Example**:

```python 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">
  Target microns per pixel.
</ParamField>

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

**Returns**:

Union\[WSIDims, WSIBounds]: Dimensions or bounds at specified MPP.

**Example**:

```python 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">
  Acts as the `bounded` toggle when a bool.
</ParamField>

<ParamField body="bounded">
  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">
  Target pyramid level.
</ParamField>

<ParamField body="bounded">
  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">
  Target optical magnification.
</ParamField>

<ParamField body="bounded">
  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">
  Target microns per pixel.
</ParamField>

<ParamField body="bounded">
  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">
  Desired resolution (Level, Magnification, or MPP).
</ParamField>

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

**Returns**:

Union\[WSIDims, WSIBounds]: Dimensions or bounds at specified resolution.

**Example**:

```python 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)

>>> 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)

>>> 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">
  The target resolution (Level, Magnification, or MPP).
</ParamField>

**Returns**:

* `float` - Downsample factor for the given resolution.

**Example**:

```python 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">
  Pyramid level index.
</ParamField>

**Returns**:

* `float` - Downsample factor for the given level.

**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">
  Target microns per pixel.
</ParamField>

**Returns**:

* `float` - Downsample factor for the target MPP.

**Raises**:

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

**Example**:

```python 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">
  Target magnification power.
</ParamField>

**Returns**:

* `float` - Downsample factor for the target magnification.

**Raises**:

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

**Example**:

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

***

#### props

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

Slide metadata properties.

**Returns**:

* `WSIProps` - Metadata extracted from the slide.

**Example**:

```python 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">
  Target scaling factor.
</ParamField>

**Returns**:

* `int` - Best pyramid level index for the downsample.

**Raises**:

* `ValueError` - If downsample is too small.

**Example**:

```python 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]
```

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

<ParamField body="resolution">
  Desired resolution of the slide. Can be one of:
</ParamField>

* Level: integer pyramid level
* Magnification: desired optical magnification
* MPP: microns per pixel

**Returns**:

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

**Raises**:

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

**Example**:

```python 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">
  (x, y) at Level 0.
</ParamField>

<ParamField body="size">
  (width, height) at target resolution.
</ParamField>

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

<ParamField body="measurement_unit">
  Unit for the region shape
</ParamField>

<ParamField body="(default">
  pixels).
</ParamField>

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

**Returns**:

* `Region` - Object containing the image and metadata for the requested area.

**Example**:

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

**Returns**:

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

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

***

#### \_\_enter\_\_

```python theme={null}
def __enter__() -> "WSIReader"
```

Context manager entry.

**Returns**:

* `WSIReader` - The reader instance with slide file open.

**Example**:

```python theme={null}
>>> with SomeWSIReader("slide.svs") as reader:
...     dims = reader.dimensions()
```

***

#### \_\_exit\_\_

```python theme={null}
def __exit__(exc_type: Any, exc_value: Any, traceback: Any) -> None
```

Context manager exit.

<ParamField body="exc_type">
  Exception type.
</ParamField>

<ParamField body="exc_value">
  Exception value.
</ParamField>

<ParamField body="traceback">
  Exception traceback.
</ParamField>

**Returns**:

None

**Example**:

```python theme={null}
>>> with SomeWSIReader("slide.svs") as reader:
...     pass
```

***

#### get\_thumbnail

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

Generates a slide thumbnail.

<ParamField body="size">
  Max (width, height) for result.
</ParamField>

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

**Returns**:

* `Image.Image` - RGB thumbnail image.

**Example**:

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


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