# reconstruction_segmentation_loss

Python API: `luxonis_train.attached_modules.losses.reconstruction_segmentation_loss`

DRAEM 损失，它将重建的 L2 和结构相似性误差添加到异常掩码上的焦点损失中。

该模块还包含损失使用的结构相似性 (SSIM) 辅助函数。

## 类

### ReconstructionSegmentationLoss

[DiscSubNetHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/discsubnet_head/discsubnet_head.md)
的重建和异常分割损失。

该损失遵循 [DRAEM](https://arxiv.org/abs/2108.07610)。它将重建图像与干净图像进行比较，并将预测的异常分割与异常掩码进行比较。

 * `输入:`: * `predictions` (`Tensor`): [B, 2, H, W] 异常 logits
    * `reconstruction` (`Tensor`): [B, 3, H, W] 重建图像
    * `target_original_segmentation` (`Tensor`): [B, 3, H, W] 干净图像
    * `target_segmentation` (`Tensor`): [B, 2, H, W] one-hot 异常掩码
 * `输出:`: * `Tensor`: 标量总损失，当 `reduction` 为 `"none"` 时为 [B, H, W]
    * `dict[str, Tensor]`: 子损失 `l2_loss`、`ssim_loss`、`focal_loss`
 * `公式:`: r 是重建，x 是干净图像，z 是 logits，y 是 one-hot 掩码： L = MSE(r, x) + (1 − SSIM(r, x)) + FL(z, y) MSE 是所有元素的均值。SSIM 是来自
   [ssim](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/reconstruction_segmentation_loss.md)
   的映射均值，使用 11×11 高斯窗口。FL 是
   [SoftmaxFocalLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/softmax_focal_loss.md)，带有
   `alpha`、`gamma`、`smooth` 和 `reduction`。

> **参考**
> * 来源：本项目。
 * 许可证：Apache-2.0 (本项目)

> **注意事项**
> 焦点项来自没有节点的内部 [SoftmaxFocalLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/softmax_focal_loss.md)。SSIM 项在 `float32` 中运行，自动转换关闭，并从 `reconstruction` 估计动态范围。子损失未分离。

> **示例**
> 附加到 `model.nodes` 中的 `DiscSubNetHead`：

```yaml
- name: DiscSubNetHead
  inputs: [RecSubNet]
  losses:
    - name: ReconstructionSegmentationLoss
```

 * `兼容:`: *
   使用者：[AnomalyDetectionModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/anomaly_detection/v1/model.md)
    * 节点：[DiscSubNetHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/discsubnet_head/discsubnet_head.md)

#### 方法

##### init

```python
def __init__(alpha: float = 1, gamma: float = 2.0, reduction: Literal['none', 'mean', 'sum'] = 'mean', smooth: float = 1e-05, **kwargs):
```

初始化 L2、SSIM 和焦点损失。

参数

 * `alpha` (`float`):
   [SoftmaxFocalLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/softmax_focal_loss.md)
   的因子 α。它缩放每个像素的焦点损失。
 * `gamma` (`float`):
   [SoftmaxFocalLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/softmax_focal_loss.md)
   的焦点指数 γ。值越大，对头部已经很好分类的像素的权重越小。
 * `reduction` (`Literal['none', 'mean', 'sum']`):
   [SoftmaxFocalLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/softmax_focal_loss.md)
   如何减少像素损失。当为 `"none"` 时，焦点项和总损失的形状为 `[B, H, W]`。
 * `smooth` (`float`):
   [SoftmaxFocalLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/softmax_focal_loss.md)
   的标签平滑。当 `smooth` 不在 `[0, 1]` 中时，其构造函数会引发 `ValueError`。
 * `**kwargs`: 转发给
   [BaseLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/base_loss.md)
   的关键字参数，例如 `node` 和 `final_loss_weight`。

##### forward

```python
def forward(predictions: Tensor, reconstruction: Tensor, target_original_segmentation: Tensor, target_segmentation: Tensor) -> tuple[Tensor, dict[str, Tensor]]:
```

计算重建和分割损失。

当 `predictions` 的通道少于 `2` 或其形状与 `target_segmentation`
的形状不匹配时，[SoftmaxFocalLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/softmax_focal_loss.md)
会引发 `ValueError`。

> **示例**
> 完美的重建使 L2 和 SSIM 项为 `0`。零 logits 使焦点项为 − (1 − 0.5)2ln0.5 ≈ 0.1733：

```pycon
>>> import torch
>>> loss = ReconstructionSegmentationLoss()
>>> image = torch.linspace(0, 1, 48).reshape(1, 3, 4, 4)
>>> logits = torch.zeros(1, 2, 4, 4)
>>> mask = torch.zeros(1, 2, 4, 4)
>>> mask[:, 0] = 1
>>> total, sub_losses = loss(logits, image, image, mask)
>>> sorted(sub_losses)
['focal_loss', 'l2_loss', 'ssim_loss']
>>> round(total.item(), 4)
0.1733
```

参数

 * `predictions` (`Tensor`): 形状为 `[B, C, H, W]` 的异常 logits，其中 `C` 至少为 `2`。节点的 `segmentation` 输出。
 * `reconstruction` (`Tensor`): 形状为 `[B, 3, H, W]` 的重建图像。节点的 `reconstruction` 输出。
 * `target_original_segmentation` (`Tensor`): 形状与 `reconstruction` 相同的干净图像。任务的 `original_segmentation` 标签。
 * `target_segmentation` (`Tensor`): 形状与 `predictions` 相同的 one-hot 异常掩码。任务的 `segmentation` 标签。

返回

 * `tuple[Tensor, dict[str, Tensor]]`: 三个项的总和，以及一个将 `"l2_loss"`、`"ssim_loss"` 和 `"focal_loss"` 映射到这些项的字典。L2 和 SSIM
   项是标量。焦点项和总和是标量，或者当 `reduction` 为 `"none"` 时形状为 `[B, H, W]`。

#### 属性

##### loss_focal

##### loss_l2

##### loss_ssim

##### node

##### supported_tasks

### SSIM

结构不相似性损失，1 − SSIM。

该模块调用
[ssim](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/reconstruction_segmentation_loss.md)，使用标准差为
`1.5` 的高斯窗口，并返回 1 减去结果。它缓存上次输入的通道数的窗口。

#### 方法

##### init

```python
def __init__(window_size: int = 11, size_average: bool = True, val_range: float | None = None):
```

使用一个通道的窗口初始化损失。

参数

 * `window_size` (`int`): 正方形高斯窗口的边长，以像素为单位。
 * `size_average` (`bool`):
   [forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/reconstruction_segmentation_loss.md)
   是否对整个批次进行平均。当为 `False` 时，它为每个图像返回一个值。
 * `val_range` (`float | None`):
   [ssim](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/reconstruction_segmentation_loss.md)
   的动态范围。[forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/reconstruction_segmentation_loss.md)
   不将其传递给
   [ssim](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/reconstruction_segmentation_loss.md)，因此
   [ssim](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/reconstruction_segmentation_loss.md)
   总是从 `img1` 估计动态范围。

##### forward

```python
def forward(img1: Tensor, img2: Tensor) -> Tensor:
```

返回两个图像批次的 SSIM 的一减去结果。

该方法关闭自动转换并将两个批次都转换为 `float32`。当 `img1` 的通道数与缓存窗口不同时，该方法会构建一个新窗口并将其缓存。

> **示例**
> ```pycon
>>> import torch
>>> loss = SSIM()
>>> image = torch.linspace(0, 1, 768).reshape(1, 3, 16, 16)
>>> loss(image, image).item()
0.0
>>> round(loss(image, 1 - image).item(), 4)
0.7642
```

参数

 * `img1` (`Tensor`): 形状为 `[B, C, H, W]` 的图像。[ssim](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/reconstruction_segmentation_loss.md) 从它们估计动态范围。
 * `img2` (`Tensor`): 形状与 `img1` 相同的图像。

返回

 * `Tensor`: 平均 SSIM 作为标量，或者当 `size_average` 为 `False` 时形状为 `[B]`。对于相同的图像为 `1`。

## 函数

### create_window

```python
def create_window(window_size: int, channel: int = 1) -> Tensor:
```

为 [ssim](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/reconstruction_segmentation_loss.md) 构建一个归一化的 2D 高斯窗口。

该窗口是 1D [gaussian](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/reconstruction_segmentation_loss.md) 与其自身的外部积。标准差始终为 `1.5`。每个通道获得相同的窗口。

> **示例**
> ```pycon
>>> import torch
>>> window = create_window(11, channel=3)
>>> window.shape
torch.Size([3, 1, 11, 11])
>>> torch.allclose(window.sum(dim=(1, 2, 3)), torch.ones(3))
True
```

参数

 * `window_size` (`int`): 正方形窗口的边长，以像素为单位。
 * `channel` (`int`): 通道数。

返回

 * `Tensor`: 形状为 `[channel, 1, window_size, window_size]` 的 `float32` 窗口，即分组卷积的权重形状。每个通道的权重总和为 `1`。

### gaussian

```python
def gaussian(window_size: int, sigma: float) -> Tensor:
```

构建一个 `window_size` 样本的归一化 1D 高斯。

样本 i 获得权重 exp⎛⎝ − ((i − c)2)/(2σ2)⎞⎠，其中中心 c 在 `window_size // 2`。然后函数将权重除以它们的总和。对于偶数 `window_size`，中心是两个中间样本中的右侧一个。

> **示例**
> ```pycon
>>> [round(weight, 4) for weight in gaussian(3, 1.5).tolist()]
[0.3078, 0.3844, 0.3078]
```

参数

 * `window_size` (`int`): 样本数。
 * `sigma` (`float`): 标准差 σ，以样本为单位。

返回

 * `Tensor`: 形状为 `[window_size]` 的权重，总和为 `1`。

### ssim

```python
def ssim(img1: Tensor, img2: Tensor, window_size: int = 11, window: Tensor | None = None, size_average: bool = True, val_range:
float | None = None) -> Tensor:
```

计算两个图像批次的结构相似性 (SSIM)。

窗口过滤两个批次的每个通道，并进行零填充。过滤器给出局部均值 μ1 和 μ2，局部方差 σ21 和 σ22，以及局部协方差 σ12。SSIM 映射为

SSIM = ((2μ1μ2 + C1)(2σ12 + C2))/((μ21 + μ22 + C1)(σ21 + σ22 + C2))

其中 C1 = (0.01L)2 和 C2 = (0.03L)2，L 为动态范围。

> **示例**
> ```pycon
>>> import torch
>>> image = torch.linspace(0, 1, 64).reshape(1, 1, 8, 8)
>>> ssim(image, image).item()
1.0
>>> round(ssim(image, 1 - image).item(), 4)
0.0926
```

参数

 * `img1` (`Tensor`): 形状为 `[B, C, H, W]` 的图像。
 * `img2` (`Tensor`): 形状与 `img1` 相同的图像。
 * `window_size` (`int`): 窗口的边长。填充始终为 `window_size // 2`，即使 `window` 具有不同的大小。
 * `window` (`Tensor | None`): 形状为 `[C, 1, k, k]` 的过滤器权重，例如来自
   [create_window](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/reconstruction_segmentation_loss.md)。当为
   `None` 时，函数会构建一个边长为 `min(window_size, H, W)` 的窗口。
 * `size_average` (`bool`): 是否返回整个映射的均值。当为 `False` 时，函数返回每个图像的均值。
 * `val_range` (`float | None`): 动态范围 L。当为 `None` 时，函数从 `img1` 估计 L 为最大值减去最小值。当 `img1` 的值高于 `128` 时，最大值为 `255`，否则为 `1`。当 `img1`
   的值低于 `-0.5` 时，最小值为 `-1`，否则为 `0`。

返回

 * `Tensor`: 平均 SSIM 作为标量，或者当 `size_average` 为 `False` 时形状为 `[B]`。对于相同的图像为 `1`。
