Filled Box Annotator

Draw semi-transparent filled boxes on detected objects.

Overview

The filled_box() annotator draws semi-transparent filled rectangles over each detection's bounding box. It creates clean overlays that enhance object visibility without obscuring underlying image details, using alpha blending for professional-quality results.

Python

pf.annotators.filled_box(image, detections)

Function Signature

Python

def filled_box(    image: np.ndarray,    detections: Detections,    opacity: Optional[float] = 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.
opacity	float or None	None	Fill opacity [0.0-1.0]. None = auto-adapt to image size (typically 0.3-0.5).
colors	List[tuple] or None	None	List of BGR colors. None = use default palette.

Returns:
np.ndarray - The input image with filled 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 filled boxesannotated = pf.annotators.filled_box(image, detections)cv2.imshow("Result", annotated)cv2.waitKey(0)

Examples

Auto-Adaptive Opacity (Recommended)

Python

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

Custom Opacity

Python

# Subtle overlay for minimal obstructionannotated = pf.annotators.filled_box(image, detections, opacity=0.25)# High opacity for maximum emphasis in presentationsannotated = pf.annotators.filled_box(image, detections, opacity=0.8)

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.filled_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: filled boxes + box outlines + labelsimage = pf.annotators.filled_box(image, detections, opacity=0.3)image = pf.annotators.box(image, detections)image = pf.annotators.label(image, detections)# Highlight detections with filled boxes and labelsimage = pf.annotators.filled_box(image, detections, opacity=0.4)image = pf.annotators.label(image, detections)

Notes

In-place modification: The input image is modified directly. Use image.copy() if you need the original preserved.
Alpha blending: Uses cv2.addWeighted() for smooth transparency without artifacts.
Overlapping boxes: Multiple overlapping detections create cumulative opacity effects.
Empty detections: If detections is empty, the image is returned unchanged.
Performance: Creates temporary overlay per detection. Adds ~20% overhead vs simple rectangle drawing.