tlc.helpers.segmentation_helper¶

Helpers for working with segmentation data, including RLE and polygon conversion.

Module Contents¶

Classes¶

Class

Description

SegmentationHelper

Helper class for segmentation operations.

API¶

class SegmentationHelper¶

Helper class for segmentation operations.

static area_from_rle(
rle: CocoRle,
) → float¶

Return the area, in pixels, of the mask encoded by an RLE.

Parameters:

rle – The RLE mask to measure.

Returns:

The number of foreground pixels in the mask.

static bounding_box_from_rle(
rle: CocoRle,
) → list[float]¶

Convert an RLE mask to a bounding box.

Parameters:

rle – The RLE mask to convert

Returns:

The tight bounding box around the mask in COCO [x, y, width, height] format, where (x, y) is the top-left corner in absolute pixels.

static component_polygons_from_mask(
mask: ndarray,
*,
relative: bool = False,
) → list[list[float]]¶

Convert a binary mask to one polygon per connected component, with holes carved out.

Each returned polygon is a single self-touching polygon for one connected component: its hole (inner) contours are bridged into its outer contour via nearest-point connections, so the zero-width slits let even-odd rasterization exclude the holes. This is the COCO multi-polygon form (segmentation as a list of polygons). For the single-polygon form required by YOLO, see polygons_from_mask().

Parameters:

  • mask – The binary mask to convert.

  • relative – Whether to return coordinates relative to the image dimensions.

Returns:

List of polygons, one per connected component, each a flattened list of x,y coordinates.

static empty_rle(
height: int,
width: int,
) → CocoRle¶

Create an empty RLE mask with the given dimensions.

Parameters:

  • height – Height of the mask

  • width – Width of the mask

Returns:

An empty RLE mask dictionary with ‘counts’ and ‘size’ fields

static mask_from_polygons(
polygons: list[list[float]],
height: int,
width: int,
*,
relative: bool = False,
) → ndarray¶

Convert a list of polygons to a numpy array.

Parameters:

  • polygons – The list of polygons to convert

  • height – The height of the image

  • width – The width of the image

  • relative – Whether the polygons are relative to the image size

Returns:

A numpy array of shape (H, W, N) containing N binary masks

static mask_from_rle(
rle: dict[str, list[int] | bytes],
) → ndarray¶

Convert an RLE mask to a numpy array.

Parameters:

rle – The RLE mask to convert

Returns:

A numpy array of shape (H, W, N) containing N binary masks

static masks_from_rles(
rles: list[CocoRle],
) → ndarray¶

Convert multiple RLE masks to a numpy array.

Parameters:

rles – List of RLE dictionaries with ‘counts’ and ‘size’ fields

Returns:

A numpy array of shape (H, W, N) containing N binary masks

static polygon_groups_from_rles(
rles: list[CocoRle],
*,
relative: bool = False,
) → list[list[list[float]]]¶

Convert a list of RLE encoded masks to per-instance polygon groups.

Like polygons_from_rles(), but each instance maps to a list of polygons (one per connected component, with holes carved out) rather than a single bridged polygon. This is the COCO multi-polygon segmentation form.

Parameters:

  • rles – List of RLE dictionaries with ‘counts’ and ‘size’ fields.

  • relative – Whether to return coordinates relative to image dimensions.

Returns:

List with one entry per instance; each entry is a list of polygons, each a flattened list of x,y coordinates.

static polygons_from_mask(
mask: ndarray,
*,
relative: bool = False,
) → list[float]¶

Convert a binary mask to a single self-touching polygon using OpenCV contour detection.

All connected components and holes are bridged into one polygon via nearest-point connections, as required by single-polygon-per-instance formats (YOLO). The zero-width slits let even-odd rasterization carve out holes, and avoid the self-crossing, area-wrong shape that naive coordinate concatenation would produce. For the COCO multi-polygon form, see component_polygons_from_mask().

Parameters:

  • mask – The binary mask to convert.

  • relative – Whether to return coordinates relative to the image dimensions.

Returns:

A single polygon as a flattened list of x,y coordinates, or an empty list for an empty mask.

static polygons_from_rles(
rles: list[CocoRle],
*,
relative: bool = False,
) → list[list[float]]¶

Convert a list of RLE encoded masks to polygons.

Parameters:

  • rles – List of RLE dictionaries with ‘counts’ and ‘size’ fields

  • relative – Whether to return polygons with coordinates relative to image dimensions

Returns:

List of polygons where each polygon is a flattened list of x,y coordinates

static rles_from_masks(
masks: ndarray,
) → list[CocoRle]¶

Convert a stack of binary masks to RLE format.

Parameters:

masks – A numpy array of shape (H, W, N) containing N binary masks

Returns:

List of RLE dictionaries with ‘counts’ and ‘size’ fields

static rles_from_polygons(
polygons: list[list[float]],
height: int,
width: int,
*,
relative: bool = False,
) → list[CocoRle]¶

Convert a list of polygons to RLE format.

Parameters:

  • polygons – The list of polygons to convert

  • height – The height of the image

  • width – The width of the image

  • relative – Whether the polygons are relative to the image size

Returns:

List of RLE dictionaries with ‘counts’ and ‘size’ fields