kornia.geometry.bbox

Module with useful functionalities for 2D and 3D bounding boxes manipulation.

kornia.geometry.bbox.bbox_generator(x_start, y_start, width, height)[source]

Generate 2D bounding boxes according to the provided start coords, width and height.

Parameters
  • x_start (Tensor) – a tensor containing the x coordinates of the bounding boxes to be extracted. Shape must be a scalar tensor or \((B,)\).

  • y_start (Tensor) – a tensor containing the y coordinates of the bounding boxes to be extracted. Shape must be a scalar tensor or \((B,)\).

  • width (Tensor) – widths of the masked image. Shape must be a scalar tensor or \((B,)\).

  • height (Tensor) – heights of the masked image. Shape must be a scalar tensor or \((B,)\).

Return type

Tensor

Returns

the bounding box tensor.

Examples

>>> x_start = torch.tensor([0, 1])
>>> y_start = torch.tensor([1, 0])
>>> width = torch.tensor([5, 3])
>>> height = torch.tensor([7, 4])
>>> bbox_generator(x_start, y_start, width, height)
tensor([[[0, 1],
         [4, 1],
         [4, 7],
         [0, 7]],

        [[1, 0],
         [3, 0],
         [3, 3],
         [1, 3]]])
kornia.geometry.bbox.bbox_generator3d(x_start, y_start, z_start, width, height, depth)[source]

Generate 3D bounding boxes according to the provided start coords, width, height and depth.

Parameters
  • x_start (Tensor) – a tensor containing the x coordinates of the bounding boxes to be extracted. Shape must be a scalar tensor or \((B,)\).

  • y_start (Tensor) – a tensor containing the y coordinates of the bounding boxes to be extracted. Shape must be a scalar tensor or \((B,)\).

  • z_start (Tensor) – a tensor containing the z coordinates of the bounding boxes to be extracted. Shape must be a scalar tensor or \((B,)\).

  • width (Tensor) – widths of the masked image. Shape must be a scalar tensor or \((B,)\).

  • height (Tensor) – heights of the masked image. Shape must be a scalar tensor or \((B,)\).

  • depth (Tensor) – depths of the masked image. Shape must be a scalar tensor or \((B,)\).

Return type

Tensor

Returns

the 3d bounding box tensor \((B, 8, 3)\).

Examples

>>> x_start = torch.tensor([0, 3])
>>> y_start = torch.tensor([1, 4])
>>> z_start = torch.tensor([2, 5])
>>> width = torch.tensor([10, 40])
>>> height = torch.tensor([20, 50])
>>> depth = torch.tensor([30, 60])
>>> bbox_generator3d(x_start, y_start, z_start, width, height, depth)
tensor([[[ 0,  1,  2],
         [10,  1,  2],
         [10, 21,  2],
         [ 0, 21,  2],
         [ 0,  1, 32],
         [10,  1, 32],
         [10, 21, 32],
         [ 0, 21, 32]],

        [[ 3,  4,  5],
         [43,  4,  5],
         [43, 54,  5],
         [ 3, 54,  5],
         [ 3,  4, 65],
         [43,  4, 65],
         [43, 54, 65],
         [ 3, 54, 65]]])
kornia.geometry.bbox.bbox_to_mask(boxes, width, height)[source]

Convert 2D bounding boxes to masks. Covered area is 1. and the remaining is 0.

Parameters
  • boxes (Tensor) – a tensor containing the coordinates of the bounding boxes to be extracted. The tensor must have the shape of Bx4x2, where each box is defined in the following clockwise order: top-left, top-right, bottom-right and bottom-left. The coordinates must be in the x, y order.

  • width (int) – width of the masked image.

  • height (int) – height of the masked image.

Return type

Tensor

Returns

the output mask tensor.

Note

It is currently non-differentiable.

Examples

>>> boxes = torch.tensor([[
...        [1., 1.],
...        [3., 1.],
...        [3., 2.],
...        [1., 2.],
...   ]])  # 1x4x2
>>> bbox_to_mask(boxes, 5, 5)
tensor([[[0., 0., 0., 0., 0.],
         [0., 1., 1., 1., 0.],
         [0., 1., 1., 1., 0.],
         [0., 0., 0., 0., 0.],
         [0., 0., 0., 0., 0.]]])
kornia.geometry.bbox.bbox_to_mask3d(boxes, size)[source]

Convert 3D bounding boxes to masks. Covered area is 1. and the remaining is 0.

Parameters
  • boxes (Tensor) – a tensor containing the coordinates of the bounding boxes to be extracted. The tensor must have the shape of Bx8x3, where each box is defined in the following clockwise order: front-top-left, front-top-right, front-bottom-right, front-bottom-left, back-top-left, back-top-right, back-bottom-right, back-bottom-left. The coordinates must be in the x, y, z order.

  • size (Tuple[int, int, int]) – depth, height and width of the masked image.

Return type

Tensor

Returns

the output mask tensor.

Examples

