0
# Low-Level API
1
2
Direct bindings to the OpenSlide C library providing maximum performance and fine-grained control. This module provides nearly direct equivalents to the OpenSlide C API for advanced users who need precise control over slide operations and resource management.
3
4
```python
5
import openslide.lowlevel as lowlevel
6
from openslide.lowlevel import OpenSlideError, OpenSlideVersionError, OpenSlideUnsupportedFormatError
7
from PIL import Image
8
import os
9
```
10
11
## Capabilities
12
13
### Core Library Functions
14
15
Basic slide operations including opening, closing, and library information retrieval.
16
17
```python { .api }
18
import openslide.lowlevel as lowlevel
19
20
def open(filename: str | bytes | os.PathLike[Any]) -> lowlevel._OpenSlide:
21
"""
22
Open a whole-slide image file.
23
24
Args:
25
filename: Path to the slide file
26
27
Returns:
28
_OpenSlide handle for the opened slide
29
30
Raises:
31
OpenSlideUnsupportedFormatError: If file format is not supported
32
OpenSlideError: If there's an error opening the file
33
"""
34
35
def close(slide: lowlevel._OpenSlide) -> None:
36
"""
37
Close a slide and free associated resources.
38
39
Args:
40
slide: _OpenSlide handle to close
41
42
Note: After calling close(), the slide handle becomes invalid
43
"""
44
45
def detect_vendor(filename: str | bytes | os.PathLike[Any]) -> str:
46
"""
47
Detect the format vendor of a slide file.
48
49
Args:
50
filename: Path to the slide file
51
52
Returns:
53
String describing the format vendor
54
55
Raises:
56
OpenSlideError: If there's an error accessing the file
57
"""
58
59
def get_version() -> str:
60
"""
61
Get the OpenSlide library version string.
62
63
Returns:
64
Version string of the OpenSlide C library
65
"""
66
67
def get_error(slide: lowlevel._OpenSlide) -> str:
68
"""
69
Get the current error state of a slide.
70
71
Args:
72
slide: _OpenSlide handle
73
74
Returns:
75
Error message string, or None if no error
76
"""
77
```
78
79
### Level and Dimension Functions
80
81
Functions for querying slide structure and resolution levels.
82
83
```python { .api }
84
def get_level_count(slide: lowlevel._OpenSlide) -> int:
85
"""
86
Get the number of resolution levels in the slide.
87
88
Args:
89
slide: _OpenSlide handle
90
91
Returns:
92
Number of levels in the slide
93
"""
94
95
def get_level_dimensions(slide: lowlevel._OpenSlide, level: int) -> tuple[int, int]:
96
"""
97
Get the dimensions of a specific level.
98
99
Args:
100
slide: _OpenSlide handle
101
level: Level number (0-based)
102
103
Returns:
104
(width, height) tuple for the specified level
105
"""
106
107
def get_level_downsample(slide: lowlevel._OpenSlide, level: int) -> float:
108
"""
109
Get the downsample factor for a specific level.
110
111
Args:
112
slide: _OpenSlide handle
113
level: Level number (0-based)
114
115
Returns:
116
Downsample factor relative to level 0
117
"""
118
119
def get_best_level_for_downsample(slide: lowlevel._OpenSlide, downsample: float) -> int:
120
"""
121
Find the best level for a given downsample factor.
122
123
Args:
124
slide: _OpenSlide handle
125
downsample: Desired downsample factor
126
127
Returns:
128
Level number that best matches the downsample factor
129
"""
130
```
131
132
### Region Reading Functions
133
134
Low-level functions for reading image data from slides.
135
136
```python { .api }
137
def read_region(slide: lowlevel._OpenSlide, x: int, y: int, level: int, w: int, h: int) -> Image.Image:
138
"""
139
Read a rectangular region from the slide.
140
141
Args:
142
slide: _OpenSlide handle
143
x: X coordinate in level 0 reference frame
144
y: Y coordinate in level 0 reference frame
145
level: Level number to read from
146
w: Width of region to read
147
h: Height of region to read
148
149
Returns:
150
PIL.Image in RGBA format with the region data (not premultiplied)
151
152
Raises:
153
OpenSlideError: If w or h is negative, or other read error occurs
154
"""
155
```
156
157
### Property Functions
158
159
Functions for accessing slide metadata and properties.
160
161
```python { .api }
162
def get_property_names(slide: lowlevel._OpenSlide) -> list[str]:
163
"""
164
Get list of all property names available for the slide.
165
166
Args:
167
slide: _OpenSlide handle
168
169
Returns:
170
List of property name strings
171
"""
172
173
def get_property_value(slide: lowlevel._OpenSlide, name: str | bytes) -> str | None:
174
"""
175
Get the value of a specific property.
176
177
Args:
178
slide: _OpenSlide handle
179
name: Property name
180
181
Returns:
182
Property value as string, or None if property doesn't exist
183
"""
184
```
185
186
### Associated Image Functions
187
188
Functions for working with associated images like labels and thumbnails.
189
190
```python { .api }
191
def get_associated_image_names(slide: lowlevel._OpenSlide) -> list[str]:
192
"""
193
Get list of all associated image names.
194
195
Args:
196
slide: _OpenSlide handle
197
198
Returns:
199
List of associated image name strings
200
"""
201
202
def get_associated_image_dimensions(slide: lowlevel._OpenSlide, name: str | bytes) -> tuple[int, int]:
203
"""
204
Get dimensions of an associated image.
205
206
Args:
207
slide: _OpenSlide handle
208
name: Associated image name
209
210
Returns:
211
(width, height) tuple for the associated image
212
"""
213
214
def read_associated_image(slide: lowlevel._OpenSlide, name: str | bytes) -> Image.Image:
215
"""
216
Read an associated image.
217
218
Args:
219
slide: _OpenSlide handle
220
name: Associated image name
221
222
Returns:
223
PIL.Image with the associated image data (not premultiplied)
224
225
Raises:
226
KeyError: If the associated image name doesn't exist
227
"""
228
```
229
230
### ICC Profile Functions
231
232
Functions for accessing ICC color profiles (requires OpenSlide 4.0.0+).
233
234
```python { .api }
235
def get_icc_profile_size(slide: lowlevel._OpenSlide) -> int:
236
"""
237
Get the size of the ICC color profile for the slide.
238
239
Args:
240
slide: _OpenSlide handle
241
242
Returns:
243
Size of ICC profile in bytes, or 0 if no profile available
244
245
Raises:
246
OpenSlideVersionError: If OpenSlide version < 4.0.0
247
"""
248
249
def read_icc_profile(slide: lowlevel._OpenSlide) -> bytes | None:
250
"""
251
Read the ICC color profile for the slide.
252
253
Args:
254
slide: _OpenSlide handle
255
256
Returns:
257
ICC profile as bytes, or None if no profile available
258
259
Raises:
260
OpenSlideVersionError: If OpenSlide version < 4.0.0
261
"""
262
263
def get_associated_image_icc_profile_size(slide: lowlevel._OpenSlide, name: str | bytes) -> int:
264
"""
265
Get the size of the ICC color profile for an associated image.
266
267
Args:
268
slide: _OpenSlide handle
269
name: Associated image name
270
271
Returns:
272
Size of ICC profile in bytes, or 0 if no profile available
273
274
Raises:
275
OpenSlideVersionError: If OpenSlide version < 4.0.0
276
"""
277
278
def read_associated_image_icc_profile(slide: lowlevel._OpenSlide, name: str | bytes) -> bytes | None:
279
"""
280
Read the ICC color profile for an associated image.
281
282
Args:
283
slide: _OpenSlide handle
284
name: Associated image name
285
286
Returns:
287
ICC profile as bytes, or None if no profile available
288
289
Raises:
290
OpenSlideVersionError: If OpenSlide version < 4.0.0
291
"""
292
```
293
294
### Cache Functions
295
296
Functions for managing tile caches (requires OpenSlide 4.0.0+).
297
298
```python { .api }
299
def cache_create(capacity: int) -> lowlevel._OpenSlideCache:
300
"""
301
Create a new tile cache.
302
303
Args:
304
capacity: Cache capacity in bytes
305
306
Returns:
307
_OpenSlideCache handle
308
309
Raises:
310
OpenSlideVersionError: If OpenSlide version < 4.0.0
311
"""
312
313
def set_cache(slide: lowlevel._OpenSlide, cache: lowlevel._OpenSlideCache) -> None:
314
"""
315
Set the tile cache for a slide.
316
317
Args:
318
slide: _OpenSlide handle
319
cache: _OpenSlideCache handle
320
321
Raises:
322
OpenSlideVersionError: If OpenSlide version < 4.0.0
323
"""
324
325
def cache_release(cache: lowlevel._OpenSlideCache) -> None:
326
"""
327
Release a tile cache and free associated resources.
328
329
Args:
330
cache: _OpenSlideCache handle to release
331
332
Raises:
333
OpenSlideVersionError: If OpenSlide version < 4.0.0
334
"""
335
```
336
337
## Low-Level Types
338
339
```python { .api }
340
class _OpenSlide:
341
"""
342
Wrapper class for OpenSlide C library handles.
343
344
Not intended for direct instantiation - use lowlevel.open() instead.
345
"""
346
347
class _OpenSlideCache:
348
"""
349
Wrapper class for OpenSlide cache handles.
350
351
Not intended for direct instantiation - use lowlevel.cache_create() instead.
352
"""
353
354
# Type alias for filename parameters
355
Filename = str | bytes | os.PathLike[Any]
356
```
357
358
## Exception Classes
359
360
```python { .api }
361
class OpenSlideError(Exception):
362
"""
363
Base exception class for OpenSlide errors.
364
365
Raised when the OpenSlide C library encounters an error.
366
"""
367
368
class OpenSlideVersionError(OpenSlideError):
369
"""
370
Exception raised when requested functionality requires a newer OpenSlide version.
371
372
Attributes:
373
minimum_version: String indicating the minimum required version
374
"""
375
376
def __init__(self, minimum_version: str): ...
377
378
class OpenSlideUnsupportedFormatError(OpenSlideError):
379
"""
380
Exception raised when OpenSlide doesn't support the requested file format.
381
"""
382
```
383
384
## Usage Examples
385
386
### Basic Low-Level Usage
387
388
```python
389
import openslide.lowlevel as lowlevel
390
from PIL import Image
391
392
# Open slide at low level
393
slide = lowlevel.open("slide.svs")
394
395
try:
396
# Get basic information
397
level_count = lowlevel.get_level_count(slide)
398
dimensions = lowlevel.get_level_dimensions(slide, 0)
399
print(f"Levels: {level_count}, Level 0 dimensions: {dimensions}")
400
401
# Read a region
402
region = lowlevel.read_region(slide, 1000, 1000, 0, 512, 512)
403
region.save("region.png")
404
405
# Check for errors
406
error = lowlevel.get_error(slide)
407
if error:
408
print(f"Error: {error}")
409
410
finally:
411
# Always close the slide
412
lowlevel.close(slide)
413
```
414
415
### Working with Properties
416
417
```python
418
import openslide.lowlevel as lowlevel
419
420
slide = lowlevel.open("slide.svs")
421
422
try:
423
# Get all property names
424
prop_names = lowlevel.get_property_names(slide)
425
print(f"Found {len(prop_names)} properties:")
426
427
# Read specific properties
428
for name in prop_names:
429
value = lowlevel.get_property_value(slide, name)
430
print(f" {name}: {value}")
431
432
# Check for specific properties
433
vendor = lowlevel.get_property_value(slide, "openslide.vendor")
434
if vendor:
435
print(f"Slide vendor: {vendor}")
436
437
finally:
438
lowlevel.close(slide)
439
```
440
441
### Advanced Caching Usage
442
443
```python
444
import openslide.lowlevel as lowlevel
445
446
# Check if caching is available
447
if lowlevel.cache_create.available:
448
# Create a 128MB cache
449
cache = lowlevel.cache_create(128 * 1024 * 1024)
450
451
slide1 = lowlevel.open("slide1.svs")
452
slide2 = lowlevel.open("slide2.svs")
453
454
try:
455
# Share cache between slides
456
lowlevel.set_cache(slide1, cache)
457
lowlevel.set_cache(slide2, cache)
458
459
# Read regions (will use shared cache)
460
region1 = lowlevel.read_region(slide1, 0, 0, 0, 1024, 1024)
461
region2 = lowlevel.read_region(slide2, 0, 0, 0, 1024, 1024)
462
463
finally:
464
lowlevel.close(slide1)
465
lowlevel.close(slide2)
466
lowlevel.cache_release(cache)
467
else:
468
print("Caching not available - upgrade to OpenSlide 4.0.0+")
469
```
470
471
### ICC Profile Access
472
473
```python
474
import openslide.lowlevel as lowlevel
475
from PIL import ImageCms
476
from io import BytesIO
477
478
slide = lowlevel.open("slide.svs")
479
480
try:
481
if lowlevel.read_icc_profile.available:
482
# Read main image ICC profile
483
profile_data = lowlevel.read_icc_profile(slide)
484
if profile_data:
485
profile = ImageCms.getOpenProfile(BytesIO(profile_data))
486
print(f"Color space: {profile.color_space}")
487
488
# Read associated image profiles
489
assoc_names = lowlevel.get_associated_image_names(slide)
490
for name in assoc_names:
491
assoc_profile = lowlevel.read_associated_image_icc_profile(slide, name)
492
if assoc_profile:
493
print(f"Associated image '{name}' has ICC profile")
494
else:
495
print("ICC profile support not available - upgrade to OpenSlide 4.0.0+")
496
497
finally:
498
lowlevel.close(slide)
499
```