Implementation:Kornia Kornia Bbox Utilities

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

Overview

Provides utility functions for generating, validating, transforming, and converting 2D and 3D axis-aligned bounding boxes in PyTorch tensor format.

Description

The bbox.py module in the Kornia geometry library offers a comprehensive set of functions for working with bounding boxes represented as PyTorch tensors. It supports both 2D bounding boxes (defined by 4 corner points in clockwise order as Bx4x2 tensors) and 3D bounding boxes (defined by 8 corner points as Bx8x3 tensors). Key capabilities include validation of box rectangularity/cuboid shape, shape inference, mask generation, box generation from start coordinates and dimensions, affine transformation of boxes, and non-maximum suppression (NMS) for object detection post-processing.

Usage

Import these functions when you need to programmatically create, validate, transform, or filter bounding boxes in computer vision pipelines such as object detection, data augmentation, or crop extraction.

Code Reference

Source Location

• Repository: Kornia
• File: kornia/geometry/bbox.py
• Lines: 1-589

Signature

def validate_bbox(boxes: torch.Tensor) -> bool

def validate_bbox3d(boxes: torch.Tensor) -> bool

def infer_bbox_shape(boxes: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]

def infer_bbox_shape3d(boxes: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]

def bbox_to_mask(boxes: torch.Tensor, width: int, height: int) -> torch.Tensor

def bbox_to_mask3d(boxes: torch.Tensor, size: tuple[int, int, int]) -> torch.Tensor

def bbox_generator(
    x_start: torch.Tensor, y_start: torch.Tensor,
    width: torch.Tensor, height: torch.Tensor
) -> torch.Tensor

def bbox_generator3d(
    x_start: torch.Tensor, y_start: torch.Tensor, z_start: torch.Tensor,
    width: torch.Tensor, height: torch.Tensor, depth: torch.Tensor
) -> torch.Tensor

def transform_bbox(
    trans_mat: torch.Tensor, boxes: torch.Tensor,
    mode: str = "xyxy", restore_coordinates: Optional[bool] = None
) -> torch.Tensor

def nms(boxes: torch.Tensor, scores: torch.Tensor, iou_threshold: float) -> torch.Tensor

Import

from kornia.geometry.bbox import (
    validate_bbox, validate_bbox3d,
    infer_bbox_shape, infer_bbox_shape3d,
    bbox_to_mask, bbox_to_mask3d,
    bbox_generator, bbox_generator3d,
    transform_bbox, nms,
)

I/O Contract

Inputs (validate_bbox)

Name	Type	Required	Description
boxes	torch.Tensor	Yes	Bounding boxes of shape (B, 4, 2) or (B, N, 4, 2) with clockwise corner order: top-left, top-right, bottom-right, bottom-left in (x, y) coordinates

Outputs (validate_bbox)

Name	Type	Description
result	bool	True if boxes are valid rectangles, False otherwise

Inputs (bbox_generator)

Name	Type	Required	Description
x_start	torch.Tensor	Yes	X coordinates of bounding box origins, scalar or shape (B,)
y_start	torch.Tensor	Yes	Y coordinates of bounding box origins, scalar or shape (B,)
width	torch.Tensor	Yes	Widths of the bounding boxes, scalar or shape (B,)
height	torch.Tensor	Yes	Heights of the bounding boxes, scalar or shape (B,)

Outputs (bbox_generator)

Name	Type	Description
boxes	torch.Tensor	Generated bounding boxes of shape (B, 4, 2) in clockwise corner order

Inputs (nms)

Name	Type	Required	Description
boxes	torch.Tensor	Yes	Encoded bounding boxes of shape (N, 4) in (x1, y1, x2, y2) format
scores	torch.Tensor	Yes	Confidence scores of shape (N,)
iou_threshold	float	Yes	IoU threshold to discard overlapping boxes

Outputs (nms)

Name	Type	Description
keep	torch.Tensor	Indices of boxes to keep after suppression

Usage Examples

import torch
from kornia.geometry.bbox import bbox_generator, bbox_to_mask, nms, validate_bbox

# Generate 2D bounding boxes
x_start = torch.tensor([0, 1])
y_start = torch.tensor([1, 0])
width = torch.tensor([5, 3])
height = torch.tensor([7, 4])
boxes = bbox_generator(x_start, y_start, width, height)
# boxes shape: (2, 4, 2)

# Validate the generated boxes
is_valid = validate_bbox(boxes)  # True

# Convert boxes to a binary mask
single_box = torch.tensor([[[1., 1.], [3., 1.], [3., 2.], [1., 2.]]])
mask = bbox_to_mask(single_box, width=5, height=5)
# mask shape: (1, 5, 5)

# Non-maximum suppression
det_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])
keep = nms(det_boxes, scores, iou_threshold=0.8)
# keep: tensor([0, 3, 1])

Related Pages

• Principle:Kornia_Kornia_Bounding_Box_Operations