Implementation:Kornia Kornia Boxes

Knowledge Sources	Kornia
Domains	Vision, Geometry
Last Updated	2026-02-09 15:00 GMT

Overview

Provides object-oriented 2D and 3D bounding box containers (Boxes, Boxes3D, VideoBoxes) with rich format conversion, transformation, masking, and area computation capabilities.

Description

The boxes.py module in the Kornia geometry library defines the Boxes class for 2D quadrilateral bounding boxes and Boxes3D for 3D hexahedral bounding boxes. These classes internally store boxes as vertex-based tensors (Nx4x2 for 2D, Nx8x3 for 3D) and support conversion to and from common formats such as xyxy, xyxy_plus, xywh, and vertices. The classes provide methods for affine transformation, mask generation, area computation via the Shoelace formula, padding, clamping, filtering by area, and merging. A VideoBoxes subclass extends Boxes with a temporal dimension for video-based applications.

Usage

Import these classes when you need a high-level, format-agnostic bounding box abstraction that supports multiple input/output formats, batched operations, GPU acceleration, and geometric transformations in vision pipelines.

Code Reference

Source Location

• Repository: Kornia
• File: kornia/geometry/boxes.py
• Lines: 1-1144

Signature

class Boxes:
    def __init__(
        self,
        boxes: torch.Tensor | list[torch.Tensor],
        raise_if_not_floating_point: bool = True,
        mode: str = "vertices_plus",
    ) -> None

    @classmethod
    def from_tensor(
        cls, boxes: torch.Tensor | list[torch.Tensor],
        mode: str = "xyxy", validate_boxes: bool = True
    ) -> Boxes

    def to_tensor(
        self, mode: Optional[str] = None, as_padded_sequence: bool = False
    ) -> torch.Tensor | list[torch.Tensor]

    def to_mask(self, height: int, width: int) -> torch.Tensor
    def transform_boxes(self, M: torch.Tensor, inplace: bool = False) -> Boxes
    def compute_area(self) -> torch.Tensor
    def get_boxes_shape(self) -> tuple[torch.Tensor, torch.Tensor]
    def merge(self, boxes: Boxes, inplace: bool = False) -> Boxes
    def pad(self, padding_size: torch.Tensor) -> Boxes
    def clamp(self, topleft, botright, inplace: bool = False) -> Boxes
    def filter_boxes_by_area(self, min_area=None, max_area=None, inplace=False) -> Boxes

class Boxes3D:
    def __init__(
        self, boxes: torch.Tensor,
        raise_if_not_floating_point: bool = True,
        mode: str = "xyzxyz_plus",
    ) -> None

    @classmethod
    def from_tensor(
        cls, boxes: torch.Tensor, mode: str = "xyzxyz", validate_boxes: bool = True
    ) -> Boxes3D

    def to_tensor(self, mode: str = "xyzxyz") -> torch.Tensor
    def to_mask(self, depth: int, height: int, width: int) -> torch.Tensor
    def transform_boxes(self, M: torch.Tensor, inplace: bool = False) -> Boxes3D

class VideoBoxes(Boxes):
    temporal_channel_size: int

Import

from kornia.geometry.boxes import Boxes, Boxes3D, VideoBoxes

I/O Contract

Inputs (Boxes.from_tensor)

Name	Type	Required	Description
boxes	torch.Tensor or list[torch.Tensor]	Yes	2D boxes in shape (N, 4), (B, N, 4), (N, 4, 2) or (B, N, 4, 2)
mode	str	No	Box format: xyxy, xyxy_plus, xywh, vertices, or vertices_plus. Default: xyxy
validate_boxes	bool	No	Whether to validate box dimensions. Default: True

Outputs (Boxes.from_tensor)

Name	Type	Description
boxes	Boxes	A Boxes instance storing data internally as (N, 4, 2) or (B, N, 4, 2) quadrilaterals

Inputs (Boxes.to_tensor)

Name	Type	Required	Description
mode	str	No	Output format: xyxy, xyxy_plus, xywh, vertices, or vertices_plus
as_padded_sequence	bool	No	Whether to keep padding for list-constructed boxes. Default: False

Outputs (Boxes.to_tensor)

Name	Type	Description
tensor	torch.Tensor or list[torch.Tensor]	Boxes in the requested format, shape depends on mode

Usage Examples

import torch
from kornia.geometry.boxes import Boxes, Boxes3D

# Create 2D Boxes from xyxy format
boxes_xyxy = torch.as_tensor([[0, 3, 1, 4], [5, 1, 8, 4]])
boxes = Boxes.from_tensor(boxes_xyxy, mode='xyxy')

# Convert back to xyxy tensor
boxes_tensor = boxes.to_tensor(mode='xyxy')
assert (boxes_xyxy == boxes_tensor).all()

# Get box dimensions
heights, widths = boxes.get_boxes_shape()

# Compute area
areas = boxes.compute_area()

# Generate binary mask
mask = boxes.to_mask(height=10, width=10)

# Apply a transformation matrix
M = torch.eye(3).unsqueeze(0).repeat(1, 1, 1)
transformed = boxes.transform_boxes(M)

# Create 3D Boxes from xyzxyz format
boxes3d_data = torch.as_tensor([[0, 3, 6, 1, 4, 8], [5, 1, 3, 8, 4, 9]])
boxes3d = Boxes3D.from_tensor(boxes3d_data, mode='xyzxyz')
depths, heights_3d, widths_3d = boxes3d.get_boxes_shape()

Related Pages

• Principle:Kornia_Kornia_Box_Representation