tiling module

This module provides functions for splitting an image and its annotations into smaller, overlapping tiles.

The tile_image function splits a PIL Image object into a grid of tiles with a specified size and overlap ratio. It handles padding the image with black pixels if necessary to ensure all tiles fit perfectly within the image boundaries.

The tile_annotations function is a sister function to tile_image and can be used to tile annotations associated with the image using (nearly) the same parameters as tile_image. It assumes annotations implement a ‘box’ property representing their location within the image. Each annotation is assigned to the tile(s) that completely enclose its bounding box.

utilities.tiling.tile_image(image: Image, slice_width: int, slice_height: int, horizontal_overlap_ratio: float, vertical_overlap_ratio: float) → List[Image]

Splits a larger image into smaller ‘tiles’.

In the likely event that the exact choices of overlap ratios and slice dimensions do not multiply to make exactly the image’s dimensions, the image.crop method pads the image with black on the right and bottom sides.

Parameters:

  • image (PIL Image) – The image to tile.

  • slice_height (int) – The height of each slice.

  • slice_width (int) – The width of each slice.

  • horizontal_overlap_ratio (float) – The amount of left-right overlap between slices.

  • vertical_overlap_ratio (float) – The amount of top-bottom overlap between slices.

Returns:

A list of sliced images.

utilities.tiling.validate_tile_parameters(image: Image, slice_width: int, slice_height: int, horizontal_overlap_ratio: float, vertical_overlap_ratio: float) → None

Validates the parameters for the function ‘tile_image’.

Parameters:

  • image (PIL Image) – The image to tile.

  • slice_height (int) – The height of each slice.

  • slice_width (int) – The width of each slice.

  • horizontal_overlap_ratio (float) – The amount of left-right overlap between slices.

  • vertical_overlap_ratio (float) – The amount of top-bottom overlap between slices.

Raises:

ValueError – If slice_width is not within (0, image_width], slice_height not within (0, image_height), or horizontal/vertical overlap ratio not in (0, 1].

utilities.tiling.generate_tile_coordinates(image_width: int, image_height: int, slice_width: int, slice_height: int, horizontal_overlap_ratio: int, vertical_overlap_ratio: int) → List[List[Tuple[int, int, int, int]]]

Generates the box coordinates of the tiles for the function ‘tile_image’.

Parameters:

  • image_width (int) – The image’s width.

  • image_height (int) – The image’s height.

  • slice_height (int) – The height of each slice.

  • slice_width (int) – The width of each slice.

  • horizontal_overlap_ratio (float) – The amount of left-right overlap between slices.

  • vertical_overlap_ratio (float) – The amount of top-bottom overlap between slices.

Returns:

A 2d list of four coordinate tuples encoding the left, top, right, and bottom of each tile.

utilities.tiling.tile_annotations(annotations: List[BoundingBox | Keypoint], image_width: int, image_height: int, slice_width: int, slice_height: int, horizontal_overlap_ratio: float, vertical_overlap_ratio: float)

Tiles image annotations based on a specified grid pattern with overlap.

This function takes a list of annotations (any annotation that implements the ‘box’ property) representing objects within an image, and divides the image into a grid of tiles with a specified size and overlap. It then assigns each annotation to the tile(s) based on whether the annotation fully fits into the tile.

Parameters:

  • annotations (List[Union[BoundingBox, Keypoint]]) – A list of annotations (anything that implements the ‘box’ property).

  • image_width (int) – The width of the image in pixels.

  • image_height (int) – The height of the image in pixels.

  • slice_width (int) – The width of each tile in pixels.

  • slice_height (int) – The height of each tile in pixels.

  • horizontal_overlap_ratio (float) – The ratio (0.0 to 1.0) of the tile width that overlaps horizontally between adjacent tiles.

  • vertical_overlap_ratio (float) – The ratio (0.0 to 1.0) of the tile height that overlaps vertically between adjacent tiles.

Returns:

A list of lists, where each sub-list represents a tile in the grid. Each tile’s sub-list contains the annotations that intersect fully with that specific tile.

utilities.tiling.get_annotations_in_tile(annotations: List[BoundingBox | Keypoint], tile: Tuple[int, int, int, int]) → List

Filters annotations that fully intersect with a given tile.

This function takes a list of annotations (assumed to implement the ‘box’ property) and a tile represented by its top-left and bottom-right corner coordinates (left, top, right, bottom) as a tuple. It returns a new list containing only the annotations that have a bounding box intersecting with the specified tile area.

Parameters:

  • annotations – A list of annotations (expected to implement the ‘box’ property).

  • tile (Tuple[int, int, int, int]) – A tuple representing the tile’s bounding box coordinates (left, top, right, bottom).

Returns:

A list of BoundingBox objects that intersect with the specified tile.

utilities.tiling.correct_annotation_coords(annotation: BoundingBox | Keypoint, tile_left: int, tile_top: int, direction: Literal['image_to_tile', 'tile_to_image']) → BoundingBox | Keypoint

Corrects annotation coordinates from tiles to full images or from full images to tiles.

Parameters:

  • annotation (Union[BoundingBox, Keypoint]) – The annotation to correct.

  • tile_left (int) – The tile’s left side coordinate relative to the entire untiled image.

  • tile_top (int) – The tile’s left side coordinate relative to the entire untiled image.

  • direction (Literal["image_to_tile", "tile_to_image"]) – Determines whether the function subtracts or adds the tile’s left and top. Either “image_to_tile” or “tile_to_image”.

Returns: A new annotation with changed coordinates.