^jddlmZddlmZddlmZddlmZmZm Z ddl Z ddl Z ddl mZddlmZmZddlmZmZmZddlmZmZdd lmZdd lmZmZmZmZm Z m!Z!m"Z"m#Z#m$Z$m%Z%m&Z&m'Z'dd l(m)Z)dd l*m+Z+dd l,m-Z-ddl.m/Z/m0Z0ddl1m2Z2m3Z3m4Z4ddl5m6Z6ddl7m8Z8m9Z9ddl:m;Z;mm?Z?m@Z@mAZAddlBmCZCmDZDddlEmFZFmGZGmHZHmIZIddlJmKZKeKeLZMe dKdZNe dLdZNdLdZNe jZPGddeZQGddeZRGddeZS dM dNd ZTGd!d"eZUGd#d$eZVGd%d&eZWGd'd(eZXGd)d*eZYGd+d,eZZGd-d.eZ[Gd/d0eZ\Gd1d2eQZ]Gd3d4eQZ^Gd5d6eZ_Gd7d8eZ`Gd9d:eZaGd;deZcGd?d@eZdGdAdBeZeGdCdDeZfGdEdFeZgGdGdHeZhGdIdJZiy)O) annotations) lru_cache)sqrt)AnycastoverloadN) deprecatedvoid)Image ImageDraw ImageFont)splevsplprep) BaseAnnotator) PENDING_TRACK_ID ColorLookupTrace_validate_labelscalculate_dynamic_kernel_sizecalculate_dynamic_pixel_sizeget_labels_text hex_to_rgba resolve_colorresolve_text_background_xyxy snap_boxes wrap_text)ORIENTED_BOX_COORDINATES) CompactMask) Detections) clip_boxesspread_out_boxes)mask_to_polygonspolygon_to_maskxyxy_to_polygons) ImageType)Color ColorPalette) draw_polygondraw_rounded_rectangle draw_text)PointPositionRect)!ensure_cv2_image_for_class_method!ensure_pil_image_for_class_method) crop_imageletterbox_image overlay_image scale_image) _get_loggercyNcolors f/var/www/ramen.bs-engineer-server.com/venv/lib/python3.12/site-packages/supervision/annotators/core.py_normalize_color_inputr;9s9<cyr6r7r8s r:r;r;=sr<cvt|tr(t|\}}}}tj|||fS|S)aNormalize accepted color inputs to internal color objects. Accepts `Color`, `ColorPalette`, or hex string input. Hex strings are parsed via `hex_to_rgba` and converted to `Color` (alpha channel is ignored because annotator drawing uses RGB/BGR colors). ) isinstancestrrr&from_rgb_tuple)r9rgb_s r:r;r;Cs<% ' 1a##Q1I.. Lr<c eZdZdZej ejejde jddddf d dZ d dZ y) _BaseLabelAnnotatora Base class for annotators that add labels to detections. Attributes: color: The color to use for the label background. color_lookup: The method used to determine the color of the label. text_color: The color to use for the label text. text_padding: The padding around the label text, in pixels. text_anchor: The position of the text relative to the detection bounding box. text_offset: A tuple of 2D coordinates `(x, y)` to offset the text position from the anchor point, in pixels. border_radius: The radius of the label background corners, in pixels. smart_position: Whether to intelligently adjust the label position to avoid overlapping with other elements. max_line_length: Maximum number of characters per line before wrapping the text. None means no wrapping. rrrFNc t||_||_t||_||_||_||_||_||_| |_ y)a Initializes the _BaseLabelAnnotator. Args: color: The color to use for the label background. color_lookup: The method used to determine the color of the label text_color: The color to use for the label text. text_padding: The padding around the label text, in pixels. text_position: The position of the text relative to the detection bounding box. text_offset: A tuple of 2D coordinates `(x, y)` to offset the text position from the anchor point, in pixels. border_radius: The radius of the label background corners, in pixels. smart_position: Whether to intelligently adjust the label position to avoid overlapping with other elements. max_line_length: Maximum number of characters per line before wrapping the text. None means no wrapping. N) r;r9 color_lookup text_color text_padding text_anchor text_offset border_radiussmart_positionmax_line_length) selfr9rKrLrM text_positionrOrPrQrRs r:__init__z_BaseLabelAnnotator.__init__gsVD,B%+H )50Fz0R!-%2,7"/,+:r<c|j}t|ddddf||ddddf<t|dkDr?|ddddf}t|}||ddddf<t|ddddf||ddddf<|S)a Adjusts the position of labels to ensure they stay within the frame boundaries. Args: resolution_wh: The width and height of the frame. labels: The list of text labels. label_properties: An array of label properties, where each row contains [x1, y1, x2, y2, text_height, ...]. Returns: The adjusted label properties. N)copyrlenr!)rS resolution_whlabelslabel_propertiesadjusted_propertiesboxes spread_boxess r:_adjust_labels_in_framez+_BaseLabelAnnotator._adjust_labels_in_frames$/335&0 2A2 & & ArrE" v;?'2A2.E+E2L)5 2A2 &*4#ArrE*M* 2A2 &#"r<)r9Color | ColorPalette | strrKrrLrbrMintrTr,rOtuple[int, int]rPrcrQboolrR int | None)r[rdr\ list[str]r]npt.NDArray[np.float32]returnnpt.NDArray[np.uint8])__name__ __module__ __qualname____doc__r'DEFAULTrCLASSr&WHITEr,TOP_LEFTrUrar7r<r:rGrGSs*-9,@,@$/$5$516"*"3"3'-$&**;)*;"*;/ *;  *;  *;%*;*;*;$*;X(#&(#(#2 (#  (#r<rGcveZdZdZej dejf ddZe d ddZ y) BoxAnnotatorzS A class for drawing bounding boxes on an image using provided detections. c@t||_||_||_ya0 Args: color: The color or color palette to use for annotating detections. thickness: Thickness of the bounding box lines. color_lookup: Strategy for mapping colors to annotations. Options are `INDEX`, `CLASS`, `TRACK`. Nr;r9 thicknessrKrSr9ryrKs r:rUzBoxAnnotator.__init__ ,B%+H ')5r<Ncxt|tjs|Stt |D]}|j |j t\}}}}t|j||| |jn|} tj|||f||f| j|j|S)a7 Annotates the given scene with bounding boxes based on the provided detections. Args: scene: The image where bounding boxes will be drawn. `ImageType` is a flexible type, accepting either `numpy.ndarray` or `PIL.Image.Image`. detections: Object detections to annotate. custom_color_lookup: Custom color lookup array. Allows to override the default color mapping strategy. Returns: The annotated image, matching the type of `scene` (`numpy.ndarray` or `PIL.Image.Image`) Examples: ```pycon >>> import numpy as np >>> import supervision as sv >>> image = np.zeros((100, 100, 3), dtype=np.uint8) >>> detections = sv.Detections( ... xyxy=np.array([[20, 20, 80, 80]]), ... class_id=np.array([0]) ... ) >>> box_annotator = sv.BoxAnnotator() >>> annotated_frame = box_annotator.annotate( ... scene=image.copy(), ... detections=detections ... ) ``` ![bounding-box-annotator-example](https://media.roboflow.com/ supervision-annotator-examples/bounding-box-annotator-example-purple.png) r9 detections detection_idxrKimgpt1pt2r9ry)r?npndarrayrangerZxyxyastypercrr9rKcv2 rectangleas_bgrry) rSscener~custom_color_lookuprx1y1x2y2r9s r:annotatezBoxAnnotator.annotatesT%,L"3z?3 M'__];BB3GNBB!jj%+&."..( E MMHHlln..   " r<r9rbryrcrKrr6rr%r~rrnpt.NDArray[np.int_] | Nonerir% rkrlrmrnr'rorrprUr.rr7r<r:rtrt -9,@,@$/$5$5 6)66" 6$' <@ <<<9 <  <'<r<rtcveZdZdZej dejf ddZe d ddZ y) OrientedBoxAnnotatorz\ A class for drawing oriented bounding boxes on an image using provided detections. ruc@t||_||_||_yrwrxrzs r:rUzOrientedBoxAnnotator.__init__r{r<Nct|tjs|S|jt|jvr|Stj |jtj t}tt|D]`}||}t|j||| |jn|}tj||gd|j|j b|S)a Annotates the given scene with oriented bounding boxes based on the provided detections. Args: scene: The image where bounding boxes will be drawn. `ImageType` is a flexible type, accepting either `numpy.ndarray` or `PIL.Image.Image`. detections: Object detections to annotate. custom_color_lookup: Custom color lookup array. Allows to override the default color mapping strategy. Returns: The annotated image, matching the type of `scene` (`numpy.ndarray` or `PIL.Image.Image`) Example: ```python import cv2 import supervision as sv from ultralytics import YOLO image = cv2.imread("") model = YOLO("yolov8n-obb.pt") result = model(image)[0] detections = sv.Detections.from_ultralytics(result) oriented_box_annotator = sv.OrientedBoxAnnotator() annotated_frame = oriented_box_annotator.annotate( scene=image.copy(), detections=detections ) ``` r}r)r?rrdatararrayrrcrrZrr9rKr drawContoursrry)rSrr~r obb_boxesrobbr9s r:rzOrientedBoxAnnotator.annotate,sT%,L ?? "&>joo&ULHHZ__-EFGNNsS "3z?3 NMM*C!jj%+&."..( E   USE1ellndnn M N r<rr6rrr7r<r:rrrr<rc|j}|y|r(tj|jddtnd}t |t r|nd}tjtj|jD]}t||||j} |t|j|df} t|j|df} |j|} | j\} }| || | | z| | |zf| <||| | | z| | |zfxx| zcc<tj||t}| ||<|||z}|S)aEPaint each detection's mask into `canvas` in descending-area order. Smaller masks are drawn on top of larger ones. `CompactMask` detections are painted into their bounding-box crop only, avoiding a full `(H, W)` allocation per mask; dense masks fall back to full-frame boolean indexing. Args: canvas: BGR image array painted in place. Shape ``(H, W, 3)``. detections: Detections whose masks to paint. Returns immediately without modifying `canvas` when ``detections.mask`` is ``None``. color: Single color or palette used to resolve each detection's color. color_lookup: Strategy for mapping colors to detection indices. collect_union: When ``True``, allocate and return a ``(H, W)`` boolean array that accumulates the union of all painted masks (useful for callers like `HaloAnnotator` that need the combined mask footprint). When ``False`` (default), returns ``None``. Returns: A ``(H, W)`` boolean union array when ``collect_union=True``, otherwise ``None``. Nrudtyper}rrX)maskrzerosshaperer?rflipargsortarearrrcoffsetscropasarray)canvasr~r9rK collect_unionmasksunion compact_maskr color_bgrrrcrop_mcrop_hcrop_wrs r:_paint_masks_by_arearmsp8 OOE }2?bq!.T 'uk:5LJOO!<= !!'%  &(   #\))-*:; b2;&R&[(889VC9::eM2$?D$F4L  '( Lr<cveZdZdZej dejf ddZe d ddZ y) MaskAnnotatorz A class for drawing masks on an image using provided detections. !!! warning This annotator uses `sv.Detections.mask`. ?c@t||_||_||_yaC Args: color: The color or color palette to use for annotating detections. opacity: Opacity of the overlay mask. Must be between `0` and `1`. color_lookup: Strategy for mapping colors to annotations. Options are `INDEX`, `CLASS`, `TRACK`. N)r;r9opacityrKrSr9rrKs r:rUzMaskAnnotator.__init__s ,B%+H  )5r<NcVt|tjs|S|j|Stj|dtj }t |||j| |jn|tj||j|d|jz d||S)aV Annotates the given scene with masks based on the provided detections. Args: scene: The image where masks will be drawn. `ImageType` is a flexible type, accepting either `numpy.ndarray` or `PIL.Image.Image`. detections: Object detections to annotate. custom_color_lookup: Custom color lookup array. Allows to override the default color mapping strategy. Returns: The annotated image, matching the type of `scene` (`numpy.ndarray` or `PIL.Image.Image`) Examples: ```pycon >>> import numpy as np >>> import supervision as sv >>> image = np.zeros((100, 100, 3), dtype=np.uint8) >>> detections = sv.Detections( ... xyxy=np.array([[20, 20, 80, 80]]), ... mask=np.zeros((1, 100, 100), dtype=bool), ... class_id=np.array([0]) ... ) >>> mask_annotator = sv.MaskAnnotator() >>> annotated_frame = mask_annotator.annotate( ... scene=image.copy(), ... detections=detections ... ) ``` ![mask-annotator-example](https://media.roboflow.com/ supervision-annotator-examples/mask-annotator-example-purple.png) T)rYrrXrdst) r?rrrruint8rr9rKr addWeightedr)rSrr~r colored_masks r:rzMaskAnnotator.annotatesV%,L ?? "LxxDA    JJ!4!>> import numpy as np >>> import supervision as sv >>> image = np.zeros((100, 100, 3), dtype=np.uint8) >>> detections = sv.Detections( ... xyxy=np.array([[20, 20, 80, 80]]), ... class_id=np.array([0]) ... ) >>> polygon_annotator = sv.PolygonAnnotator() >>> annotated_frame = polygon_annotator.annotate( ... scene=image.copy(), ... detections=detections ... ) ``` ![polygon-annotator-example](https://media.roboflow.com/ supervision-annotator-examples/polygon-annotator-example-purple.png) r})r)rpolygonr9ry) r?rrrrrZrr9rKr"r(ry)rSrr~rrrr9rs r:rzPolygonAnnotator.annotatesT%,L ?? "L"3z?3 M??=1D!jj%+&."..( E,6 $#"nn   $ r<rr6rrr7r<r:rrs-9,@,@$/$5$5 6)66" 6$' <@ @@@9 @  @'@r<rcveZdZdZej dejf ddZe d ddZ y) ColorAnnotatorzN A class for drawing box masks on an image using provided detections. rc@t||_||_||_yr)r;r9rKrrs r:rUzColorAnnotator.__init__cs ,B%+H )5 r<Nct|tjs|S|j}t t |D]|}|j |jt\}}}} t|j||| |jn|} tj|||f|| f| jd~tj||j |d|j z d||S)a0 Annotates the given scene with box masks based on the provided detections. Args: scene: The image where bounding boxes will be drawn. `ImageType` is a flexible type, accepting either `numpy.ndarray` or `PIL.Image.Image`. detections: Object detections to annotate. custom_color_lookup: Custom color lookup array. Allows to override the default color mapping strategy. Returns: The annotated image, matching the type of `scene` (`numpy.ndarray` or `PIL.Image.Image`) Examples: ```pycon >>> import numpy as np >>> import supervision as sv >>> image = np.zeros((100, 100, 3), dtype=np.uint8) >>> detections = sv.Detections( ... xyxy=np.array([[20, 20, 80, 80]]), ... class_id=np.array([0]) ... ) >>> color_annotator = sv.ColorAnnotator() >>> annotated_frame = color_annotator.annotate( ... scene=image.copy(), ... detections=detections ... ) ``` ![box-mask-annotator-example](https://media.roboflow.com/ supervision-annotator-examples/box-mask-annotator-example-purple.png) r}rrXr)gammar)r?rrrYrrZrrrcrr9rKrrrrr) rSrr~rscene_with_boxesrrrrrr9s r:rzColorAnnotator.annotateusT%,L ::<"3z?3 M'__];BB3GNBB!jj%+&."..( E MM$HHlln   $  dllE1t||3C1RW  r<rr6rrr7r<r:rr^s -9,@,@$/$5$5 )" $' <@ AAA9 A  A'Ar<rc|eZdZdZej ddejf ddZe d d dZ y) HaloAnnotatorz A class for drawing Halos on an image using provided detections. !!! warning This annotator uses `sv.Detections.mask`. g?(cNt||_||_||_||_y)a Args: color: The color or color palette to use for annotating detections. opacity: Opacity of the overlay mask. Must be between `0` and `1`. kernel_size: The size of the average pooling kernel used for creating the halo. color_lookup: Strategy for mapping colors to annotations. Options are `INDEX`, `CLASS`, `TRACK`. N)r;r9rrK kernel_size)rSr9rrrKs r:rUzHaloAnnotator.__init__s(",B%+H  )5 +r<Nct|tjs|S|j|Stj|tj }t |||j| |jn|d}|Jtj||j|jf}gd||<tj|tj}|j}|dk(r|S|j|z|z }|ddddtj f} tj |d| z z||jzz} tj"|| |S)ab Annotates the given scene with halos based on the provided detections. Args: scene: The image where the halo effect will be applied. `ImageType` is a flexible type, accepting either `numpy.ndarray` or `PIL.Image.Image`. detections: Object detections to annotate. custom_color_lookup: Custom color lookup array. Allows to override the default color mapping strategy. Returns: The annotated image, matching the type of `scene` (`numpy.ndarray` or `PIL.Image.Image`) Examples: ```pycon >>> import numpy as np >>> import supervision as sv >>> image = np.zeros((100, 100, 3), dtype=np.uint8) >>> detections = sv.Detections( ... xyxy=np.array([[20, 20, 80, 80]]), ... mask=np.zeros((1, 100, 100), dtype=bool), ... class_id=np.array([0]) ... ) >>> halo_annotator = sv.HaloAnnotator() >>> annotated_frame = halo_annotator.annotate( ... scene=image.copy(), ... detections=detections ... ) ``` ![halo-annotator-example](https://media.roboflow.com/ supervision-annotator-examples/halo-annotator-example-purple.png) NrT)r)rrrrrX)r?rrr zeros_likerrr9rKrblurrcvtColorCOLOR_BGR2GRAYmaxrnewaxiscopyto) rSrr~rrfmaskgraygray_maxalpha alpha_mask blended_scenes r:rzHaloAnnotator.annotates,V%,L ?? "L}}U"((; $   JJ!4!>> import numpy as np >>> import supervision as sv >>> image = np.zeros((100, 100, 3), dtype=np.uint8) >>> detections = sv.Detections( ... xyxy=np.array([[20, 20, 80, 80]]), ... class_id=np.array([0]) ... ) >>> ellipse_annotator = sv.EllipseAnnotator() >>> annotated_frame = ellipse_annotator.annotate( ... scene=image.copy(), ... detections=detections ... ) ``` ![ellipse-annotator-example](https://media.roboflow.com/ supervision-annotator-examples/ellipse-annotator-example-purple.png) r}rugffffff?)centeraxesangle startAngleendAngler9rylineType)r?rrrrZrrrcrr9rKrellipserrrryLINE_4) rSrr~rrr_y1rrr9rwidths r:rzEllipseAnnotator.annotate=sT%,L"3z?3 M(oom<CCCHOBR!jj%+&."..( E27a-("-FGE KK%j#dUl"34++lln..  . r<) r9rbryrcrrcrrcrKrr6rrr7r<r:rr s -9,@,@$/$5$5 6)66 6  6 " 60' <@ BBB9 B  B'Br<rc|eZdZdZej ddejf ddZe d d dZ y) BoxCornerAnnotatorzP A class for drawing box corners on an image using provided detections. rWcNt||_||_||_||_y)aa Args: color: The color or color palette to use for annotating detections. thickness: Thickness of the corner lines. corner_length: Length of each corner line. color_lookup: Strategy for mapping colors to annotations. Options are `INDEX`, `CLASS`, `TRACK`. N)r;r9ry corner_lengthrK)rSr9ryrrKs r:rUzBoxCornerAnnotator.__init__s( ,B%+H '"/)5r<Nc t|tjs|Stt |D]}|j |j t\}}}}t|j||| |jn|} ||f||f||f||fg} | D]\} } | |k(r| |jzn| |jz } tj|| | f| | f| j|j| |k(r| |jzn| |jz }tj|| | f| |f| j|j|S)a9 Annotates the given scene with box corners based on the provided detections. Args: scene: The image where box corners will be drawn. `ImageType` is a flexible type, accepting either `numpy.ndarray` or `PIL.Image.Image`. detections: Object detections to annotate. custom_color_lookup: Custom color lookup array. Allows to override the default color mapping strategy. Returns: The annotated image, matching the type of `scene` (`numpy.ndarray` or `PIL.Image.Image`) Examples: ```pycon >>> import numpy as np >>> import supervision as sv >>> image = np.zeros((100, 100, 3), dtype=np.uint8) >>> detections = sv.Detections( ... xyxy=np.array([[20, 20, 80, 80]]), ... class_id=np.array([0]) ... ) >>> corner_annotator = sv.BoxCornerAnnotator() >>> annotated_frame = corner_annotator.annotate( ... scene=image.copy(), ... detections=detections ... ) ``` ![box-corner-annotator-example](https://media.roboflow.com/ supervision-annotator-examples/box-corner-annotator-example-purple.png) r}ry)r?rrrrZrrrcrr9rKrrlinerry)rSrr~rrrrrrr9cornersxyx_endy_ends r:rzBoxCornerAnnotator.annotatesPT%,L"3z?3 M'__];BB3GNBB!jj%+&."..( EBx"bB8b"X>G 123r'D...q4CUCU?UAq6E1:u||~34r'D...q4CUCU?UAq6Au:u||~  , r<)r9rbryrcrrcrKrr6rrr7r<r:rrs -9,@,@$/$5$5 6)66 6 " 6*' <@ AAA9 A  A'Ar<rcveZdZdZej dejf ddZe d ddZ y) CircleAnnotatorzK A class for drawing circle on an image using provided detections. ruc@t||_||_||_y)a) Args: color: The color or color palette to use for annotating detections. thickness: Thickness of the circle line. color_lookup: Strategy for mapping colors to annotations. Options are `INDEX`, `CLASS`, `TRACK`. Nrxrzs r:rUzCircleAnnotator.__init__s ,B%+H ')5r<Nct|tjs|Stt |D]}|j |j t\}}}}||zdz||zdzf} t|| dz dz|| dz dzz} t|j||| |jn|} tj|| t| | j|j|S)a+ Annotates the given scene with circles based on the provided detections. Args: scene: The image where box corners will be drawn. `ImageType` is a flexible type, accepting either `numpy.ndarray` or `PIL.Image.Image`. detections: Object detections to annotate. custom_color_lookup: Custom color lookup array. Allows to override the default color mapping strategy. Returns: The annotated image, matching the type of `scene` (`numpy.ndarray` or `PIL.Image.Image`) Examples: ```pycon >>> import numpy as np >>> import supervision as sv >>> image = np.zeros((100, 100, 3), dtype=np.uint8) >>> detections = sv.Detections( ... xyxy=np.array([[20, 20, 80, 80]]), ... class_id=np.array([0]) ... ) >>> circle_annotator = sv.CircleAnnotator() >>> annotated_frame = circle_annotator.annotate( ... scene=image.copy(), ... detections=detections ... ) ``` ![circle-annotator-example](https://media.roboflow.com/ supervision-annotator-examples/circle-annotator-example-purple.png) rurrXr}rrradiusr9ry)r?rrrrZrrrcrrr9rKrcirclerry) rSrr~rrrrrrrdistancer9s r:rzCircleAnnotator.annotatesV%,L"3z?3 M'__];BB3GNBBBw1nrBw1n5FR&)^1R&)^4IIJH!jj%+&."..( E JJ8}lln..   ( r<rr6rrr7r<r:rrs -9,@,@$/$5$5 6)66" 6&' <@ @@@9 @  @'@r<rceZdZdZej dejejde jf ddZ e d d dZy) DotAnnotatorzh A class for drawing dots on an image at specific coordinates based on provided detections. rWrc|t||_||_||_||_||_t||_y)aW Args: color: The color or color palette to use for annotating detections. radius: Radius of the drawn dots. position: The anchor position for placing the dot. color_lookup: Strategy for mapping colors to annotations. Options are `INDEX`, `CLASS`, `TRACK`. outline_thickness: Thickness of the outline of the dot. outline_color: The color or color palette to use for outline. It is activated by setting outline_thickness to a value greater than 0. N)r;r9r positionrKoutline_thickness outline_color)rSr9r rrKrrs r:rUzDotAnnotator.__init__Ds<,,B%+H ! "* )5!23I-3Xr<Ncvt|tjs|S|j|j}t t |D]}t|j||| |jn|}t||dft||dff}tj|||j|jd|jst|j ||| |jn|}tj|||j|j|j|S)a Annotates the given scene with dots based on the provided detections. Args: scene: The image where dots will be drawn. `ImageType` is a flexible type, accepting either `numpy.ndarray` or `PIL.Image.Image`. detections: Object detections to annotate. custom_color_lookup: Custom color lookup array. Allows to override the default color mapping strategy. Returns: The annotated image, matching the type of `scene` (`numpy.ndarray` or `PIL.Image.Image`) Examples: ```pycon >>> import numpy as np >>> import supervision as sv >>> image = np.zeros((100, 100, 3), dtype=np.uint8) >>> detections = sv.Detections( ... xyxy=np.array([[20, 20, 80, 80]]), ... class_id=np.array([0]) ... ) >>> dot_annotator = sv.DotAnnotator() >>> annotated_frame = dot_annotator.annotate( ... scene=image.copy(), ... detections=detections ... ) ``` ![dot-annotator-example](https://media.roboflow.com/ supervision-annotator-examples/dot-annotator-example-purple.png) anchorr}rrXr)r?rrget_anchors_coordinatesrrrZrr9rKrcrr r rrr) rSrr~rxyrr9rrs r:rzDotAnnotator.annotateas'T%,L  / /t}} / E"3z?3 M!jj%+&."..( E"]A-./R q8H5I1JKF JJufdkk5<<>2 F%% -,,)"/*2"&!2!2, !  KK!((*** + 8 r<) r9rbr rcrr,rKrrrcrrbr6r)rkrlrmrnr'ror,CENTERrrpr&BLACKrUr.rr7r<r:r r >s-9,@,@%__$/$5$5!"49KKY)YY Y " Y  Y2Y:' <@ HHH9 H  H'Hr<r c :eZdZdZej ejejddde jddddf dfd Z e d dd Z dd Z dd Ze dd ZxZS)LabelAnnotatorzN A class for annotating labels on an image using provided detections. rrXrHrIrFNc R||_||_t | ||||||| | |  y)a Args: color: The color or color palette to use for annotating the text background. color_lookup: Strategy for mapping colors to annotations. Options are `INDEX`, `CLASS`, `TRACK`. text_color: The color or color palette to use for the text. text_scale: Font scale for the text. text_thickness: Thickness of the text characters. text_padding: Padding around the text within its background box. text_position: Position of the text relative to the detection. Possible values are defined in the `Position` enum. text_offset: A tuple of 2D coordinates `(x, y)` to offset the text position from the anchor point, in pixels. border_radius: The radius to apply round edges. If the selected value is higher than the lower dimension, width or height, is clipped. smart_position: Spread out the labels to avoid overlapping. max_line_length: Maximum number of characters per line before wrapping the text. None means no wrapping. r9rKrLrMrTrOrPrQrRN) text_scaletext_thicknesssuperrU) rSr9rKrLrrrMrTrOrPrQrR __class__s r:rUzLabelAnnotator.__init__sBF",#1 %!%'#')+  r<cvt|tjs|St||t ||}|j ||}|j rP|ddddf}t|}||ddddf<|j|jd|jdf||}|j||||||S)a Annotates the given scene with labels based on the provided detections. Args: scene: The image where labels will be drawn. `ImageType` is a flexible type, accepting either `numpy.ndarray` or `PIL.Image.Image`. detections: Object detections to annotate. labels: Custom labels for each detection. custom_color_lookup: Custom color lookup array. Allows to override the default color mapping strategy. Returns: The annotated image, matching the type of `scene` (`numpy.ndarray` or `PIL.Image.Image`) Examples: ```pycon >>> import numpy as np >>> import supervision as sv >>> image = np.zeros((100, 100, 3), dtype=np.uint8) >>> detections = sv.Detections( ... xyxy=np.array([[20, 20, 80, 80]]), ... confidence=np.array([0.9]), ... class_id=np.array([0]), ... data={'class_name': np.array(['person'])} ... ) >>> labels = [ ... f"{class_name} {confidence:.2f}" ... for class_name, confidence ... in zip(detections['class_name'], detections.confidence) ... ] >>> label_annotator = sv.LabelAnnotator(text_position=sv.Position.CENTER) >>> annotated_frame = label_annotator.annotate( ... scene=image.copy(), ... detections=detections, ... labels=labels ... ) ``` ![label-annotator-example](https://media.roboflow.com/ supervision-annotator-examples/label-annotator-example-purple.png) NrWrXr)rr\r]r~r) r?rrrr_get_label_propertiesrQr!rar _draw_labels)rSrr~r\rr]rs r:rzLabelAnnotator.annotatesh%,L, V4484N4N 5    #ArrE*D#D)D&* QU ##;;QQ0    -! 3   r<cTg}|j|jjt}t ||D]3\}}|d|j dz|d|j dzf}t ||j}g}g} |D][} tj| t|j|jd\} } |j| | j| ]| r t| nd} t|t!|dz |j"zz}| d|j"zz}|d|j"zz}t%|||f|j}|jg||6t'j(|t&j*j-dd S) NrrrXtextfontFace fontScaleryrucenter_coordinatestext_whrrr)rrNrrcziprOrrRr getTextSizeCV2_FONTrrappendrsumrZrMrrrfloat32reshape)rSr~r\r]anchors_coordinateslabelr* wrapped_lines line_heights line_widthsrtext_wtext_h max_width total_height width_padded height_paddedtext_background_xyxys r:r"z$LabelAnnotator._get_label_properties5s 5?5W5W##6X6 &+ *-V5H)I)  %E%"1%(8(8(;;"1%(8(8(;;"  &eT-A-ABMLK% +#&??%"oo"11 $  $  ##F+""6* +-8K(QIL!S%6%:d>O>O$OO  %q4+<+<'<< 8 C,jj%!)    'oo%!) J&bq)005H  ' '&--/"00 ( &fSk43G3GHM  d&7&77I%! 8"%//!!)"&//"&"5"5 #  #KQ $*;*;!;;I!oo%"oo"11    F"!t'8'88"V+ (%"oo$++-"11 [[ Vd&7&777 C! 87< 8r<cn|\}}}}||z }||z } t|t|| dz}||z|f||z |ff|||zf|||z ffg} ||z||zf||z ||zf||z||z f||z ||z fg} | D]"} tj|| d| d|d$| D]} tj|| ||d|S)NrurrXrrr)minrrr )rrr9rPrrrrrheightrectangle_coordinatescircle_centers coordinatesrs r:r)z%LabelAnnotator.draw_rounded_rectangles5BBRbM3uf+=+BC = " %](:B'? @"}$ %B,>'? @!  - m!3 4 - m!3 4 - m!3 4 - m!3 4  1 K MMNN   % F JJ$    r<)r9rbrKrrLrbrrrrcrMrcrTr,rOrdrPrcrQrerRrfNN r Image.Imager~rr\zlist[str] | NonerrrirY)r~rr\rgrir) rrjr\rgr]rhr~rrrriNone) rrjrztuple[int, int, int, int]r9ztuple[int, int, int]rPrcrirj)rkrlrmrnr'rorrpr&rqr,rrrUr.rr"r# staticmethodr) __classcell__r s@r:rrs -9,@,@$/$5$516"*"3"3'-$&*/ )/ "/ / /  /  / /  / %/ / / $/ b' $(;? OOO! O 9 O  O'Ob4K4K4K 4KlP8$P8P82 P8  P8 9 P8 P8d'$'''$' '  ''r<rc 6eZdZdZej ejejddde jddddf d fd Z e d ddZ dd Z dd Ze dd ZxZS)RichLabelAnnotatorz A class for annotating labels on an image using provided detections, with support for Unicode characters by using a custom font. NrHrIrFc ||_||_|j|||_t |||||||| | |  y)a Args: color: The color or color palette to use for annotating the text background. color_lookup: Strategy for mapping colors to annotations. Options are `INDEX`, `CLASS`, `TRACK`. text_color: The color to use for the text. font_path: Path to the font file (e.g., ".ttf" or ".otf") to use for rendering text. If `None`, the default PIL font will be used. font_size: Font size for the text. text_padding: Padding around the text within its background box. text_position: Position of the text relative to the detection. Possible values are defined in the `Position` enum. text_offset: A tuple of 2D coordinates `(x, y)` to offset the text position from the anchor point, in pixels. border_radius: The radius to apply round edges. If the selected value is higher than the lower dimension, width or height, is clipped. smart_position: Spread out the labels to avoid overlapping. max_line_length: Maximum number of characters per line before wrapping the text. None means no wrapping. rN) font_path font_size _load_fontfontrrU) rSr9rKrLrarbrMrTrOrPrQrRr s r:rUzRichLabelAnnotator.__init__sSF#"OOIy9  %!%'#')+  r<ct|tjsJt||tj|}t ||}|j |||}|jrJ|ddddf}t|}||ddddf<|j|j|jf||}|j||||||S)a Annotates the given scene with labels based on the provided detections, with support for Unicode characters. Args: scene: The image where labels will be drawn. `ImageType` is a flexible type, accepting either `numpy.ndarray` or `PIL.Image.Image`. detections: Object detections to annotate. labels: Custom labels for each detection. custom_color_lookup: Custom color lookup array. Allows to override the default color mapping strategy. Returns: The annotated image, matching the type of `scene` (`numpy.ndarray` or `PIL.Image.Image`) Examples: ```pycon >>> import numpy as np >>> import supervision as sv >>> from PIL import Image >>> image = Image.fromarray(np.zeros((100, 100, 3), dtype=np.uint8)) >>> detections = sv.Detections( ... xyxy=np.array([[20, 20, 80, 80]]), ... confidence=np.array([0.9]), ... class_id=np.array([0]), ... data={'class_name': np.array(['person'])} ... ) >>> labels = [ ... f"{class_name} {confidence:.2f}" ... for class_name, confidence ... in zip(detections['class_name'], detections.confidence) ... ] >>> rich_label_annotator = sv.RichLabelAnnotator() >>> annotated_frame = rich_label_annotator.annotate( ... scene=image.copy(), ... detections=detections, ... labels=labels ... ) ``` NrW)drawr\r]r~r) r?r rr Drawrr"rQr!rarrSr#)rSrr~r\rrfr]rs r:rzRichLabelAnnotator.annotate sf%---,~~e$ V4484N4N *f5    #ArrE*D#D)D&* QU ##;;ell+    -! 3   r<c|g}|j|jjt}t ||D]E\}}|d|j dz|d|j dzf}t ||j}d} d} |D]@} |jd| |j\} } }}|| z }|| z }t| |} | |z } Bt|dkDr| t|dz |jzz } t| d|jzz}t| d|jzz}t|||f|j}|jdd |j\}}}}|jg|||Htj |tj" j%d d }|S) NrrrXrrIrdrur)rErr)rrNrrcr-rOrrRtextbboxrdrrZrMrr0rrr2r3)rSrfr~r\r]anchor_coordinatesr5r*r6r;r<rlefttoprightbottom line_width line_heightr=r>r? text_lefttext_toprEresults r:r"z(RichLabelAnnotator._get_label_propertiesqs4>4V4V##5W5 &+ *-V5G)H$ R %E%"1%(8(8(;;"1%(8(8(;;"  &eT-A-ABMIL% ,+/==DII=+V(c5&"T\ $sl  :6  +  ,=!A%]!3a!74;L;L LL y1t/@/@+@@AL q43D3D/D DEM#?#5%}5))$ )- fd (S %IxA  # #$P&:$PI$Px$P QI$ RL+-(( BJJ+ '"a.  r<c pt|t|cxk(rt|k(s.nJdt|dt|dt|d||n |j}t|D]C\}}t|j|||} t|j |||} |ddj t} |d} |d} |jt| |j| jdt|||j}| d |jz| z }| d |jz| z }|D]k}|j||f||j | j |j#d ||j \}}}}||z }|||jzz }mFy)NrArBrCrDr}rWr,)r filloutlinerrX)rr&rdrwrIri)rZrKrGrr9rLrrcrounded_rectangletuplerPas_rgbrrRrMr&rdrk)rSrfr\r]r~rrKrJrKrLrLrMrsrtr6 x_position y_positionr_leftrn_rightrprrs r:r#zRichLabelAnnotator._draw_labelss6{c"23Fs:F *3/?+@*AB6{m#5c*o5FG  F#. ""  $--=#>* > C,jj%!)    'oo%!) J&bq)005H&q)I%a(H  " "h))%,,. # &fSk43G3GHM!!t'8'889DJ!!t'8'888CJ% > "J/#**, .2]]64dii]-X*sFF$sl kD,=,===  >?* >r<c dd}|||S tj||S#t$r!tj d|||cYSwxYw)Nct tj|S#t$rtjcYSwxYwr6)r load_default TypeError)sizes r:load_default_fontz8RichLabelAnnotator._load_font..load_default_fonts6 0 --d33 0 --// 0s 77z3Font path '%s' not found. Using PIL's default font.)rrcri,ImageFont.FreeTypeFont | ImageFont.ImageFont)r truetypeOSErrorloggerwarning)rbrars r:rczRichLabelAnnotator._load_fontso 0 0 9 0  $Y/ / 0%%i; ; 0 NNEy %Y/ /  0s*'AA)r9rbrKrrLrbra str | NonerbrcrMrcrTr,rOrdrPrcrQrerRrfrWrX)rfImageDraw.ImageDrawr~rr\rgrir) rfrr\rgr]rhr~rrrrirZ)rbrcrarrir)rkrlrmrnr'rorrpr&rqr,rrrUr/rr"r#r[rcr\r]s@r:r_r_s-9,@,@$/$5$516 $"*"3"3'-$&*0 )0 "0 / 0  0  0 0  0 %0 0 0 $0 d' $(;? NNN! N 9 N  N'N`2'25?2IR2 2h=>!=>=>2 =>  => 9 => =>~00#-0 500r<r_cteZdZdZdej df ddZe d d dZe d dZ y) IconAnnotatorzM A class for drawing an icon on an image, using provided detections. )@rrIc.||_||_||_y)a\ Args: icon_resolution_wh: The size of drawn icons. All icons will be resized to this resolution, keeping the aspect ratio. icon_position: The position of the icon. offset_xy: The offset to apply to the icon position, in pixels. Can be both positive and negative. N)icon_resolution_whr offset_xy)rSr icon_positionrs r:rUzIconAnnotator.__init__s#5% "r<ct|tjs|St|tr;t |t |k7r$t dt |dt |d|j |jjt}tt |D]}t|tr|n||}|dk(r |j|}|jdd\}} t||df| dz z |jdz} t||d f|dz z |jd z} t||| | f|dd|S) a# Annotates the given scene with given icons. Args: scene: The image where labels will be drawn. `ImageType` is a flexible type, accepting either `numpy.ndarray` or `PIL.Image.Image`. detections: Object detections to annotate. icon_path: The path to the PNG image to use as an icon. Must be a single path or a list of paths, one for each detection. Pass an empty string `""` to draw nothing. Returns: The annotated image, matching the type of `scene` (`numpy.ndarray` or `PIL.Image.Image`) Example: ```python import supervision as sv image = ... detections = sv.Detections(...) available_icons = ["roboflow.png", "lenny.png"] icon_paths = [np.random.choice(available_icons) for _ in detections] icon_annotator = sv.IconAnnotator() annotated_frame = icon_annotator.annotate( scene=image.copy(), detections=detections, icon_path=icon_paths ) ``` ![icon-annotator-example](https://media.roboflow.com/ supervision-annotator-examples/icon-annotator-example.png) z#The number of icon paths provided (z+) does not match the number of detections (z?). Either provide a single icon path or one for each detection.rNrurrX)r?rrlistrZ ValueErrorrrrrcrr@ _load_iconrrr2) rSrr~ icon_pathrr current_pathiconicon_hicon_wrrs r:rzIconAnnotator.annotatesbX%,L i &3y>S_+L5c)n5EF--0_,=>89  %/$F$F==%G% &+ #3z?3 :M' 37 Y}=U r!??<0D!ZZ^NFFB}a'(6A:5q8IIJAB}a'(6A:5q8IIJA$UD1a&9E!H : r<ctj|tj}|td|t t j tjt||j}|S)Nz)Error: Couldn't load the icon image from )imager[) rimreadIMREAD_UNCHANGEDFileNotFoundErrorrnptNDArrayrrr1r)rSrrs r:rzIconAnnotator._load_icon[sgzz)S%9%9: <#;I;G  KK ! $d6M6M N  r<N)rrdrr,rrd)r)rr%r~rrzstr | list[str]rir%)rr@rirj) rkrlrmrnr, TOP_CENTERrUr.rrrr7r<r:rrs /7"*"5"5%+ #+# ## #$' &( EEE# E  E'EN  r<rc8eZdZdZdddZe ddZy) BlurAnnotatorzM A class for blurring regions in an image using provided detections. Nc>||dkrtd|d||_y)a Args: kernel_size: The size of the average pooling kernel used for blurring. If not set, a dynamic size is computed as one-third of the shorter bounding-box dimension. Must be >= 1 when provided. NrXzkernel_size must be >= 1, got .)rr)rSrs r:rUzBlurAnnotator.__init__ns-  "{Q=k]!LM M'2r<ct|tjs|S|jdd\}}t |j ||fj t}|D]f\}}}} ||ks| |kr||| ||f} |j |jn t|||| } tj| | | f} | ||| ||f<h|S)a Annotates the given scene by blurring regions based on the provided detections. Args: scene: The image where blurring will be applied. `ImageType` is a flexible type, accepting either `numpy.ndarray` or `PIL.Image.Image`. detections: Object detections to annotate. Returns: The annotated image, matching the type of `scene` (`numpy.ndarray` or `PIL.Image.Image`) Examples: ```pycon >>> import numpy as np >>> import supervision as sv >>> image = np.zeros((100, 100, 3), dtype=np.uint8) >>> detections = sv.Detections( ... xyxy=np.array([[20, 20, 80, 80]]), ... class_id=np.array([0]) ... ) >>> blur_annotator = sv.BlurAnnotator() >>> annotated_frame = blur_annotator.annotate( ... scene=image.copy(), ... detections=detections ... ) ``` ![blur-annotator-example](https://media.roboflow.com/ supervision-annotator-examples/blur-annotator-example-purple.png) Nrurr[) r?rrrr rrrcrrrr) rSrr~ image_height image_width clipped_xyxyrrrrroirs r:rzBlurAnnotator.annotateysN%,L$)KKO! k.8l0K/ &+ + &NBBRx282r"u %C##/  22r2rB  ((3k :;C"%E"R%B,  & r<r6)rrfrr%r~rrir%rkrlrmrnrUr.rr7r<r:rris< 3'999  9'9r<rceZdZdZej ejdddejf ddZ e d d dZ y) TraceAnnotatora A class for drawing trace paths on an image based on detection coordinates. !!! warning This annotator uses the `sv.Detections.tracker_id`. Read [here](/latest/trackers/) to learn how to plug tracking into your inference pipeline. ruFcrt||_t|||_||_||_||_y)a) Args: color: The color to draw the trace, can be a single color or a color palette. position: The position of the trace. Defaults to `CENTER`. trace_length: The maximum length of the trace in terms of historical points. Defaults to `30`. thickness: The thickness of the trace lines. Defaults to `2`. smooth: If `True`, applies spline smoothing to trace lines using consecutive unique anchor points. Falls back to a raw polyline when fewer than 4 unique points are available (e.g. when a tracker is stationary). color_lookup: Strategy for mapping colors to annotations. Options are `INDEX`, `CLASS`, `TRACK`. )max_sizerN)r;r9rtracerysmoothrK)rSr9r trace_lengthryrrKs r:rUzTraceAnnotator.__init__s52,B%+H LB " )5r<Nc t|tjs|S|j t d||jt k7}|j j|tt|D]}|j|}|t|}t|j||| |jn|}|j j|} | jtj } |j"r| tj$dgtj&tj(| ddk7df} t| d kDr{ | dddf| dddf} } t+| | gd \}}t-tj.ddd |}tj0|djtj } n| jtj } t| dkDst3j4|| gd |j7|j8|S#t$r"| jtj } YrwxYw)a Draws trace paths on the frame based on the detection coordinates provided. Args: scene: The image on which the traces will be drawn. `ImageType` is a flexible type, accepting either `numpy.ndarray` or `PIL.Image.Image`. detections: The detections which include coordinates for which the traces will be drawn. custom_color_lookup: Custom color lookup array. Allows to override the default color mapping strategy. Returns: The annotated image, matching the type of `scene` (`numpy.ndarray` or `PIL.Image.Image`) Example: ```python import supervision as sv from ultralytics import YOLO model = YOLO('yolov8x.pt') trace_annotator = sv.TraceAnnotator() video_info = sv.VideoInfo.from_video_path(video_path='...') frames_generator = sv.get_video_frames_generator(source_path='...') tracker = sv.ByteTrack() with sv.VideoSink(target_path='...', video_info=video_info) as sink: for frame in frames_generator: result = model(frame)[0] detections = sv.Detections.from_ultralytics(result) detections = tracker.update_with_detections(detections) annotated_frame = trace_annotator.annotate( scene=frame.copy(), detections=detections) sink.write_frame(frame=annotated_frame) ``` ![trace-annotator-example](https://media.roboflow.com/ supervision-annotator-examples/trace-annotator-example-purple.png) NzThe `tracker_id` field is missing in the provided detections. See more: https://supervision.roboflow.com/latest/how_to/track_objectsr}) tracker_idTr)axisrX)sdF)r9ry)r?rrrrrrputrrZrcrr9rKgetrint32r concatenateanydiffrrlinspacestackr polylinesrry)rSrr~rfiltered_detectionsrtracker_id_valrr9r spline_points unique_xyrrtck_uxy_news r:rzTraceAnnotator.annotates'b%,L  (Z +5  ! !%5 5+  *+"3':#;<& M0;;MJN%^,J!jj.+&."..( E:6B3599RXX3FM{{NNTFBFF2772A3F!3KRS,T#UV y>A%C(A !Q$1")1a&B"7R!&r{{1a'=s!C(*a(@(G(G(Q %.$4$4RXX$>M2w{ "O,,."nn A& N &C(1(8(8(B CsA9I(I+*I+) r9rbrr,rrcryrcrrerKrr6r) rkrlrmrnr'ror,rrrprUr.rr7r<r:rrs-9,@,@%__$/$5$56)66 6  6  6"6>' <@ ccc9 c  c'cr<rcbeZdZdZej dddddf d dZed dZy ) HeatMapAnnotatorz A class for drawing heatmaps on an image based on provided detections. Heat accumulates over time and is drawn as a semi-transparent overlay of blurred circles. g?rr}cf||_||_||_||_||_||_d|_y)a Args: position: The position of the heatmap. Defaults to `BOTTOM_CENTER`. opacity: Opacity of the overlay mask. Must be between `0` and `1`. radius: Radius of the heat circle. kernel_size: Kernel size for blurring the heatmap. Pass `None` to disable blurring entirely. top_hue: Hue at the top of the heatmap. Defaults to 0 (red). low_hue: Hue at the bottom of the heatmap. Defaults to 125 (blue). N)rrr rtop_huelow_hue heat_mask)rSrrr rrrs r:rUzHeatMapAnnotator.__init__Ns6(!   &  9=r<ct|tjs|S|j7tj|j ddtj |_tj|j dd}|j|jD]D}t|dt|d}}tj|||f|jddF||jz|_|jj}|j}|dkDr,|j||z |j|j z zz }|j#tj$}|j&,tj(||j&|j&f}tj*|j d tj$} || d <tj,| tj.}tj,|jj#tj$tj0dkD}tj2||j4|d|j4z d|||<|S) aX Annotates the scene with a heatmap based on the provided detections. Args: scene: The image where the heatmap will be drawn. `ImageType` is a flexible type, accepting either `numpy.ndarray` or `PIL.Image.Image`. detections: Object detections to annotate. Returns: The annotated image, matching the type of `scene` (`numpy.ndarray` or `PIL.Image.Image`) Note: When `detections` is empty or no heat has accumulated yet, the scene is returned unchanged without raising a ``RuntimeWarning``. Example: ```python import supervision as sv from ultralytics import YOLO model = YOLO('yolov8x.pt') heat_map_annotator = sv.HeatMapAnnotator() video_info = sv.VideoInfo.from_video_path(video_path='...') frames_generator = sv.get_video_frames_generator(source_path='...') with sv.VideoSink(target_path='...', video_info=video_info) as sink: for frame in frames_generator: result = model(frame)[0] detections = sv.Detections.from_ultralytics(result) annotated_frame = heat_map_annotator.annotate( scene=frame.copy(), detections=detections) sink.write_frame(frame=annotated_frame) ``` ![heatmap-annotator-example](https://media.roboflow.com/ supervision-annotator-examples/heat-map-annotator-example-purple.png) NrurrrX)rXrr).r)r?rrrrrr2rrrcrr r rYrrrrrrrfullr COLOR_HSV2BGRCOLOR_GRAY2BGRrr) rSrr~rrrrtempmax_valhsvs r:rzHeatMapAnnotator.annotatejsX%,L >> !XXekk"1oRZZHDNxx BQ(44T]]C Br!u:s2a5zqA JJ1v{{   .~~""$((* Q;<<$.DLL4<<4O"PPD{{288$    '88D4#3#3T5E5E"FGDggekk3bhh7F ||C!2!23||DNN11"((;S=O=OPSTToodDLL%T\\AQSTU  d  r<N) rr,rrr rcrrfrrcrrcr) rkrlrmrnr, BOTTOM_CENTERrUr.rr7r<r:rrGsv&33"$>>> >  >  >>8'I'Ir<rc8eZdZdZdddZe ddZy)PixelateAnnotatorzO A class for pixelating regions in an image using provided detections. Nc>||dkrtd|d||_y)a Args: pixel_size: The size of the pixelation. If not set, a dynamic size is computed as one-half of the shorter bounding-box dimension. When set and the detection area is smaller than `pixel_size`, the region is filled with its average colour instead to avoid an OpenCV crash. Must be >= 1 when provided. NrXzpixel_size must be >= 1, got r)r pixel_size)rSrs r:rUzPixelateAnnotator.__init__s,  !j1nL*-((3- *FE"R%B,'JJtJ1z>M"jj!yy|SYYq\2!//O #2E"R%B, 7 2: r<r6)rrfrrr7r<r:rrsA 1'HHH  H'Hr<rceZdZdZej ddejejde jf ddZ e d d dZy) TriangleAnnotatorzt A class for drawing triangle markers on an image at specific coordinates based on provided detections. rHrct||_||_||_||_||_||_t||_y)a Args: color: The color or color palette to use for annotating detections. base: The base width of the triangle. height: The height of the triangle. position: The anchor position for placing the triangle. color_lookup: Strategy for mapping colors to annotations. Options are `INDEX`, `CLASS`, `TRACK`. outline_thickness: Thickness of the outline of the triangle. outline_color: The color or color palette to use for outline. It is activated by setting outline_thickness to a value greater than 0. N)r;r9baserSrrKrr)rSr9rrSrrKrrs r:rUzTriangleAnnotator.__init__ sC0,B%+H  ! "* )5&73I-3Xr<Nc"t|tjs|S|j|j}t t |D]>}t|j||| |jn|}t||dft||df}}tj||jdzz ||jz g||jdzz||jz g||ggtj} tj || g|j#|j$st|j&||| |jn|} tj(|| gd| j#|j$A|S)a- Annotates the given scene with triangles based on the provided detections. Args: scene: The image where triangles will be drawn. `ImageType` is a flexible type, accepting either `numpy.ndarray` or `PIL.Image.Image`. detections: Object detections to annotate. custom_color_lookup: Custom color lookup array. Allows to override the default color mapping strategy. Returns: The annotated image, matching the type of `scene` (`numpy.ndarray` or `PIL.Image.Image`) Examples: ```pycon >>> import numpy as np >>> import supervision as sv >>> image = np.zeros((100, 100, 3), dtype=np.uint8) >>> detections = sv.Detections( ... xyxy=np.array([[20, 20, 80, 80]]), ... class_id=np.array([0]) ... ) >>> triangle_annotator = sv.TriangleAnnotator() >>> annotated_frame = triangle_annotator.annotate( ... scene=image.copy(), ... detections=detections ... ) ``` ![triangle-annotator-example](https://media.roboflow.com/ supervision-annotator-examples/triangle-annotator-example.png) rr}rrXruTr)r?rrrrrrZrr9rKrcrrrSrrfillPolyrrrr) rSrr~rrrr9tip_xtip_yverticesrs r:rzTriangleAnnotator.annotate; sT%,L  / /t}} / E"3z?3# M!jj%+&."..( Er-"234c"]A=M:N6O5ExxTYY!^+UT[[-@ATYY!^+UT[[-@AEN  H LL ELLN ;%% -,,)"/*2"&!2!2, !  J!((*"44 ;# H r<)r9rbrrcrSrcrr,rKrrrcrrbr6r)rkrlrmrnr'ror,rrrpr&rrUr.rr7r<r:rr s-9,@,@%00$/$5$5!"49KKY)YY Y  Y " YY2Y@' <@ PPP9 P  P'Pr<rc|eZdZdZej dejdf ddZe d d dZ y) RoundBoxAnnotatorzh A class for drawing bounding boxes with round edges on an image using provided detections. rug333333?ct||_||_||_d|cxkrdkst dt d||_y)a+ Args: color: The color or color palette to use for annotating detections. thickness: Thickness of the bounding box lines. color_lookup: Strategy for mapping colors to annotations. Options are `INDEX`, `CLASS`, `TRACK`. roundness: Percent of roundness for edges of bounding box. Value must be float 0 < roundness <= 1.0 By default roundness percent is calculated based on smaller side length (width or height). r?z2roundness attribute must be float between (0, 1.0]N)r;r9ryrKr roundness)rSr9ryrKrs r:rUzRoundBoxAnnotator.__init__ sQ&,B%+H ')59##QR R$QR R )r<Nc t|tjs|Stt |D]}|j |j t\}}}}t|j||| |jn|} t||z t||z krt||z dz|jznt||z dz|jz} || z|| zf|| z || zf|| z || z f|| z|| z fg} || z|f|| z |ff||| zf||| z ff|| z|f|| z |ff||| zf||| z ffg} d} d}t| | | |D]v\}}}}tj||| | fd||| j!|j"tj$||d|d| j!|j"x|S) ae Annotates the given scene with bounding boxes with rounded edges based on the provided detections. Args: scene: The image where rounded bounding boxes will be drawn. `ImageType` is a flexible type, accepting either `numpy.ndarray` or `PIL.Image.Image`. detections: Object detections to annotate. custom_color_lookup: Custom color lookup array. Allows to override the default color mapping strategy. Returns: The annotated image, matching the type of `scene` (`numpy.ndarray` or `PIL.Image.Image`) Examples: ```pycon >>> import numpy as np >>> import supervision as sv >>> image = np.zeros((100, 100, 3), dtype=np.uint8) >>> detections = sv.Detections( ... xyxy=np.array([[20, 20, 80, 80]]), ... class_id=np.array([0]) ... ) >>> round_box_annotator = sv.RoundBoxAnnotator() >>> annotated_frame = round_box_annotator.annotate( ... scene=image.copy(), ... detections=detections ... ) ``` ![round-box-annotator-example](https://media.roboflow.com/ supervision-annotator-examples/round-box-annotator-example-purple.png) r}ru)rZ)rihrrr)rrrrrrr9ryrXr)r?rrrrZrrrcrr9rKabsrr-rrrryr)rSrr~rrrrrrr9r circle_coordinatesline_coordinates start_angles end_anglesr*rrrs r:rzRoundBoxAnnotator.annotate s-V%,L"3z?36 M'__];BB3GNBB!jj%+&."..( ErBw<#b2g,.R"WNT^^34"r'a$..89 v+f.v+f.v+f.v+f. " v+r"R&["$56b6k"Rf$56v+r"R&["$56b6k"Rf$56   -L,JDG"$4lJE @"D+y - &)*&,,."nn QQ,,."nn  E6 p r<)r9rbryrcrKrrrr6rrr7r<r:rr s-9,@,@$/$5$5 *)**" *  *4' <@ ddd9 d  d'dr<rcJeZdZdZddej ejeje jdf d dZ e d ddZe ddZe ddZeeej&d d  dd Zy)PercentageBarAnnotatorzT A class for drawing percentage bars on an image using provided detections. PNc||_||_t||_t||_||_||_|||_ytd|jz|_y)a5 Args: height: The height in pixels of the percentage bar. width: The width in pixels of the percentage bar. color: The color or color palette to use for annotating detections. border_color: The color of the border lines. position: The anchor position of drawing the percentage bar. color_lookup: Strategy for mapping colors to annotations. Options are `INDEX`, `CLASS`, `TRACK`. border_thickness: The thickness of the border lines. Ng333333?) rSrr;r9 border_colorrrKrcborder_thickness)rSrSrr9rrrKrs r:rUzPercentageBarAnnotator.__init__ sj,"  +A%+H #9,#G"* )5 +  TDKK'( r<c Ft|tjs|S|j|||j |j }t t|D]=}||}|jt|dt|df|j|jf|j }|dd|ddz } |||} n|jJ|j|} t|j||| |jn|} t!j"||d|ddt| | zz|ddf| j%dt!j"||d|d|j&j%|j(@|S) aR Annotates the given scene with percentage bars based on the provided detections. The percentage bars visually represent the confidence or custom values associated with each detection. Args: scene: The image where percentage bars will be drawn. `ImageType` is a flexible type, accepting either `numpy.ndarray` or `PIL.Image.Image`. detections: Object detections to annotate. custom_color_lookup: Custom color lookup array. Allows to override the default color mapping strategy. custom_values: Custom values array to use instead of the default detection confidences. This array should have the same length as the number of detections and contain a value between 0 and 1 (inclusive) for each detection, representing the percentage to be displayed. Returns: The annotated image, matching the type of `scene` (`numpy.ndarray` or `PIL.Image.Image`) Examples: ```pycon >>> import numpy as np >>> import supervision as sv >>> image = np.zeros((100, 100, 3), dtype=np.uint8) >>> detections = sv.Detections( ... xyxy=np.array([[20, 20, 80, 80]]), ... confidence=np.array([0.9]), ... class_id=np.array([0]) ... ) >>> percentage_bar_annotator = sv.PercentageBarAnnotator() >>> annotated_frame = percentage_bar_annotator.annotate( ... scene=image.copy(), ... detections=detections ... ) ``` ![percentage-bar-example](https://media.roboflow.com/ supervision-annotator-examples/percentage-bar-annotator-example-purple.png)  custom_valuesr~rrrX) anchor_xy border_whrr}rr)r?rr_validate_custom_valuesrrrrZcalculate_border_coordinatesrcrrS confidencerr9rKrrrrr) rSrr~rranchorsrrborder_coordinates border_widthvaluer9s r:rzPercentageBarAnnotator.annotate? sf%,L $$=Z$X44DMM4J"3z?3' M]+F!%!B!Bvay>3vay>:::t{{3"C"  .a036H6KA6NNL(%m4!,,888"--m<!jj%+&."..( E MM&q)&q)!,s<%3G/HH&q)!,lln  MM&q)&q)''..0//  C' P r<c|\}}|\}}|tjk(r||z ||z f||ffS|tjk(r||dzz |f||dzz||z ffS|tjk(r||f||z||z ffS|tjk(r||z ||dzz f|||dzzffS|tj k(s|tj k(r ||dzz ||dzz f||dzz||dzzffS|tjk(r|||dzz f||z||dzzffS|tjk(r||z |f|||zffS|tjk(r||dzz |f||dzz||zffS|tjk(r||f||z||zffSyNru r,rrr TOP_RIGHT CENTER_LEFTrCENTER_OF_MASS CENTER_RIGHT BOTTOM_LEFTr BOTTOM_RIGHT)rrrcxcyrrSs r:rz3PercentageBarAnnotator.calculate_border_coordinates sB! v x(( (JV ,r2h6 6 ,, ,!OR(2 ?BK*HH H ++ +8b5j"v+66 6 -- -JVq[ 01BVq[8H3II I  (H8O8O,Oeqj"v{"23eqj"v{"23 .. .Vq[()BJVq[8H+II I -- -J#b"v+%66 6 // /!OR(2 ?BK*HH H .. .8b5j"v+66 6/r<c ||j tdyt|tjt fs t dt|t|k7r tdtd|Ds tdy)NzThe provided detections do not contain confidence values. Please provide `custom_values` or ensure that the detections contain confidence values (e.g. by using a different model).z?custom_values must be either a numpy array or a list of floats.z@The length of custom_values must match the number of detections.c3<K|]}d|cxkxrdkncyw)rrXNr7).0rs r: zAPercentageBarAnnotator._validate_custom_values.. sB5qEQBsz4All values in custom_values must be between 0 and 1.) rrr?rrrrrZallrs r:rz.PercentageBarAnnotator._validate_custom_values s  $$, S-mbjj$-?@U=!S_4 VBMBB !WXXCr<z0.29.0z0.32.0)target deprecated_in remove_inct||yr6)r rs r:validate_custom_valuesz-PercentageBarAnnotator.validate_custom_values s ]J'r<)rSrcrrcr9rbr Color | strrr,rKrrrfrW) rr%r~rrrrznpt.NDArray[np.float64] | Nonerir%)rrdrrdrr,ri'tuple[tuple[int, int], tuple[int, int]])rz,npt.NDArray[np.float64] | list[float] | Noner~rrirZ)rkrlrmrnr'ror&rr,rrrprUr.rr[rrr __func__r1r7r<r:r r  s ,8,@,@$)KK%00$/$5$5'+! ! ! * ! " !  ! "! %! F' <@8< ___9 _ 6 _  _'_B7"7/>7JR7 0778YCYY YY4&// (C(( (  (r<r ceZdZdZej dejdejf ddZ e d d dZ e d dZy) CropAnnotatorzI A class for drawing scaled up crops of detections on the scene. g@ruc\||_||_t||_||_||_y)a Args: position: The anchor position for placing the cropped and scaled part of the detection in the scene. scale_factor: The factor by which to scale the cropped image part. A factor of 2, for example, would double the size of the cropped area, allowing for a closer view of the detection. border_color: The color or color palette to use for annotating border around the cropped area. border_thickness: The thickness of the border around the cropped area. border_color_lookup: Strategy for mapping colors to annotations. Options are `INDEX`, `CLASS`, `TRACK`. N)r scale_factorr;rrborder_color_lookup)rSrr8rrr9s r:rUzCropAnnotator.__init__ s0*#+ #/2H2V%50C r<Nc t|tjs|S|jj t Dcgc]}t ||}}|Dcgc]}t||j}}|j|jj t }tt||D]\} \} } | jd| jdf} |j| | |j\\} }\}}t|| | |f}t!|j"|| | |j$n|}t'j(|| |f||f|j+|j, |Scc}wcc}w) a Annotates the provided scene with scaled and cropped parts of the image based on the provided detections. Each detection is cropped from the original scene and scaled according to the annotator's scale factor before being placed back onto the scene at the specified position. Args: scene: The image where cropped detection will be placed. `ImageType` is a flexible type, accepting either `numpy.ndarray` or `PIL.Image.Image`. detections: Object detections to annotate. custom_color_lookup: Custom color lookup array. Allows to override the default color mapping strategy. Returns: The annotated image. Examples: ```pycon >>> import numpy as np >>> import supervision as sv >>> image = np.zeros((100, 100, 3), dtype=np.uint8) >>> detections = sv.Detections( ... xyxy=np.array([[20, 20, 80, 80]]), ... class_id=np.array([0]) ... ) >>> crop_annotator = sv.CropAnnotator() >>> annotated_frame = crop_annotator.annotate( ... scene=image.copy(), ... detections=detections ... ) ``` ![crop-annotator-example](https://media.roboflow.com/ supervision-annotator-examples/crop-annotator-example.png) )rr)rr8rrXr)rcrop_whr)roverlayrr}r)r?rrrrrcr0r3r8rrrGr-rcalculate_crop_coordinatesr2rrr9rrrr)rSrr~rrcropsr resized_cropsrrJ resized_croprr;rrrrr9s r:rzCropAnnotator.annotate sZ%,L;E??;Q;QRU;V 37JU .  QV HLKd1B1B C  *4)K)K==*L* &+ ,5S5P+Q  'C',"((+\-?-?-BBG!%!@!@w"A" HRhr2"|RQSHUE!''%!&."55( E MMHHlln//   , A  s E;Fc|\}}|\}}|tjk(r||z ||z f||ffS|tjk(r||dzz ||z f||dzz|ffS|tjk(r|||z f||z|ffS|tjk(r||z ||dzz f|||dzzffS|tj k(s|tj k(r ||dzz ||dzz f||dzz||dzzffS|tjk(r|||dzz f||z||dzzffS|tjk(r||z |f|||zffS|tjk(r||dzz |f||dzz||zffS|tjk(r||f||z||zffSyrr)rr;ranchor_xanchor_yrrSs r:r=z(CropAnnotator.calculate_crop_coordinatesW s-$( v x(( (u$h&788X:NN N ,, ,EQJ&6(9:EQJ&1 ++ +h/08e3CX2NN N -- -E!8fk#9:8fk12  (H8O8O,OEQJ&6Q;(>?EQJ&6Q;(>? .. .8fk12E!8fk#9: -- -u$h/(Hv|jjtD]\}}}}|||||f|||||f<n4|jD]%}tj|t } || || <'tj"|||S)a Applies a colored overlay to the scene outside of the detected regions. Args: scene: The image where masks will be drawn. `ImageType` is a flexible type, accepting either `numpy.ndarray` or `PIL.Image.Image`. detections: Object detections to annotate. Returns: The annotated image, matching the type of `scene` (`numpy.ndarray` or `PIL.Image.Image`) Examples: ```pycon >>> import numpy as np >>> import supervision as sv >>> image = np.zeros((100, 100, 3), dtype=np.uint8) >>> detections = sv.Detections( ... xyxy=np.array([[20, 20, 80, 80]]), ... class_id=np.array([0]) ... ) >>> background_overlay_annotator = sv.BackgroundOverlayAnnotator() >>> annotated_frame = background_overlay_annotator.annotate( ... scene=image.copy(), ... detections=detections ... ) ``` ![background-overlay-annotator-example](https://media.roboflow.com/ supervision-annotator-examples/background-color-annotator-example-purple.png) rrXrr)r?rr full_liker9rrrrrrrGrrrcrrer) rSrr~rrrrrr mask_bools r:rz#BackgroundOverlayAnnotator.annotate s F%,L||E4::+<+<+>bhhO   1t||#\4<<   ?? "dnn",//"8"8"= ABB-22b5"R%<-@ RUBrE\* A# ;JJt48 */ *: Y' ; %& r<N)r9r&rrrGrer) rkrlrmrnr&rrUr.rr7r<r:rErE sK  {{ ### #"'3'3r<rEc0eZdZdZej ej ejfdddddd ddZe ddZ e ddZ e dd Z e dd Ze dd Ze dd Zdd Zy)ComparisonAnnotatoraH Highlights the differences between two sets of detections. Useful for comparing results from two different models, or the difference between a ground truth and a prediction. If present, uses the oriented bounding box data. Otherwise, if present, uses a mask. Otherwise, uses the bounding box data. g?rr)rlabel_1label_2 label_overlap label_scalec||_||_||_||_||_||_||_||_t|jdz|_ y)a{ Args: color_1: Color of areas only present in the first set of detections. color_2: Color of areas only present in the second set of detections. color_overlap: Color of areas present in both sets of detections. opacity: Opacity of the overlay mask. Must be between `0` and `1`. label_1: Label for the first set of detections. label_2: Label for the second set of detections. label_overlap: Label for areas present in both sets of detections. label_scale: Controls how large the labels are. g333333?N) color_1color_2 color_overlaprrMrNrOrPrcr) rSrRrSrTrrMrNrOrPs r:rUzComparisonAnnotator.__init__ sW4  *   *&!$"2"2S"89r<ct|tjs|S|jr|jr|S|j ||}|j ||}|r%|j ||}|j ||}nK|r%|j||}|j||}n$|j||}|j||}||z}||z}||z}tj|tj} |jj| |<|jj| |<|jj| |<d|jz ||z|j| |zz||<d|jz ||z|j| |zz||<d|jz ||z|j| |zz||<|j!||S)aL Highlights the differences between two sets of detections. Args: scene: The image where detections will be drawn. `ImageType` is a flexible type, accepting either `numpy.ndarray` or `PIL.Image.Image`. detections_1: The first set of detections or predictions. detections_2: The second set of detections to compare or ground truth. Returns: The annotated image. Example: ```python import supervision as sv image = ... detections_1 = sv.Detections(...) detections_2 = sv.Detections(...) comparison_annotator = sv.ComparisonAnnotator() annotated_frame = comparison_annotator.annotate( scene=image.copy(), detections_1=detections_1, detections_2=detections_2 ) ``` ![comparison-annotator-example](https://media.roboflow.com/ supervision-annotator-examples/comparison-annotator-example.png) rrX)r?rris_empty_use_obb _use_mask_mask_from_obb_mask_from_mask_mask_from_xyxyrrrTrrRrSrr#) rSr detections_1 detections_2use_obbuse_maskmask_1mask_2 mask_overlap color_layers r:rzComparisonAnnotator.annotate sJ%,L  "|'<'<'>L-- l;>>, = (( =F(( =F ))%>F))%>F))%>F))%>F <-'<-'mmE: $($6$6$=$=$? L!"ll113 F"ll113 F 4<</5 4  LL;|4 45lT\\)U6]:T\\K M >  f T\\)U6]:T\\K M >  f  %  r<c|jr|jrJt|jv}t|jv}|xr|xs*|xr|jxs|jxr|Sr6)rVrr)r\r]is_obb_1is_obb_2s r:rWzComparisonAnnotator._use_obbX sx((*,2G2G2III+|/@/@@+|/@/@@  "( 64\224 6%%'4H r<c|jr|jrJ|jdu}|jdu}|xr|xs*|xr|jxs|jxr|Sr6)rVr)r\r] is_mask_1 is_mask_2s r:rXzComparisonAnnotator._use_maskc sx((*,2G2G2III %%T1  %%T1  $9 75l335 7%%'5I r<c`tj|jddtj}|j r|S|jd|jdf}t |j }|D]1}t||}||jtjz}3|SNrurrXr)r[) rrrbool_rVr$rr#r)rr~rr[polygonsr polygon_masks r:r[z#ComparisonAnnotator._mask_from_xyxyn sxx BQrxx8    K A A6 #JOO4 2G*7-PL L''1 1D 2 r<cXtj|jddtj}|j r|S|jd|jdf}|j t D]1}t||}||jtjz}3|Srk) rrrrlrVrrr#r)rr~rr[rrns r:rYz"ComparisonAnnotator._mask_from_obb~ sxx BQrxx8    K A A6 !'?@ 2G*7-PL L''1 1D 2 r<ctj|jddtj}|j r|S|j J|j D]$}||j tjz}&|S)Nrur)rrrrlrVrr)rr~rdetections_masks r:rZz#ComparisonAnnotator._mask_from_mask stxx BQrxx8    K***) 5O O**2884 4D 5 r<c td|jz}td|jz}td|jz}td|jz}td|jz}td|jz}td|jz}td|jz} |j} |j|jf|j|j f|j |jfg} |} | D]\} }| s tj| t|j|jd\}}||z|dzz}| |dzz}||dzz}t|t| ||| tj| t|t| |z||dz z || || t!|| t#||z| | |j | ||zz } y )z Draw the labels, explaining what each color represents, with automatically computed positions. Args: scene: The image where the labels will be drawn. 2rrrHrWr%rru)rrrrS)rrectr9rP)rr)rNrrN)rcrPrMrRrNrSrOrTrr.r/rr)r-r&rqr*r+)rSrmargingapy0rS marker_sizepaddingtext_box_corner_radiusmarker_corner_radiusrlabel_color_pairsx0r&r9r9rErcenter_xcenter_ys r:r#z ComparisonAnnotator._draw_labels sR$***+"t'''( d&&& 'R$***+"t///0 b4+++,!$R$*:*:%:!;"1t'7'7#78%% \\4<< ( \\4<< (   !3!3 4  ,* KD%//!**--   KVQ[(7Q;6EEQJHFaK'H "B"E&Akk4   #7lq0%&  2  !H{$:hG%#22   %#+ BU* r<N)rRr&rSr&rTr&rrrMr@rNr@rOr@rPr)rr%r\rr]rrir%)r\rr]rrire)rrjr~rriznpt.NDArray[np.bool_])rrjrirZ)rkrlrmrnr&REDGREENBLUErUr.rr[rWrXr[rYrZr#r7r<r:rLrL su$zz #:  #:#:#: #:  #:#:#:#:#:J'MM.8MHRM M'M^     $ 2<     $ 2<     $ 2<    Dr<rL)r9r2rir&)r9rbriColor | ColorPalette)F) rrjr~rr9rrKz"ColorLookup | npt.NDArray[np.int_]rreriznpt.NDArray[np.bool_] | None)j __future__r functoolsrmathrtypingrrrrnumpyr numpy.typingr deprecater r PILr r r scipy.interpolaterrsupervision.annotators.basersupervision.annotators.utilsrrrrrrrrrrrrsupervision.configr"supervision.detection.compact_maskrsupervision.detection.corer!supervision.detection.utils.boxesr r!&supervision.detection.utils.convertersr"r#r$supervision.draw.baser%supervision.draw.colorr&r'supervision.draw.utilsr(r)r*supervision.geometry.corer+r,r-supervision.utils.conversionr.r/supervision.utils.imager0r1r2r3supervision.utils.loggerr4rkrr;FONT_HERSHEY_SIMPLEXr/rGrtrrrrrrrrrr rr_rrrrrrrr r6rErLr7r<r:rs|"&& &++,5    8:1J ,6RR;; 1 X  < <  %    # #h#-h#VT=TnT=Tz 7 !77 75 7  7 " 7tUMUp\}\~Y]YxcMcL`}`F\\~YmYxl=l^x(xv Q0,Q0hjMjZJMJZN]Nbm}m`[ [|w wtE EPL(]L(^XOMXOvTTnFFr<