vis4d.op.box.box2d¶

Utility functions for bounding boxes.

Functions

`apply_mask`(masks, *args)	Apply given masks (either bool or indices) to given list of tensors.
`bbox_area`(boxes)	Compute bounding box areas.
`bbox_clip`(boxes, image_hw[, epsilon])	Clip bounding boxes to image dims.
`bbox_intersection`(boxes1, boxes2)	Given two lists of boxes of size N and M, compute N x M intersection.
`bbox_intersection_aligned`(boxes1, boxes2)	Given two lists of boxes both of size N, compute N intersection.
`bbox_iou`(boxes1, boxes2)	Compute IoU between all pairs of boxes.
`bbox_iou_aligned`(boxes1, boxes2)	Compute IoU between aligned pairs of boxes.
`bbox_project`(boxes, homography_matrix)	Apply geometric transform to boxes in-place.
`bbox_scale`(boxes, scale_factor_xy)	Scale bounding box tensor.
`corner2hbox`(corners)	Convert box coordinates from corners to boxes.
`filter_boxes_by_area`(boxes[, min_area])	Filter a set of 2D bounding boxes given a minimum area.
`hbox2corner`(boxes)	Convert box coordinates from boxes to corners.
`multiclass_nms`(multi_bboxes, multi_scores, ...)	Non-maximum suppression with multiple classes.
`non_intersection`(tensor_a, tensor_b)	Get the elements of tensor_a that are not present in tensor_b.
`random_choice`(tensor, sample_size)	Randomly choose elements from a tensor.
`scale_and_clip_boxes`(boxes, original_hw, ...)	Postprocess boxes by scaling and clipping to given image dims.
`transform_bbox`(trans_mat, boxes)	Apply trans_mat (3, 3) / (B, 3, 3) to (N, 4) / (B, N, 4) xyxy boxes.

apply_mask(masks, *args)[source]¶

Apply given masks (either bool or indices) to given list of tensors.

Parameters:

masks (list[torch.Tensor]) – Masks to apply on tensors.
*args (list[torch.Tensor]) – List of tensors to apply the masks on.

Returns:

Masked tensor lists.

Return type:

tuple[list[torch.Tensor], …]

bbox_area(boxes)[source]¶

Compute bounding box areas.

Parameters:: boxes (torch.Tensor) – [N, 4] tensor of 2D boxes in format (x1, y1, x2, y2).
Returns:: [N,] tensor of box areas.
Return type:: torch.Tensor

bbox_clip(boxes, image_hw, epsilon=0)[source]¶

Clip bounding boxes to image dims.

Parameters:

boxes (torch.Tensor) – Bounding boxes with shape [N, 4]
image_hw (tuple[float, float]) – Image dimensions.
epsilon (int) – Epsilon for clipping. Defaults to 0.

Returns:

Clipped bounding boxes.

Return type:

torch.Tensor

bbox_intersection(boxes1, boxes2)[source]¶

Given two lists of boxes of size N and M, compute N x M intersection.

Parameters:

boxes1 (Tensor) – N 2D boxes in format (x1, y1, x2, y2)
boxes2 (Tensor) – M 2D boxes in format (x1, y1, x2, y2)

Returns:

intersection (N, M).

Return type:

Tensor

bbox_intersection_aligned(boxes1, boxes2)[source]¶

Given two lists of boxes both of size N, compute N intersection.

Parameters:

boxes1 (Tensor) – N 2D boxes in format (x1, y1, x2, y2)
boxes2 (Tensor) – N 2D boxes in format (x1, y1, x2, y2)

Returns:

intersection (N).

Return type:

Tensor

bbox_iou(boxes1, boxes2)[source]¶

Compute IoU between all pairs of boxes.

Parameters:

boxes1 (Tensor) – N 2D boxes in format (x1, y1, x2, y2)
boxes2 (Tensor) – M 2D boxes in format (x1, y1, x2, y2)

Returns:

IoU (N, M).

Return type:

Tensor

bbox_iou_aligned(boxes1, boxes2)[source]¶

Compute IoU between aligned pairs of boxes.

The number of boxes in both inputs must be the same.

Parameters:

boxes1 (Tensor) – N 2D boxes in format (x1, y1, x2, y2)
boxes2 (Tensor) – N 2D boxes in format (x1, y1, x2, y2)

Returns:

IoU (N).

Return type:

Tensor

bbox_project(boxes, homography_matrix)[source]¶

Apply geometric transform to boxes in-place.

Parameters:

