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

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 pyramid level, size in pixels (Level 2 ≈ 16× downsample), tissue-bounded:
region_px = wsi.read_region(location=(1625, 0), size=(1200, 1200),
                            resolution=Level(2),
                            measurement_unit=MeasurementUnit.PIXELS, bounded=True)

# The same window requested in micrometers (physical units):
region_um = wsi.read_region(location=(1625, 0), size=(599.0, 599.0),
                            resolution=Level(2),
                            measurement_unit=MeasurementUnit.UM, bounded=True)

img = region_px.image       # PIL image
print(region_px.image.size, region_px.resolution)
Region read in pixels versus micrometers, side by side
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=False)  # PIL image
images = wsi.associated_images                             # {'thumbnail','label','macro'}
macro = images["macro"]                                    # slide-level macro photograph
props = wsi.props                                          # scanner, objective, MPP_X/Y, ...
Whole-slide image thumbnail
Macro associated image of the whole slide
For inference you don’t usually call the reader directly — the Inference pipeline and SlideInference handle tiling. Use the reader for QC, custom region extraction, or building your own pipelines.