imgutils.detect.similarity

This module provides functions for calculating similarities between bounding boxes and detections.

It includes functions to calculate Intersection over Union (IoU) for individual bounding boxes, compute similarities between lists of bounding boxes, and compare detections with labels. The module is designed to work with various types of bounding box representations and offers different modes for aggregating similarity scores.

Key components:

  • calculate_iou: Computes IoU between two bounding boxes

  • bboxes_similarity: Calculates similarities between two lists of bounding boxes

  • detection_similarity: Compares two lists of detections, considering both bounding boxes and labels

This module is particularly useful for tasks involving object detection, image segmentation, and evaluation of detection algorithms.

calculate_iou

imgutils.detect.similarity.calculate_iou(box1: Tuple[float, float, float, float], box2: Tuple[float, float, float, float]) → float[source]

Calculate the Intersection over Union (IoU) between two bounding boxes.

Parameters:

  • box1 (BBoxTyping) – The first bounding box, represented as (x1, y1, x2, y2).

  • box2 (BBoxTyping) – The second bounding box, represented as (x1, y1, x2, y2).

Returns:

The IoU value between the two bounding boxes.

Return type:

float

This function computes the IoU, which is a measure of the overlap between two bounding boxes. The IoU is calculated as the area of intersection divided by the area of union of the two boxes.

Example::
>>> box1 = (0, 0, 2, 2)
>>> box2 = (1, 1, 3, 3)
>>> iou = calculate_iou(box1, box2)
>>> print(f"IoU: {iou:.4f}")
IoU: 0.1429

bboxes_similarity

imgutils.detect.similarity.bboxes_similarity(bboxes1: List[Tuple[float, float, float, float]], bboxes2: List[Tuple[float, float, float, float]], mode: Literal['max', 'mean', 'raw'] = 'mean') → float | List[float][source]

Calculate the similarity between two lists of bounding boxes.

Parameters:

  • bboxes1 (List[BBoxTyping]) – First list of bounding boxes.

  • bboxes2 (List[BBoxTyping]) – Second list of bounding boxes.

  • mode (Literal['max', 'mean', 'raw']) – The mode for calculating similarity. Options are ‘max’, ‘mean’, or ‘raw’. Defaults to ‘mean’.

Returns:

The similarity score or list of scores, depending on the mode.

Return type:

Union[float, List[float]]

Raises:

ValueError – If the lengths of bboxes1 and bboxes2 do not match, or if an unknown mode is specified.

This function computes the similarity between two lists of bounding boxes using the Hungarian algorithm to find the optimal assignment. It then returns the similarity based on the specified mode:

  • max: Returns the maximum IoU among all matched pairs.

  • mean: Returns the average IoU of all matched pairs.

  • raw: Returns a list of IoU values for all matched pairs.

Example::
>>> bboxes1 = [(0, 0, 2, 2), (3, 3, 5, 5)]
>>> bboxes2 = [(1, 1, 3, 3), (4, 4, 6, 6)]
>>> similarity = bboxes_similarity(bboxes1, bboxes2, mode='mean')
>>> print(f"Mean similarity: {similarity:.4f}")
Mean similarity: 0.1429

detection_similarity

imgutils.detect.similarity.detection_similarity(detect1: List[Tuple[Tuple[float, float, float, float], str, float]], detect2: List[Tuple[Tuple[float, float, float, float], str, float]], mode: Literal['max', 'mean', 'raw'] = 'mean') → float | List[float][source]

Calculate the similarity between two lists of detections, considering both bounding boxes and labels.

Parameters:

  • detect1 (List[BBoxWithScoreAndLabel]) – First list of detections, each containing a bounding box, label, and score.

  • detect2 (List[BBoxWithScoreAndLabel]) – Second list of detections, each containing a bounding box, label, and score.

  • mode (Literal['max', 'mean', 'raw']) – The mode for calculating similarity. Options are ‘max’, ‘mean’, or ‘raw’. Defaults to ‘mean’.

Returns:

The similarity score or list of scores, depending on the mode.

Return type:

Union[float, List[float]]

Raises:

ValueError – If the number of bounding boxes for any label doesn’t match between detect1 and detect2, or if an unknown mode is specified.

This function compares two lists of detections by:

  1. Grouping detections by their labels.

  2. For each label, calculating the similarity between the corresponding bounding boxes.

  3. Aggregating the similarities based on the specified mode.

The function ensures that for each label, the number of bounding boxes matches between detect1 and detect2.

Example::
>>> detect1 = [((0, 0, 2, 2), 'car', 0.9), ((3, 3, 5, 5), 'person', 0.8)]
>>> detect2 = [((1, 1, 3, 3), 'car', 0.85), ((4, 4, 6, 6), 'person', 0.75)]
>>> similarity = detection_similarity(detect1, detect2, mode='mean')
>>> print(f"Mean detection similarity: {similarity:.4f}")
Mean detection similarity: 0.1429