>>> boxes = torch.tensor([[
...     [1., 1., 1.],
...     [2., 1., 1.],
...     [2., 2., 1.],
...     [1., 2., 1.],
...     [1., 1., 2.],
...     [2., 1., 2.],
...     [2., 2., 2.],
...     [1., 2., 2.],
... ]])  # 1x8x3
>>> bbox_to_mask3d(boxes, (4, 5, 5))
tensor([[[[[0., 0., 0., 0., 0.],
           [0., 0., 0., 0., 0.],
           [0., 0., 0., 0., 0.],
           [0., 0., 0., 0., 0.],
           [0., 0., 0., 0., 0.]],

          [[0., 0., 0., 0., 0.],
           [0., 1., 1., 0., 0.],
           [0., 1., 1., 0., 0.],
           [0., 0., 0., 0., 0.],
           [0., 0., 0., 0., 0.]],

          [[0., 0., 0., 0., 0.],
           [0., 1., 1., 0., 0.],
           [0., 1., 1., 0., 0.],
           [0., 0., 0., 0., 0.],
           [0., 0., 0., 0., 0.]],

          [[0., 0., 0., 0., 0.],
           [0., 0., 0., 0., 0.],
           [0., 0., 0., 0., 0.],
           [0., 0., 0., 0., 0.],
           [0., 0., 0., 0., 0.]]]]])
kornia.geometry.bbox.infer_bbox_shape(boxes)[source]

Auto-infer the output sizes for the given 2D bounding boxes.

Parameters

boxes (Tensor) – a tensor containing the coordinates of the bounding boxes to be extracted. The tensor must have the shape of Bx4x2, where each box is defined in the following clockwise order: top-left, top-right, bottom-right, bottom-left. The coordinates must be in the x, y order.

Return type

Tuple[Tensor, Tensor]

Returns

  • Bounding box heights, shape of \((B,)\).

  • Boundingbox widths, shape of \((B,)\).

Example

>>> boxes = torch.tensor([[
...     [1., 1.],
...     [2., 1.],
...     [2., 2.],
...     [1., 2.],
... ], [
...     [1., 1.],
...     [3., 1.],
...     [3., 2.],
...     [1., 2.],
... ]])  # 2x4x2
>>> infer_bbox_shape(boxes)
(tensor([2., 2.]), tensor([2., 3.]))
kornia.geometry.bbox.infer_bbox_shape3d(boxes)[source]

Auto-infer the output sizes for the given 3D bounding boxes.

Parameters

boxes (Tensor) – a tensor containing the coordinates of the bounding boxes to be extracted. The tensor must have the shape of Bx8x3, where each box is defined in the following clockwise order: front-top-left, front-top-right, front-bottom-right, front-bottom-left, back-top-left, back-top-right, back-bottom-right, back-bottom-left. The coordinates must be in the x, y, z order.

Return type

Tuple[Tensor, Tensor, Tensor]

Returns

  • Bounding box depths, shape of \((B,)\).

  • Bounding box heights, shape of \((B,)\).

  • Bounding box widths, shape of \((B,)\).

Example

>>> boxes = torch.tensor([[[ 0,  1,  2],
...         [10,  1,  2],
...         [10, 21,  2],
...         [ 0, 21,  2],
...         [ 0,  1, 32],
...         [10,  1, 32],
...         [10, 21, 32],
...         [ 0, 21, 32]],
...        [[ 3,  4,  5],
...         [43,  4,  5],
...         [43, 54,  5],
...         [ 3, 54,  5],
...         [ 3,  4, 65],
...         [43,  4, 65],
...         [43, 54, 65],
...         [ 3, 54, 65]]]) # 2x8x3
>>> infer_bbox_shape3d(boxes)
(tensor([31, 61]), tensor([21, 51]), tensor([11, 41]))
kornia.geometry.bbox.transform_bbox(trans_mat, boxes, mode='xyxy')[source]

Function that applies a transformation matrix to a box or batch of boxes. Boxes must be a tensor of the shape (N, 4) or a batch of boxes (B, N, 4) and trans_mat must be a (3, 3) transformation matrix or a batch of transformation matrices (B, 3, 3)

Parameters
  • trans_mat (Tensor) – The transformation matrix to be applied

  • boxes (Tensor) – The boxes to be transformed

  • mode (str, optional) – The format in which the boxes are provided. If set to ‘xyxy’ the boxes are assumed to be in the format xmin, ymin, xmax, ymax. If set to ‘xywh’ the boxes are assumed to be in the format xmin, ymin, width, height Default: 'xyxy'

Return type

Tensor

Returns

The set of transformed points in the specified mode

kornia.geometry.bbox.validate_bbox(boxes)[source]

Validate if a 2D bounding box usable or not. This function checks if the boxes are rectangular or not.

Parameters

boxes (Tensor) – a tensor containing the coordinates of the bounding boxes to be extracted. The tensor must have the shape of Bx4x2, where each box is defined in the following clockwise order: top-left, top-right, bottom-right, bottom-left. The coordinates must be in the x, y order.

Return type

bool

kornia.geometry.bbox.validate_bbox3d(boxes)[source]

Validate if a 3D bounding box usable or not. This function checks if the boxes are cube or not.

Parameters

boxes (Tensor) – a tensor containing the coordinates of the bounding boxes to be extracted. The tensor must have the shape of Bx8x3, where each box is defined in the following clockwise order: front-top-left, front-top-right, front-bottom-right, front-bottom-left, back-top-left, back-top-right, back-bottom-right, back-bottom-left. The coordinates must be in the x, y, z order.

Return type

bool