bbox package¶

bbox.bbox2d¶

2D bounding box module.

class BBox2D(x, mode=0)[source]¶

Bases: object

Class to reprsent a 2D bounding box.

Parameters

x – Sequence of length 4 representing (x, y, w, h) or (x1, y1, x2, y2) depending on mode.
mode (BoxMode2D) – Indicator of box format (x, y, w, h) or (x1, y1, x2, y2). The values are 0 for XYWH format and 1 for XYXY format. See box_modes.

Raises

ValueError – If x is not of length 4.
TypeError – If x is not of type {list, tuple, numpy.ndarray, BBox2D}

aspect_ratio(ratio)[source]¶

Return bounding box mapped to new aspect ratio denoted by ratio.

Parameters: ratio (float) – The new ratio should be given as the result of width / height.

center()[source]¶: Return center coordinates of the bounding box.

copy()[source]¶: Return a deep copy of this 2D bounding box.

property h¶

Syntactic sugar for height.

Type: float

property height¶

Height of bounding box.

Type: float

mul(s)[source]¶

Multiply the box by a scalar. Used for scaling bounding boxes.

Parameters: s (float or int) – Scalar value to scale the box by.

numpy(mode=0)[source]¶

Return bounding box as a numpy vector of length 4. Format depends on mode flag (default is XYWH).

Parameters: mode (BoxMode2D) – Mode in which to return the box. See box_modes.

tolist(mode=0)[source]¶

Return bounding box as a list of 4 numbers. Format depends on mode flag (default is XYWH).

Parameters: mode (BoxMode2D) – Mode in which to return the box. See box_modes.

property w¶

Syntactic sugar for width.

Type: float

property width¶

Width of bounding box.

Type: float

property x1¶

Left x coordinate.

Type: float

property x2¶

Right x coordinate.

Type: float

property y1¶

Top y coordinate.

Type: float

property y2¶

Bottom y coordinate.

Type: float

bbox.bbox2d_list¶

Bounding Box 2D list module.

class BBox2DList(arr, mode=0)[source]¶

Bases: object

Bounding Box 2D list class.

append(x, mode=0)[source]¶

Append a bounding box to the bounding box list.

Parameters: x – Bounding box to append.

copy()[source]¶: Return a deep copy of this bounding box list.

delete(index)[source]¶

Delete bounding box at index from this list.

Parameters: index (int) – Index of the box to delete.

property h¶

Syntactic sugar for height.

Type: float

property height¶

Height of bounding box of all boxes.

Type: float

insert(x, idx, mode=0)[source]¶

Insert a bounding box at a specific location.

Parameters

x – Bounding box to insert.
idx (int) – Position where to insert bounding box.

mul(scale)[source]¶

Scale the bounding boxes by the factor s.

Parameters: scale – Scalar factor to scale by.

numpy(mode=0)[source]¶

Return np.ndarray of shape (N, 4) representing all the bounding boxes.

Parameters: mode (BoxMode2D) – Mode in which to return the box. See box_modes.

property shape¶

Return the shape of the bounding boxes container in the form (N, 4).

Type: tuple

property w¶

Syntactic sugar for width.

Type: float

property width¶

Width of bounding box of all boxes.

Type: float

property x1¶

Left x coordinate of all boxes.

Type: float

property x2¶

Right x coordinate of all boxes.

Type: float

property y1¶

Top y coordinate of all boxes.

Type: float

property y2¶

Bottom y coordinate of all boxes.

Type: float

bbox.bbox3d¶

3D bounding box module.

class BBox3D(x, y, z, length=1, width=1, height=1, rw=1, rx=0, ry=0, rz=0, q=None, euler_angles=None, is_center=True)[source]¶

Bases: object

Class for 3D Bounding Boxes (3-orthotope). It takes either the center of the 3D bounding box or the back-bottom-left corner, the width, height and length of the box, and quaternion values to indicate the rotation.

Parameters

