PyBBoxes: Light Weight Toolkit for Bounding Boxes

0.2.0 · active · verified Thu Apr 16

PyBBoxes is a lightweight Python toolkit designed for handling bounding box operations. It provides abstractions for various bounding box formats (e.g., Pascal VOC, YOLO, COCO, Albumentations, FiftyOne) and allows for seamless conversions, common mathematical operations, scaling, clamping, and IoU computations. The current version is 0.2.0, and the library maintains an active release cadence with regular updates.

Common errors

```
AttributeError: module 'pybboxes' has no attribute 'bbox_iou'
```
cause Functional methods like `bbox_iou` were moved from the top-level `pybboxes` module to the `pybboxes.functional` submodule in version 0.1.0.

fix Change your import statement from `from pybboxes import bbox_iou` to `from pybboxes.functional import bbox_iou`.
```
ERROR: Package 'pybboxes' requires a different Python; you have 3.7.x but 'pybboxes' requires >=3.8
```
cause Versions of `pybboxes` 0.2.0 and later explicitly require Python 3.8 or higher. Python 3.6 support was dropped in v0.1.6.

fix Upgrade your Python environment to 3.8 or newer. If upgrading Python is not an option, you would need to install an older compatible version of `pybboxes` (e.g., `pip install pybboxes<0.2.0` for Python 3.7).
```
ValueError: Bounding box values are out of bounds for image (width, height): (640, 480).
```
cause This error likely occurs in versions prior to 0.1.5 where `strict=True` was the default. If your bounding box coordinates exceed image dimensions, it raises an error.

fix As of v0.1.5, the default `strict` parameter changed to `False`. To replicate the older behavior, set `strict=True` explicitly. If you want to allow out-of-bounds boxes and clamp them, ensure `strict=False` (the new default) and use the `.clamp()` method if needed.

Warnings

breaking The default value of the `strict` parameter for `BoundingBox` and conversion methods changed from `True` to `False` in v0.1.5. This means out-of-bounds boxes are now allowed by default instead of raising an error.
Fix: If your code relies on strict boundary checking, explicitly set `strict=True` when creating `BoundingBox` objects or performing conversions. If you previously handled `OutOfBoundsError` and now want the non-strict behavior, you might need to adjust.
breaking All functional computations (e.g., `bbox_iou`, `bbox_shift`, `bbox_scale`) were moved from the top-level `pybboxes` module to the `pybboxes.functional` submodule.
Fix: Update your imports to fetch functional methods from `pybboxes.functional` (e.g., `from pybboxes.functional import bbox_iou`).
breaking Support for Python 3.6 was dropped in v0.1.6. As of v0.2.0, the library explicitly requires Python 3.8 or newer.
Fix: Upgrade your Python environment to version 3.8 or higher. If you need to use an older Python version, you must use an older `pybboxes` release (e.g., v0.1.1 supported Python 3.6).
gotcha The `from_array()` method, introduced in v0.2.0, now supports multidimensional input. While this adds flexibility, ensure your input arrays match the expected (N, 4) or (N, H, W, 4) shapes to avoid unexpected parsing.
Fix: Review calls to `from_array()` if you are providing multidimensional inputs and verify the output is as expected. Refer to documentation for supported input shapes for specific box types.

Install

pip install pybboxes Install stable version

Imports

BoundingBox
wrong:
```
from pybboxes.boxes import BoundingBox
```
correct:
```
from pybboxes import BoundingBox
```
The primary BoundingBox class is imported directly from the top-level package.
bbox_iou
wrong:
```
from pybboxes import bbox_iou
```
correct:
```
from pybboxes.functional import bbox_iou
```
As of v0.1.0, all functional computations (like IoU, shift, scale) were moved to the `pybboxes.functional` submodule.
bbox_factory
wrong:
```
from pybboxes.factory import bbox_factory
```
correct:
```
from pybboxes import bbox_factory
```
The bbox_factory for generic box creation is imported from the top-level package.

Quickstart

This quickstart demonstrates how to create a `BoundingBox` object from Pascal VOC coordinates, convert it to YOLO format, calculate Intersection over Union (IoU) with another box, and apply scaling and clamping operations. It highlights the use of both the `BoundingBox` class and functions from `pybboxes.functional`.

from pybboxes import BoundingBox
from pybboxes.functional import bbox_iou

# Example coordinates: (x_min, y_min, x_max, y_max)
voc_bbox_values = (10, 20, 100, 120)
image_size = (640, 480) # (width, height)

# Create a BoundingBox object from Pascal VOC format
# 'strict=False' is the default since v0.1.5, allowing out-of-bounds boxes
bbox1 = BoundingBox(voc_bbox_values, image_size=image_size, from_type="voc")

print(f"Original VOC (bbox1): {bbox1.values}")
print(f"Normalized (bbox1): {bbox1.to_yolo().values}")

# Convert to another format, e.g., YOLO
yolo_bbox = bbox1.to_yolo()
print(f"Converted YOLO (bbox1): {yolo_bbox.values}")
print(f"Type: {yolo_bbox.box_type}")

# Perform a functional operation, e.g., Intersection over Union (IoU)
# Note: functional methods moved to pybboxes.functional in v0.1.0
bbox2_values = (15, 25, 105, 115)
bbox2 = BoundingBox(bbox2_values, image_size=image_size, from_type="voc")

iou = bbox_iou(bbox1, bbox2)
print(f"IoU between bbox1 and bbox2: {iou:.4f}")

# Example of scaling and clamping
scaled_bbox = bbox1.scale(scale=1.2)
print(f"Scaled bbox1 (1.2x): {scaled_bbox.values}")

clamped_bbox = scaled_bbox.clamp()
print(f"Clamped scaled bbox1 (to {image_size}): {clamped_bbox.values}")

view raw JSON →