kornia.geometry.boxes#

Object-oriented API for 2D and 3D bounding boxes: the Boxes and Boxes3D classes wrap a tensor of boxes and provide format conversions (xyxy, xywh, vertices), transformations and padding.

class kornia.geometry.boxes.Boxes(boxes, raise_if_not_floating_point=True, mode='vertices_plus')[source]#

2D boxes containing N or BxN boxes.

Parameters:

boxes (Tensor | list[Tensor]) – 2D boxes, shape of \((N, 4, 2)\), \((B, N, 4, 2)\) or a list of \((N, 4, 2)\). See below for more details.
raise_if_not_floating_point (bool, optional) – flag to control floating point casting behaviour when boxes is not a floating point tensor. True to raise an error when boxes isn’t a floating point tensor, False to cast to float. Default: True
mode (str, optional) – Representation label reused as the default output mode by to_tensor(). The constructor does not convert boxes; use from_tensor() to import another representation. Default: "vertices_plus"

Convention:

A box is a quadrilateral of four floating-point (x, y) vertices, \((N, 4, 2)\) or \((B, N, 4, 2)\), built in clockwise top-left, top-right, bottom-right, bottom-left order; transform_boxes() can make it an arbitrary (rotated) quadrilateral.
The stored form is inclusive ('vertices_plus'): width = xmax - xmin + 1. The exclusive 'xyxy', 'xywh' and 'vertices' modes are converted by from_tensor() and to_tensor(); the constructor converts nothing and only records mode.
to_tensor() reduces the vertices with amin/amax, so every export is an axis-aligned bounding box and to_tensor('vertices_plus') is not the identity for a rotated box.
get_boxes_shape() returns (heights, widths); padding entries of a list-backed object report as 1-by-1 boxes (the inclusive +1, #3934).
infer_bbox_shape() and bbox_to_mask() read their input as inclusive: pass them the 'vertices_plus' export, unbatched. nms() takes exclusive xyxy.
With validate_boxes=True, every mode rejects a non-finite coordinate. The 'xy*' modes raise ValueError and also reject non-positive extents. The vertex modes raise RuntimeError through torch._assert_async (on CPU and CUDA, skipped on MPS), so they stay fullgraph-compilable, and take no extent or shape check, so the arbitrary quadrilaterals of transform_boxes() import unchanged.
The constructor rejects an integer tensor unless raise_if_not_floating_point=False (a list is checked by its first element’s dtype); from_tensor() casts integer input to the default dtype.
merge() and index_put() are non-mutating by default.

Warning

The inclusive +1 differs from torchvision, COCO and albumentations: #3934. A sub-unit extent (normalized [0, 1] boxes) is corrupted by the - 1 of the converting modes: #4061. Passing the 'vertices' export to the bbox helpers reads one pixel larger: #4009. compute_area() is the shoelace area of the stored inclusive vertices, (width - 1) * (height - 1): #4010. nms() is exclusive: #4008. to_mask() and bbox_to_mask() take opposite size orders: #4014. The integer-input split is #4012. 'vertices' subtracts the inclusive offset at fixed vertex slots, so it deforms a quadrilateral that is not an axis-aligned rectangle in clockwise order: #3934. trim, translate(method='fast') and tuple-bound clamp are unimplemented: #4017.

clamp(topleft=None, botright=None, inplace=False)[source]#

Clamp every box vertex inside per-image coordinate limits.

See the Convention block on Boxes.

Convention:: Bounds are tensors with one (x, y) pair per batch element, or a single row that broadcasts (an unbatched container needs exactly one row). Every vertex is clamped independently, so a box wholly outside the bounds collapses onto the boundary instead of being removed.

Parameters:

topleft (Union[Tensor, tuple[int, int], None], optional) – Tensor of shape \((B, 2)\) containing the minimum x and y coordinate allowed for each batch item. A single row broadcasts across the batch. Default: None
botright (Union[Tensor, tuple[int, int], None], optional) – Tensor of shape \((B, 2)\) containing the maximum x and y coordinate allowed for each batch item. A single row broadcasts across the batch. Default: None
inplace (bool, optional) – If True, clamp this object in place. Otherwise, return a new Boxes object with clamped data. Default: False

Return type:

Boxes

Returns:

Boxes whose vertex coordinates are restricted to the provided bounds.

clone()[source]#

Create an independent copy of the box container.

Return type:: Boxes
Returns:: New Boxes object with cloned tensor storage. Metadata such as the current mode, original list lengths, and batched flag is preserved.

compute_area()[source]#

Compute polygon area with the shoelace formula.

See the Convention block on Boxes.

Convention:: Vertices are sorted by angle about their centroid, so a convex quadrilateral is assumed.

Warning

On the stored inclusive vertices an axis-aligned box gives (width - 1) * (height - 1), not the width * height of get_boxes_shape(): #4010.

Return type:: Tensor
Returns:: Area for each box, shaped \((N,)\) or \((B, N)\).

property data: Tensor#

Return the raw quadrilateral coordinate tensor.

Returns:: Tensor storing four vertices per box in (x, y) order. The common shapes are \((N, 4, 2)\) for unbatched boxes and \((B, N, 4, 2)\) for batched boxes, where \(B\) is batch size and \(N\) is the number of boxes.

property device: device#: Returns boxes device.

property dtype: dtype#: Returns boxes dtype.

filter_boxes_by_area(min_area=None, max_area=None, inplace=False)[source]#

Zero boxes whose polygon area is outside the requested range.

See the Convention block on Boxes.

The box area is computed from its four vertices. Boxes smaller than min_area or larger than max_area are not dropped from the tensor; their coordinates are replaced with zeros so the original batch and box dimensions stay unchanged. See compute_area() for the area convention used by the thresholds. Filtered boxes export as exact zeros in every mode and draw no mask pixels, including after subsequent coordinate transforms.

Parameters:

min_area (Optional[float], optional) – Optional lower inclusive area threshold. Boxes with area below this value are zeroed. Default: None
max_area (Optional[float], optional) – Optional upper inclusive area threshold. Boxes with area above this value are zeroed. Default: None
inplace (bool, optional) – If True, update this object in place. Otherwise, return a filtered clone. Default: False

Return type:

Boxes

Returns:

Boxes with the same shape as the input container and out-of-range boxes replaced by zero coordinates.

classmethod from_tensor(boxes, mode='xyxy', validate_boxes=True)[source]#

Create Boxes from boxes stored in another format.

See the Convention block on Boxes.

Parameters:

boxes (Tensor | list) – 2D boxes, shape of \((N, 4)\), \((B, N, 4)\), \((N, 4, 2)\) or \((B, N, 4, 2)\), a nested numeric list with one of those shapes, or a list of \((N, 4)\) or \((N, 4, 2)\) tensors matching mode.
mode (str, optional) –
The format in which the boxes are provided: Default: "xyxy"
- ’xyxy’: xmin, ymin, xmax, ymax with exclusive extent. With shape \((N, 4)\), \((B, N, 4)\).
- ’xyxy_plus’: xmin, ymin, xmax, ymax with inclusive extent. With shape \((N, 4)\), \((B, N, 4)\).
- ’xywh’: xmin, ymin, width, height with exclusive extent. With shape \((N, 4)\), \((B, N, 4)\).
- ’vertices’: boxes are defined by their vertices points in the following clockwise order: top-left, top-right, bottom-right, bottom-left. Vertices coordinates are in (x,y) order. This is the exclusive input form. With shape \((N, 4, 2)\), \((B, N, 4, 2)\).
- ’vertices_plus’: the inclusive stored vertex form. With shape \((N, 4, 2)\), \((B, N, 4, 2)\).
validate_boxes (bool, optional) – Reject a non-finite coordinate in every mode: ValueError for the 'xy*' modes, which also reject non-positive extents in each mode’s convention, and RuntimeError from torch._assert_async for the vertex modes (skipped on MPS), which take no extent or shape check. Default: True

Return type:

Boxes

Returns:

Boxes containing the converted inclusive vertex representation.

Examples

>>> boxes_xyxy = torch.as_tensor([[0, 3, 1, 4], [5, 1, 8, 4]])
>>> boxes = Boxes.from_tensor(boxes_xyxy, mode='xyxy')
>>> boxes.data  # (2, 4, 2)
tensor([[[0., 3.],
         [0., 3.],
         [0., 3.],
         [0., 3.]],

        [[5., 1.],
         [7., 1.],
         [7., 3.],
         [5., 3.]]])

get_boxes_shape()[source]#

Compute boxes heights and widths.

See the Convention block on Boxes.

Return type:

tuple[Tensor, Tensor]

Returns:

Boxes heights, shape of \((N,)\) or \((B,N)\).
Boxes widths, shape of \((N,)\) or \((B,N)\).

Example

>>> boxes_xyxy = torch.tensor([[[1,1,2,2],[1,1,3,2]]])
>>> boxes = Boxes.from_tensor(boxes_xyxy)
>>> boxes.get_boxes_shape()
(tensor([[1., 1.]]), tensor([[1., 2.]]))

index_put(indices, values, inplace=False)[source]#

Write box coordinates at selected tensor indices.

See the Convention block on Boxes.

This mirrors torch.Tensor.index_put_() for the internal quadrilateral tensor. It is useful when a subset of boxes in a batch must be replaced while keeping the Boxes wrapper and metadata.

Parameters:

indices (tuple[Tensor, ...] | list[Tensor]) – Index tuple or list accepted by Tensor.index_put_. The indices address entries in the stored tensor, commonly shaped \((B, N, 4, 2)\) or \((N, 4, 2)\).
values (Tensor | Boxes) – Replacement coordinates. If a Boxes object is passed, its coordinates and filtering validity are copied. Raw tensor writes change only coordinates and preserve the existing filtering validity.
inplace (bool, optional) – If True, update this object and return self. If False, clone the current data first and return a new Boxes instance. Default: False

Return type:

Boxes

Returns:

Boxes containing the updated coordinates.

merge(boxes, inplace=False)[source]#

Merge boxes.

See the Convention block on Boxes.

For batched boxes, if the current instance holds \((B, N, 4, 2)\) and the incoming boxes holds \((B, M, 4, 2)\), the merge results in \((B, N + M, 4, 2)\).

For unbatched boxes, if the current instance holds \((N, 4, 2)\) and the incoming boxes holds \((M, 4, 2)\), the merge results in \((N + M, 4, 2)\).

Parameters:

boxes (Boxes) – 2D boxes.
inplace (bool, optional) – do transform in-place and return self. Default: False

Return type:

Boxes

Note

When either input was created from a list, each batch row is repacked so that its real boxes precede all trailing padding. The merged object keeps the combined per-image padding counts in _N.

property mode: str#

Return the box format remembered by this container.

Returns:: Mode string used as the default by to_tensor(), such as "xyxy", "xywh", "vertices", or their "_plus" variants.

pad(padding_size)[source]#

Pad every box in place.

See the Convention block on Boxes.

padding_size is ordered as (left, right, top, bottom). Only left and top change the coordinate origin; this method returns self after adding those two values to every vertex. Both the batched \((B, N, 4, 2)\) and the unbatched \((N, 4, 2)\) container are supported; the unbatched form carries a single image, so padding_size must have exactly one row.

Parameters:: padding_size (Tensor) – Per-batch padding in (left, right, top, bottom) order, shaped \((B, 4)\). A single row broadcasts across the batch.
Return type:: Boxes

property shape: tuple[int, ...] | Size#

Return the tensor shape used to store the boxes.

Returns:: Shape of data. For unbatched boxes this is usually \((N, 4, 2)\), where \(N\) is the number of boxes, 4 is the number of corner vertices, and 2 stores (x, y). For batched boxes the shape is usually \((B, N, 4, 2)\), where \(B\) is the batch size.

to(device=None, dtype=None)[source]#

Like torch.nn.Module.to() method.

Return type:: Boxes

to_mask(height, width)[source]#

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

See the Convention block on Boxes.

Convention:: The size is (height, width) and the mask \((N, height, width)\) or \((B, N, height, width)\) in the box dtype. The exclusive 'xyxy' export is clamped to the image, rounded to the nearest integer and filled over [xmin, xmax), [ymin, ymax). Padding entries of a list-backed object give empty masks. A box tensor that requires grad raises RuntimeError.

Warning

bbox_to_mask() takes (width, height) (#4014) and does not round, so a fractional box can fill a different area (#4015).

Parameters:

height (int) – height of the masked image/images.
width (int) – width of the masked image/images.

Return type:

Tensor

Returns:

the output mask tensor, shape of \((N, height, width)\) or \((B, N, height, width)\) and dtype of Boxes.dtype() (it can be any floating point dtype).

Note

It is currently non-differentiable.

Examples

>>> boxes = Boxes(torch.tensor([[  # Equivalent to Boxes.from_tensor([[1, 1, 4, 3]], mode='xyxy_plus')
...        [1., 1.],
...        [4., 1.],
...        [4., 3.],
...        [1., 3.],
...   ]]))  # 1x4x2
>>> boxes.to_mask(5, 5)
tensor([[[0., 0., 0., 0., 0.],
         [0., 1., 1., 1., 1.],
         [0., 1., 1., 1., 1.],
         [0., 1., 1., 1., 1.],
         [0., 0., 0., 0., 0.]]])

to_tensor(mode=None, as_padded_sequence=False)[source]#

Cast Boxes to a tensor.

See the Convention block on Boxes.

mode selects the output representation. 'xyxy', 'xywh', and 'vertices' are exclusive exports; the '_plus' variants are inclusive. Every mode exports the axis-aligned bounds of the stored vertices, reduced with amin/amax, so the export is lossy for rotated boxes: to_tensor('vertices_plus') does not return data unchanged after a transform_boxes() call that rotates, shears, or otherwise reorders the vertices. A quarter turn keeps the box axis-aligned and still yields an export that differs from data, because the reduction re-canonicalizes the vertex order.

Parameters:

mode (Optional[str], optional) –
the output box format, or None to reuse mode. That attribute depends on the construction path: the constructor defaults to 'vertices_plus', while from_tensor() records the mode its input was given in. It could be: Default: None
- ’xyxy’: xmin, ymin, xmax, ymax with exclusive extent.
- ’xyxy_plus’: xmin, ymin, xmax, ymax with inclusive extent.
- ’xywh’: xmin, ymin, width, height with exclusive extent.
- ’vertices’: boxes are defined by their vertices points in the following clockwise order: top-left, top-right, bottom-right, bottom-left. Vertices coordinates are in (x,y) order. This is the exclusive export form.
- ’vertices_plus’: the inclusive stored vertex form.
as_padded_sequence (bool, optional) – If this object was created from a list, return its padded tensor rather than a list of tensors trimmed to their original lengths. The padded values follow the selected output mode. Batch slicing, index tensors, and boolean masks preserve the list metadata. Selecting a single batch element with an integer or scalar tensor returns an unbatched object without list metadata. Default: False

Return type:

Tensor | list[Tensor]

Returns:

Boxes tensor in the mode format, or a list of tensors when the object was created from a list and as_padded_sequence=False. The tensor shape depends on the mode value:

’vertices’ or ‘vertices_plus’: \((N, 4, 2)\) or \((B, N, 4, 2)\).

Any other value: \((N, 4)\) or \((B, N, 4)\).

Examples

>>> boxes_xyxy = torch.as_tensor([[0, 3, 1, 4], [5, 1, 8, 4]])
>>> boxes = Boxes.from_tensor(boxes_xyxy)
>>> assert (boxes_xyxy == boxes.to_tensor(mode='xyxy')).all()

transform_boxes(M, inplace=False)[source]#

Apply a transformation matrix to the 2D boxes.

See the Convention block on Boxes.

Parameters:

M (Tensor) – The transformation matrix to be applied, shape of \((3, 3)\) or \((B, 3, 3)\).
inplace (bool, optional) – do transform in-place and return self. Default: False

Return type:

Boxes

Returns:

The transformed boxes.

transform_boxes_(M)[source]#

Apply transform_boxes() in place and return self.

See the Convention block on Boxes.

Convention:: The internal tensor is rebound, not written: a tensor obtained from data before the call keeps the old coordinates (an empty container keeps its tensor).

Return type:: Boxes
Returns:: This Boxes object after the transformation.

translate(size, method='warp', inplace=False)[source]#

Translate boxes by the provided size.

See the Convention block on Boxes.

size supplies one (x, y) translation per batch item. Only the "warp" method is implemented; "fast" raises NotImplementedError.

Parameters:

size (Tensor) – translate size for x, y direction, shape of \((B, 2)\).
method (str, optional) – “warp” or “fast”. Default: "warp"
inplace (bool, optional) – do transform in-place and return self. Default: False

Return type:

Boxes

Returns:

The transformed boxes.

trim(correspondence_preserve=False, inplace=False)[source]#

Raise because trimming padded boxes is not implemented.

See the Convention block on Boxes.

Parameters:

correspondence_preserve (bool, optional) – Reserved for a future implementation. Default: False
inplace (bool, optional) – Reserved for a future implementation. Default: False

Raises:

NotImplementedError – Always.

Return type:

Boxes

type(dtype)[source]#

Cast the stored box coordinates to a new dtype.

Parameters:: dtype (dtype) – Target floating-point dtype for the coordinate tensor.
Return type:: Boxes
Returns:: self after converting data in place.

unpad(padding_size)[source]#

Undo pad() in place.

See the Convention block on Boxes.

padding_size is ordered as (left, right, top, bottom). Only left and top change the coordinate origin; this method returns self after subtracting those two values from every vertex. Both the batched \((B, N, 4, 2)\) and the unbatched \((N, 4, 2)\) container are supported; the unbatched form carries a single image, so padding_size must have exactly one row.

Parameters:: padding_size (Tensor) – Per-batch padding in (left, right, top, bottom) order, shaped \((B, 4)\). A single row broadcasts across the batch.
Return type:: Boxes

class kornia.geometry.boxes.Boxes3D(boxes, raise_if_not_floating_point=True, mode='xyzxyz_plus')[source]#

3D boxes containing N or BxN boxes.

Parameters:

boxes (Tensor) – 3D boxes, shape of \((N,8,3)\) or \((B,N,8,3)\). See below for more details.
raise_if_not_floating_point (bool, optional) – flag to control floating point casting behaviour when boxes is not a floating point tensor. True to raise an error when boxes isn’t a floating point tensor, False to cast to float. Default: True
mode (str, optional) – Representation label reported by mode. The constructor does not convert boxes and to_tensor() does not consult the label; use from_tensor() to import another representation. Default: "xyzxyz_plus"

Convention:

A box is a hexahedron of eight floating-point (x, y, z) vertices, \((N, 8, 3)\) or \((B, N, 8, 3)\): front-top-left, front-top-right, front-bottom-right, front-bottom-left, then the same four back vertices.
The stored form is inclusive (depth = zmax - zmin + 1), as for Boxes. from_tensor() takes \((N, 6)\) or \((B, N, 6)\) in 'xyzxyz', 'xyzwhd' (exclusive) or 'xyzxyz_plus'; the vertex modes exist for to_tensor() only. Modes are case-insensitive.
to_tensor() exports the amin/amax axis-aligned bounding box and defaults to 'xyzxyz' whatever the stored label.
get_boxes_shape() returns (depths, heights, widths), inclusive.
infer_bbox_shape3d() and bbox_to_mask3d() read their input as inclusive: pass them the 'vertices_plus' export, unbatched.
With validate_boxes=True, from_tensor() rejects a non-finite coordinate and extents that are not positive in the given mode (xmax == xmin fails in 'xyzxyz', passes in 'xyzxyz_plus').
The constructor rejects an integer tensor unless raise_if_not_floating_point=False; from_tensor() casts integer input to the default dtype.
transform_boxes() returns a new object labelled 'xyzxyz_plus'; transform_boxes_() rebinds the internal tensor of self and keeps the label.

Warning

The inclusive +1 is #3934 and the 'vertices' export trap #4009. The integer-input split is #4012 and the validator split with validate_bbox() is #4013. Boxes from bbox_generator3d() measure one larger than requested: #4018. The to_tensor() default differs from Boxes.to_tensor(), which defaults to the stored mode: #4251.

property data: Tensor#

Return the raw 3D corner-coordinate tensor.

Returns:: Tensor containing eight 3D corner coordinates per box, usually shaped \((N, 8, 3)\) or \((B, N, 8, 3)\).

property device: device#: Returns boxes device.

property dtype: dtype#: Returns boxes dtype.

classmethod from_tensor(boxes, mode='xyzxyz', validate_boxes=True)[source]#

Create Boxes3D from 3D boxes stored in another format.

See the Convention block on Boxes3D.

Parameters:

boxes (Tensor) – 3D boxes, shape of \((N,6)\) or \((B,N,6)\). Integer input is cast to torch.get_default_dtype().
mode (str, optional) –
The format in which the 3D boxes are provided, matched case-insensitively. Default: "xyzxyz"
- ’xyzxyz’: boxes are assumed to be in the format xmin, ymin, zmin, xmax, ymax, zmax where width = xmax - xmin, height = ymax - ymin and depth = zmax - zmin.
- ’xyzxyz_plus’: similar to ‘xyzxyz’ mode but where box width, length and depth are defined as width = xmax - xmin + 1, height = ymax - ymin + 1 and depth = zmax - zmin + 1.
- ’xyzwhd’: boxes are assumed to be in the format xmin, ymin, zmin, width, height, depth where width = xmax - xmin, height = ymax - ymin and depth = zmax - zmin.
validate_boxes (bool, optional) – reject boxes with a non-finite coordinate, and boxes whose width, height or depth is not positive when measured in the given mode’s convention, so xmax == xmin is rejected in 'xyzxyz' and accepted in 'xyzxyz_plus'. Default: True

Return type:

Boxes3D

Returns:

Boxes3D containing the converted inclusive vertex representation, labelled with mode.

Examples

>>> boxes_xyzxyz = torch.as_tensor([[0, 3, 6, 1, 4, 8], [5, 1, 3, 8, 4, 9]])
>>> boxes = Boxes3D.from_tensor(boxes_xyzxyz, mode='xyzxyz')
>>> boxes.data  # (2, 8, 3)
tensor([[[0., 3., 6.],
         [0., 3., 6.],
         [0., 3., 6.],
         [0., 3., 6.],
         [0., 3., 7.],
         [0., 3., 7.],
         [0., 3., 7.],
         [0., 3., 7.]],

        [[5., 1., 3.],
         [7., 1., 3.],
         [7., 3., 3.],
         [5., 3., 3.],
         [5., 1., 8.],
         [7., 1., 8.],
         [7., 3., 8.],
         [5., 3., 8.]]])

get_boxes_shape()[source]#

Compute boxes depths, heights and widths.

See the Convention block on Boxes3D.

Return type:

tuple[Tensor, Tensor, Tensor]

Returns:

Boxes depths, shape of \((N,)\) or \((B,N)\).
Boxes heights, shape of \((N,)\) or \((B,N)\).
Boxes widths, shape of \((N,)\) or \((B,N)\).

Example

>>> boxes_xyzxyz = torch.tensor([[ 0,  1,  2, 10, 21, 32], [3, 4, 5, 43, 54, 65]])
>>> boxes3d = Boxes3D.from_tensor(boxes_xyzxyz)
>>> boxes3d.get_boxes_shape()
(tensor([30., 60.]), tensor([20., 50.]), tensor([10., 40.]))

property mode: str#

Return the 3D box format remembered by this container.

Returns:: Mode string describing how this container should be interpreted during tensor conversion.

property shape: tuple[int, ...] | Size#

Return the tensor shape used to store 3D boxes.

Returns:: Shape of data. For unbatched boxes this is usually \((N, 8, 3)\), where \(N\) is the number of boxes, 8 is the number of cuboid corners, and 3 stores (x, y, z). For batched boxes the shape is usually \((B, N, 8, 3)\).

to(device=None, dtype=None)[source]#

Like torch.nn.Module.to() method.

Return type:: Boxes3D

to_mask(depth, height, width)[source]#

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

See the Convention block on Boxes3D.

Convention:: The size is (depth, height, width) and the mask \((N, depth, height, width)\) or \((B, N, depth, height, width)\) in the box dtype, with no channel axis. The exclusive 'xyzxyz' export is clamped to the volume, rounded to the nearest integer and filled over half-open ranges. A box tensor that requires grad raises RuntimeError.

Warning

bbox_to_mask3d() truncates instead of rounding, so a fractional box can fill a different volume: #4015.

Parameters:

depth (int) – depth of the masked image/images.
height (int) – height of the masked image/images.
width (int) – width of the masked image/images.

Return type:

Tensor

Returns:

the output mask tensor, shape of \((N, depth, height, width)\) or \((B, N, depth, height, width)\) and dtype of Boxes3D.dtype() (it can be any floating point dtype).

Note

It is currently non-differentiable.

Examples

>>> boxes = Boxes3D(torch.tensor([[  # Same as Boxes3D.from_tensor([[1, 1, 1, 3, 3, 2]], 'xyzxyz_plus')
...     [1., 1., 1.],
...     [3., 1., 1.],
...     [3., 3., 1.],
...     [1., 3., 1.],
...     [1., 1., 2.],
...     [3., 1., 2.],
...     [3., 3., 2.],
...     [1., 3., 2.],
... ]]))  # 1x8x3
>>> boxes.to_mask(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., 1., 0.],
          [0., 1., 1., 1., 0.],
          [0., 1., 1., 1., 0.],
          [0., 0., 0., 0., 0.]],

         [[0., 0., 0., 0., 0.],
          [0., 1., 1., 1., 0.],
          [0., 1., 1., 1., 0.],
          [0., 1., 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.]]]])

