/bbox

Python library for 2D/3D bounding boxes

Primary LanguagePythonMIT LicenseMIT

bbox

bbox a Python library that is intended to ease the use of 2D and 3D bounding boxes in areas such as Object Detection by providing a set of flexible primitives and functions that are intuitive and easy to use out of the box.

Build Status codecov

PyPI version PyPI format

Say Thanks!

Features

2D Bounding Box

Easily work with bounding boxes using a simple class that abstracts and maintains various attributes.

from bbox import BBox2D, XYXY

# x, y, w, h
box = BBox2D([0, 0, 32, 32])

# equivalently, in (x1, y1, x2, y2) (aka two point format), we can use
box = BBox2D([0, 0, 31, 31], mode=XYXY)

print(box.x1, box.y1)  # -> 0 0
print(box.x2, box.y2)  # -> 31 31
print(box.height, box.width)  # -> 32 32

# Syntatic sugar for height and width
print(box.h, box.w)  # -> 32 32

Sequence of 2D bounding boxes

Most tasks involve dealing with multiple bounding boxes. This can also be handled conveniently with the BBox2DList class.

bbl = BBox2DList(np.random.randint(10, 4),
                 mode=XYWH)

The above snippet creates a list of 10 bounding boxes neatly abstracted into a convenient object.

Non-maximum Suppression

Need to perform non-maximum suppression? It is as easy as a single function call.

from bbox.utils import nms

# bbl -> BBox2DList
# scores -> list/ndarray of confidence scores
new_boxes = nms(bbl, scores)

Intersection over Union (Jaccard Index)

The Jaccard Index or IoU is a very useful metric for finding similarities between bounding boxes. bbox provides native support for this.

from bbox.metrics import jaccard_index_2d

box1 = BBox2D([0, 0, 32, 32])
box2 = BBox2D([10, 12, 32, 46])

iou = jaccard_index_2d(box1, box2)

We can even use the Jaccard Index to compute a distance metric between boxes as a distance matrix:

from bbox.metrics import multi_jaccard_index_2d

dist = 1 - multi_jaccard_index_2d(bbl, bbl)

3D Bounding Box

bbox also support 3D bounding boxes, providing convenience methods and attributes for working with them.