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

  • calculate_mask_iou: Computes IoU between two masks

  • masks_similarity: Calculates similarities between two lists of masks

  • detection_with_mask_similarity: Compares two lists of detections (with masks), considering both bounding masks 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 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] | Tuple[Tuple[float, float, float, float], str, float, ndarray]], detect2: List[Tuple[Tuple[float, float, float, float], str, float] | Tuple[Tuple[float, float, float, float], str, float, ndarray]], 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[Union[BBoxWithScoreAndLabel, MaskWithScoreAndLabel]]) – First list of detections, each containing a bounding box, label, and score.

  • detect2 (List[Union[BBoxWithScoreAndLabel, MaskWithScoreAndLabel]]) – 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 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 processes detections label by label and combines their similarities. It’s particularly useful for evaluating object detection results against ground truth.

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

calculate_mask_iou

imgutils.detect.similarity.calculate_mask_iou(mask1: ndarray, mask2: ndarray, threshold: float = 0.5) → float[source]

Calculate the Intersection over Union (IoU) between two masks.

Parameters:

  • mask1 (np.ndarray) – The first mask.

  • mask2 (np.ndarray) – The second mask.

  • threshold (float) – The threshold value for converting masks to boolean. Defaults to 0.5.

Returns:

The IoU value between the two masks.

Return type:

float

This function computes the IoU between two masks, which is defined as the area of intersection divided by the area of union. The masks are first converted to boolean arrays using the specified threshold.

Example::
>>> import numpy as np
>>> mask1 = np.array([[1, 1], [1, 0]])
>>> mask2 = np.array([[0, 1], [1, 1]])
>>> iou = calculate_mask_iou(mask1, mask2)
>>> print(f"IoU: {iou:.4f}")
IoU: 0.5000

masks_similarity

imgutils.detect.similarity.masks_similarity(masks1: List[ndarray], masks2: List[ndarray], mode: Literal['max', 'mean', 'raw'] = 'mean') → float | List[float][source]

Calculate the similarity between two lists of masks.

Parameters:

  • masks1 (List[np.ndarray]) – First list of masks.

  • masks2 (List[np.ndarray]) – Second list of masks.

  • 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 an unknown mode is specified.

This function computes the similarity between two lists of masks 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.

If both lists are empty, the function returns 1.0 for ‘max’ and ‘mean’ modes, and an empty list for ‘raw’ mode.

Example::
>>> import numpy as np
>>> masks1 = [np.array([[1, 1], [1, 0]]), np.array([[0, 0], [1, 1]])]
>>> masks2 = [np.array([[0, 1], [1, 1]]), np.array([[1, 0], [0, 0]])]
>>> similarity = masks_similarity(masks1, masks2, mode='mean')
>>> print(f"Mean similarity: {similarity:.4f}")
Mean similarity: 0.5000

detection_with_mask_similarity

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

Calculate the similarity between two lists of mask detections, considering both masks and labels.

Parameters:

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

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

  • 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 an unknown mode is specified.

This function compares two lists of mask detections by:

  1. Grouping detections by their labels.

  2. For each label, calculating the similarity between the corresponding masks.

  3. Aggregating the similarities based on the specified mode.

The function processes detections label by label and combines their similarities. It’s particularly useful for evaluating instance segmentation results against ground truth.

Example::
>>> import numpy as np
>>> # Example with simplified MaskWithScoreAndLabel format (_, label, score, mask)
>>> detect1 = [(None, 'car', 0.9, np.array([[1, 1], [1, 0]])),
...            (None, 'person', 0.8, np.array([[0, 0], [1, 1]]))]
>>> detect2 = [(None, 'car', 0.85, np.array([[0, 1], [1, 1]])),
...            (None, 'person', 0.75, np.array([[1, 0], [0, 0]]))]
>>> similarity = detection_with_mask_similarity(detect1, detect2, mode='mean')
>>> print(f"Mean detection similarity: {similarity:.4f}")
Mean detection similarity: 0.2500