​
Overview

Simple and efficient bounding box visualization for object detection results. Automatically adapts line thickness based on image dimensions for optimal visibility.

​
Function Signature

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

​
Parameters

​
image
np.ndarray
required
Input image to draw boxes on (BGR format). Modified in-place with drawn bounding boxes.
​
detections
Detections
required
Detections object containing bounding boxes. Each detection must have a ‘bbox’ attribute with (x1, y1, x2, y2) coordinates.
​
thickness
Optional[int]
default:"None"
Line thickness for bounding boxes in pixels. If None, automatically determined based on image size.
​
colors
Optional[List[tuple]]
default:"None"
List of BGR color tuples to override default colors. Colors are mapped to unique class_ids in order of appearance. If None, uses default ColorManager colors.

​
Returns

​
result
np.ndarray
Image with bounding boxes drawn. The input image is modified in-place.

​
Examples

import cv2
import pixelflow as pf
from ultralytics import YOLO

# Load image and get model predictions
image = cv2.imread("path/to/image.jpg")
model = YOLO("yolo11n.pt")
outputs = model.predict(image)  # Raw model outputs
detections = pf.results.from_ultralytics(outputs)  # Convert to PixelFlow format

# Draw boxes with default colors and adaptive thickness
annotated = pf.annotators.box(image, detections)

# Override with custom colors for specific classes
custom_colors = [(255, 0, 0), (0, 255, 0), (0, 0, 255)]  # Blue, Green, Red
annotated = pf.annotators.box(image, detections, colors=custom_colors)

# Use custom thickness for fine control
annotated = pf.annotators.box(image, detections, thickness=3)

# Combine with other annotators for comprehensive visualization
annotated = pf.annotators.box(image, detections, thickness=2)

​
Error Handling

This function may raise the following exceptions:
  • AttributeError: If detection objects lack required ‘bbox’ attribute.
  • ValueError: If bounding box coordinates are invalid or out of bounds.

​
Notes

  • Input image is modified in-place for memory efficiency
  • Thickness automatically adapts to image dimensions when not specified
  • Coordinates are automatically converted to integers for drawing
  • Color selection uses ColorManager for consistent visualization across detections