bbox-visualizer

The bbox_visualizer package is organized into three main functional areas:

• Rectangle Drawing: Basic functions for drawing bounding boxes.
• Label Drawing: Functions for adding text labels to boxes.
• Special Labels: Specialized visualizations including T-shaped and flag-style label styles.

To install from the source code, clone the repository and use uv (recommended) or pip to install it in editable mode. For development environments, you can include the [dev] extra dependencies.

# Clone the repository
git clone https://github.com/shoumikchow/bbox-visualizer.git

# Navigate to the directory and install (using uv)
uv pip install -e .

# OR install with development dependencies
uv pip install -e ".[dev]"

# OR using pip
pip install -e .
pip install -e ".[dev]"

The repository includes several scripts and notebooks in the examples/ directory to demonstrate different use cases:

• quickstart.py: A minimal example on a blank canvas.
• single_object.py: Demonstrates every single-object label style.
• multiple_objects.py: Demonstrates every multi-object label style.
• single_object_example.ipynb: Basic usage with single objects in a Jupyter notebook.
• multiple_objects_example.ipynb: Working with multiple bounding boxes in a Jupyter notebook.

To use bbox-visualizer, import the library and use its drawing functions.

Important: All functions return a new image and do not modify the input image in-place. You must capture the return value to see changes.

Example workflow:

1. Load an image using OpenCV (cv2).
2. Call bbv.draw_box() to draw a bounding box.
3. Call bbv.add_label() to attach a text label to the box.

import bbox_visualizer as bbv
import cv2
import numpy as np

# Load an image
image = cv2.imread('image.jpg')

# Draw a bounding box
bbox = (100, 100, 200, 200)  # (x1, y1, x2, y2) format
image = bbv.draw_box(image, bbox)

# Add a label
image = bbv.add_label(image, "Object", bbox)

Install the bbox-visualizer package using pip to start drawing bounding boxes and labels on images.

pip install bbox-visualizer

The recommended way to install bbox-visualizer is using uv, a fast Python package installer. Ensure you have Python 3.10 or newer installed.

# Install uv if not already present
pip install uv

# Install bbox-visualizer
uv pip install bbox-visualizer

To quickly visualize a bounding box on an image, use bbox_visualizer.draw_box to render the rectangle and bbox_visualizer.add_label to attach a text label. The package works with standard NumPy arrays (OpenCV format).

import bbox_visualizer as bbv
import cv2
import numpy as np

# Create a sample image
image = np.ones((400, 600, 3), dtype=np.uint8) * 255

# Draw a bounding box with label
bbox = (100, 100, 300, 200)
image = bbv.draw_box(image, bbox, bbox_color=(0, 255, 0))
image = bbv.add_label(image, "Object", bbox)

# Display the result
cv2.imshow('Result', image)
cv2.waitKey(0)

You can install bbox-visualizer using the standard pip package manager.

pip install bbox-visualizer

To draw a single labeled bounding box, use bbv.draw_box and bbv.add_label.

Important: All functions return a new image and do not modify the input image in-place. You must capture the return value.

By default, bounding boxes are expected in Pascal VOC format: [x_min, y_min, x_max, y_max].

import cv2
import bbox_visualizer as bbv

img = cv2.imread("path/to/image.jpg")

# Bounding boxes use [x_min, y_min, x_max, y_max]
bbox = [150, 100, 450, 300]
label = "person"

img = bbv.draw_box(img, bbox, bbox_color=(0, 255, 0))
img = bbv.add_label(img, label, bbox)

cv2.imwrite("output.jpg", img)

The library uses Python's standard logging module to report warnings (e.g., when a label falls back to a different style). To silence these warnings, set the logging level for the bbox_visualizer logger to ERROR.

import logging

logging.getLogger("bbox_visualizer").setLevel(logging.ERROR)

Bounding Box Format Errors

If boxes are not appearing correctly, ensure you are using the correct format. The default is Pascal VOC [x_min, y_min, x_max, y_max]. If your data is in COCO or YOLO, pass bbox_format="coco" or bbox_format="yolo".

Color Format (BGR vs RGB)

bbox-visualizer works with OpenCV, which uses BGR color format.

• Red: (0, 0, 255)
• Green: (0, 255, 0)
• Blue: (255, 0, 0)

Image Not Displaying

If you are in an environment without a GUI, use cv2.imwrite() to save the result to a file instead of cv2.imshow().

The library uses Python's logging module to report fallback warnings (e.g., when a label cannot fit). To suppress these warnings, set the logger level to ERROR.

import logging

logging.getLogger("bbox_visualizer").setLevel(logging.ERROR)