glasscut.slides.backends package¶

Submodules¶

glasscut.slides.backends.base module¶

Abstract backend interface for slide reading.

class glasscut.slides.backends.base.SlideBackend[source]¶

Bases: ABC

Abstract base class for slide reading backends.

This defines the interface that all slide backends must implement. Backends handle the actual reading of slide files and tile extraction.

abstractmethod open(path)[source]¶

Open a slide file.

Parameters:: path (str | Path) – Path to the slide file
Return type:: None

abstractmethod close()[source]¶

Close the slide and free resources.

Return type:: None

abstract property dimensions: tuple[int, int]¶

Get slide dimensions at level 0 (width, height).

Returns:: Width and height in pixels at highest magnification
Return type:: tuple[int, int]

abstract property properties: dict[str, str]¶

Get slide metadata/properties.

Returns:: Dictionary of slide properties
Return type:: dict[str, str]

abstract property num_levels: int¶

Get number of pyramid levels.

Returns:: Number of pyramid levels
Return type:: int

abstractmethod read_region(location, level, size)[source]¶

Read a region/tile from the slide.

Parameters:

location (tuple[int, int]) – (x, y) coordinates at level 0
level (int) – Pyramid level to read from
size (tuple[int, int]) – (width, height) of the tile to read in pixels

Returns:

The tile image in RGB format

Return type:

PIL.Image.Image

abstractmethod get_thumbnail(size)[source]¶

Get thumbnail of the slide.

Parameters:: size (tuple[int, int]) – Maximum size of the thumbnail (width, height)
Returns:: Thumbnail image
Return type:: PIL.Image.Image

abstract property mpp: float¶

Get microns per pixel at base magnification.

Returns:: Microns per pixel
Return type:: float
Raises:: SlidePropertyError – If MPP cannot be determined from slide metadata

abstract property base_magnification: int | float¶

Get the base magnification (objective power) of the slide.

This is the magnification at level 0 (highest resolution). For example, 40x, 20x, 10x, etc.

Returns:: Base magnification value
Return type:: int | float
Raises:: SlidePropertyError – If base magnification cannot be determined from slide metadata

__enter__()[source]¶: Context manager entry.

__exit__(exc_type, exc_val, exc_tb)[source]¶

Context manager exit.

Parameters:

exc_type (type[BaseException] | None)
exc_val (BaseException | None)
exc_tb (TracebackType | None)

Return type:

None

glasscut.slides.backends.cucim_backend module¶

CuCim backend for GPU-accelerated slide reading.

class glasscut.slides.backends.cucim_backend.CuPyArrayProtocol(*args, **kwargs)[source]¶

Bases: Protocol

Protocol for CuPy GPU arrays with NumPy-like interface.

get()[source]¶

Transfer array from GPU to CPU (NumPy array).

Return type:: object

__init__(*args, **kwargs)¶

class glasscut.slides.backends.cucim_backend.CuImageProtocol(*args, **kwargs)[source]¶

Bases: Protocol

Protocol describing the interface of cucim.CuImage objects.

property shape: tuple[int, ...]¶: Image shape as (height, width, channels).

read_region(location, level, size)[source]¶

Read a region from the image at specified level.

Returns a CuPy array or NumPy array.

Parameters:

location (tuple[int, int])
level (int)
size (tuple[int, int])

Return type:

CuPyArrayProtocol | object

__init__(*args, **kwargs)¶

class glasscut.slides.backends.cucim_backend.CuCimBackend[source]¶

Bases: SlideBackend

CuCim-based backend for GPU-accelerated slide reading.

This backend uses RAPIDS cuCim for high-performance GPU-accelerated reading of whole slide images. Falls back to OpenSlide for metadata and operations not supported by cuCim.

__init__()[source]¶

Return type:: None

open(path)[source]¶

Open a slide file using CuCim.

Parameters:

path (str | Path) – Path to the slide file

Raises:

FileNotFoundError – If the slide file does not exist
BackendError – If cuCim cannot open the file

Return type:

None

close()[source]¶

Close the slide and free GPU memory.

Return type:: None

property dimensions: tuple[int, int]¶

Get slide dimensions at level 0.

Returns:: (width, height) at highest magnification
Return type:: Tuple[int, int]

property properties: dict[str, str]¶

Get slide metadata properties.

Falls back to OpenSlide for metadata retrieval.

Returns:: Dictionary of slide properties
Return type:: dict[str, str]

property num_levels: int¶

Get number of pyramid levels.

Falls back to OpenSlide for level information.

Returns:: Number of pyramid levels
Return type:: int

read_region(location, level, size)[source]¶

Read a region/tile from the slide using GPU acceleration.

Parameters:

location (tuple[int, int]) – (x, y) coordinates at level 0
level (int) – Pyramid level to read from
size (tuple[int, int]) – (width, height) of the tile in pixels

