OpenSlide Python¶

OpenSlide Python is a Python interface to the OpenSlide library.

OpenSlide is a C library that provides a simple interface for reading whole-slide images, also known as virtual slides, which are high-resolution images used in digital pathology. These images can occupy tens of gigabytes when uncompressed, and so cannot be easily read using standard tools or libraries, which are designed for images that can be comfortably uncompressed into RAM. Whole-slide images are typically multi-resolution; OpenSlide allows reading a small amount of image data at the resolution closest to a desired zoom level.

OpenSlide can read virtual slides in several formats:

Aperio (.svs, .tif)
Hamamatsu (.ndpi, .vms, .vmu)
Leica (.scn)
MIRAX (.mrxs)
Philips (.tiff)
Sakura (.svslide)
Trestle (.tif)
Ventana (.bif, .tif)
Generic tiled TIFF (.tif)

OpenSlide Python is released under the terms of the GNU Lesser General Public License, version 2.1.

Installing¶

OpenSlide Python requires OpenSlide, which must be installed separately.

On Linux and macOS, the easiest way to get both components is to install with a package manager that packages both, such as Anaconda, DNF or Apt on Linux systems, or MacPorts on macOS systems. You can also install OpenSlide Python with pip after installing OpenSlide with a package manager or from source. Except for pip, do not mix OpenSlide and OpenSlide Python from different package managers (for example, OpenSlide from MacPorts and OpenSlide Python from Anaconda), since you’ll get library conflicts.

On Windows, download the OpenSlide Windows binaries and extract them to a known path. Then, import openslide inside a with os.add_dll_directory() statement:

# The path can also be read from a config file, etc.
OPENSLIDE_PATH = r'c:\path\to\openslide-win64\bin'

import os
if hasattr(os, 'add_dll_directory'):
    # Python >= 3.8 on Windows
    with os.add_dll_directory(OPENSLIDE_PATH):
        import openslide
else:
    import openslide

This won’t work with Python 3.7 or earlier; you’ll need to add the OpenSlide bin directory to your PATH instead.

Basic usage¶

OpenSlide objects¶

class openslide.OpenSlide(filename)¶

An open whole-slide image.

If any operation on the object fails, OpenSlideError is raised. OpenSlide has latching error semantics: once OpenSlideError is raised, all future operations on the OpenSlide, other than close(), will also raise OpenSlideError.

close() is called automatically when the object is deleted. The object may be used as a context manager, in which case it will be closed upon exiting the context.

Parameters:

filename (str) – the file to open

Raises:

OpenSlideUnsupportedFormatError – if the file is not recognized by OpenSlide
OpenSlideError – if the file is recognized but an error occurred

classmethod detect_format(filename)¶

Return a string describing the format vendor of the specified file. This string is also accessible via the PROPERTY_NAME_VENDOR property.

If the file is not recognized, return None.

Parameters:: filename (str) – the file to examine

level_count¶: The number of levels in the slide. Levels are numbered from 0 (highest resolution) to level_count - 1 (lowest resolution).

dimensions¶: A (width, height) tuple for level 0 of the slide.

level_dimensions¶: A list of (width, height) tuples, one for each level of the slide. level_dimensions[k] are the dimensions of level k.

level_downsamples¶: A list of downsample factors for each level of the slide. level_downsamples[k] is the downsample factor of level k.

properties¶: Metadata about the slide, in the form of a Mapping from OpenSlide property name to property value. Property values are always strings. OpenSlide provides some Standard properties, plus additional properties that vary by slide format.

associated_images¶

Images, such as label or macro images, which are associated with this slide. This is a Mapping from image name to RGBA Image.

Unlike in the C interface, these images are not premultiplied.

read_region(location, level, size)¶

Return an RGBA Image containing the contents of the specified region.

Unlike in the C interface, the image data is not premultiplied.

Parameters:

location (tuple) – (x, y) tuple giving the top left pixel in the level 0 reference frame
level (int) – the level number
size (tuple) – (width, height) tuple giving the region size

get_best_level_for_downsample(downsample)¶

Return the best level for displaying the given downsample.

Parameters:: downsample (float) – the desired downsample factor

get_thumbnail(size)¶

Return an Image containing an RGB thumbnail of the slide.

Parameters:: size (tuple) – the maximum size of the thumbnail as a (width, height) tuple

set_cache(cache)¶

Use the specified OpenSlideCache to store recently decoded slide tiles. By default, the OpenSlide has a private cache with a default size.

Parameters:: cache (OpenSlideCache) – a cache object
Raises:: OpenSlideVersionError – if OpenSlide is older than version 3.5.0

close()¶: Close the OpenSlide object.

Caching¶

class openslide.OpenSlideCache(capacity)¶

An in-memory tile cache.

Tile caches can be attached to one or more OpenSlide objects with OpenSlide.set_cache() to cache recently-decoded tiles. By default, each OpenSlide has its own cache with a default size.

Parameters:: capacity (int) – the cache capacity in bytes
Raises:: OpenSlideVersionError – if OpenSlide is older than version 3.5.0

Standard properties¶

The openslide module provides attributes containing the names of some commonly-used OpenSlide properties.

openslide.PROPERTY_NAME_COMMENT¶: The name of the property containing a slide’s comment, if any.