to_tensor(mode='xyzxyz')[source]#

Cast Boxes3D to a tensor.

See the Convention block on Boxes3D.

Convention:: mode defaults to 'xyzxyz' regardless of the stored label (#4251). Every export is the amin/amax axis-aligned bounding box of the stored vertices.

Parameters:

mode (str, optional) –

The format in which the boxes are provided, matched case-insensitively. Default: "xyzxyz"

’xyzxyz’: boxes are assumed to be in the format xmin, ymin, zmin, xmax, ymax, zmax where width = xmax - xmin, height = ymax - ymin and depth = zmax - zmin.
’xyzxyz_plus’: similar to ‘xyzxyz’ mode but where box width, length and depth are defined as
width = xmax - xmin + 1, height = ymax - ymin + 1 and depth = zmax - zmin + 1.
’xyzwhd’: boxes are assumed to be in the format xmin, ymin, zmin, width, height, depth where width = xmax - xmin, height = ymax - ymin and depth = zmax - zmin.
’vertices’: boxes are defined by their vertices points 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. Vertices coordinates are in (x,y, z) order. Finally, box width, height and depth are defined as width = xmax - xmin, height = ymax - ymin and depth = zmax - zmin.
’vertices_plus’: similar to ‘vertices’ mode but where box width, height and depth are defined as width = xmax - xmin + 1, height = ymax - ymin + 1 and depth = zmax - zmin + 1; this is the stored form.

Returns:

‘vertices’ or ‘vertices_plus’: \((N, 8, 3)\) or \((B, N, 8, 3)\).
Any other value: \((N, 6)\) or \((B, N, 6)\).

Return type:

3D Boxes tensor in the mode format. The shape depends with the mode value

Note

The amin/amax reduction ties on every face of an axis-aligned box (4 vertices share each extremum), so the gradient there is a subgradient shared among the tied vertices; it sums to one over them but need not match a finite-difference estimate such as torch.autograd.gradcheck().

Examples

>>> boxes_xyzxyz = torch.as_tensor([[0, 3, 6, 1, 4, 8], [5, 1, 3, 8, 4, 9]])
>>> boxes = Boxes3D.from_tensor(boxes_xyzxyz, mode='xyzxyz')
>>> assert (boxes.to_tensor(mode='xyzxyz') == boxes_xyzxyz).all()

transform_boxes(M, inplace=False)[source]#

Apply a transformation matrix to the 3D boxes.

See the Convention block on Boxes3D.

Parameters:

M (Tensor) – The transformation matrix to be applied, shape of \((4, 4)\) or \((B, 4, 4)\), where B must equal the box batch size and an unbatched box counts as one.
inplace (bool, optional) – do transform in-place and return self. Default: False

Returns:

a new Boxes3D labelled 'xyzxyz_plus' when inplace is false, otherwise self.

Return type:

The transformed boxes

transform_boxes_(M)[source]#

Apply transform_boxes() in place and return self.

See the Convention block on Boxes3D.

Convention:: The internal tensor is rebound, not written: a tensor obtained from data before the call keeps the old coordinates. The stored mode label is kept.

Return type:: Boxes3D
Returns:: This Boxes3D object after the transformation.

class kornia.geometry.boxes.VideoBoxes(boxes, raise_if_not_floating_point=True, mode='vertices_plus')[source]#

2D boxes with an explicit temporal channel for video sequences.

Accepts and returns box corners for a batch of videos as \((B, T, N, 4, 2)\) in vertices_plus mode. Internally the corners are stored flattened as \((B \cdot T, N, 4, 2)\). AugmentationSequential uses this wrapper when the pipeline contains a video sequential so that to_tensor restores the temporal axis after geometric transforms.

See the Convention block on Boxes.

Convention:

from_tensor() stores \((B, T, N, 4, 2)\) input unchanged as \((B \cdot T, N, 4, 2)\) 'vertices_plus' data, with no mode or conversion; integer input is cast to the default dtype, and another shape or a list raises ValueError. validate_boxes=True rejects a non-finite coordinate as Boxes.from_tensor() does for 'vertices_plus'.
to_tensor() accepts every Boxes mode and restores the temporal axis (to_tensor('xyxy') is \((B, T, N, 4)\)).
Indexing selects the video batch axis while preserving the temporal axis. An integer index returns a one-video VideoBoxes so to_tensor() keeps the shape \((1, T, \ldots)\). Index assignment, video_boxes[key] = other, writes the same whole videos.
A transformation matrix is \((B \cdot T, 3, 3)\); a \((3, 3)\) matrix raises ValueError unless \(B \cdot T = 1\).
transform_boxes(), translate(), clamp(), filter_boxes_by_area() and merge() return a new VideoBoxes; pad(), unpad(), to() and type() update self in place.

Variables:: temporal_channel_size – Number of frames \(T\) stored with the boxes.

clone()[source]#

Create an independent copy of the video box container.

Return type:: VideoBoxes
Returns:: New VideoBoxes with cloned tensor storage and the same temporal_channel_size, mode, and batch metadata.

classmethod from_tensor(boxes, validate_boxes=True)[source]#

Create VideoBoxes from a video box tensor.

Parameters:

boxes (Tensor | list[Tensor]) – Box corners with shape \((B, T, N, 4, 2)\) in vertices_plus order (top-left, top-right, bottom-right, bottom-left), stored unchanged; integer input is cast to torch.get_default_dtype(). Lists of tensors are not supported yet.
validate_boxes (bool, optional) – Reject a non-finite coordinate with RuntimeError (torch._assert_async, skipped on MPS). There is no extent or shape check, as for 'vertices_plus' in from_tensor(). Default: True

Return type:

VideoBoxes

Returns:

VideoBoxes with temporal_channel_size set to boxes.size(1).

Raises:

ValueError – If boxes is a list or does not have shape \((B, T, N, 4, 2)\).

to_tensor(mode=None, as_padded_sequence=False)[source]#

Cast VideoBoxes to a tensor with the temporal axis restored.

Parameters:

mode (Optional[str], optional) – Output box format forwarded to Boxes.to_tensor(). When None, uses the stored mode (vertices_plus by default). Default: None
as_padded_sequence (bool, optional) – Forwarded to Boxes.to_tensor(). It only changes the result of a list-backed container; a VideoBoxes built from a \((B, T, N, 4, 2)\) tensor is not list-backed, so the value makes no difference there. The keyword is accepted because the inherited get_boxes_shape() and to_mask() pass it. Default: False

Return type:

Tensor | list[Tensor]

Returns:

Tensor shaped \((B, T, \ldots)\) where \(T\) is temporal_channel_size.