x (float) – X axis coordinate of 3D bounding box. Can be either center of bounding box or back-bottom-left corner.
y (float) – Y axis coordinate of 3D bounding box. Can be either center of bounding box or back-bottom-left corner.
z (float) – Z axis coordinate of 3D bounding box. Can be either center of bounding box or back-bottom-left corner.
length (float, optional) – The length of the box (default is 1).
width (float, optional) – The width of the box (default is 1).
height (float, optional) – The height of the box (default is 1).
rw (float, optional) – The real part of the rotation quaternion (default is 1).
rx (int, optional) – The first element of the quaternion vector (default is 0).
ry (int, optional) – The second element of the quaternion vector (default is 0).
rz (int, optional) – The third element of the quaternion vector (default is 0).
euler_angles (list or ndarray of float, optional) – Sequence of euler angles in [x, y, z] rotation order (the default is None).
is_center (bool, optional) – Flag to indicate if the provided coordinate is the center of the box (the default is True).

property center¶

Attribute to access center coordinates of box in (x, y, z) format. Can be set to list or ndarray of float.

Returns: 3-dimensional vector representing (x, y, z) coordinates of the box.
Return type: ndarray of float
Raises: ValueError – If c is not a vector/list of length 3.

copy()[source]¶

property cx¶

X coordinate of center.

Type: float

property cy¶

Y coordinate of center.

Type: float

property cz¶

Z coordinate of center.

Type: float

property h¶

Syntactic sugar for height of the box.

Type: float

property height¶

The height of the box.

Type: float

property l¶

Syntactic sugar for length of the box.

Type: float

property length¶

Length of the box.

Type: float

property p¶

Attribute to access ndarray of all corners of box in order.

Returns: All corners of the bounding box in order.
Return type: ndarray of float

property p1¶

Back-left-bottom point.

Type: float

property p2¶

Front-left-bottom point.

Type: float

property p3¶

Front-right-bottom point.

Type: float

property p4¶

Back-right-bottom point.

Type: float

property p5¶

Back-left-top point.

Type: float

property p6¶

Front-left-top point.

Type: float

property p7¶

Front-right-top point.

Type: float

property p8¶

Back-right-top point.

Type: float

property q¶

Syntactic sugar for the rotation quaternion of the box.

Returns: ndarray of float: Quaternion values in (w, x, y, z) form.

property quaternion¶

The rotation quaternion.

Returns: Quaternion values in (w, x, y, z) form.
Return type: ndarray of float

property w¶

Syntactic sugar for width of the box.

Type: float

property width¶

The width of the box.

Type: float

bbox.box_modes¶

Enumerations of bounding box modes.

class BoxMode2D[source]¶

Bases: enum.Enum

BoxMode2D defines the mode in which the bounding box is defined.

Most data sources have bounding boxes defined as XYWH where XY is the top left corner and W and H are the width and height of the box, respectively.

However, many algorithms prefer to deal with bounding boxes as XYXY where the box is defined is defined by the top-left corner and the bottom-right corner.

To help disambiguate between these two configurations, bbox provides a means to specify the mode and maintains the state internally.

XYWH = 0¶

XYXY = 1¶

bbox.geometry¶

Useful functions to deal with 3D geometry

edges_of(vertices)[source]¶

Return the vectors for the edges of the polygon defined by vertices.

Parameters: vertices – list of vertices of the polygon.

get_plane(a, b, c)[source]¶: Get plane equation from 3 points. Returns the coefficients of ax + by + cz + d = 0

is_separating_axis(o, p1, p2)[source]¶

Return True and the push vector if o is a separating axis of p1 and p2. Otherwise, return False and None.

Parameters

o – 2D array representing a vector.
p1 – 2D array of points representing a polygon.
p2 – 2D array of points representing a polygon.

orthogonal(v)[source]¶

Return a 90 degree clockwise rotation of the vector v.

Parameters: v – 2D array representing a vector.

