kornia.geometry.bbox#

Box functions on plain corner tensors: build, measure, validate, mask, transform and NMS.

A 2D box is four (x, y) corners in clockwise order, top-left, top-right, bottom-right, bottom-left, so one box per image is (B, 4, 2). A 3D box is those four corners at the front followed by the same four at the back, (B, 8, 3) with (x, y, z) corners. Corners are inclusive pixel centres: a box covering pixels 0..9 has corners at 0 and 9 and width x_max - x_min + 1 = 10, unlike the exclusive boxes of torchvision, COCO and albumentations (#3934). The generators and the shape and mask functions share this convention; nms() takes exclusive (N, 4) xyxy boxes instead (#4008), and transform_bbox() takes xyxy or xywh boxes, or corners, and adds no +1. From an unbatched Boxes, pass its to_tensor('vertices_plus') export; the 'vertices' export reads one pixel larger (#4009). See Conventions & Pitfalls for the box formats of the rest of kornia.

Which function to use:

Corners from a start corner and a size: bbox_generator() in 2D, bbox_generator3d() in 3D.
The size of axis-aligned corners: infer_bbox_shape() returns heights and widths, infer_bbox_shape3d() depths, heights and widths.
Whether corners are laid out as a box: validate_bbox() returns False when they are not, validate_bbox3d() raises AssertionError.
A filled mask per box: bbox_to_mask() returns (B, H, W), bbox_to_mask3d() (B, 1, D, H, W).
Boxes moved by 3 x 3 matrices: transform_bbox() for xyxy or xywh tensors and corners; transform_boxes() moves all four corners of a box container.
The highest-scored of overlapping boxes: nms(), by IoU. The local maxima of a response map are nms2d() instead.
Boxes as objects with format conversions, several boxes per image, padding and filtering: Boxes and Boxes3D. The image patch inside each box: crop_and_resize().

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

Build (B, 4, 2) inclusive box corners from top-left starts, widths and heights.

boxes = bbox_generator(x_start, y_start, width, height) takes (B,) or scalar tensors and returns (B, 4, 2) corners in clockwise order from the top-left one, with the far corner at start + size - 1, in the dtype of the inputs and with a gradient path to them. These are the corners from_tensor() stores for the same boxes in 'xywh' mode, which also validates them and wraps them in a container; to crop the boxes from images, pass the result to crop_and_resize(). For 3D boxes, use bbox_generator3d().

Convention:: The far corner is at start + size - 1 (inclusive, see infer_bbox_shape()), so infer_bbox_shape() reads back width and height; a zero size puts the far corner one before the start. Scalar inputs give a batch of one, and scalar sizes broadcast against (B,) starts; scalar starts with (B,) sizes, B > 1, raise RuntimeError. The four tensors must share dtype and device, otherwise AssertionError.

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 bounding boxes. Shape must be a scalar tensor or (B,).
height (Tensor) – heights of the bounding boxes. Shape must be a scalar tensor or (B,).

Return type:

Tensor

Returns:

the bounding box tensor, shape of (B, 4, 2).

See also

bbox_generator3d(): the 3D form, (B, 8, 3) corners from a start corner and three sizes.
infer_bbox_shape(): the inverse, the height and width of the corners.
from_tensor(): the same corners from 'xywh' boxes, validated and kept in a container with format conversions.
crop_and_resize(): crops one such box per image and resizes it.

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]#

Build (B, 8, 3) inclusive 3D box corners from start corners and sizes.

boxes = bbox_generator3d(x_start, y_start, z_start, width, height, depth) takes (B,) or scalar tensors and returns (B, 8, 3) corners: four at the front, at z_start, in clockwise order from the top-left one, then the same four at the back, at z_start + depth - 1. They are in the dtype of the inputs, with a gradient path to them. These are the corners from_tensor() stores for the same boxes in 'xyzwhd' mode. For 2D boxes, use bbox_generator().

Convention:

The four front vertices precede the four back vertices. Scalar inputs give a batch of one, and scalar sizes broadcast against (B,) starts; scalar starts with (B,) sizes, B > 1, raise RuntimeError. The six tensors must share dtype and device, otherwise AssertionError.

The far corner is at start + size - 1 (inclusive, see infer_bbox_shape3d()), so infer_bbox_shape3d() reads back size on every axis, matching bbox_generator().

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 bounding boxes. Shape must be a scalar tensor or (B,).
height (Tensor) – heights of the bounding boxes. Shape must be a scalar tensor or (B,).
depth (Tensor) – depths of the bounding boxes. Shape must be a scalar tensor or (B,).

