CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-openslide-python

Python interface to OpenSlide for reading whole-slide images used in digital pathology

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

OpenSlide Python

A Python interface to the OpenSlide library for reading whole-slide images (virtual slides) used in digital pathology. OpenSlide Python provides both high-level convenience APIs and low-level bindings for efficient access to large-scale microscopy images without loading entire multi-gigabyte files into memory.

Package Information

  • Package Name: openslide-python
  • Language: Python
  • Installation: pip install openslide-python
  • System Requirements: OpenSlide C library (install via pip install openslide-bin or system package manager)

Core Imports

import openslide

Common imports for typical usage:

from openslide import OpenSlide, ImageSlide, open_slide
from openslide import OpenSlideError, OpenSlideCache

Version information:

import openslide
print(f"Package version: {openslide.__version__}")
print(f"Library version: {openslide.__library_version__}")

Basic Usage

import openslide
from openslide import OpenSlide, open_slide

# Open a whole-slide image
with open_slide("path/to/slide.svs") as slide:
    # Get basic slide information
    print(f"Dimensions: {slide.dimensions}")
    print(f"Levels: {slide.level_count}")
    print(f"Level dimensions: {slide.level_dimensions}")
    print(f"Vendor: {slide.properties.get('openslide.vendor', 'Unknown')}")
    
    # Read a region from the slide
    # Location in level 0 coordinates, level to read from, size of region
    region = slide.read_region((1000, 1000), 0, (512, 512))
    region.save("region.png")
    
    # Generate a thumbnail
    thumbnail = slide.get_thumbnail((300, 300))
    thumbnail.save("thumbnail.png")
    
    # Access associated images (like label, macro, etc.)
    for name, image in slide.associated_images.items():
        print(f"Associated image: {name}, size: {image.size}")
        image.save(f"{name}.png")

Architecture

OpenSlide Python provides a layered architecture:

  • High-level API (openslide module): User-friendly classes with automatic memory management, context manager support, and PIL Image integration
  • Low-level API (openslide.lowlevel module): Direct bindings to OpenSlide C library functions for maximum performance
  • Deep Zoom Generator (openslide.deepzoom module): Tile generation for web-based viewers and zoomable interfaces

The library handles the complexities of multi-resolution whole-slide images, including format-specific optimizations, efficient region reading, and proper resource management for the underlying C library.

Capabilities

Slide Operations

Core functionality for opening, reading, and manipulating whole-slide images. Includes automatic format detection, multi-level image access, region reading, thumbnail generation, and metadata extraction.

def open_slide(filename: str | bytes | os.PathLike[Any]) -> OpenSlide | ImageSlide: ...

class OpenSlide:
    def __init__(self, filename: str | bytes | os.PathLike[Any]): ...
    def read_region(self, location: tuple[int, int], level: int, size: tuple[int, int]) -> Image.Image: ...
    def get_thumbnail(self, size: tuple[int, int]) -> Image.Image: ...
    def get_best_level_for_downsample(self, downsample: float) -> int: ...
    def close(self) -> None: ...
    
    @property
    def dimensions(self) -> tuple[int, int]: ...
    @property
    def level_count(self) -> int: ...
    @property 
    def level_dimensions(self) -> tuple[tuple[int, int], ...]: ...
    @property
    def level_downsamples(self) -> tuple[float, ...]: ...
    @property
    def properties(self) -> Mapping[str, str]: ...
    @property
    def associated_images(self) -> Mapping[str, Image.Image]: ...

class ImageSlide:
    def __init__(self, file: str | bytes | os.PathLike[Any] | Image.Image): ...

Slide Operations

Low-Level API

Direct bindings to OpenSlide C library functions for maximum performance and fine-grained control. Provides access to all OpenSlide C API functionality including error handling, caching, and ICC color profile support.

import openslide.lowlevel as lowlevel

def open(filename: str | bytes | os.PathLike[Any]) -> lowlevel._OpenSlide: ...
def close(slide: lowlevel._OpenSlide) -> None: ...
def read_region(slide: lowlevel._OpenSlide, x: int, y: int, level: int, w: int, h: int) -> Image.Image: ...
def get_property_names(slide: lowlevel._OpenSlide) -> list[str]: ...
def get_property_value(slide: lowlevel._OpenSlide, name: str | bytes) -> str: ...
def detect_vendor(filename: str | bytes | os.PathLike[Any]) -> str: ...
def get_version() -> str: ...

Low-Level API

Deep Zoom Generation

Generate Deep Zoom tiles and metadata for web-based slide viewing with smooth zooming and panning. Supports tile-based rendering, custom tile sizes, overlap settings, and bounds limiting for efficient web visualization.

from openslide.deepzoom import DeepZoomGenerator

class DeepZoomGenerator:
    def __init__(self, osr: openslide.AbstractSlide, tile_size: int = 254, overlap: int = 1, limit_bounds: bool = False): ...
    def get_tile(self, level: int, address: tuple[int, int]) -> Image.Image: ...
    def get_dzi(self, format: str) -> str: ...
    
    @property
    def level_count(self) -> int: ...
    @property
    def level_tiles(self) -> tuple[tuple[int, int], ...]: ...
    @property
    def level_dimensions(self) -> tuple[tuple[int, int], ...]: ...
    @property
    def tile_count(self) -> int: ...

Deep Zoom

Exception Handling

class OpenSlideError(Exception):
    """Base exception for OpenSlide errors"""

class OpenSlideVersionError(OpenSlideError):
    """OpenSlide version does not support requested functionality"""

class OpenSlideUnsupportedFormatError(OpenSlideError):
    """OpenSlide does not support the requested file format"""

Common Property Names

# Slide metadata property constants
PROPERTY_NAME_COMMENT = 'openslide.comment'
PROPERTY_NAME_VENDOR = 'openslide.vendor'
PROPERTY_NAME_QUICKHASH1 = 'openslide.quickhash-1'
PROPERTY_NAME_BACKGROUND_COLOR = 'openslide.background-color'
PROPERTY_NAME_OBJECTIVE_POWER = 'openslide.objective-power'
PROPERTY_NAME_MPP_X = 'openslide.mpp-x'
PROPERTY_NAME_MPP_Y = 'openslide.mpp-y'
PROPERTY_NAME_BOUNDS_X = 'openslide.bounds-x'
PROPERTY_NAME_BOUNDS_Y = 'openslide.bounds-y'
PROPERTY_NAME_BOUNDS_WIDTH = 'openslide.bounds-width'
PROPERTY_NAME_BOUNDS_HEIGHT = 'openslide.bounds-height'

Version Information

# Package version information
__version__: str  # OpenSlide Python package version ('1.4.2')
__library_version__: str  # OpenSlide C library version string

Caching

class OpenSlideCache:
    """In-memory tile cache for improved performance"""
    def __init__(self, capacity: int): ...

docs

deep-zoom.md

index.md

low-level-api.md

slide-operations.md

tile.json