point_plane_dist(pt, plane, signed=False)[source]¶

Get the signed distance from a point pt to a plane plane. Reference: http://mathworld.wolfram.com/Point-PlaneDistance.html

Plane is of the format [A, B, C, D], where the plane equation is Ax+By+Cz+D=0 Point is of the form [x, y, z] signed flag indicates whether to return signed distance.

polygon_area(polygon)[source]¶

Get the area of a polygon which is represented by a 2D array of points. Area is computed using the Shoelace Algorithm.

Parameters: polygon – 2D array of points.

polygon_collision(p1, p2)[source]¶

Return True if the shapes collide. Otherwise, return False.

p1 and p2 are np.arrays, the vertices of the polygons in the counterclockwise direction.

Source: https://hackmd.io/s/ryFmIZrsl

Parameters

p1 – 2D array of points representing a polygon.
p2 – 2D array of points representing a polygon.

polygon_intersection(poly1, poly2)[source]¶: Use the Sutherland-Hodgman algorithm to compute the intersection of 2 convex polygons.

bbox.metrics¶

Functions for metrics related to 2D and 3D bounding boxes.

iou_2d(a: bbox.bbox2d.BBox2D, b: bbox.bbox2d.BBox2D)[source]¶

Compute the Intersection over Union (IoU) of a pair of 2D bounding boxes.

Alias for jaccard_index_2d.

iou_3d(a: bbox.bbox3d.BBox3D, b: bbox.bbox3d.BBox3D)[source]¶

Compute the Intersection over Union (IoU) of a pair of 3D bounding boxes.

Alias for jaccard_index_3d.

jaccard_index_2d(a: bbox.bbox2d.BBox2D, b: bbox.bbox2d.BBox2D)[source]¶

Compute the Jaccard Index / Intersection over Union (IoU) of a pair of 2D bounding boxes.

Parameters

a (BBox2D) – 2D bounding box.
b (BBox2D) – 2D bounding box.

Returns

The IoU of the 2 bounding boxes.

Return type

float

jaccard_index_3d(a: bbox.bbox3d.BBox3D, b: bbox.bbox3d.BBox3D)[source]¶

Compute the Jaccard Index / Intersection over Union (IoU) of a pair of 3D bounding boxes. We compute the IoU using the top-down bird’s eye view of the boxes.

Note: We follow the KITTI format and assume only yaw rotations (along z-axis).

Parameters

a (BBox3D) – 3D bounding box.
b (BBox3D) – 3D bounding box.

Returns

The IoU of the 2 bounding boxes.

Return type

float

multi_iou_2d(a: bbox.bbox2d_list.BBox2DList, b: bbox.bbox2d_list.BBox2DList)[source]¶

Compute the Intersection over Union (IoU) of two sets of 2D bounding boxes.

Alias for multi_jaccard_index_2d.

multi_jaccard_index_2d(a: bbox.bbox2d_list.BBox2DList, b: bbox.bbox2d_list.BBox2DList)[source]¶

Compute the Jaccard Index (Intersection over Union) of two sets of 2D bounding boxes.

Parameters

a (BBox2DList) – List of 2D bounding boxes.
b (BBox2DList) – List of 2D bounding boxes.

Returns

IoU Matrix

Return type

ndarray

bbox.utils¶

Utility code.

NMS adapted from Tomasz Malisiewicz’s & Ross Girshick’s code.

aspect_ratio(bbox, ratios)[source]¶

Enumerate box for each aspect ratio.

Parameters

bbox (BBox2D) – 2D bounding box.
ratios (list) – list of int/float values.

nms(bbl, scores, thresh)[source]¶

Perform fast non-maximum suppression on a set of bounding boxes given their associated confidences.

Parameters

bbl (BBox2DList) – List of 2D bounding boxes.
scores (list or ndarray) – Scores for each bounding box.

Raises

ValueError – If arguments are of incorrect type or size.

Module contents¶

Main package initialization