Skip to main content
The 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

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

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, ...
For inference you don’t usually call the reader directly — the Inference facade and SlideInference handle tiling. Use the reader for QC, custom region extraction, or building your own pipelines.