Return type:

Tensor

Returns:

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

See also

bbox_generator(): the 2D form, (B, 4, 2) corners from a start corner, a width and a height.
infer_bbox_shape3d(): the inverse, the depth, height and width of the corners.
from_tensor(): the same corners from 'xyzwhd' boxes, validated and kept in a container with format conversions.
crop_and_resize3d(): crops one such box per volume and resizes it; pass align_corners=True there.

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],
         [ 9,  1,  2],
         [ 9, 20,  2],
         [ 0, 20,  2],
         [ 0,  1, 31],
         [ 9,  1, 31],
         [ 9, 20, 31],
         [ 0, 20, 31]],

        [[ 3,  4,  5],
         [42,  4,  5],
         [42, 53,  5],
         [ 3, 53,  5],
         [ 3,  4, 64],
         [42,  4, 64],
         [42, 53, 64],
         [ 3, 53, 64]]])

kornia.geometry.bbox.bbox_to_mask(boxes, width=None, height=None, size=None)[source]#

Draw (B, 4, 2) inclusive box corners as filled (B, H, W) masks.

mask = bbox_to_mask(boxes, size=(H, W)) takes one box per image, (B, 4, 2) corners, and returns (B, H, W) masks in the dtype of boxes: 1 on each pixel (x, y) with xmin <= x <= xmax and ymin <= y <= ymax, read from the top-left and bottom-right corners, and 0 elsewhere, with no gradient path. The bounds are compared inclusively and unrounded, and a box partly outside the image fills only its part inside. For several boxes per image, use to_mask(), which returns (N, H, W) for unbatched boxes and (B, N, H, W) for batched ones; for volumes, bbox_to_mask3d().

Convention:: The size is size=(height, width), as for bbox_to_mask3d() and to_mask(); the deprecated width, height arguments come in the opposite order. Only vertices 0 (top-left) and 2 (bottom-right) are read. Pass the 'vertices_plus' export of Boxes. (B, N, 4, 2) raises ShapeError.

Warning

The (width, height) form is deprecated in favour of size=(height, width): #4014. For fractional coordinates the raw comparison differs from the rounding of to_mask() and the truncation of bbox_to_mask3d(): #4015. The exclusive-export trap is #4009.

Parameters:

boxes (Tensor) – a tensor containing the coordinates of the bounding boxes to be extracted. The tensor must have the shape of (B, 4, 2), 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 (Optional[int], optional) – deprecated since 0.9.1; pass size=(height, width) instead. Width of the masked image. Default: None
height (Optional[int], optional) – deprecated since 0.9.1; pass size=(height, width) instead. Height of the masked image. Default: None
size (Optional[tuple[int, int]], optional) – (height, width) of the masked image. Default: None

Return type:

Tensor

Returns:

the output mask tensor, shape of (B, height, width) and dtype of boxes.

Raises:

ShapeError – if boxes does not have shape (B, 4, 2).
ValueError – if size is passed together with width or height.
TypeError – if neither size nor both width and height are given.

See also

bbox_to_mask3d(): the 3D form, (B, 1, D, H, W) masks of (B, 8, 3) corners, whose bounds are truncated toward zero.
to_mask(): masks of several boxes per image, (N, H, W) for unbatched boxes and (B, N, H, W) for batched ones, filled over the rounded exclusive bounds.
infer_bbox_shape(): the inclusive height and width of the same corners.

Note

The pixel-position grid is built in float32 regardless of boxes.dtype, so float16/bfloat16 boxes are masked exactly even on images wider or taller than the integer-exact range of those dtypes (2048 px for float16, 256 px for bfloat16). The result is still returned in boxes.dtype.

Examples

