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

# WSI processing

> Read whole-slide images: pyramid levels, MPP, regions, and thumbnails.

The Bioptimus SDK's `WSI` factory provides uniform access to whole-slide images, automatically selecting the best available backend.

**Supported backends** (auto-selected, in order of preference):

* **CuCIM** — GPU-accelerated reading, used when available.
* **OpenSlide** — CPU fallback, broad format support.

**Supported formats** include `.svs`, `.tiff`, `.tif`, `.ndpi`, `.vms`, `.vsi`, `.scn`, `.mrxs`, and `.jp2` (subject to the active backend).

## Open a slide

```python theme={null}
from bioptimus.io.wsi import WSI, Level, MPP, Magnification, MeasurementUnit

wsi = WSI("/data/wsi/tcga_coad.svs")
print(wsi.level_count)                      # pyramid levels (0 = highest resolution)
print(wsi.level_dimensions(Level(0)))       # base dimensions
print(wsi.mpp)                              # microns per pixel at level 0
```

## Properties

Slides carry rich scanning metadata. Access it through `props`, and inspect the pyramid with `level_dimensions` and `level_downsample`.

```python theme={null}
props = wsi.props
print(props.SCANNER)          # scanning device
print(props.OBJECTIVE_POWER)  # objective magnification (e.g. 40)
print(props.MPP_X, props.MPP_Y)

# Per-level pyramid structure:
for level in range(wsi.level_count):
    dims = wsi.level_dimensions(Level(level))
    ds = wsi.level_downsample(Level(level))
    print(f"Level {level}: {dims.width}x{dims.height} (downsample {ds:.1f}x)")
```

## Bounded vs. unbounded

Scanners capture the whole slide, but tissue occupies only part of it. `bounded=True` returns the tissue area; `bounded=False` returns the full slide.

```python theme={null}
tissue = wsi.dimensions(bounded=True)    # tissue area only
full   = wsi.dimensions(bounded=False)   # entire slide
```

## Read a region

Specify resolution three ways — by pyramid `Level`, by physical `MPP`, or by `Magnification` — and choose pixel or micrometer units.

```python theme={null}
# By level, in pixels:
region = wsi.read_region(location=(1000, 2000), size=(512, 512),
                         resolution=Level(0), measurement_unit=MeasurementUnit.PIXELS)

# By physical resolution, in micrometers:
region_um = wsi.read_region(location=(1000, 2000), size=(200, 200),
                            resolution=MPP(1.0), measurement_unit=MeasurementUnit.UM)

img = region.image          # PIL image
print(region.shape, region.resolution)
```

`MPP ≈ 10 / magnification` (40× ≈ 0.25 MPP, 20× ≈ 0.5 MPP, 10× ≈ 1.0 MPP). Bioptimus embeddings use 0.5 MPP; tissue segmentation uses 8 MPP.

## Thumbnails & associated images

```python theme={null}
thumb = wsi.get_thumbnail(size=(512, 512), bounded=True)   # PIL image
images = wsi.associated_images                              # {'thumbnail','label','macro'}
props = wsi.props                                           # scanner, objective, MPP_X/Y, ...
```

<Tip>
  For inference you don't usually call the reader directly — the [Inference pipeline](/guides/get-started/inference-pipeline) and `SlideInference` handle tiling. Use the reader for QC, custom region extraction, or building your own pipelines.
</Tip>