0
# Annotators
1

2
Comprehensive visualization tools for adding annotations to images. All annotators inherit from `BaseAnnotator` and provide consistent APIs for drawing boxes, labels, masks, shapes, and visual effects on detection results.
3

4
## Capabilities
5

6
### Basic Shape Annotators
7

8
Core geometric shape annotations for highlighting detected objects.
9

10
```python { .api }
11
class BoxAnnotator(BaseAnnotator):
12
    """
13
    Draw bounding boxes around detections.
14
    
15
    Args:
16
        color (Color | ColorPalette): Box color or color palette
17
        thickness (int): Line thickness in pixels
18
        color_lookup (ColorLookup): Color mapping strategy (CLASS, TRACK, INDEX)
19
    """
20
    def __init__(
21
        self,
22
        color: Color | ColorPalette = ColorPalette.DEFAULT,
23
        thickness: int = 2,
24
        color_lookup: ColorLookup = ColorLookup.CLASS
25
    ): ...
26

27
    def annotate(
28
        self,
29
        scene: ImageType,
30
        detections: Detections,
31
        custom_color_lookup: np.ndarray | None = None
32
    ) -> ImageType:
33
        """Draw bounding boxes on the image."""
34

35
class BoxCornerAnnotator(BaseAnnotator):
36
    """
37
    Draw corner markers on bounding boxes.
38
    
39
    Args:
40
        color (Color | ColorPalette): Corner color or color palette  
41
        thickness (int): Line thickness in pixels
42
        corner_length (int): Length of corner lines in pixels
43
        color_lookup (ColorLookup): Color mapping strategy
44
    """
45
    def __init__(
46
        self,
47
        color: Color | ColorPalette = ColorPalette.DEFAULT,
48
        thickness: int = 4,
49
        corner_length: int = 15,
50
        color_lookup: ColorLookup = ColorLookup.CLASS
51
    ): ...
52

53
class RoundBoxAnnotator(BaseAnnotator):
54
    """Draw bounding boxes with rounded corners."""
55

56
class OrientedBoxAnnotator(BaseAnnotator):
57
    """Draw oriented/rotated bounding boxes for OBB detection."""
58

59
class CircleAnnotator(BaseAnnotator):
60
    """
61
    Draw circles around detections.
62
    
63
    Args:
64
        color (Color | ColorPalette): Circle color or color palette
65
        thickness (int): Circle line thickness  
66
        color_lookup (ColorLookup): Color mapping strategy
67
    """
68

69
class EllipseAnnotator(BaseAnnotator):
70
    """
71
    Draw ellipses around detections.
72
    
73
    Args:
74
        color (Color | ColorPalette): Ellipse color
75
        thickness (int): Line thickness
76
        start_angle (int): Starting angle of ellipse
77
        end_angle (int): Ending angle of ellipse
78
        color_lookup (ColorLookup): Color mapping strategy
79
    """
80

81
class DotAnnotator(BaseAnnotator):
82
    """Draw center dots on detections."""
83

84
class TriangleAnnotator(BaseAnnotator):
85
    """Draw triangular markers on detections."""
86
```
87

88
### Mask and Region Annotators
89

90
Annotations for segmentation masks and polygonal regions.
91

92
```python { .api }
93
class MaskAnnotator(BaseAnnotator):
94
    """
95
    Overlay segmentation masks with transparency.
96
    
97
    Args:
98
        color (Color | ColorPalette): Mask color or color palette
99
        opacity (float): Mask transparency (0.0 to 1.0)
100
        color_lookup (ColorLookup): Color mapping strategy
101
    """
102
    def __init__(
103
        self,
104
        color: Color | ColorPalette = ColorPalette.DEFAULT,
105
        opacity: float = 0.5,
106
        color_lookup: ColorLookup = ColorLookup.CLASS
107
    ): ...
108

109
class PolygonAnnotator(BaseAnnotator):
110
    """
111
    Draw polygon outlines from masks or polygon data.
112
    
113
    Args:
114
        color (Color | ColorPalette): Polygon color
115
        thickness (int): Line thickness
116
        color_lookup (ColorLookup): Color mapping strategy
117
    """
118

119
class HaloAnnotator(BaseAnnotator):
120
    """
121
    Add halo effects around segmentation masks.
122
    
123
    Args:
124
        color (Color | ColorPalette): Halo color
125
        opacity (float): Halo transparency
126
        kernel_size (int): Blur kernel size for halo effect
127
        color_lookup (ColorLookup): Color mapping strategy
128
    """
129
```
130

