Mean Intersection over Union (mIoU)

Module Interface

class torchmetrics.segmentation.MeanIoU(num_classes, include_background=True, per_class=False, input_format='one-hot', **kwargs)

Computes Mean Intersection over Union (mIoU) for semantic segmentation.

The metric is defined by the overlap between the predicted segmentation and the ground truth, divided by the total area covered by the union of the two. The metric can be computed for each class separately or for all classes at once. The metric is optimal at a value of 1 and worst at a value of 0.

As input to forward and update the metric accepts the following input:

• preds (Tensor): An one-hot boolean tensor of shape (N, C, ...) with N being the number of samples and C the number of classes. Alternatively, an integer tensor of shape (N, ...) can be provided, where the integer values correspond to the class index. The input type can be controlled with the input_format argument.

• target (Tensor): An one-hot boolean tensor of shape (N, C, ...) with N being the number of samples and C the number of classes. Alternatively, an integer tensor of shape (N, ...) can be provided, where the integer values correspond to the class index. The input type can be controlled with the input_format argument.

As output to forward and compute the metric returns the following output:

• miou (Tensor): The mean Intersection over Union (mIoU) score. If per_class is set to True, the output will be a tensor of shape (C,) with the IoU score for each class. If per_class is set to False, the output will be a scalar tensor.

Parameters:

• num_classes (int) – The number of classes in the segmentation problem.

• include_background (bool) – Whether to include the background class in the computation

• per_class (bool) – Whether to compute the IoU for each class separately. If set to False, the metric will compute the mean IoU over all classes.

• input_format (Literal['one-hot', 'index']) – What kind of input the function receives. Choose between "one-hot" for one-hot encoded tensors or "index" for index tensors

• kwargs (Any) – Additional keyword arguments, see Advanced metric settings for more info.

Raises:

• ValueError – If num_classes is not a positive integer

• ValueError – If include_background is not a boolean

• ValueError – If per_class is not a boolean

• ValueError – If input_format is not one of "one-hot" or "index"

Example

>>> from torch import randint
>>> from torchmetrics.segmentation import MeanIoU
>>> miou = MeanIoU(num_classes=3)
>>> preds = randint(0, 2, (10, 3, 128, 128))
>>> target = randint(0, 2, (10, 3, 128, 128))
>>> miou(preds, target)
tensor(0.3326)
>>> miou = MeanIoU(num_classes=3, per_class=True)
>>> miou(preds, target)
tensor([0.3334, 0.3327, 0.3318])
>>> miou = MeanIoU(num_classes=3, per_class=True, include_background=False)
>>> miou(preds, target)
tensor([0.3327, 0.3318])

plot(val=None, ax=None)

Plot a single or multiple values from the metric.

Parameters:

• val (Union[Tensor, Sequence[Tensor], None]) – Either a single result from calling metric.forward or metric.compute or a list of these results. If no value is provided, will automatically call metric.compute and plot that result.

• ax (Optional[Axes]) – An matplotlib axis object. If provided will add plot to that axis

Return type:

Tuple[Figure, Union[Axes, ndarray]]

Returns:

Figure and Axes object

Raises:

ModuleNotFoundError – If matplotlib is not installed

>>> # Example plotting a single value
>>> import torch
>>> from torchmetrics.audio import PerceptualEvaluationSpeechQuality
>>> metric = PerceptualEvaluationSpeechQuality(8000, 'nb')
>>> metric.update(torch.rand(8000), torch.rand(8000))
>>> fig_, ax_ = metric.plot()

>>> # Example plotting multiple values
>>> import torch
>>> from torchmetrics.audio import PerceptualEvaluationSpeechQuality
>>> metric = PerceptualEvaluationSpeechQuality(8000, 'nb')
>>> values = [ ]
>>> for _ in range(10):
...     values.append(metric(torch.rand(8000), torch.rand(8000)))
>>> fig_, ax_ = metric.plot(values)

Functional Interface

torchmetrics.functional.segmentation.mean_iou(preds, target, num_classes, include_background=True, per_class=False, input_format='one-hot')

Calculates the mean Intersection over Union (mIoU) for semantic segmentation.

Parameters:

• preds (Tensor) – Predictions from model

• target (Tensor) – Ground truth values

• num_classes (int) – Number of classes

• include_background (bool) – Whether to include the background class in the computation

• per_class (bool) – Whether to compute the IoU for each class separately, else average over all classes

• input_format (Literal['one-hot', 'index']) – What kind of input the function receives. Choose between "one-hot" for one-hot encoded tensors or "index" for index tensors

Return type:

Tensor

Returns:

The mean IoU score

Example

>>> from torch import randint
>>> from torchmetrics.functional.segmentation import mean_iou
>>> preds = randint(0, 2, (4, 5, 16, 16))  # 4 samples, 5 classes, 16x16 prediction
>>> target = randint(0, 2, (4, 5, 16, 16))  # 4 samples, 5 classes, 16x16 target
>>> mean_iou(preds, target, num_classes=5)
tensor([0.3193, 0.3305, 0.3382, 0.3246])
>>> mean_iou(preds, target, num_classes=5, per_class=True)
tensor([[0.3093, 0.3500, 0.3081, 0.3389, 0.2903],
        [0.2963, 0.3316, 0.3505, 0.2804, 0.3936],
        [0.3724, 0.3249, 0.3660, 0.3184, 0.3093],
        [0.3085, 0.3267, 0.3155, 0.3575, 0.3147]])