glasscut.tiler package

Submodules

glasscut.tiler.base module

Base Tiler abstract class for tile extraction strategies.

class glasscut.tiler.base.Tiler[source]

Bases: ABC

Abstract base class for tile extraction strategies.

A Tiler is responsible for determining which tiles to extract from a slide and providing them to the user. Different tiling strategies can be implemented by subclassing this class.

abstractmethod extract(slide, *, n_workers=4, batch_size=128)[source]

Extract tiles from slide.

This is the primary extraction API for all tilers. Implementations can use batching and parallelism internally.

Parameters:

  • slide (Slide) – The slide object to extract tiles from

  • n_workers (int, optional) – Worker hint for internal parallel extraction. Default is 4.

  • batch_size (int, optional) – Internal extraction batch size. Default is 128.

Yields:

Tile – Individual tile objects with image, coordinates, and metadata

Raises:

  • MagnificationError – If the requested magnification is not available on this slide

  • TileSizeOrCoordinatesError – If generated coordinates are invalid for the slide

  • Example: – 

    >>> slide = Slide("slide.svs")
    >>> tiler = GridTiler(tile_size=(512, 512), overlap=50)
    >>> for tile in tiler.extract(slide):
    ...     tile.save(f"tile_{tile.coords}.png")

Return type:

Generator[Tile, None, None]

abstractmethod get_tile_boxes(slide)[source]

Get all tile boxes without extracting images.

This method computes which tile regions would be extracted without actually reading images from the slide. Useful for planning, filtering, or batch processing.

Parameters:

slide (Slide) – The slide object

Returns:

  • list[tuple[int, int, int, int]] – List of tile boxes as (x, y, width, height) in level-0 space.

  • Example – >>> tiler = GridTiler(tile_size=(512, 512)) >>> boxes = tiler.get_tile_boxes(slide) >>> print(f”Will extract {len(boxes)} tiles”)

Return type:

list[tuple[int, int, int, int]]

visualize(slide, scale_factor=32, colors=None, linewidth=1)[source]

Visualize tile grid on a slide thumbnail.

This method creates a thumbnail of the slide and draws the tile grid on top of it. Useful for verifying tiling strategy before processing.

Parameters:

  • slide (Slide) – The slide object to visualize

  • scale_factor (int, optional) – Scale factor for thumbnail downsampling. Default is 32.

  • colors (list[tuple[int, int, int]] | None, optional) – RGB colors for tile rectangles. If None, uses a cycle of colors. Default is None.

  • alpha (int, optional) – Transparency alpha value for rectangles (0-255). Default is 200.

  • linewidth (int, optional) – Width of rectangle lines in pixels. Default is 1.

Returns:

  • PIL.Image.Image – Thumbnail image with tile grid drawn on it

  • Example – >>> tiler = GridTiler(tile_size=(512, 512)) >>> viz_image = tiler.visualize(slide) >>> viz_image.show()

Return type:

Image

glasscut.tiler.grid module

Grid-based tiler implementation for GlassCut.

class glasscut.tiler.grid.GridTiler(tile_size=(512, 512), magnification=20, overlap=0, min_tissue_ratio=0.2, tissue_detector=None, transforms=None, show_progress=True, debug=False)[source]

Bases: Tiler

Extract tiles using a regular grid.

Parameters:

  • tile_size (tuple[int, int], optional) – Default tile size as (width, height) in pixels at requested magnification. Default is (512, 512).

  • magnification (int | float, optional) – Magnification used for extraction and coordinate generation. Default is 20.

  • overlap (int, optional) – Overlap between neighboring tiles in pixels at requested magnification. Default is 0.

  • min_tissue_ratio (float, optional) – Minimum tissue ratio in [0.0, 1.0] required for preselection. Default is 0.2.

  • tissue_detector (TissueDetector | None, optional) – Tissue detector used for preselection mask. Defaults to OtsuTissueDetector.

  • show_progress (bool, optional) – Whether to display a loading bar while extracting tiles. Default is True.

  • debug (bool, optional) – When True, record and print per-phase timing breakdown (tissue mask, candidate grid, tile extraction, transforms). Default is False.

  • transforms (list[Callable[[Image], Image]] | None)

__init__(tile_size=(512, 512), magnification=20, overlap=0, min_tissue_ratio=0.2, tissue_detector=None, transforms=None, show_progress=True, debug=False)[source]
Parameters:
Return type:

None

get_tile_boxes(slide)[source]

Return preselected grid boxes as (x, y, width, height).

Parameters:

slide (Slide)

Return type:

list[tuple[int, int, int, int]]

get_tile_candidates(slide)[source]

Return preselected boxes with tissue ratio as (x, y, w, h, ratio).

Parameters:

slide (Slide)

Return type:

list[tuple[int, int, int, int, float]]

extract(slide, *, n_workers=4, batch_size=128)[source]

Yield tiles using batched parallel extraction.

Each worker thread extracts a single tile from the slide and immediately applies the full transform pipeline.

Parameters:
Return type:

Generator[Tile, None, None]

print_profile()[source]
Return type:

None

Module contents

Tiler module for tile extraction strategies.

Main Classes:

  • Tiler: Abstract base class for all tiling strategies

  • GridTiler: Regular grid tiling

  • RandomTiler: Random sampling based tiling

