girder-large-image

1.34.1 verified Sat May 09 auth: no python

A Girder plugin for working with large, multiresolution images (e.g., whole-slide images, satellite imagery). Supports tile serving, annotation, warping, and multiple backends (OpenSlide, TIFF, DICOM). Current version 1.34.1, requires Python >=3.10, released under Apache 2.0. Package is actively maintained; releases occur approximately monthly.

pip install girder-large-image

Common errors

error ModuleNotFoundError: No module named 'large_image' ↓

cause girder-large-image not installed or installed without core dependencies.

fix

Run pip install girder-large-image (the core module). If using extras, install with e.g. girder-large-image[openslide].

error ImportError: cannot import name 'OpenSlideFileTileSource' from 'large_image_source_openslide' ↓

cause Import path changed; the source modules are now under `large_image.tilesource`.

fix

Use from large_image.tilesource.openslide import OpenSlideFileTileSource.

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

cause Older versions of the library had a different API; or the library is not up to date.

fix

Upgrade to latest version: pip install --upgrade girder-large-image. For versions <1.30, use large_image.OpenSlideFileTileSource directly.

Warnings

breaking In v1.33.0, the `frames` and `subdatasets` parameters in geospatial sources changed. Code relying on old parameter names will break. ↓

fix Update calls to use new parameter structure: see PR #1972.

deprecated The old `girder_large_image` import path is removed. Use `large_image` for core module, and `large_image_source_*` for specific sources. ↓

fix Replace `from girder_large_image import ...` with `from large_image import ...` or `from large_image.tilesource.openslide import ...`.

gotcha When using `girder-large-image` as a Girder plugin, you must also install `girder` and configure it. The plugin is not automatically enabled. ↓

fix Install via `pip install girder-large-image[girder]`, then enable the plugin in Girder configuration.

gotcha The `pillow-jpls` module was moved out of common extras in v1.32.10. If you need JPEG-LS support, install separately. ↓

fix Run `pip install pillow-jpls` explicitly.

Install

pip install girder-large-image[girder]

pip install girder-large-image[openslide]

Imports

OpenSlideFileTileSource

wrong

from large_image_source_openslide import OpenSlideFileTileSource

correct

from large_image.tilesource.openslide import OpenSlideFileTileSource

Wrong: the source module is nested under large_image.tilesource.

TileSource

wrong

from girder_large_image import TileSource

correct

from large_image import tilesource

Wrong: the old Girder-based import path was deprecated.

tileSource
```
from large_image.tilesource import TileSource
```
Correct import for the base tile source class.

Quickstart

Basic usage: open a large image, read metadata, get tiles and regions.

import large_image

# Open an image file (e.g., SVS, TIFF, PNG)
ts = large_image.open('path/to/image.svs')

# Get basic metadata
print(ts.getMetadata())

# Get a tile (256x256) at level 0, coordinates (0,0)
tile, format = ts.getTile(0, 0, 0)
print(f'Tile size: {tile.size}, format: {format}')

# Get a region (512x512) from level 1
region, format = ts.getRegion(region=dict(left=100, top=100, width=512, height=512), scale=dict(colsLevel=1))
print(f'Region size: {region.size}')