def add_label(
    image: np.ndarray,
    label_name: str,
    color: tuple[int, int, int],
    confidence: float | None = None,
    font_scale: float = 5e-3,
    thickness_scale: float = 1e-3,
) -> np.ndarray:
    """Add a text label with optional confidence score to an image.

    This function adds a text label to the top-left corner of an image. The label has a
    colored background patch and can optionally include a confidence percentage.

    Args:
        image (np.ndarray): Input image to add the label to. Must be a 3-channel RGB or
            BGR image.
        label_name (str): Text label to display on the image (e.g. "normal",
            "anomalous").
        color (tuple[int, int, int]): RGB color values for the label background as a
            tuple of 3 integers in range [0,255].
        confidence (float | None, optional): Confidence score between 0 and 1 to display
            as percentage. If ``None``, only the label name is shown. Defaults to
            ``None``.
        font_scale (float, optional): Scale factor for font size relative to image
            dimensions. Larger values produce bigger text. Defaults to ``5e-3``.
        thickness_scale (float, optional): Scale factor for font thickness relative to
            image dimensions. Larger values produce thicker text. Defaults to ``1e-3``.

    Returns:
        np.ndarray: Copy of input image with label added to top-left corner.

    Example:
        Add a normal label with 95% confidence:

        >>> import numpy as np
        >>> image = np.zeros((100, 100, 3), dtype=np.uint8)
        >>> labeled_image = add_label(
        ...     image=image,
        ...     label_name="normal",
        ...     color=(0, 255, 0),
        ...     confidence=0.95
        ... )

        Add an anomalous label without confidence:

        >>> labeled_image = add_label(
        ...     image=image,
        ...     label_name="anomalous",
        ...     color=(255, 0, 0)
        ... )

    Note:
        - The function creates a copy of the input image to avoid modifying it
        - Font size and thickness scale automatically with image dimensions
        - Label is always placed in the top-left corner
        - Uses OpenCV's FONT_HERSHEY_PLAIN font family
    """
    image = image.copy()
    img_height, img_width, _ = image.shape

    font = cv2.FONT_HERSHEY_PLAIN
    text = label_name if confidence is None else f"{label_name} ({confidence * 100:.0f}%)"

    # get font sizing
    font_scale = min(img_width, img_height) * font_scale
    thickness = math.ceil(min(img_width, img_height) * thickness_scale)
    (width, height), baseline = cv2.getTextSize(text, font, fontScale=font_scale, thickness=thickness)

    # create label
    label_patch = np.zeros((height + baseline, width + baseline, 3), dtype=np.uint8)
    label_patch[:, :] = color
    cv2.putText(
        label_patch,
        text,
        (0, baseline // 2 + height),
        font,
        fontScale=font_scale,
        thickness=thickness,
        color=0,
        lineType=cv2.LINE_AA,
    )

    # add label to image
    image[: baseline + height, : baseline + width] = label_patch
    return image
Add a text label with optional confidence score to an image.

    This function adds a text label to the top-left corner of an image. The label has a
    colored background patch and can optionally include a confidence percentage.

    Args:
        image (np.ndarray): Input image to add the label to. Must be a 3-channel RGB or
            BGR image.
        label_name (str): Text label to display on the image (e.g. "normal",
            "anomalous").
        color (tuple[int, int, int]): RGB color values for the label background as a
            tuple of 3 integers in range [0,255].
        confidence (float | None, optional): Confidence score between 0 and 1 to display
            as percentage. If ``None``, only the label name is shown. Defaults to
            ``None``.
        font_scale (float, optional): Scale factor for font size relative to image
            dimensions. Larger values produce bigger text. Defaults to ``5e-3``.
        thickness_scale (float, optional): Scale factor for font thickness relative to
            image dimensions. Larger values produce thicker text. Defaults to ``1e-3``.

    Returns:
        np.ndarray: Copy of input image with label added to top-left corner.

    Example:
        Add a normal label with 95% confidence:

        >>> import numpy as np
        >>> image = np.zeros((100, 100, 3), dtype=np.uint8)
        >>> labeled_image = add_label(
        ...     image=image,
        ...     label_name="normal",
        ...     color=(0, 255, 0),
        ...     confidence=0.95
        ... )

        Add an anomalous label without confidence:

        >>> labeled_image = add_label(
        ...     image=image,
        ...     label_name="anomalous",
        ...     color=(255, 0, 0)
        ... )

    Note:
        - The function creates a copy of the input image to avoid modifying it
        - Font size and thickness scale automatically with image dimensions
        - Label is always placed in the top-left corner
        - Uses OpenCV's FONT_HERSHEY_PLAIN font family
    
src/anomalib/utils/post_processing.py