Bounding Box Annotator

Draw bounding boxes around detected objects.

Overview

The box() annotator draws rectangular outlines around each detection's bounding box. It's the most fundamental visualization for object detection - simple, fast, and universally understood.

Python

pf.annotators.box(image, detections)

Function Signature

Python

def box(    image: np.ndarray,    detections: Detections,    thickness: Optional[int] = None,    colors: Optional[List[tuple]] = None) -> np.ndarray

Parameters

Parameter	Type	Default	Description
image	np.ndarray	required	Input image in BGR format. Modified in-place.
detections	Detections	required	PixelFlow detections with bounding boxes.
thickness	int or None	None	Line thickness in pixels. None = auto-adapt to image size.
colors	List[tuple] or None	None	List of BGR colors. None = use default palette.

Returns:
np.ndarray - The input image with bounding boxes drawn (same array, modified in-place).

Basic Usage

Python

import cv2import pixelflow as pffrom ultralytics import YOLO# Load image and run detectionimage = cv2.imread("street.jpg")model = YOLO("yolo11n.pt")results = model.predict(image)detections = pf.from_ultralytics(results)# Draw bounding boxesannotated = pf.annotators.box(image, detections)cv2.imshow("Result", annotated)cv2.waitKey(0)

Examples

Auto-Adaptive Thickness (Recommended)

Python

# Let PixelFlow choose appropriate thickness based on image resolutionannotated = pf.annotators.box(image, detections)

Custom Thickness

Python

# Thin lines for dense detectionsannotated = pf.annotators.box(image, detections, thickness=1)# Thick lines for presentations/demosannotated = pf.annotators.box(image, detections, thickness=4)

Custom Colors

Python

# Override with specific colors (BGR format)custom_colors = [    (0, 255, 0),    # Green - assigned to first unique class_id    (0, 0, 255),    # Red - assigned to second unique class_id    (255, 0, 0),    # Blue - assigned to third unique class_id]annotated = pf.annotators.box(image, detections, colors=custom_colors)

Colors are mapped to class_id values in order of appearance. If you have 5 classes but only 3 colors, colors will cycle.

By default same class_id always gets the same color across frames, ensuring visual consistency.

Combining with Other Annotators

Python

# Common pattern: boxes + labelsimage = pf.annotators.box(image, detections)image = pf.annotators.label(image, detections)# Full visualization stackimage = pf.annotators.box(image, detections, thickness=2)image = pf.annotators.label(image, detections)image = pf.annotators.mask(image, detections, opacity=0.3)

Notes

In-place modification: The input image is modified directly. Use image.copy() if you need the original preserved.
Coordinate handling: Bounding box coordinates are automatically converted to integers.
Empty detections: If detections is empty, the image is returned unchanged.
Performance: Optimized for real-time video processing. Minimal overhead per detection.