Returns:

The tile image in RGB format

Return type:

PIL.Image.Image

get_thumbnail(size)[source]¶

Get thumbnail of the slide.

Falls back to OpenSlide if available.

Parameters:: size (tuple[int, int]) – Maximum size of the thumbnail (width, height)
Returns:: Thumbnail image in RGB format
Return type:: PIL.Image.Image

property mpp: float¶

Get microns per pixel at base magnification.

Falls back to OpenSlide for metadata retrieval.

Returns:: Microns per pixel (MPP)
Return type:: float
Raises:: SlidePropertyError – If MPP cannot be determined from metadata

property base_magnification: int | float¶

Get the base magnification (objective power) of the slide.

Falls back to OpenSlide for metadata retrieval.

Returns:: Base magnification value
Return type:: int | float
Raises:: SlidePropertyError – If base magnification cannot be determined from metadata

glasscut.slides.backends.openslide_backend module¶

OpenSlide backend for slide reading (CPU-based).

class glasscut.slides.backends.openslide_backend.OpenSlideBackend[source]¶

Bases: SlideBackend

OpenSlide-based backend for reading whole slide images.

This is the CPU-based fallback backend. It uses the OpenSlide library to read various slide formats (SVS, TIFF, etc.).

__init__()[source]¶

Return type:: None

open(path)[source]¶

Open a slide file using OpenSlide.

Parameters:

path (Union[str, Path]) – Path to the slide file

Raises:

FileNotFoundError – If the slide file does not exist
BackendError – If OpenSlide cannot open the file

Return type:

None

close()[source]¶

Close the slide.

Return type:: None

property dimensions: Tuple[int, int]¶

Get slide dimensions at level 0.

Returns:: (width, height) at highest magnification
Return type:: Tuple[int, int]

property properties: Dict[str, str]¶

Get slide metadata properties.

Returns:: Dictionary of slide properties
Return type:: Dict[str, str]

property num_levels: int¶

Get number of pyramid levels.

Returns:: Number of pyramid levels
Return type:: int

read_region(location, level, size)[source]¶

Read a region/tile from the slide.

Parameters:

location (Tuple[int, int]) – (x, y) coordinates at level 0
level (int) – Pyramid level to read from
size (Tuple[int, int]) – (width, height) of the tile in pixels

Returns:

The tile image in RGB format

Return type:

PIL.Image.Image

get_thumbnail(size)[source]¶

Get thumbnail of the slide.

Parameters:: size (Tuple[int, int]) – Maximum size of the thumbnail (width, height)
Returns:: Thumbnail image in RGB format
Return type:: PIL.Image.Image

property mpp: float¶

Get microns per pixel at base magnification.

Returns:: Microns per pixel (MPP)
Return type:: float
Raises:: SlidePropertyError – If MPP cannot be determined from metadata

property base_magnification: int | float¶

Get the base magnification (objective power) of the slide.

Returns:: Base magnification value
Return type:: int | float
Raises:: SlidePropertyError – If base magnification cannot be determined from metadata

Module contents¶

Slide reading backends.

class glasscut.slides.backends.SlideBackend[source]¶

Bases: ABC

Abstract base class for slide reading backends.

This defines the interface that all slide backends must implement. Backends handle the actual reading of slide files and tile extraction.

abstractmethod open(path)[source]¶

Open a slide file.

Parameters:: path (str | Path) – Path to the slide file
Return type:: None

abstractmethod close()[source]¶

Close the slide and free resources.

Return type:: None

abstract property dimensions: tuple[int, int]¶

Get slide dimensions at level 0 (width, height).

Returns:: Width and height in pixels at highest magnification
Return type:: tuple[int, int]

abstract property properties: dict[str, str]¶

Get slide metadata/properties.

Returns:: Dictionary of slide properties
Return type:: dict[str, str]

abstract property num_levels: int¶

Get number of pyramid levels.

Returns:: Number of pyramid levels
Return type:: int

abstractmethod read_region(location, level, size)[source]¶

Read a region/tile from the slide.

Parameters:

location (tuple[int, int]) – (x, y) coordinates at level 0
level (int) – Pyramid level to read from
size (tuple[int, int]) – (width, height) of the tile to read in pixels

Returns:

The tile image in RGB format

Return type:

PIL.Image.Image

abstractmethod get_thumbnail(size)[source]¶

Get thumbnail of the slide.

Parameters:: size (tuple[int, int]) – Maximum size of the thumbnail (width, height)
Returns:: Thumbnail image
Return type:: PIL.Image.Image

abstract property mpp: float¶

Get microns per pixel at base magnification.

Returns:: Microns per pixel
Return type:: float
Raises:: SlidePropertyError – If MPP cannot be determined from slide metadata

abstract property base_magnification: int | float¶

Get the base magnification (objective power) of the slide.

