BoundingBoxes3D

Bounding Boxes 3D Tensor of shape (n, 7) of which the last dimension is : [xc, yc, zc, Dx, Dy, Dz, heading]

• Coordinate xc, yc, zc of boxes’ center

• Boxes’ dimension Dx, Dy, Dz along the 3 axis

• Heading is the orientation by rotating around vertical Y-axis.

With this coordinate system convention:

• The X axis is positive to the right

• The Y axis is positive downwards

• The Z axis is positive forwards

Basic usage:

• Visualization
• Transformation
• IoU / GIoU 3D
• Other features

API

class aloscene.bounding_boxes_3d.BoundingBoxes3D(x, labels: Optional[Union[dict, aloscene.labels.Labels]] = None, names=('N', None), *args, **kwargs)

Bases: aloscene.tensors.augmented_tensor.AugmentedTensor

Bounding Boxes 3D Tensor of shape (n, 7) of which the last dimension is : [xc, yc, zc, Dx, Dy, Dz, heading]

• Coordinate xc, yc, zc of boxes’ center

• Boxes’ dimension Dx, Dy, Dz along the 3 axis

• Heading is the orientation by rotating around Y-axis.

Coordinate system convention:

• The X axis is positive to the right

• The Y axis is positive downwards

• The Z axis is positive forwards

bev_boxes()

Return the bird eye view boxes of shape (n, 4).

The last dimension: (x, z, dx, dz, converted heading). Because XZ is in inversed order, converted heading = - heading

Return type

OrientedBoxes2D

static boxes_3d_hflip(boxes, cam_extrinsic, **kwargs)

Flip boxes 3d horizontally

1. Bring boxes to camera refenrence frame using cam_extrinsic

2. Flip x coordinates

3. Rotate heading using Y-axis rotation of cam_extrinsic to get local heading w.r.t. camera. Then flip the heading and finally rotate local heading back to global heading

Parameters

boxesBoundingBoxes3D

shape (n, 7)

cam_extrinsicTensor

Shape (4, 4) or (t, 4, 4) of which the first dimension is “T”

Returns

BoundingBoxes3D

flipped boungding boxes 3d of shape (n, 7)

static get_enclosing_box_2d(boxes, cam_intrinsic, cam_extrinsic, frame_size, **kwargs)

Get the 2d box enclosing the 3d box on image plan

Parameters

boxesBoundingBoxes3D

Shape (n, 7)

cam_intrinsicCameraIntrinsic

Shape (3, 4)

cam_extrinsicCameraExtrinsic

Shape (4, 4)

frame_sizetuple[int, int]

(H, W)

Returns

BoundingBoxes2D

Shape (n, 4). Format “xyxy” with absolute coordinates. This instance is populated with frame_size and the same labels as boxes.labels

static get_vertices_3d(boxes)

Get 8 vertices for each boxes in x, y, z coordinates

Parameters

boxesBoundingBoxes3D

Shape (n, 7)

Returns

torch.Tensor

vertices in 3d Shape (n, 8, 3) for n boxes, 8 vertices, 3 coordinates [x, y, z]

rtype

Tensor ..

static get_vertices_3d_proj(boxes, cam_intrinsic, cam_extrinsic, include_vertice_behind_image_plan=True)

Get 8 vertices projected on image for each box 3d

Parameters

boxesBoundingBoxes3D

Shape (n, 7)

cam_intrinsicaloscene.camera_calib.CameraIntrinsic

Shape (3, 4)

cam_extrinsicCameraExtrinsic

Shape (4, 4)

include_vertice_behind_image_planbool, optional

If True, returns all vertices from box behind the image plan (negative Z coordinates). If False, filter out those boxes By default True

Returns

Tensor

Shape (m, 8, 2) for n boxes, 8 vertices, 2 coordinates x, y in pixel

with m <= n

rtype

Tensor ..

get_view(frame, size=None, mode='3D', **kwargs)

Create a View instance from a Frame

Parameters

framealoscene.Frame

The Frame must contain cam_intrinsic and cam_extrinsic matrices

sizetuple, optional

Desired size of the view, by default None.

modestr, optional

View mode, either “3D” or “2D”, by default “3D”

Returns

View

rtype

View ..

static giou3d(boxes1, boxes2, enclosing_type='smallest', ret_iou3d=False)

Calculate GIoU 3D for 2 aligned sets of boxes in order

This function works only with boxes1 and boxes2 in CUDA device.

Parameters

boxes1BoundingBoxes3D or torch.Tensor

Shape (n, 7)

boxes2BoundingBoxes3D or torch.Tensor

Shape (n, 7)

enclosing_typestr, optional

Choose the algorithm for finding enclosing box :

aligned # simple and naive. bad performance. fastest pca # approximated smallest box. slightly worse performance. smallest # [default]. brute force. smallest box. best performance. slowest

ret_iou3dbool, optional

If True, return also IoU 3D, by default False

Returns

Tensor or tuple of (Tensor, Tensor)

GIoU 3D, of shape (n,) IoU 3D, of shape (n,) (if ret_iou3d True)

rtype

Union[Tensor, Tuple[Tensor, Tensor]] ..

giou3d_with(boxes2, enclosing_type='smallest', ret_iou3d=False)

Calculate GIoU 3D for 2 aligned sets of boxes in order

This function works only with self and boxes2 in CUDA device.

Parameters

boxes2BoundingBoxes3D

Shape (n, 7)

enclosing_typestr, optional

Choose the algorithm for finding enclosing box :

aligned # simple and naive. bad performance. fastest pca # approximated smallest box. slightly worse performance. smallest # [default]. brute force. smallest box. best performance. slowest

ret_iou3dbool, optional

If True, return also IoU 3D, by default False

Returns

Tensor or tuple of (Tensor, Tensor)

GIoU 3D, of shape (n,) IoU 3D, of shape (n,) (if ret_iou3d True)

rtype

Union[Tensor, Tuple[Tensor, Tensor]] ..

static iou3d(boxes1, boxes2, ret_union=False)

Calculate IoU 3D for 2 aligned sets of boxes in order

This function works only with boxes1 and boxes2 in CUDA device.

Parameters

boxes1BoundingBoxes3D

Shape (n, 7)

boxes2BoundingBoxes3D

Shape (n, 7)

ret_unionbool, optional

If True, return also union volume, by default False

Returns

Tensor or tuple of (Tensor, Tensor)

IoU 3D, of shape (n,) Union volume, of shape (n,) (if ret_union True)

rtype

Union[Tensor, Tuple[Tensor, Tensor]] ..

iou3d_with(boxes2, ret_union=False)

Calculate IoU 3D for 2 aligned sets of boxes in order

This function works only with self and boxes2 in CUDA device.

Parameters

boxes2BoundingBoxes3D

Shape (n, 7)

ret_unionbool, optional

If True, return also union volume, by default False

Returns

Tensor or tuple of (Tensor, Tensor)

IoU 3D, of shape (n,) Union volume, of shape (n,) (if ret_union True)