Geometry utilities

flat_bug.geometric.chw2hwc_uint8(crop: Tensor, mask: Tensor) → Tensor

Converts a crop from CHW to HWC format, and adds the mask as an alpha channel if it exists.

Parameters:

  • crop (torch.Tensor) – The crop to convert from CHW to HWC format.

  • mask (torch.Tensor) – The mask to add as an alpha channel.

Returns:

The crop in HWC format with the mask as an alpha channel, if supplied.

Return type:

out (torch.Tensor)

flat_bug.geometric.contours_to_masks(contours: List[Tensor], height: int | Tensor, width: int | Tensor) → Tensor

Takes a list of contours represented as (i, j) index-coordinates in a Xx2 tensor and returns a NxHxW tensor of boolean masks with the contours filled in.

Parameters:

  • contours (List[torch.Tensor]) – List of contours represented as (i, j) index-coordinates in a Nx2 tensor (OBS: dtype=torch.long)

  • height (Union[int, torch.Tensor]) – The height of the masks

  • width (Union[int, torch.Tensor]) – The width of the masks

Returns:

NxHxW tensor of boolean masks with the contours filled in

Return type:

out (torch.Tensor)

flat_bug.geometric.create_contour_mask(mask: Tensor, width: int = 1) → Tensor

Converts a binary mask for a filled polygon to a binary mask for the non-filled polygon:

#      Before         After
#
#    ---------      ---------
#    --#####--      --#####--
#    -#######-  =>  -##---##-
#    --#####--      --#####--
#    ---------      ---------
#
# (here dashes "-" represent 0s and hashes "#" represent 1s)

We call the result (“After”) the “contour mask”.

Optionally, the “linewidth” of the contour mask can be increased.

Parameters:

  • mask (torch.Tensor) – a NxM binary tensor with 1s inside the “polygon”.

  • width (int, optional) – Width of the contour in the result. Reasonable values are >= 1; Setting to 0 will result in all 0s in the output. Defaults to 1.

Returns:

a NxM binary tensor with 1s on the edge/border of the “polygon”.

Return type:

out (torch.Tensor)

flat_bug.geometric.equal_allocate_overlaps(total: int, segments: int, size: int) → List[int]

Generates cumulative positions for placing segments of a given size within a total length, with controlled overlaps.

This function divides the specified total length into segments positions, ensuring each segment (of given size) fits evenly by introducing a small overlap between adjacent segments. The overlap is distributed uniformly, with the first few gaps adjusted slightly to ensure the segments collectively sum to total.

Parameters:

  • total (int) – The total length to be covered by the segments. This is the target cumulative length the segments should fit into.

  • segments (int) – The number of segments to place within the total length. Must be greater than or equal to 2.

  • size (int) – The desired size of each segment, used to determine the ideal spacing between segments.

Returns:

A list of cumulative positions (starting from 0) where each segment should be placed.

These positions are spaced with controlled overlaps to ensure they collectively cover the total length.

Return type:

out (List[int])

Example

>>> equal_allocate_overlaps(1000, 5, 250)
[0, 187, 374, 562, 750]
flat_bug.geometric.linear_interpolate(poly: ndarray, scale: int) → ndarray

Linearly interpolates a N x 2 polygon to have N x scale vertices.

flat_bug.geometric.poly_normals(polygon: Tensor) → Tensor

Calculates the normals of a polygon.

Parameters:

poly (torch.Tensor) – A tensor of shape (n, 2), where n is the number of vertices and the 2 columns are the x and y coordinates of the vertices.

Returns:

A tensor of shape (n, 2), where n is the number of vertices and the 2 columns are the x and y coordinates of the normals.

Return type:

out (torch.Tensor)

flat_bug.geometric.resize_mask(masks: Tensor, new_shape: Tuple[int, int] | List[int]) → Tensor

Takes a mask (or a batch of masks) and resizes it by scaling the contour coordinates and snapping to the integer grid, ensuring that snapping is always done towards the outside of the mask.

Parameters:

  • mask (torch.Tensor) – A mask of shape (H, W) or (N, H, W) where N is the batch size.

  • new_shape (Tuple[int, int] | List[int]) – The new shape of the mask (H’, W’).

Returns:

The resized mask of shape (H’, W’) or (N, H’, W’).

Return type:

out (torch.Tensor)

flat_bug.geometric.simplify_contour(contour: Tensor | ndarray, tolerance: float = 1.0) → Tensor | ndarray

Wrapper for cv2.approxPolyDP that simplifies a contour by reducing the number of points while keeping the shape of the contour. Only works for simple closed contours without holes.

Parameters:

  • contour (Union[torch.Tensor, np.ndarray]) – The contour to simplify, represented as a Nx2 tensor or a Nx1x2 tensor.

  • tolerance (float, optional) – The maximum distance between the original contour and the simplified contour. Defaults to 1.0.

Returns:

The simplified contour in the same format as the input.

Return type:

out (Union[torch.Tensor, np.ndarray])