This is the magnification at level 0 (highest resolution). For example, 40x, 20x, 10x, etc.

Returns:: Base magnification value
Return type:: int | float
Raises:: SlidePropertyError – If base magnification cannot be determined from slide metadata

__enter__()[source]¶: Context manager entry.

__exit__(exc_type, exc_val, exc_tb)[source]¶

Context manager exit.

Parameters:

exc_type (type[BaseException] | None)
exc_val (BaseException | None)
exc_tb (TracebackType | None)

Return type:

None

class glasscut.slides.backends.OpenSlideBackend[source]¶

Bases: SlideBackend

OpenSlide-based backend for reading whole slide images.

This is the CPU-based fallback backend. It uses the OpenSlide library to read various slide formats (SVS, TIFF, etc.).

__init__()[source]¶

Return type:: None

open(path)[source]¶

Open a slide file using OpenSlide.

Parameters:

path (Union[str, Path]) – Path to the slide file

Raises:

FileNotFoundError – If the slide file does not exist
BackendError – If OpenSlide cannot open the file

Return type:

None

close()[source]¶

Close the slide.

Return type:: None

property dimensions: Tuple[int, int]¶

Get slide dimensions at level 0.

Returns:: (width, height) at highest magnification
Return type:: Tuple[int, int]

property properties: Dict[str, str]¶

Get slide metadata properties.

Returns:: Dictionary of slide properties
Return type:: Dict[str, str]

property num_levels: int¶

Get number of pyramid levels.

Returns:: Number of pyramid levels
Return type:: int

read_region(location, level, size)[source]¶

Read a region/tile from the slide.

Parameters:

location (Tuple[int, int]) – (x, y) coordinates at level 0
level (int) – Pyramid level to read from
size (Tuple[int, int]) – (width, height) of the tile in pixels

Returns:

The tile image in RGB format

Return type:

PIL.Image.Image

get_thumbnail(size)[source]¶

Get thumbnail of the slide.

Parameters:: size (Tuple[int, int]) – Maximum size of the thumbnail (width, height)
Returns:: Thumbnail image in RGB format
Return type:: PIL.Image.Image

property mpp: float¶

Get microns per pixel at base magnification.

Returns:: Microns per pixel (MPP)
Return type:: float
Raises:: SlidePropertyError – If MPP cannot be determined from metadata

property base_magnification: int | float¶

Get the base magnification (objective power) of the slide.

Returns:: Base magnification value
Return type:: int | float
Raises:: SlidePropertyError – If base magnification cannot be determined from metadata

class glasscut.slides.backends.CuCimBackend[source]¶

Bases: SlideBackend

CuCim-based backend for GPU-accelerated slide reading.

This backend uses RAPIDS cuCim for high-performance GPU-accelerated reading of whole slide images. Falls back to OpenSlide for metadata and operations not supported by cuCim.

__init__()[source]¶

Return type:: None

open(path)[source]¶

Open a slide file using CuCim.

Parameters:

path (str | Path) – Path to the slide file

Raises:

FileNotFoundError – If the slide file does not exist
BackendError – If cuCim cannot open the file

Return type:

None

close()[source]¶

Close the slide and free GPU memory.

Return type:: None

property dimensions: tuple[int, int]¶

Get slide dimensions at level 0.

Returns:: (width, height) at highest magnification
Return type:: Tuple[int, int]

property properties: dict[str, str]¶

Get slide metadata properties.

Falls back to OpenSlide for metadata retrieval.

Returns:: Dictionary of slide properties
Return type:: dict[str, str]

property num_levels: int¶

Get number of pyramid levels.

Falls back to OpenSlide for level information.

Returns:: Number of pyramid levels
Return type:: int

read_region(location, level, size)[source]¶

Read a region/tile from the slide using GPU acceleration.

Parameters:

location (tuple[int, int]) – (x, y) coordinates at level 0
level (int) – Pyramid level to read from
size (tuple[int, int]) – (width, height) of the tile in pixels

Returns:

The tile image in RGB format

Return type:

PIL.Image.Image

get_thumbnail(size)[source]¶

Get thumbnail of the slide.

Falls back to OpenSlide if available.

Parameters:: size (tuple[int, int]) – Maximum size of the thumbnail (width, height)
Returns:: Thumbnail image in RGB format
Return type:: PIL.Image.Image

property mpp: float¶

Get microns per pixel at base magnification.

Falls back to OpenSlide for metadata retrieval.

Returns:: Microns per pixel (MPP)
Return type:: float
Raises:: SlidePropertyError – If MPP cannot be determined from metadata

property base_magnification: int | float¶

Get the base magnification (objective power) of the slide.

Falls back to OpenSlide for metadata retrieval.

Returns:: Base magnification value
Return type:: int | float
Raises:: SlidePropertyError – If base magnification cannot be determined from metadata