Hausdorff Distance

Module Interface

class torchmetrics.segmentation.HausdorffDistance(num_classes, include_background=False, distance_metric='euclidean', spacing=None, directed=False, input_format='one-hot', **kwargs)

Compute the Hausdorff Distance between two subsets of a metric space for semantic segmentation.

\[d_{\Pi}(X,Y) = \max{/sup_{x\in X} {d(x,Y)}, /sup_{y\in Y} {d(X,y)}}\]

where \(\X, \Y\) are two subsets of a metric space with distance metric \(d\). The Hausdorff distance is the maximum distance from a point in one set to the closest point in the other set. The Hausdorff distance is a measure of the degree of mismatch between two sets.

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 of forward and compute the metric returns the following output:

• hausdorff_distance (Tensor): A scalar float tensor with the Hausdorff distance averaged over

  classes and samples

Parameters:

• num_classes (int) – number of classes

• include_background (bool) – whether to include background class in calculation

• distance_metric (Literal['euclidean', 'chessboard', 'taxicab']) – distance metric to calculate surface distance. Choose one of “euclidean”, “chessboard” or “taxicab”

• spacing (Union[Tensor, list[float], None]) – spacing between pixels along each spatial dimension. If not provided the spacing is assumed to be 1

• directed (bool) – whether to calculate directed or undirected Hausdorff distance

• 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.

Example

>>> from torch import randint
>>> from torchmetrics.segmentation import HausdorffDistance
>>> 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
>>> hausdorff_distance = HausdorffDistance(distance_metric="euclidean", num_classes=5)
>>> hausdorff_distance(preds, target)
tensor(1.9567)

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

>>> from torch import randint
>>> from torchmetrics.segmentation import HausdorffDistance
>>> 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
>>> metric = HausdorffDistance(num_classes=5)
>>> metric.update(preds, target)
>>> fig_, ax_ = metric.plot()

Functional Interface

torchmetrics.functional.segmentation.hausdorff_distance(preds, target, num_classes, include_background=False, distance_metric='euclidean', spacing=None, directed=False, input_format='one-hot')

Calculate Hausdorff Distance for semantic segmentation.

Parameters:

• preds (Tensor) – predicted binarized segmentation map

• target (Tensor) – target binarized segmentation map

• num_classes (int) – number of classes

• include_background (bool) – whether to include background class in calculation

• distance_metric (Literal['euclidean', 'chessboard', 'taxicab']) – distance metric to calculate surface distance. Choose one of “euclidean”, “chessboard” or “taxicab”

• spacing (Union[Tensor, list[float], None]) – spacing between pixels along each spatial dimension. If not provided the spacing is assumed to be 1

• directed (bool) – whether to calculate directed or undirected Hausdorff distance

• 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:

Hausdorff Distance for each class and batch element

Example

>>> from torch import randint
>>> from torchmetrics.functional.segmentation import hausdorff_distance
>>> 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
>>> hausdorff_distance(preds, target, num_classes=5)
tensor([[2.0000, 1.4142, 2.0000, 2.0000],
        [1.4142, 2.0000, 2.0000, 2.0000],
        [2.0000, 2.0000, 1.4142, 2.0000],
        [2.0000, 2.8284, 2.0000, 2.2361]])