131
### Text and Label Annotators
132

133
Annotations for adding text labels and information overlays.
134

135
```python { .api }
136
class LabelAnnotator(BaseAnnotator):
137
    """
138
    Add text labels to detections.
139
    
140
    Args:
141
        color (Color | ColorPalette): Label background color
142
        text_color (Color | ColorPalette): Label text color
143
        text_padding (int): Padding around text in pixels
144
        text_position (Position): Label position relative to detection
145
        text_scale (float): Text size scaling factor
146
        text_thickness (int): Text line thickness
147
        font (int): OpenCV font type
148
        color_lookup (ColorLookup): Color mapping strategy
149
        border_radius (int): Background corner radius
150
        smart_position (bool): Auto-adjust position to avoid overlaps
151
    """
152
    def __init__(
153
        self,
154
        color: Color | ColorPalette = ColorPalette.DEFAULT,
155
        text_color: Color | ColorPalette = Color.WHITE,
156
        text_padding: int = 10,
157
        text_position: Position = Position.TOP_LEFT,
158
        text_scale: float = 0.5,
159
        text_thickness: int = 1,
160
        font: int = cv2.FONT_HERSHEY_SIMPLEX,
161
        color_lookup: ColorLookup = ColorLookup.CLASS,
162
        border_radius: int = 0,
163
        smart_position: bool = False
164
    ): ...
165

166
class RichLabelAnnotator(BaseAnnotator):
167
    """Enhanced labels with advanced formatting and styling options."""
168

169
class PercentageBarAnnotator(BaseAnnotator):
170
    """
171
    Display confidence or progress bars.
172
    
173
    Args:
174
        height (int): Bar height in pixels
175
        width (int): Bar width in pixels  
176
        color_lookup (ColorLookup): Color mapping strategy
177
        border_color (Color): Bar border color
178
        background_color (Color): Bar background color
179
    """
180
```
181

182
### Effect and Style Annotators
183

184
Advanced visual effects and image processing annotations.
185

186
```python { .api }
187
class BlurAnnotator(BaseAnnotator):
188
    """
189
    Apply blur effects to detection regions.
190
    
191
    Args:
192
        kernel_size (int): Blur kernel size (must be odd)
193
    """
194
    def __init__(self, kernel_size: int = 15): ...
195

196
class PixelateAnnotator(BaseAnnotator):
197
    """
198
    Apply pixelation effects to detection regions.
199
    
200
    Args:
201
        pixel_size (int): Size of pixelation blocks
202
    """
203

204
class ColorAnnotator(BaseAnnotator):
205
    """Apply color overlays to detection regions."""
206

207
class BackgroundOverlayAnnotator(BaseAnnotator):
208
    """Overlay background images or patterns."""
209

210
class HeatMapAnnotator(BaseAnnotator):
211
    """
212
    Generate heat map visualizations from detection density.
213
    
214
    Args:
215
        opacity (float): Heat map transparency
216
        kernel_size (int): Smoothing kernel size
217
        colormap (int): OpenCV colormap for visualization
218
    """
219

220
class IconAnnotator(BaseAnnotator):
221
    """
222
    Overlay custom icons on detections.
223
    
224
    Args:
225
        icon_path (str): Path to icon image file
226
        icon_size (tuple[int, int]): Icon dimensions (width, height)
227
        position (Position): Icon position relative to detection
228
    """
229

230
class CropAnnotator(BaseAnnotator):
231
    """Crop and display detection regions as overlays."""
232

233
class ComparisonAnnotator(BaseAnnotator):
234
    """Create side-by-side image comparisons."""
235
```
236

237
### Tracking Annotators
238

239
Specialized annotations for object tracking visualization.
240

