Implementation:Kornia Kornia Mean Average Precision

Knowledge Sources	Kornia
Domains	Vision, Metrics
Last Updated	2026-02-09 15:00 GMT

Overview

Computes the Mean Average Precision (mAP) for object detection by evaluating predicted bounding boxes against ground truth across all classes.

Description

The mean_average_precision function calculates the standard mAP metric used in object detection evaluation. For each class (excluding the background class at index 0), the function computes the Average Precision (AP) using the 11-point interpolation method (recall thresholds from 0 to 1 in steps of 0.1). The algorithm sorts detections by confidence score in descending order, then determines true positives and false positives based on IoU overlap with ground truth boxes using a configurable threshold (default 0.5). Each ground truth box can only be matched once to prevent double counting. The final mAP is the mean of per-class APs. The implementation relies on the mean_iou_bbox function from the mean_iou module to compute IoU overlaps between detection boxes and ground truth boxes.

Usage

Import this metric when evaluating object detection models. It accepts lists of per-image predictions (boxes, labels, scores) and ground truth (boxes, labels), making it suitable for batch evaluation across an entire dataset.

Code Reference

Source Location

• Repository: Kornia
• File: kornia/metrics/mean_average_precision.py
• Lines: 1-182

Signature

def mean_average_precision(
    pred_boxes: List[torch.Tensor],
    pred_labels: List[torch.Tensor],
    pred_scores: List[torch.Tensor],
    gt_boxes: List[torch.Tensor],
    gt_labels: List[torch.Tensor],
    n_classes: int,
    threshold: float = 0.5,
) -> Tuple[torch.Tensor, Dict[int, float]]:

Import

from kornia.metrics import mean_average_precision

I/O Contract

Inputs

Name	Type	Required	Description
pred_boxes	List[torch.Tensor]	Yes	List of tensors, one per image, each of shape (N_i, 4) containing predicted bounding boxes in (x1, y1, x2, y2) format.
pred_labels	List[torch.Tensor]	Yes	List of tensors, one per image, each of shape (N_i,) containing predicted class labels (integer indices, 0 is background).
pred_scores	List[torch.Tensor]	Yes	List of tensors, one per image, each of shape (N_i,) containing confidence scores for each prediction.
gt_boxes	List[torch.Tensor]	Yes	List of tensors, one per image, each of shape (M_i, 4) containing ground truth bounding boxes in (x1, y1, x2, y2) format.
gt_labels	List[torch.Tensor]	Yes	List of tensors, one per image, each of shape (M_i,) containing ground truth class labels.
n_classes	int	Yes	Total number of classes including the background class (index 0). Must be at least 2.
threshold	float	No	IoU threshold above which a detection is considered a true positive. Defaults to 0.5.

Outputs

Name	Type	Description
mean_ap	torch.Tensor	Scalar tensor containing the mean average precision across all non-background classes.
ap_dict	Dict[int, float]	Dictionary mapping each class index (1 through n_classes-1) to its average precision value.

Usage Examples

import torch
from kornia.metrics import mean_average_precision

# Single image with one detection matching ground truth
boxes = torch.tensor([[100, 50, 150, 100.]])
labels = torch.tensor([1])
scores = torch.tensor([.7])
gt_boxes = torch.tensor([[100, 50, 150, 100.]])
gt_labels = torch.tensor([1])

mAP, ap_per_class = mean_average_precision(
    [boxes], [labels], [scores],
    [gt_boxes], [gt_labels],
    n_classes=2
)
# mAP: tensor(1.), ap_per_class: {1: 1.0}

# Multiple images with multiple classes
pred_boxes_list = [
    torch.tensor([[10, 10, 50, 50.], [60, 60, 100, 100.]]),
    torch.tensor([[20, 20, 70, 70.]])
]
pred_labels_list = [torch.tensor([1, 2]), torch.tensor([1])]
pred_scores_list = [torch.tensor([0.9, 0.8]), torch.tensor([0.7])]
gt_boxes_list = [
    torch.tensor([[10, 10, 50, 50.], [55, 55, 95, 95.]]),
    torch.tensor([[25, 25, 65, 65.]])
]
gt_labels_list = [torch.tensor([1, 2]), torch.tensor([1])]

mAP, ap_per_class = mean_average_precision(
    pred_boxes_list, pred_labels_list, pred_scores_list,
    gt_boxes_list, gt_labels_list,
    n_classes=3, threshold=0.5
)

Related Pages

• Principle:Kornia_Kornia_Detection_Metrics