large-image

1.34.1 verified Fri May 01 auth: no python

A Python library for working with large, multiresolution images, supporting tiles, annotations, and warping. Current version is 1.34.1, with regular releases every few weeks.

pip install large-image

Common errors

error ModuleNotFoundError: No module named 'openslide' ↓

cause Missing OpenSlide native library or Python binding.

fix

Install OpenSlide system package (e.g., apt install openslide-tools) and then pip install openslide-python.

error AttributeError: module 'large_image' has no attribute 'LargeImageSource' ↓

cause Incorrect import of legacy class name.

fix

Use from large_image import getTileSource instead of instantiating a class.

Warnings

gotcha Tile coordinates (x, y, z) are integer tile indices, not pixel coordinates. Use getRegion for pixel-based cropping. ↓

fix Use getRegion with pixel coordinates if you need arbitrary rectangular crops.

deprecated The `large_image_source_tiff` and other per-format modules are deprecated in favor of the unified `source` API. ↓

fix Use `from large_image import source` or `getTileSource` directly.

gotcha When installed without optional dependencies (e.g., OpenSlide, tifffile), unsupported image formats will raise an ImportError. ↓

fix Install with the appropriate extras: `pip install large-image[openslide,tiff]`.

Install

pip install large-image[sources]

Imports

source
wrong
```
import large_image_source_tiff
```
correct
```
from large_image import source
```
Use the unified 'source' API instead of per-format modules.

getTileSource

wrong

from large_image_source_tiff import getTileSource

correct

from large_image import getTileSource

The main entry point is 'getTileSource' from the top-level package.

Quickstart

Opens a multiresolution image and retrieves a tile and a region.

from large_image import getTileSource

# Open an image (replace with a path to a large image)
source = getTileSource('path/to/large_image.svs')
print('Image metadata:', source.getMetadata())

# Get a tile (x, y, z) - e.g., tile at top-left of level 0
tile = source.getTile(0, 0, 0)
print('Tile shape:', tile.shape)

# Get a region (format: {'left', 'top', 'right', 'bottom'})
region = source.getRegion(region={'left': 0, 'top': 0, 'right': 256, 'bottom': 256})
print('Region shape:', region.shape)