openslide.PROPERTY_NAME_VENDOR¶: The name of the property containing an identification of the vendor.

openslide.PROPERTY_NAME_QUICKHASH1¶: The name of the property containing the “quickhash-1” sum.

openslide.PROPERTY_NAME_BACKGROUND_COLOR¶: The name of the property containing a slide’s background color, if any. It is represented as an RGB hex triplet.

openslide.PROPERTY_NAME_OBJECTIVE_POWER¶: The name of the property containing a slide’s objective power, if known.

openslide.PROPERTY_NAME_MPP_X¶: The name of the property containing the number of microns per pixel in the X dimension of level 0, if known.

openslide.PROPERTY_NAME_MPP_Y¶: The name of the property containing the number of microns per pixel in the Y dimension of level 0, if known.

openslide.PROPERTY_NAME_BOUNDS_X¶: The name of the property containing the X coordinate of the rectangle bounding the non-empty region of the slide, if available.

openslide.PROPERTY_NAME_BOUNDS_Y¶: The name of the property containing the Y coordinate of the rectangle bounding the non-empty region of the slide, if available.

openslide.PROPERTY_NAME_BOUNDS_WIDTH¶: The name of the property containing the width of the rectangle bounding the non-empty region of the slide, if available.

openslide.PROPERTY_NAME_BOUNDS_HEIGHT¶: The name of the property containing the height of the rectangle bounding the non-empty region of the slide, if available.

Exceptions¶

exception openslide.OpenSlideError¶

An error produced by the OpenSlide library.

Once OpenSlideError has been raised by a particular OpenSlide, all future operations on that OpenSlide (other than close()) will also raise OpenSlideError.

exception openslide.OpenSlideUnsupportedFormatError¶: OpenSlide does not support the requested file. Subclass of OpenSlideError.

exception openslide.OpenSlideVersionError¶: This version of OpenSlide does not support the requested functionality. Subclass of OpenSlideError.

Wrapping a PIL Image¶

class openslide.ImageSlide(file)¶

A wrapper around an Image object that provides an OpenSlide-compatible API.

Parameters:: file – a filename or Image object
Raises:: OSError – if the file cannot be opened

openslide.open_slide(filename)¶

Return an OpenSlide for whole-slide images and an ImageSlide for other types of images.

Parameters:

filename (str) – the file to open

Raises:

OpenSlideError – if the file is recognized by OpenSlide but an error occurred
OSError – if the file is not recognized at all

Deep Zoom support¶

OpenSlide Python provides functionality for generating individual Deep Zoom tiles from slide objects. This is useful for displaying whole-slide images in a web browser without converting the entire slide to Deep Zoom or a similar format.

class openslide.deepzoom.DeepZoomGenerator(osr, tile_size=254, overlap=1, limit_bounds=False)¶

A Deep Zoom generator that wraps an OpenSlide or ImageSlide object.

Parameters:

osr – the slide object
tile_size (int) – the width and height of a single tile. For best viewer performance, tile_size + 2 * overlap should be a power of two.
overlap (int) – the number of extra pixels to add to each interior edge of a tile
limit_bounds (bool) – True to render only the non-empty slide region

level_count¶: The number of Deep Zoom levels in the image.

tile_count¶: The total number of Deep Zoom tiles in the image.

level_tiles¶: A list of (tiles_x, tiles_y) tuples for each Deep Zoom level. level_tiles[k] are the tile counts of level k.

level_dimensions¶: A list of (pixels_x, pixels_y) tuples for each Deep Zoom level. level_dimensions[k] are the dimensions of level k.

get_dzi(format)¶

Return a string containing the XML metadata for the Deep Zoom .dzi file.

Parameters:: format (str) – the delivery format of the individual tiles (png or jpeg)

get_tile(level, address)¶

Return an RGB Image for a tile.

Parameters:

level (int) – the Deep Zoom level
address (tuple) – the address of the tile within the level as a (column, row) tuple

get_tile_coordinates(level, address)¶

Return the OpenSlide.read_region() arguments corresponding to the specified tile.

Most applications should use get_tile() instead.

Parameters:

level (int) – the Deep Zoom level
address (tuple) – the address of the tile within the level as a (column, row) tuple

get_tile_dimensions(level, address)¶

Return a (pixels_x, pixels_y) tuple for the specified tile.

Parameters:

level (int) – the Deep Zoom level
address (tuple) – the address of the tile within the level as a (column, row) tuple

Example programs¶

Several Deep Zoom examples are included with OpenSlide Python:

deepzoom_server.py

A basic server for a single slide. It serves a web page with a zoomable slide viewer, a list of slide properties, and the ability to view associated images.

deepzoom_multiserver.py

A basic server for a directory tree of slides. It serves an index page which links to zoomable slide viewers for all slides in the tree.

deepzoom_tile.py

A program to generate and store a complete Deep Zoom directory tree for a slide. It can optionally store an HTML page with a zoomable slide viewer, a list of slide properties, and the ability to view associated images.

This program is intended as an example. If you need to generate Deep Zoom trees for production applications, consider using VIPS instead.

OpenSlide Python¶

Installing¶

Basic usage¶

OpenSlide objects¶

Caching¶

Standard properties¶

Exceptions¶

Wrapping a PIL Image¶

Deep Zoom support¶

Example programs¶

Table of Contents

This Page