>>> boxes = torch.tensor([[
...        [1., 1.],
...        [3., 1.],
...        [3., 2.],
...        [1., 2.],
...   ]])  # 1x4x2
>>> bbox_to_mask(boxes, size=(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]#

Draw (B, 8, 3) inclusive 3D box corners as filled (B, 1, D, H, W) masks.

mask = bbox_to_mask3d(boxes, (D, H, W)) takes one box per volume, (B, 8, 3) corners, and returns (B, 1, D, H, W) masks in the dtype of boxes: 1 on the voxels inside each box and 0 elsewhere, with no gradient path. It first checks the corners as validate_bbox3d() does and raises AssertionError where that check finds extents that disagree, or for a non-finite coordinate. For several boxes per volume, use to_mask(); for images, bbox_to_mask().

Convention:

size is (depth, height, width) and the mask (B, 1, depth, height, width) in the input dtype, with a channel axis that bbox_to_mask() does not have (kornia.geometry.boxes.Boxes3D.to_mask() returns (N, depth, height, width) for unbatched boxes and (B, N, depth, height, width) for batched ones). The bounds are truncated toward zero and compared inclusively: pass the 'vertices_plus' export. (B, N, 8, 3) input raises ShapeError.

The bounds come from fixed vertices, x from the first two, y from the second and third and z from the first and fifth, and fill axis-aligned ranges. A sheared box that validate_bbox3d() accepts, such as one whose back face is shifted in x, is masked as the axis-aligned box of those vertices, not rasterized.

Warning

For fractional coordinates the truncation differs from bbox_to_mask() and to_mask(): #4015. An invalid box, including a non-finite coordinate, raises AssertionError: #4013.

Parameters:

boxes (Tensor) – a tensor containing the coordinates of the bounding boxes to be extracted. The tensor must have the shape of (B, 8, 3), 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, shape of (B, 1, depth, height, width) and dtype of boxes.

See also

bbox_to_mask(): the 2D form, (B, H, W) masks of (B, 4, 2) corners with no channel axis, whose bounds are compared unrounded.
to_mask(): masks of several boxes per volume, (N, D, H, W) for unbatched boxes and (B, N, D, H, W) for batched ones, filled over the rounded exclusive bounds.
infer_bbox_shape3d(): the inclusive depth, height and width of the same corners.

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]#

Read the inclusive heights and widths of (N, 4, 2) box corners from fixed vertices.

heights, widths = infer_bbox_shape(boxes) takes (N, 4, 2) corners and returns two (N,) tensors in the dtype of boxes, the inclusive heights y_br - y_tl + 1 and widths x_tr - x_tl + 1 read from the top-left, top-right and bottom-right vertices. It does not validate the corners. For (B, N, 4, 2) corners, flatten them to (B * N, 4, 2) first; for corners in any order, such as a rotated box, use get_boxes_shape(), which measures the axis-aligned bounds; for 3D corners, infer_bbox_shape3d().

Convention:: Vertices are inclusive: a box covering pixels 0..9 has corners at 0 and 9 and width 10. The vertex-based helpers of this module share it; nms() takes exclusive xyxy and transform_bbox() converts 'xywh' exclusively (xmax = xmin + width). The order is clockwise top-left, top-right, bottom-right, bottom-left. The result is (heights, widths), read from fixed vertex indices, width = boxes[:, 1, 0] - boxes[:, 0, 0] + 1 and height = boxes[:, 2, 1] - boxes[:, 0, 1] + 1, not from a max - min reduction, so a box in another vertex order (such as a rotated polygon from transform_bbox()) can give a negative extent. kornia.geometry.boxes.Boxes.get_boxes_shape() is reduction based.

Warning

The inclusive +1 arithmetic differs from torchvision, COCO and albumentations, which are exclusive: #3934.

Parameters:

boxes (Tensor) – a tensor containing the coordinates of the bounding boxes to be extracted. The tensor must have shape (N, 4, 2), 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.

Raises:

ShapeError – if boxes does not have shape (N, 4, 2).

Return type:

tuple[Tensor, Tensor]

Returns:

Bounding box heights, shape of (N,).
Bounding box widths, shape of (N,).

See also

infer_bbox_shape3d(): the depths, heights and widths of (B, 8, 3) corners, which it validates first.
get_boxes_shape(): the inclusive size of the axis-aligned bounds of the boxes in a container, for corners in any order.
bbox_generator(): the inverse, corners from a start corner and this height and width.

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]#

Read the inclusive depths, heights and widths of (B, 8, 3) box corners, validating them.

depths, heights, widths = infer_bbox_shape3d(boxes) takes (B, 8, 3) corners, four at the front and then four at the back, and returns three (B,) tensors in the dtype of boxes, the inclusive extent of each box along z, y and x. It first checks the corners as validate_bbox3d() does and raises AssertionError where that check finds extents that disagree, such as for a box whose right face is shifted in y, or a non-finite coordinate; another shape than (B, 8, 3) raises ShapeError. For (N, 4, 2) corners, use infer_bbox_shape(), which does not validate.

Convention:: Vertices are inclusive (see infer_bbox_shape()), in validate_bbox3d() order. The result is (depths, heights, widths), each read from fixed vertex indices like infer_bbox_shape() (for example width = boxes[:, 1, 0] - boxes[:, 0, 0] + 1), so another vertex order can give a negative extent. Pass the 'vertices_plus' export of Boxes3D; 'vertices' reads one larger per axis. (B, N, 8, 3) input raises ShapeError; flatten it first.

