0
# OpenSlide Python
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: openslide-python
7
- **Language**: Python
8
- **Installation**: `pip install openslide-python`
9
- **System Requirements**: OpenSlide C library (install via `pip install openslide-bin` or system package manager)
10

11
## Core Imports
12

13
```python
14
import openslide
15
```
16

17
Common imports for typical usage:
18

19
```python
20
from openslide import OpenSlide, ImageSlide, open_slide
21
from openslide import OpenSlideError, OpenSlideCache
22
```
23

24
Version information:
25

26
```python
27
import openslide
28
print(f"Package version: {openslide.__version__}")
29
print(f"Library version: {openslide.__library_version__}")
30
```
31

32
## Basic Usage
33

34
```python
35
import openslide
36
from openslide import OpenSlide, open_slide
37

38
# Open a whole-slide image
39
with open_slide("path/to/slide.svs") as slide:
40
    # Get basic slide information
41
    print(f"Dimensions: {slide.dimensions}")
42
    print(f"Levels: {slide.level_count}")
43
    print(f"Level dimensions: {slide.level_dimensions}")
44
    print(f"Vendor: {slide.properties.get('openslide.vendor', 'Unknown')}")
45
    
46
    # Read a region from the slide
47
    # Location in level 0 coordinates, level to read from, size of region
48
    region = slide.read_region((1000, 1000), 0, (512, 512))
49
    region.save("region.png")
50
    
51
    # Generate a thumbnail
52
    thumbnail = slide.get_thumbnail((300, 300))
53
    thumbnail.save("thumbnail.png")
54
    
55
    # Access associated images (like label, macro, etc.)
56
    for name, image in slide.associated_images.items():
57
        print(f"Associated image: {name}, size: {image.size}")
58
        image.save(f"{name}.png")
59
```
60

61
## Architecture
62

63
OpenSlide Python provides a layered architecture:
64

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

69
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.
70

71
## Capabilities
72

73
### Slide Operations
74

75
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.
76

77
```python { .api }
78
def open_slide(filename: str | bytes | os.PathLike[Any]) -> OpenSlide | ImageSlide: ...
79

80
class OpenSlide:
81
    def __init__(self, filename: str | bytes | os.PathLike[Any]): ...
82
    def read_region(self, location: tuple[int, int], level: int, size: tuple[int, int]) -> Image.Image: ...
83
    def get_thumbnail(self, size: tuple[int, int]) -> Image.Image: ...
84
    def get_best_level_for_downsample(self, downsample: float) -> int: ...
85
    def close(self) -> None: ...
86
    
87
    @property
88
    def dimensions(self) -> tuple[int, int]: ...
89
    @property
90
    def level_count(self) -> int: ...
91
    @property 
92
    def level_dimensions(self) -> tuple[tuple[int, int], ...]: ...
93
    @property
94
    def level_downsamples(self) -> tuple[float, ...]: ...
95
    @property
96
    def properties(self) -> Mapping[str, str]: ...
97
    @property
98
    def associated_images(self) -> Mapping[str, Image.Image]: ...
99

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

104
[Slide Operations](./slide-operations.md)
105

106
### Low-Level API
107

108
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.
109

110
```python { .api }
111
import openslide.lowlevel as lowlevel
112

113
def open(filename: str | bytes | os.PathLike[Any]) -> lowlevel._OpenSlide: ...
114
def close(slide: lowlevel._OpenSlide) -> None: ...
115
def read_region(slide: lowlevel._OpenSlide, x: int, y: int, level: int, w: int, h: int) -> Image.Image: ...
116
def get_property_names(slide: lowlevel._OpenSlide) -> list[str]: ...
117
def get_property_value(slide: lowlevel._OpenSlide, name: str | bytes) -> str: ...
118
def detect_vendor(filename: str | bytes | os.PathLike[Any]) -> str: ...
119
def get_version() -> str: ...
120
```
121

122
[Low-Level API](./low-level-api.md)
123

124
### Deep Zoom Generation
125

126
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.
127

128
```python { .api }
129
from openslide.deepzoom import DeepZoomGenerator
130

131
class DeepZoomGenerator:
132
    def __init__(self, osr: openslide.AbstractSlide, tile_size: int = 254, overlap: int = 1, limit_bounds: bool = False): ...
133
    def get_tile(self, level: int, address: tuple[int, int]) -> Image.Image: ...
134
    def get_dzi(self, format: str) -> str: ...
135
    
136
    @property
137
    def level_count(self) -> int: ...
138
    @property
139
    def level_tiles(self) -> tuple[tuple[int, int], ...]: ...
140
    @property
141
    def level_dimensions(self) -> tuple[tuple[int, int], ...]: ...
142
    @property
143
    def tile_count(self) -> int: ...
144
```
145

146
[Deep Zoom](./deep-zoom.md)
147

148
## Exception Handling
149

150
```python { .api }
151
class OpenSlideError(Exception):
152
    """Base exception for OpenSlide errors"""
153

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

157
class OpenSlideUnsupportedFormatError(OpenSlideError):
158
    """OpenSlide does not support the requested file format"""
159
```
160

161
## Common Property Names
162

163
```python { .api }
164
# Slide metadata property constants
165
PROPERTY_NAME_COMMENT = 'openslide.comment'
166
PROPERTY_NAME_VENDOR = 'openslide.vendor'
167
PROPERTY_NAME_QUICKHASH1 = 'openslide.quickhash-1'
168
PROPERTY_NAME_BACKGROUND_COLOR = 'openslide.background-color'
169
PROPERTY_NAME_OBJECTIVE_POWER = 'openslide.objective-power'
170
PROPERTY_NAME_MPP_X = 'openslide.mpp-x'
171
PROPERTY_NAME_MPP_Y = 'openslide.mpp-y'
172
PROPERTY_NAME_BOUNDS_X = 'openslide.bounds-x'
173
PROPERTY_NAME_BOUNDS_Y = 'openslide.bounds-y'
174
PROPERTY_NAME_BOUNDS_WIDTH = 'openslide.bounds-width'
175
PROPERTY_NAME_BOUNDS_HEIGHT = 'openslide.bounds-height'
176
```
177

178
## Version Information
179

180
```python { .api }
181
# Package version information
182
__version__: str  # OpenSlide Python package version ('1.4.2')
183
__library_version__: str  # OpenSlide C library version string
184
```
185

186
## Caching
187

188
```python { .api }
189
class OpenSlideCache:
190
    """In-memory tile cache for improved performance"""
191
    def __init__(self, capacity: int): ...
192
```