Introduction to Annotators
What Are Annotators?
Annotators are visualization functions that draw detection results onto images. They transform raw detection data (bounding boxes, masks, keypoints, etc.) into visual representations that humans can interpret at a glance.
In computer vision pipelines, the model's output is just numbers, coordinates, class IDs, confidence scores. Annotators bridge the gap between machine output and human understanding.
Why Functions, Not Classes?
PixelFlow annotators are pure functions, not classes. This is a deliberate design choice:
1. Simplicity
# With functions - straightforwardimage = pf.annotators.box(image, detections)image = pf.annotators.label(image, detections)# With classes - more boilerplate ✋🏻🛑⛔️box_annotator = BoxAnnotator(thickness=2, color=(255,0,0))label_annotator = LabelAnnotator(font_scale=0.5)image = box_annotator.annotate(image, detections)image = label_annotator.annotate(image, detections)2. Easy Chaining
Functions naturally chain together - the output of one becomes the input of the next:
image = pf.annotators.box(image, detections)image = pf.annotators.label(image, detections)image = pf.annotators.mask(image, detections)3. No State to Manage
Functions don't carry hidden state between calls. Each call is independent and predictable.
4. Memory Efficient
No need to instantiate objects. The function does its work and returns.
Consistent API Pattern
Every annotator follows the same signature:
annotated_image = annotator(image, detections, **kwargs)| Parameter | Type | Description |
|---|---|---|
| image | np.ndarray | Input image (BGR format, modified in-place) |
| detections | Detections | PixelFlow detections object |
| **kwargs | various | Annotator-specific options |
| Returns | np.ndarray | The same image with annotations drawn |
This consistency means:
- Learn one, know them all
- Easy to swap annotators
- Predictable behavior
Adaptive Sizing
Annotators automatically adapt visual elements based on image dimensions:
| Image Size | Line Thickness | Font Scale | Blur Kernel |
|---|---|---|---|
| 640x480 | ~1px | ~0.3 | ~7px |
| 1920x1080 | ~2px | ~0.7 | ~15px |
| 4096x2160 | ~4px | ~1.4 | ~30px |
This ensures annotations look appropriate regardless of resolution. You can override with explicit values: