Reference for ultralytics/utils/plotting.py

def __call__(self, i, bgr=False):
    """Convert hex color codes to RGB values."""
    c = self.palette[int(i) % self.n]
    return (c[2], c[1], c[0]) if bgr else c

@staticmethod
def hex2rgb(h):
    """Convert hex color codes to RGB values (i.e. default PIL order)."""
    return tuple(int(h[1 + i : 1 + i + 2], 16) for i in (0, 2, 4))

def box_label(self, box, label="", color=(128, 128, 128), txt_color=(255, 255, 255), rotated=False):
    """
    Draw a bounding box on an image with a given label.

    Args:
        box (tuple): The bounding box coordinates (x1, y1, x2, y2).
        label (str, optional): The text label to be displayed.
        color (tuple, optional): The background color of the rectangle (B, G, R).
        txt_color (tuple, optional): The color of the text (R, G, B).
        rotated (bool, optional): Whether the task is oriented bounding box detection.

    Examples:
        >>> from ultralytics.utils.plotting import Annotator
        >>> im0 = cv2.imread("test.png")
        >>> annotator = Annotator(im0, line_width=10)
        >>> annotator.box_label(box=[10, 20, 30, 40], label="person")
    """
    txt_color = self.get_txt_color(color, txt_color)
    if isinstance(box, torch.Tensor):
        box = box.tolist()
    if self.pil or not is_ascii(label):
        if rotated:
            p1 = box[0]
            self.draw.polygon([tuple(b) for b in box], width=self.lw, outline=color)  # PIL requires tuple box
        else:
            p1 = (box[0], box[1])
            self.draw.rectangle(box, width=self.lw, outline=color)  # box
        if label:
            w, h = self.font.getsize(label)  # text width, height
            outside = p1[1] >= h  # label fits outside box
            if p1[0] > self.im.size[0] - w:  # size is (w, h), check if label extend beyond right side of image
                p1 = self.im.size[0] - w, p1[1]
            self.draw.rectangle(
                (p1[0], p1[1] - h if outside else p1[1], p1[0] + w + 1, p1[1] + 1 if outside else p1[1] + h + 1),
                fill=color,
            )
            # self.draw.text((box[0], box[1]), label, fill=txt_color, font=self.font, anchor='ls')  # for PIL>8.0
            self.draw.text((p1[0], p1[1] - h if outside else p1[1]), label, fill=txt_color, font=self.font)
    else:  # cv2
        if rotated:
            p1 = [int(b) for b in box[0]]
            cv2.polylines(self.im, [np.asarray(box, dtype=int)], True, color, self.lw)  # cv2 requires nparray box
        else:
            p1, p2 = (int(box[0]), int(box[1])), (int(box[2]), int(box[3]))
            cv2.rectangle(self.im, p1, p2, color, thickness=self.lw, lineType=cv2.LINE_AA)
        if label:
            w, h = cv2.getTextSize(label, 0, fontScale=self.sf, thickness=self.tf)[0]  # text width, height
            h += 3  # add pixels to pad text
            outside = p1[1] >= h  # label fits outside box
            if p1[0] > self.im.shape[1] - w:  # shape is (h, w), check if label extend beyond right side of image
                p1 = self.im.shape[1] - w, p1[1]
            p2 = p1[0] + w, p1[1] - h if outside else p1[1] + h
            cv2.rectangle(self.im, p1, p2, color, -1, cv2.LINE_AA)  # filled
            cv2.putText(
                self.im,
                label,
                (p1[0], p1[1] - 2 if outside else p1[1] + h - 1),
                0,
                self.sf,
                txt_color,
                thickness=self.tf,
                lineType=cv2.LINE_AA,
            )

def fromarray(self, im):
    """Update self.im from a numpy array."""
    self.im = im if isinstance(im, Image.Image) else Image.fromarray(im)
    self.draw = ImageDraw.Draw(self.im)

@staticmethod
def get_bbox_dimension(bbox=None):
    """
    Calculate the dimensions and area of a bounding box.

    Args:
        bbox (tuple): Bounding box coordinates in the format (x_min, y_min, x_max, y_max).

    Returns:
        width (float): Width of the bounding box.
        height (float): Height of the bounding box.
        area (float): Area enclosed by the bounding box.

    Examples:
        >>> from ultralytics.utils.plotting import Annotator
        >>> im0 = cv2.imread("test.png")
        >>> annotator = Annotator(im0, line_width=10)
        >>> annotator.get_bbox_dimension(bbox=[10, 20, 30, 40])
    """
    x_min, y_min, x_max, y_max = bbox
    width = x_max - x_min
    height = y_max - y_min
    return width, height, width * height

def get_txt_color(self, color=(128, 128, 128), txt_color=(255, 255, 255)):
    """
    Assign text color based on background color.

    Args:
        color (tuple, optional): The background color of the rectangle for text (B, G, R).
        txt_color (tuple, optional): The color of the text (R, G, B).

    Returns:
        (tuple): Text color for label.

    Examples:
        >>> from ultralytics.utils.plotting import Annotator
        >>> im0 = cv2.imread("test.png")
        >>> annotator = Annotator(im0, line_width=10)
        >>> annotator.get_txt_color(color=(104, 31, 17))  # return (255, 255, 255)
    """
    if color in self.dark_colors:
        return 104, 31, 17
    elif color in self.light_colors:
        return 255, 255, 255
    else:
        return txt_color

def kpts(self, kpts, shape=(640, 640), radius=None, kpt_line=True, conf_thres=0.25, kpt_color=None):
    """
    Plot keypoints on the image.

    Args:
        kpts (torch.Tensor): Keypoints, shape [17, 3] (x, y, confidence).
        shape (tuple, optional): Image shape (h, w).
        radius (int, optional): Keypoint radius.
        kpt_line (bool, optional): Draw lines between keypoints.
        conf_thres (float, optional): Confidence threshold.
        kpt_color (tuple, optional): Keypoint color (B, G, R).

    Note:
        - `kpt_line=True` currently only supports human pose plotting.
        - Modifies self.im in-place.
        - If self.pil is True, converts image to numpy array and back to PIL.
    """
    radius = radius if radius is not None else self.lw
    if self.pil:
        # Convert to numpy first
        self.im = np.asarray(self.im).copy()
    nkpt, ndim = kpts.shape
    is_pose = nkpt == 17 and ndim in {2, 3}
    kpt_line &= is_pose  # `kpt_line=True` for now only supports human pose plotting
    for i, k in enumerate(kpts):
        color_k = kpt_color or (self.kpt_color[i].tolist() if is_pose else colors(i))
        x_coord, y_coord = k[0], k[1]
        if x_coord % shape[1] != 0 and y_coord % shape[0] != 0:
            if len(k) == 3:
                conf = k[2]
                if conf < conf_thres:
                    continue
            cv2.circle(self.im, (int(x_coord), int(y_coord)), radius, color_k, -1, lineType=cv2.LINE_AA)

    if kpt_line:
        ndim = kpts.shape[-1]
        for i, sk in enumerate(self.skeleton):
            pos1 = (int(kpts[(sk[0] - 1), 0]), int(kpts[(sk[0] - 1), 1]))
            pos2 = (int(kpts[(sk[1] - 1), 0]), int(kpts[(sk[1] - 1), 1]))
            if ndim == 3:
                conf1 = kpts[(sk[0] - 1), 2]
                conf2 = kpts[(sk[1] - 1), 2]
                if conf1 < conf_thres or conf2 < conf_thres:
                    continue
            if pos1[0] % shape[1] == 0 or pos1[1] % shape[0] == 0 or pos1[0] < 0 or pos1[1] < 0:
                continue
            if pos2[0] % shape[1] == 0 or pos2[1] % shape[0] == 0 or pos2[0] < 0 or pos2[1] < 0:
                continue
            cv2.line(
                self.im,
                pos1,
                pos2,
                kpt_color or self.limb_color[i].tolist(),
                thickness=int(np.ceil(self.lw / 2)),
                lineType=cv2.LINE_AA,
            )
    if self.pil:
        # Convert im back to PIL and update draw
        self.fromarray(self.im)

def masks(self, masks, colors, im_gpu, alpha=0.5, retina_masks=False):
    """
    Plot masks on image.

    Args:
        masks (torch.Tensor): Predicted masks on cuda, shape: [n, h, w]
        colors (List[List[int]]): Colors for predicted masks, [[r, g, b] * n]
        im_gpu (torch.Tensor): Image is in cuda, shape: [3, h, w], range: [0, 1]
        alpha (float, optional): Mask transparency: 0.0 fully transparent, 1.0 opaque.
        retina_masks (bool, optional): Whether to use high resolution masks or not.
    """
    if self.pil:
        # Convert to numpy first
        self.im = np.asarray(self.im).copy()
    if len(masks) == 0:
        self.im[:] = im_gpu.permute(1, 2, 0).contiguous().cpu().numpy() * 255
    if im_gpu.device != masks.device:
        im_gpu = im_gpu.to(masks.device)
    colors = torch.tensor(colors, device=masks.device, dtype=torch.float32) / 255.0  # shape(n,3)
    colors = colors[:, None, None]  # shape(n,1,1,3)
    masks = masks.unsqueeze(3)  # shape(n,h,w,1)
    masks_color = masks * (colors * alpha)  # shape(n,h,w,3)

    inv_alpha_masks = (1 - masks * alpha).cumprod(0)  # shape(n,h,w,1)
    mcs = masks_color.max(dim=0).values  # shape(n,h,w,3)

    im_gpu = im_gpu.flip(dims=[0])  # flip channel
    im_gpu = im_gpu.permute(1, 2, 0).contiguous()  # shape(h,w,3)
    im_gpu = im_gpu * inv_alpha_masks[-1] + mcs
    im_mask = im_gpu * 255
    im_mask_np = im_mask.byte().cpu().numpy()
    self.im[:] = im_mask_np if retina_masks else ops.scale_image(im_mask_np, self.im.shape)
    if self.pil:
        # Convert im back to PIL and update draw
        self.fromarray(self.im)

def rectangle(self, xy, fill=None, outline=None, width=1):
    """Add rectangle to image (PIL-only)."""
    self.draw.rectangle(xy, fill, outline, width)

def result(self):
    """Return annotated image as array."""
    return np.asarray(self.im)

def save(self, filename="image.jpg"):
    """Save the annotated image to 'filename'."""
    cv2.imwrite(filename, np.asarray(self.im))

def show(self, title=None):
    """Show the annotated image."""
    im = Image.fromarray(np.asarray(self.im)[..., ::-1])  # Convert numpy array to PIL Image with RGB to BGR
    if IS_COLAB or IS_KAGGLE:  # can not use IS_JUPYTER as will run for all ipython environments
        try:
            display(im)  # noqa - display() function only available in ipython environments
        except ImportError as e:
            LOGGER.warning(f"Unable to display image in Jupyter notebooks: {e}")
    else:
        im.show(title=title)

def text(self, xy, text, txt_color=(255, 255, 255), anchor="top", box_style=False):
    """
    Add text to an image using PIL or cv2.

    Args:
        xy (List[int]): Top-left coordinates for text placement.
        text (str): Text to be drawn.
        txt_color (tuple, optional): Text color (R, G, B).
        anchor (str, optional): Text anchor position ('top' or 'bottom').
        box_style (bool, optional): Whether to draw text with a background box.
    """
    if anchor == "bottom":  # start y from font bottom
        w, h = self.font.getsize(text)  # text width, height
        xy[1] += 1 - h
    if self.pil:
        if box_style:
            w, h = self.font.getsize(text)
            self.draw.rectangle((xy[0], xy[1], xy[0] + w + 1, xy[1] + h + 1), fill=txt_color)
            # Using `txt_color` for background and draw fg with white color
            txt_color = (255, 255, 255)
        if "\n" in text:
            lines = text.split("\n")
            _, h = self.font.getsize(text)
            for line in lines:
                self.draw.text(xy, line, fill=txt_color, font=self.font)
                xy[1] += h
        else:
            self.draw.text(xy, text, fill=txt_color, font=self.font)
    else:
        if box_style:
            w, h = cv2.getTextSize(text, 0, fontScale=self.sf, thickness=self.tf)[0]  # text width, height
            h += 3  # add pixels to pad text
            outside = xy[1] >= h  # label fits outside box
            p2 = xy[0] + w, xy[1] - h if outside else xy[1] + h
            cv2.rectangle(self.im, xy, p2, txt_color, -1, cv2.LINE_AA)  # filled
            # Using `txt_color` for background and draw fg with white color
            txt_color = (255, 255, 255)
        cv2.putText(self.im, text, xy, 0, self.sf, txt_color, thickness=self.tf, lineType=cv2.LINE_AA)