Example:
>>> from glasscut import Slide, GridTiler
>>> slide = Slide("path/to/slide.svs")
>>> tiler = GridTiler(tile_size=512, overlap=50)
>>> for tile in tiler.extract(slide, magnification=20):
...     print(f"Tile at {tile.coords}: size {tile.image.size}")
class glasscut.tiler.Tiler[source]

Bases: ABC

Abstract base class for tile extraction strategies.

A Tiler is responsible for determining which tiles to extract from a slide and providing them to the user. Different tiling strategies can be implemented by subclassing this class.

abstractmethod extract(slide, *, n_workers=4, batch_size=128)[source]

Extract tiles from slide.

This is the primary extraction API for all tilers. Implementations can use batching and parallelism internally.

Parameters:

  • slide (Slide) – The slide object to extract tiles from

  • n_workers (int, optional) – Worker hint for internal parallel extraction. Default is 4.

  • batch_size (int, optional) – Internal extraction batch size. Default is 128.

Yields:

Tile – Individual tile objects with image, coordinates, and metadata

Raises:

  • MagnificationError – If the requested magnification is not available on this slide

  • TileSizeOrCoordinatesError – If generated coordinates are invalid for the slide

  • Example: – 

    >>> slide = Slide("slide.svs")
    >>> tiler = GridTiler(tile_size=(512, 512), overlap=50)
    >>> for tile in tiler.extract(slide):
    ...     tile.save(f"tile_{tile.coords}.png")

Return type:

Generator[Tile, None, None]

abstractmethod get_tile_boxes(slide)[source]

Get all tile boxes without extracting images.

This method computes which tile regions would be extracted without actually reading images from the slide. Useful for planning, filtering, or batch processing.

Parameters:

slide (Slide) – The slide object

Returns:

  • list[tuple[int, int, int, int]] – List of tile boxes as (x, y, width, height) in level-0 space.

  • Example – >>> tiler = GridTiler(tile_size=(512, 512)) >>> boxes = tiler.get_tile_boxes(slide) >>> print(f”Will extract {len(boxes)} tiles”)

Return type:

list[tuple[int, int, int, int]]

visualize(slide, scale_factor=32, colors=None, linewidth=1)[source]

Visualize tile grid on a slide thumbnail.

This method creates a thumbnail of the slide and draws the tile grid on top of it. Useful for verifying tiling strategy before processing.

Parameters:

  • slide (Slide) – The slide object to visualize

  • scale_factor (int, optional) – Scale factor for thumbnail downsampling. Default is 32.

  • colors (list[tuple[int, int, int]] | None, optional) – RGB colors for tile rectangles. If None, uses a cycle of colors. Default is None.

  • alpha (int, optional) – Transparency alpha value for rectangles (0-255). Default is 200.

  • linewidth (int, optional) – Width of rectangle lines in pixels. Default is 1.

Returns:

  • PIL.Image.Image – Thumbnail image with tile grid drawn on it

  • Example – >>> tiler = GridTiler(tile_size=(512, 512)) >>> viz_image = tiler.visualize(slide) >>> viz_image.show()

Return type:

Image

class glasscut.tiler.GridTiler(tile_size=(512, 512), magnification=20, overlap=0, min_tissue_ratio=0.2, tissue_detector=None, transforms=None, show_progress=True, debug=False)[source]

Bases: Tiler

Extract tiles using a regular grid.

Parameters:

  • tile_size (tuple[int, int], optional) – Default tile size as (width, height) in pixels at requested magnification. Default is (512, 512).

  • magnification (int | float, optional) – Magnification used for extraction and coordinate generation. Default is 20.

  • overlap (int, optional) – Overlap between neighboring tiles in pixels at requested magnification. Default is 0.

  • min_tissue_ratio (float, optional) – Minimum tissue ratio in [0.0, 1.0] required for preselection. Default is 0.2.

  • tissue_detector (TissueDetector | None, optional) – Tissue detector used for preselection mask. Defaults to OtsuTissueDetector.

  • show_progress (bool, optional) – Whether to display a loading bar while extracting tiles. Default is True.

  • debug (bool, optional) – When True, record and print per-phase timing breakdown (tissue mask, candidate grid, tile extraction, transforms). Default is False.

  • transforms (list[Callable[[Image], Image]] | None)

__init__(tile_size=(512, 512), magnification=20, overlap=0, min_tissue_ratio=0.2, tissue_detector=None, transforms=None, show_progress=True, debug=False)[source]
Parameters:
Return type:

None

get_tile_boxes(slide)[source]

Return preselected grid boxes as (x, y, width, height).

Parameters:

slide (Slide)

Return type:

list[tuple[int, int, int, int]]

get_tile_candidates(slide)[source]

Return preselected boxes with tissue ratio as (x, y, w, h, ratio).

Parameters:

slide (Slide)

Return type:

list[tuple[int, int, int, int, float]]

extract(slide, *, n_workers=4, batch_size=128)[source]

Yield tiles using batched parallel extraction.

Each worker thread extracts a single tile from the slide and immediately applies the full transform pipeline.

Parameters:
Return type:

Generator[Tile, None, None]

print_profile()[source]
Return type:

None