Warning

The +1 is #3934 and the exclusive-export trap #4009. An invalid box, including a non-finite coordinate, raises AssertionError rather than being reported: #4013.

Parameters:

boxes (Tensor) – a tensor containing the coordinates of the bounding boxes to be extracted. The tensor must have the shape of (B, 8, 3), 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,).

See also

infer_bbox_shape(): the heights and widths of (N, 4, 2) corners, without validation.
get_boxes_shape(): the same three sizes for the boxes of a container, from the axis-aligned bounds of the corners.
bbox_generator3d(): the inverse, corners from a start corner and these sizes.

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.nms(boxes, scores, iou_threshold)[source]#

Suppress overlapping (N, 4) xyxy boxes by IoU, keeping the highest-scored ones.

keep = nms(boxes, scores, iou_threshold) takes N exclusive xyxy boxes (N, 4) and their scores (N,), and returns the int64 indices of the boxes it keeps, highest score first: it keeps the highest-scored remaining box, drops every remaining box whose IoU with it exceeds iou_threshold, and repeats until no box remains. It takes one set of boxes per call; see the notes for how it compares with torchvision.ops.nms. To keep the local maxima of a response map rather than boxes, use nms2d().

Convention:: Boxes use exclusive xyxy coordinates. IoU area is (x_2 - x_1) * (y_2 - y_1) and the result contains kept indices rather than a boolean mask.

Parameters:

boxes (Tensor) – tensor containing exclusive xyxy bounding boxes with shape (N, 4), ordered as (x_1, y_1, x_2, y_2).
scores (Tensor) – tensor containing the scores associated to each bounding box with shape (N,).
iou_threshold (float) – the threshold to discard the overlapping boxes.

Return type:

Tensor

Returns:

Indices of the boxes kept from the input set, ordered by descending score.

Note

Coordinates in float16 or bfloat16 are computed in float32, and uint8, int8, int16 or int32 coordinates in int64. In their own dtype the sum of two areas overflows: two 181-pixel squares exceed the float16 maximum of 65504, and two 32768-pixel squares exceed int32. bfloat16 does not overflow, but its rounding can move an IoU across iou_threshold.

Note

For one box or more, torch.compile cannot capture nms in one graph: the number of loop iterations and the size of the output depend on the box values. fullgraph=True raises, and a default torch.compile runs it eagerly, so it is outside the torch.compile promise.

Note

For float32 or float64 boxes with finite coordinates, distinct scores and iou_threshold >= 0 it keeps the same boxes, in the same order, as torchvision.ops.nms. Equal scores are ordered by torch.sort(), which is not stable, so with ties the order, and which of two overlapping tied boxes is kept, can differ from torchvision. A box with a NaN coordinate has a NaN IoU with every other box, which is not above iou_threshold: it neither suppresses nor is suppressed, as in torchvision.ops.nms.

Note

Two boxes whose union is empty, such as two zero-width boxes, have an IoU of 0, so at an iou_threshold of at least 0 neither suppresses the other, as in torchvision.ops.nms. With a negative threshold the lower-scored one is dropped, where torchvision, whose IoU for them is NaN, keeps both.

Warning

This differs from the inclusive coordinate arithmetic used by several other kornia.geometry.bbox operations and is documented in #4008.

See also

nms2d(): keeps the strict local maxima of a (B, C, H, W) response map, not boxes.
to_tensor(): exports the boxes of a container as the exclusive 'xyxy' boxes this function takes.

Example

>>> boxes = torch.tensor([
...     [10., 10., 20., 20.],
...     [15., 5., 15., 25.],
...     [100., 100., 200., 200.],
...     [100., 100., 200., 200.]])
>>> scores = torch.tensor([0.9, 0.8, 0.7, 0.9])
>>> nms(boxes, scores, iou_threshold=0.8)
tensor([0, 3, 1])

kornia.geometry.bbox.transform_bbox(trans_mat, boxes, mode='xyxy', restore_coordinates=None)[source]#

Transform xyxy or xywh box tensors by 3x3 matrices through their two endpoints.

out = transform_bbox(trans_mat, boxes) takes (B, 3, 3) matrices and (N, 4) or (B, N, 4) boxes in mode 'xyxy' (the default) or 'xywh', and returns the transformed boxes in the same mode and shape. Only the two endpoints (xmin, ymin) and (xmax, ymax) are transformed, and by default sorted again so that xmin <= xmax and ymin <= ymax, so under a rotation or a shear the result is not the bounding box of the transformed box. (B, N, 4, 2) corners are transformed vertex by vertex instead. For the bounding box of a rotated box, use transform_boxes(), which transforms all four corners, and export it with to_tensor().

