Implementation:Kornia Kornia Mean IoU

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

Overview

Computes Mean Intersection-over-Union (mIoU) for semantic segmentation evaluation and bounding box IoU for object detection.

Description

This module provides two functions for computing Intersection-over-Union:

mean_iou calculates the per-class IoU for semantic segmentation by first constructing a confusion matrix from the predicted and ground truth label maps, then computing IoU for each class as: IoU_k = (TP_k + eps) / (TP_k + FP_k + FN_k + eps), where TP, FP, and FN are derived from the confusion matrix diagonal and row/column sums. A small epsilon is added to both numerator and denominator for numerical stability, ensuring that classes absent from both prediction and ground truth receive an IoU of approximately 1.0 rather than being undefined.

mean_iou_bbox computes the pairwise IoU between two sets of bounding boxes in (x1, y1, x2, y2) format, producing a matrix of shape (B1, B2) where each element represents the IoU between a box from set 1 and a box from set 2. This function is used internally by the Mean Average Precision metric.

Usage

Import mean_iou when evaluating semantic segmentation models to obtain per-class IoU scores. Import mean_iou_bbox when computing pairwise bounding box IoU for object detection evaluation or non-maximum suppression.

Code Reference

Source Location

• Repository: Kornia
• File: kornia/metrics/mean_iou.py
• Lines: 1-119

Signature

def mean_iou(
    pred: torch.Tensor,
    target: torch.Tensor,
    num_classes: int,
    eps: float = 1e-6
) -> torch.Tensor:

def mean_iou_bbox(
    boxes_1: torch.Tensor,
    boxes_2: torch.Tensor
) -> torch.Tensor:

Import

from kornia.metrics import mean_iou, mean_iou_bbox

I/O Contract

Inputs (mean_iou)

Name	Type	Required	Description
pred	torch.Tensor	Yes	Tensor with predicted class labels containing integer values between 0 and K-1. Shape can be (B, *).
target	torch.Tensor	Yes	Tensor with ground truth class labels containing integer values between 0 and K-1. Shape must match pred.
num_classes	int	Yes	Total number of possible classes. Must be an integer greater than or equal to 2.
eps	float	No	Epsilon value for numerical stability. Defaults to 1e-6.

Inputs (mean_iou_bbox)

Name	Type	Required	Description
boxes_1	torch.Tensor	Yes	Tensor of bounding boxes with shape (B1, 4) in (x1, y1, x2, y2) format. x2 > x1 and y2 > y1 must hold.
boxes_2	torch.Tensor	Yes	Tensor of bounding boxes with shape (B2, 4) in (x1, y1, x2, y2) format. x2 > x1 and y2 > y1 must hold.

Outputs

Name	Type	Description
ious (mean_iou)	torch.Tensor	Tensor of shape (B, K) containing the IoU for each class per batch element.
ious (mean_iou_bbox)	torch.Tensor	Tensor of shape (B1, B2) containing the pairwise IoU between boxes in set 1 and set 2.

Usage Examples

import torch
from kornia.metrics import mean_iou, mean_iou_bbox

# Semantic segmentation IoU
pred = torch.tensor([[0, 1, 0]])
target = torch.tensor([[0, 1, 0]])
iou = mean_iou(pred, target, num_classes=3)
# iou: tensor([[1., 1., 1.]])

# Bounding box IoU
boxes_1 = torch.tensor([[40, 40, 60, 60], [30, 40, 50, 60]])
boxes_2 = torch.tensor([[40, 50, 60, 70], [30, 40, 40, 50]])
iou_matrix = mean_iou_bbox(boxes_1, boxes_2)
# iou_matrix: tensor([[0.3333, 0.0000],
#                      [0.1429, 0.2500]])

Related Pages

• Principle:Kornia_Kornia_Segmentation_Metrics