241
```python { .api }
242
class TraceAnnotator(BaseAnnotator):
243
    """
244
    Draw object movement traces/trails.
245
    
246
    Args:
247
        color (Color | ColorPalette): Trace line color
248
        position (Position): Point to track (center, top_center, etc.)
249
        trace_length (int): Maximum trace history length
250
        thickness (int): Line thickness
251
        color_lookup (ColorLookup): Color mapping strategy
252
    """
253
    def __init__(
254
        self,
255
        color: Color | ColorPalette = ColorPalette.DEFAULT,
256
        position: Position = Position.CENTER,
257
        trace_length: int = 30,
258
        thickness: int = 2,
259
        color_lookup: ColorLookup = ColorLookup.CLASS
260
    ): ...
261
```
262

263
### Keypoint Annotators
264

265
Specialized annotations for keypoint and pose visualization.
266

267
```python { .api }
268
class VertexAnnotator(BaseAnnotator):
269
    """
270
    Draw keypoint vertices/markers.
271
    
272
    Args:
273
        color (Color | ColorPalette): Vertex color
274
        radius (int): Vertex marker radius
275
        color_lookup (ColorLookup): Color mapping strategy
276
    """
277

278
class EdgeAnnotator(BaseAnnotator):
279
    """
280
    Draw connections between keypoints.
281
    
282
    Args:
283
        color (Color | ColorPalette): Edge line color
284
        thickness (int): Line thickness
285
        edges (list[tuple[int, int]]): Pairs of keypoint indices to connect
286
        color_lookup (ColorLookup): Color mapping strategy
287
    """
288

289
class VertexLabelAnnotator(BaseAnnotator):
290
    """Add labels to keypoint vertices."""
291
```
292

293
## Usage Examples
294

295
### Basic Box and Label Annotation
296

297
```python
298
import supervision as sv
299
import cv2
300

301
# Create annotators
302
box_annotator = sv.BoxAnnotator(
303
    color=sv.ColorPalette.DEFAULT,
304
    thickness=2,
305
    color_lookup=sv.ColorLookup.CLASS
306
)
307

308
label_annotator = sv.LabelAnnotator(
309
    color=sv.ColorPalette.DEFAULT,
310
    text_color=sv.Color.WHITE,
311
    text_position=sv.Position.TOP_LEFT
312
)
313

314
# Apply annotations
315
annotated_frame = box_annotator.annotate(
316
    scene=image.copy(),
317
    detections=detections
318
)
319

320
annotated_frame = label_annotator.annotate(
321
    scene=annotated_frame,
322
    detections=detections,
323
    labels=class_names
324
)
325
```
326

327
### Advanced Multi-Annotator Pipeline
328

329
```python
330
import supervision as sv
331

332
# Create multiple annotators
333
annotators = [
334
    sv.MaskAnnotator(opacity=0.3),
335
    sv.BoxAnnotator(thickness=2),
336
    sv.LabelAnnotator(text_position=sv.Position.TOP_LEFT),
337
    sv.TraceAnnotator(trace_length=50)
338
]
339

340
# Apply all annotations
341
annotated_frame = image.copy()
342
for annotator in annotators:
343
    annotated_frame = annotator.annotate(
344
        scene=annotated_frame,
345
        detections=detections
346
    )
347
```
348

349
### Custom Color Mapping
350

351
```python
352
# Use custom colors
353
custom_colors = np.array([
354
    [255, 0, 0],    # Red for class 0
355
    [0, 255, 0],    # Green for class 1  
356
    [0, 0, 255]     # Blue for class 2
357
])
358

359
box_annotator = sv.BoxAnnotator(color_lookup=sv.ColorLookup.CLASS)
360
annotated_frame = box_annotator.annotate(
361
    scene=image,
362
    detections=detections,
363
    custom_color_lookup=custom_colors
364
)
365
```
366

367
## Types
368

369
```python { .api }
370
# Base annotator type
371
class BaseAnnotator:
372
    """Base class for all annotators providing common interface."""
373
    
374
    def annotate(
375
        self,
376
        scene: ImageType,
377
        detections: Detections,
378
        **kwargs
379
    ) -> ImageType:
380
        """Apply annotation to the scene."""
381

382
# Image type union
383
ImageType = np.ndarray | Image.Image
384

385
# Color lookup strategy
386
class ColorLookup(Enum):
387
    CLASS = "CLASS"     # Color by detection class
388
    TRACK = "TRACK"     # Color by tracking ID
389
    INDEX = "INDEX"     # Color by detection index
390
```