Spatialdistortionindex

spatialdistortionindex

Metric SpatialDistortionIndex from torchmetrics (torchmetrics.image.SpatialDistortionIndex)

When to invoke this skill

The user has predictions + ground truth and asks to evaluate with SpatialDistortionIndex, or mentions torchmetrics.image.SpatialDistortionIndex directly, or wants the standard torchmetrics implementation.

Reference signature

from torchmetrics.image import SpatialDistortionIndex

# SpatialDistortionIndex(norm_order: int = 1, window_size: int = 7, reduction: Literal['elementwise_mean', 'sum', 'none'] = 'elementwise_mean', **kwargs: Any) -> None

Library docstring

Compute Spatial Distortion Index (SpatialDistortionIndex_) also now as D_s.

The metric is used to compare the spatial distortion between two images. A value of 0 indicates no distortion
(optimal value) and corresponds to the case where the high resolution panchromatic image is equal to the low
resolution panchromatic image. The metric is defined as:

.. math::
    D_s = \\sqrt[q]{\frac{1}{L}\\sum_{l=1}^L|Q(\\hat{G_l}, P) - Q(\tilde{G}, \tilde{P})|^q}

where :math:`Q` is the universal image quality index (see this
:class:`~torchmetrics.image.UniversalImageQualityIndex` for more info), :math:`\\hat{G_l}` is the l-th band of the
high resolution multispectral image, :math:`\tilde{G}` is the high resolution panchromatic image, :math:`P` is the
high resolution panchromatic image, :math:`\tilde{P}` is the low resolution panchromatic image, :math:`L` is the
number of bands and :math:`q` is the order of the norm applied on the difference.

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

- ``preds`` (:class:`~torch.Tensor`): High resolution multispectral image of shape ``(N,C,H,W)``.
- ``target`` (:class:`~Dict`): A dictionary containing the following keys:
    - ``ms`` (:class:`~torch.Tensor`): Low resolution multispectral image of shape ``(N,C,H',W')``.
    - ``pan`` (:class:`~torch.Tensor`): High resolution panchromatic image of shape ``(N,C,H,W)``.
    - ``pan_lr`` (:class:`~torch.Tensor`): Low resolution panchromatic image of shape ``(N,C,H',W')``.

where H and W must be multiple of H' and W'.

As output of `forward` and `compute` the metric returns the following output

- ``sdi`` (:class:`~torch.Tensor`): if ``reduction!='none'`` returns float scalar tensor with average SDI value
  over sample else returns tensor of shape ``(N,)`` with SDI values per sample

Args:
    norm_order: Order of the norm applied on the difference.
    window_size: Window size of the filter applied to degrade the high resolution panchromatic image.
    reduction: a method to reduce metric score over labels.

        - ``'elementwise_mean'``: takes the mean (default)
        - ``'sum'``: takes the sum
        - ``'none'``: no reduction will be applied

    kwa

Quick recipe

import torchmetrics.image as _m
score = _m.SpatialDistortionIndex(y_true, y_pred)

Don'ts

• Don't reimplement when the library version handles edge cases (NaN, ties, empty inputs) better than a hand-rolled formula.
• Always check the library version's argument order — sklearn is (y_true, y_pred) while torchmetrics is (preds, target).