Utilities for comparing bounding boxes
Author: Kevin Barnard, kbarnard@mbari.org
box-diff is available on PyPI as boxdiff:
pip install boxdiff
All of box-diff is housed within the boxdiff
package.
import boxdiff
The core data models are defined in the boxdiff.models
module. These are split into three groups:
BoundingBox
: ID + labeled 2D bounding boxImage
: ID + collection of bounding boxesImageSet
: ID + collection of images
Note: IDs may be integers, UUIDs, or strings.
Each group has a data model (defined in boxdiff.models.core
), a delta (boxdiff.models.deltas
), and a difference flag (boxdiff.models.flags
).
The data model represents the object and its attributes, whereas a delta represents the difference in attribute values between two objects.
Difference flags represent the presence of attribute differences between two objects as derived from a delta object.
All of the data models are serializable to JSON. For example,
json_str = bounding_box.to_json(indent=2)
print(json_str)
might give
{
"id": 0,
"label": "label",
"x": 0.0,
"y": 0.0,
"width": 1.0,
"height": 1.0
}
Similarly, data model objects may be parsed from JSON. For example,
bounding_box = BoundingBox.from_json(json_str)
print(bounding_box)
# BoundingBox(id=0, label='label', x=0.0, y=0.0, width=1.0, height=1.0)
A BoundingBox
is defined by an ID, a label, and a 2D box (x, y, width, height).
from boxdiff import BoundingBox
car_box = BoundingBox(
id=0,
label='car',
x=100, y=200,
width=300, height=80
)
Equality can be checked using the ==
operator:
same_car_box = BoundingBox(
id=0,
label='car',
x=100, y=200,
width=300, height=80
)
print(car_box == same_car_box)
# True
corrected_car_box = BoundingBox(
id=0,
label='car',
x=90, y=210,
width=320, height=85
)
print(car_box == corrected_car_box)
# False
A BoundingBoxDelta
between two boxes can be computed with the -
operator:
box_delta = corrected_car_box - car_box
print(box_delta)
# BoundingBoxDelta(id=1, label_old='car', label_new='car', x_delta=-10.0, y_delta=10.0, width_delta=20.0, height_delta=5.0)
BoundingBoxDifference
flags may then be computed from the delta:
print(box_delta.flags)
# BoundingBoxDifference.RESIZED|MOVED
Deltas may be applied to a bounding box using the +
operator:
new_car_box = car_box + box_delta
print(new_car_box)
# BoundingBox(id=1, label='car', x=90.0, y=210.0, width=320.0, height=85.0)
print(new_car_box == corrected_car_box)
# True
Area may be computed from a bounding box:
print(car_box.area)
# 24000.0
Intersection over union between bounding boxes can be computed using the iou
method:
car_iou = car_box.iou(corrected_car_box)
print(car_iou)
# 0.695364238410596
An Image
is defined by an ID and a collection of bounding boxes.
from boxdiff import Image
from uuid import UUID
image = Image(
id=UUID('78d76772-4664-467c-ae88-a25496234966'),
bounding_boxes=[car_box]
)
Likewise, equality can be checked using the ==
operator and deltas computed using the -
operator:
corrected_image = Image(
id=UUID('78d76772-4664-467c-ae88-a25496234966'),
bounding_boxes=[corrected_car_box]
)
image_delta = corrected_image - image
print(image_delta)
# ImageDelta(
# id=0,
# boxes_added=[],
# boxes_removed=[],
# box_deltas=[
# BoundingBoxDelta(
# id=0,
# label_old='car',
# label_new='car',
# x_delta=-10.0,
# y_delta=10.0,
# width_delta=20.0,
# height_delta=5.0
# )
# ]
# )
Similarly, flags may be computed from the delta:
print(image_delta.flags)
# ImageDifference.BOXES_MODIFIED
An ImageSet
is defined by an ID and a collection of images.
from boxdiff import ImageSet
image_set = ImageSet(
id='my_image_set',
images=[image, ...]
)
Its syntax and structure is analogous to that of an Image
.