Spatialdistortionindex

---
name: spatialdistortionindex
description: Compute the SpatialDistortionIndex metric — provided by torchmetrics. Use when the user has predictions and ground-truth and needs to compute SpatialDistortionIndex, or asks how to score with SpatialDistortionIndex.
metadata:
  skill_kind: metric
  source_lib: torchmetrics
  import_path: torchmetrics.image.SpatialDistortionIndex
  source: library_introspection
---

# 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

```python
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

```python
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)`.