Convention:: xyxy and xywh inputs are transformed through endpoint pairs. Coordinate restoration sorts their endpoints after a flip; polygon vertices retain their transformed cyclic order. 'xywh' boxes are converted with xmax = xmin + width, without the inclusive +1 of the corner functions of this module. boxes is not modified.

Parameters:

trans_mat (Tensor) – The transformation matrix to be applied, with supported shape (B, 3, 3). For boxes shaped (N, 4), B is one or N. For boxes shaped (B, N, 4) or (B, N, 4, 2), it is one or the boxes’ B.
boxes (Tensor) – The boxes to be transformed with a common shape of (N, 4) or batched as (B, N, 4), the polygon shape of (B, N, 4, 2) is also supported.
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"
restore_coordinates (Optional[bool], optional) – Reorder endpoints after a flipped xyxy or xywh transform. Enabled by default (None behaves as True); pass False to preserve raw transformed endpoints. Polygon vertices retain their transformed order. Default: None

Return type:

Tensor

Returns:

The transformed boxes in the specified mode.

See also

transform_boxes(): transforms all four corners of the boxes in a container, whose to_tensor export is the bounding box of a rotated box.
transform_points(): the point transform applied to the endpoints and corners.
warp_perspective(): warps the images by the same source-to-destination matrix.

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

Check that 2D box corners have equal top and bottom edge vectors, returning a bool.

ok = validate_bbox(boxes) takes corners (B, 4, 2) or (B, N, 4, 2) and returns True when every coordinate is finite and, in every box, the top edge (top-left to top-right) equals the bottom edge (bottom-left to bottom-right) within 1e-4 on each axis. Otherwise it returns False, without raising, and an eager call warns with a FutureWarning. It is a check of the corner layout only; for 3D corners, use validate_bbox3d(), which raises instead.

Convention:: Vertices are inclusive, in clockwise top-left, top-right, bottom-right, bottom-left order (see infer_bbox_shape()). Returns False for any other shape too. Right angles, positive area and direction are not checked, so any parallelogram in cyclic vertex order passes. An empty batch passes.

Warning

Returning False is deprecated; a future release raises AssertionError (#4013).

Parameters:: boxes (Tensor) – a tensor containing the coordinates of the bounding boxes to be extracted. The tensor must have the shape of (B, 4, 2) or (B, N, 4, 2), 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
Returns:: True for valid boxes, False otherwise.

See also

validate_bbox3d(): the check for (B, 8, 3) corners, which raises AssertionError instead of returning False.
infer_bbox_shape(): the inclusive height and width of corners that pass.
from_tensor(): imports boxes into a container, rejecting non-finite coordinates, and non-positive extents in the 'xy*' modes, but not checking the corner layout.

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

Check that 3D box corners measure one extent per axis, raising if not.

ok = validate_bbox3d(boxes) takes corners (B, 8, 3) or (B, N, 8, 3) and returns True when, in every box, the x extents of the four left-to-right edges agree, the y extents of the two diagonals of the front face and of the back face agree, and the z extents of the four front-to-back edges agree, to the default tolerances of torch.isclose(); for a box with right angles these are its edge extents. Another shape or a disagreement raises AssertionError; a non-finite coordinate returns False, with a FutureWarning on an eager call. For 2D corners, use validate_bbox(), which returns False instead of raising.

Convention:: Vertices are inclusive, front-top-left, front-top-right, front-bottom-right, front-bottom-left, then the same four back vertices. Right angles and positive extent are not checked as such: a box whose right face is shifted in y raises, because its face diagonals then differ in y, while one whose bottom face is shifted in x or z, whose back face is shifted in x or y, or whose right face is shifted in z passes. Under graph capture only the shape is checked.

Warning

Returning False is deprecated; a future release raises AssertionError (#4013).

Parameters:: boxes (Tensor) – a tensor containing the coordinates of the bounding boxes to be extracted. The tensor must have the shape of (B, 8, 3) or (B, N, 8, 3), 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
Returns:: True, or False when any coordinate is non-finite. Invalid input otherwise raises instead of returning False.

See also

validate_bbox(): the check for (B, 4, 2) corners, which returns False instead of raising.
infer_bbox_shape3d(): runs this check, then returns the depths, heights and widths of the corners.
from_tensor(): imports (N, 6) boxes into a container, rejecting non-finite coordinates and non-positive extents.