# dice_coefficient

Python API: `luxonis_train.attached_modules.metrics.dice_coefficient`

分割掩码上的 Dice 系数。

## 类

### DiceCoefficient

用于分割掩码的 Dice 系数指标。

 * `输入:`: * `predictions` (`Tensor`): [B, nclasses, H, W] logits
    * `target` (`Tensor`): [B, nclasses, H, W] one-hot 掩码
 * `输出:`: * `Tensor`: 标量，或当 `average` 为 `"none"` 或 `None` 时为 [nclasses]。不包含背景类时，形状为 [nclasses − 1]。只有一个元素的结果是标量。
 * `公式:`: 每个预测像素获得具有最高 logit 的类别。对于图像 i 和类别 c，Pi, c 是预测像素集，Ti, c 是目标像素集。每个类别的分数是： Di, c = (2|Pi, c∩Ti, c|)/(|Pi, c| + |Ti, c|)
   `average` 结合了每个图像的类别。`"micro"` 在除法之前对所有类别的分子和分母求和。结果是所有图像的平均值。分母为零的分数是 `NaN`，平均值会跳过它。

> **参考**
> * 来源: 封装了 [torchmetrics](https://github.com/Lightning-AI/torchmetrics) (Apache-2.0)。
 * 许可证: Apache-2.0 (本项目)

> **注意**
> 当 `average` 为 `"micro"` 时，`torchmetrics` 的 `DiceScore` 构造函数会警告其默认 `average` 将来的更改。此类别始终传递 `average`，因此该警告不适用。

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

```yaml
- name: DDRNetSegmentationHead
  inputs: [DDRNet]
  metrics:
    - name: DiceCoefficient
      params:
        num_classes: 2
```

 * `兼容:`: * 节点: *
   [BiSeNetHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/bisenet_head.md)
       * [DDRNetSegmentationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ddrnet_segmentation_head.md)
       * [SegmentationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/segmentation_head.md)
       * [TransformerSegmentationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/transformer_segmentation_head.md)

#### 方法

##### init

```python
def __init__(num_classes: int, include_background: bool = True, average: Literal['micro', 'macro', 'weighted', 'none'] | None = 'micro', input_format: Literal['one-hot', 'index'] = 'index', **kwargs):
```

初始化指标和封装的 `DiceScore`。

参数

 * `num_classes` (`int`): 类别数量，输入中类别维度的大小。
 * `include_background` (`bool`): 类别 `0` 是否计入。当为 `False` 时，指标在评分前会丢弃类别 `0`。
 * `average` (`Literal['micro', 'macro', 'weighted', 'none'] | None`): 指标如何组合图像的类别： * `"micro"`: 来自所有类别总计数的单个分数。
    * `"macro"`: 每个类别分数的平均值。
    * `"weighted"`: 每个类别分数，按每个类别的目标像素份额加权。
    * `"none"` 或 `None`: 每个类别的单个分数。
 * `input_format` (`Literal['one-hot', 'index']`):
   [update](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/dice_coefficient.md)
   如何转换输入，请参阅
   [convert_format](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/dice_coefficient.md)。两种格式仅在目标像素没有类别或有多个类别时给出不同的结果。
 * `**kwargs`: 转发给
   [BaseMetric](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
   的关键字参数，例如 `node`。

##### compute

```python
def compute(self) -> Tensor:
```

返回自上次重置以来图像的 Dice 分数。

> **示例**
> 一个包含四个像素的图像。目标在前两个像素中包含类别 `0`，在后两个像素中包含类别 `1`。预测在第二个像素中是错误的。`"micro"` 平均值对两个类别的分子和分母求和：(2 + 4) ⁄ (3 + 5) = 0.75。

```pycon
>>> import torch
>>> target = torch.tensor([[[[1, 1, 0, 0]], [[0, 0, 1, 1]]]])
>>> logits = torch.tensor(
...     [[[[2.0, 0.0, 0.0, 0.0]], [[0.0, 1.0, 1.0, 1.0]]]]
... )
>>> metric = DiceCoefficient(num_classes=2)
>>> metric.update(logits, target)
>>> metric.compute().item()
0.75
```

返回

 * `Tensor`: 图像的平均分数，作为标量。对于 `average` 设置为 `"none"` 或 `None`，每个类别的平均分数，形状为 `[C]`，或不包含背景类别时为 `[C - 1]`。只有一个元素的结果是标量。

##### convert_format

```python
def convert_format(tensor: Tensor, is_target: bool = False) -> Tensor:
```

将类别分数转换为 `input_format` 的格式。

 * `"index"`: 返回维度 `1` 上的 `argmax`。该方法也对目标执行此操作，因此没有类别的目标像素变为类别 `0`。
 * `"one-hot"`，`is_target` 设置为 `False`: 返回输入形状和数据类型的 one-hot 张量。它在每个像素的 `argmax` 类别处保持 `1`。
 * `"one-hot"`，`is_target` 设置为 `True`: 返回未更改的 `tensor`。

> **示例**
> 形状为 `[1, 2, 1, 2]` 的 Logits 变为类别索引：

```pycon
>>> import torch
>>> logits = torch.tensor([[[[2.0, 0.0]], [[1.0, 3.0]]]])
>>> metric = DiceCoefficient(num_classes=2)
>>> metric.convert_format(logits).tolist()
[[[0, 1]]]
```

没有类别的目标像素变为类别 `0`：

```pycon
>>> empty = torch.zeros(1, 2, 1, 2)
>>> metric.convert_format(empty, is_target=True).tolist()
[[[0, 0]]]
```

参数

 * `tensor` (`Tensor`): 形状为 `[B, C, H, W]` 的 Logits 或掩码。
 * `is_target` (`bool`): `tensor` 是否为目标。

返回

 * `Tensor`: 对于 `"index"`，形状为 `[B, H, W]` 的类别索引，否则为形状为 `[B, C, H, W]` 的张量。

##### reset

```python
def reset(self):
```

重置封装的 `DiceScore` 的状态。

该方法不会为此指标调用 `torchmetrics` 的 `reset`。上次
[compute](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/dice_coefficient.md)
的缓存结果仍然存在，并且
[compute](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/dice_coefficient.md)
会返回它，直到下一次
[update](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/dice_coefficient.md)。

##### update

```python
def update(predictions: Tensor, target: Tensor):
```

转换一个批次并将其添加到封装的 `DiceScore`。

对于
`"index"`，[convert_format](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/dice_coefficient.md)
将两个张量转换为类别索引。对于 `"one-hot"`，它将预测转换为 one-hot 掩码，并且该方法将两个张量转换为 `bool`。封装的指标存储每个图像和类别的分子、分母和目标像素数量。

参数

 * `predictions` (`Tensor`): 形状为 `[B, C, H, W]` 的 Logits，节点的输出。
 * `target` (`Tensor`): 形状为 `[B, C, H, W]` 的 One-hot 掩码，任务的 `segmentation` 标签。

#### 属性

##### metric

##### supported_tasks