boxes (Tensor) – Horizontal box tensor with shape of (…, 4).
homography_matrix (Tensor) – Shape (3, 3) for geometric transformation.

Return type:

Tensor

bbox_scale(boxes, scale_factor_xy)[source]¶

Scale bounding box tensor.

Parameters:

boxes (torch.Tensor) – Bounding boxes with shape [N, 4]
scale_factor_xy (tuple[float, float]) – Scaling factor for x and y

Return type:

Tensor

Returns:

torch.Tensor with bounding boxes scaled by the given factors in x and y direction

corner2hbox(corners)[source]¶

Convert box coordinates from corners to boxes.

Boxes are represented as (x1, y1, x2, y2). Corners are represented as ((x1, y1), (x2, y1), (x1, y2), (x2, y2)).

Parameters:: corners (Tensor) – Corner tensor with shape of (…, 4, 2).
Returns:: Horizontal box tensor with shape of (…, 4).
Return type:: Tensor

filter_boxes_by_area(boxes, min_area=0.0)[source]¶

Filter a set of 2D bounding boxes given a minimum area.

Parameters:

boxes (Tensor) – 2D bounding boxes [N, 4].
min_area (float, optional) – Minimum area. Defaults to 0.0.

Returns:

filtered boxes, boolean mask

Return type:

tuple[Tensor, Tensor]

hbox2corner(boxes)[source]¶

Convert box coordinates from boxes to corners.

Boxes are represented as (x1, y1, x2, y2). Corners are represented as ((x1, y1), (x2, y1), (x1, y2), (x2, y2)).

Parameters:: boxes (Tensor) – Horizontal box tensor with shape of (…, 4).
Returns:: Corner tensor with shape of (…, 4, 2).
Return type:: Tensor

multiclass_nms(multi_bboxes, multi_scores, score_thr, iou_thr, max_num=-1, class_agnostic=False, split_thr=100000)[source]¶

Non-maximum suppression with multiple classes.

Parameters:

multi_bboxes (Tensor) – shape (n, #class*4) or (n, 4)
multi_scores (Tensor) – shape (n, #class), where the last column contains scores of the background class, but this will be ignored.
score_thr (float) – bbox threshold, bboxes with scores lower than it will not be considered.
iou_thr (float) – NMS IoU threshold
max_num (int, optional) – if there are more than max_num bboxes after NMS, only top max_num will be kept. Defaults to -1.
class_agnostic (bool, optional) – whether apply class_agnostic NMS. Defaults to False.
split_thr (int, optional) – If the number of bboxes is less than split_thr, use class agnostic NMS with class_agnostic=True. Defaults to 100000.

Returns:

(Tensor, Tensor, Tensor, Tensor): detections (k, 5), scores: (k), classes (k) and indices (k).

Return type:

tuple

Raises:

RuntimeError – If there is a onnx error,

non_intersection(tensor_a, tensor_b)[source]¶

Get the elements of tensor_a that are not present in tensor_b.

Parameters:

tensor_a (torch.Tensor) – First tensor
tensor_b (torch.Tensor) – Second tensor

Return type:

Tensor

Returns:

torch.Tensor containing all elements that occur in both tensors

random_choice(tensor, sample_size)[source]¶

Randomly choose elements from a tensor.

If sample_size < len(tensor) this function will sample without repetition otherwise certain elements will be repeated.

Parameters:

tensor (torch.Tensor) – Tensor to sample from
sample_size (int) – Number of elements to sample

Return type:

Tensor

Returns:

torch.Tensor containing sample_size randomly sampled entries.

scale_and_clip_boxes(boxes, original_hw, current_hw, clip=True)[source]¶

Postprocess boxes by scaling and clipping to given image dims.

Parameters:

boxes (torch.Tensor) – Bounding boxes with shape [N, 4].
original_hw (tuple[int, int]) – Original height / width of image.
current_hw (tuple[int, int]) – Current height / width of image.
clip (bool) – If true, clips box corners to image bounds.

Returns:

Rescaled and possibly clipped bounding boxes.

Return type:

torch.Tensor

transform_bbox(trans_mat, boxes)[source]¶

Apply trans_mat (3, 3) / (B, 3, 3) to (N, 4) / (B, N, 4) xyxy boxes.

Parameters:

trans_mat (torch.Tensor) – Transformation matrix of shape (3,3) or (B,3,3)
boxes (torch.Tensor) – Bounding boxes of shape (N,4) or (B,N,4)

Return type:

Tensor

Returns:

torch.Tensor containing linear transformed bounding boxes. (B?, N, 4)