# segmentation_visualizer

Python API: `luxonis_train.attached_modules.visualizers.segmentation_visualizer`

将分割掩码混合到图像中的可视化工具。

## 类

### SegmentationVisualizer

语义分割和异常掩码的可视化工具。

左图显示目标。右图显示预测。

 * `输入:`: * `prediction_canvas`, `target_canvas` (`Tensor`): [B, 3, H, W]
    * `predictions` (`Tensor`): [B, nclasses, H, W] logits
    * `target` (`Tensor | None`): [B, nclasses, H, W] one-hot
 * `输出:`: * `Tensor | tuple[Tensor, Tensor]`: [B, 3, H, W]，当给定目标时为一对

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

> **注意事项**
> 每个预测像素都获得具有最高 logit 的类别。对于一个类别，当其 logit 的 sigmoid 至少为 `0.5` 时，像素获得该类别。可视化工具将每种类别的一种颜色混合到图像中。在 `anomaly_detection` 节点上，它读取 `segmentation` 标签。

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

```yaml
- name: DDRNetSegmentationHead
  inputs: [DDRNet]
  visualizers:
    - name: SegmentationVisualizer
```

 * `兼容:`: * 使用者: *
   [AnomalyDetectionModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/anomaly_detection/v1/model.md)
       * [SegmentationModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/segmentation/v1/model.md)
    * 节点: *
      [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)
       * [DiscSubNetHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/discsubnet_head/discsubnet_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__(colors: Color | list[Color] | None = None, background_class: int | None = 0, background_color: Color = '#000000', alpha: float = 0.6, **kwargs):
```

初始化可视化工具并存储颜色选项。

参数

 * `colors` (`Color | list[Color] | None`): 每种类别的一种颜色，按类别索引的顺序排列。单个颜色变为一个颜色列表。当为
   `None`，或当颜色数量不是类别数量时，[forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/segmentation_visualizer.md)
   使用
   [BaseVisualizer.colormap](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/base_visualizer.md)
   的颜色。它在第一次调用时记录警告。
 * `background_class` (`int | None`): 获得 `background_color` 的类别索引。它仅在
   [forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/segmentation_visualizer.md)
   使用颜色映射颜色且节点具有多个类别时适用。`None` 为每个类别提供颜色映射颜色。
 * `background_color` (`Color`): 背景类别的颜色。
 * `alpha` (`float`): 掩码的不透明度，从 `0`（透明）到 `1`（不透明）。
 * `**kwargs`: 转发给
   [BaseVisualizer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/base_visualizer.md)
   的关键字参数，例如 `scale` 和 `node`。

##### draw_predictions

```python
def draw_predictions(canvas: Tensor, predictions: Tensor, alpha: float, colors: list[Color], scale: float = 1.0) -> Tensor:
```

在画布副本上绘制一批预测掩码。

对于每个图像，[seg_output_to_bool](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/segmentation.md)
将 logits 转换为每个类别的一个布尔掩码。对于多个类别，每个像素获得具有最高 logit 的类别。对于一个类别，当其 logit 的 sigmoid 至少为 `0.5`
时，像素获得该类别。[potentially_upscale_masks](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/utils.md)
按 `scale`
调整掩码大小，[draw_segmentation_targets](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/utils.md)
将它们混合到图像中。

> **示例**
> 第一个像素列是类别 `0`，第二个是类别 `1`。掩码大小加倍。

```pycon
>>> import torch
>>> canvas = torch.zeros(1, 3, 2, 4, dtype=torch.uint8)
>>> logits = torch.tensor([[[[2.0, 0.0]], [[0.0, 2.0]]]])
>>> viz = SegmentationVisualizer.draw_predictions(
...     canvas,
...     logits,
...     alpha=1.0,
...     colors=["red", "blue"],
...     scale=2.0,
... )
>>> viz[0, 0].tolist()
[[255, 255, 0, 0], [255, 255, 0, 0]]
```

参数

 * `canvas` (`Tensor`): 形状为 `[B, 3, H, W]` 的 `uint8` 图像。该方法不会更改它们。
 * `predictions` (`Tensor`): 形状为 `[B, n_classes, h, w]` 的 logits。掩码在按 `scale` 调整大小后必须具有画布大小。
 * `alpha` (`float`): 掩码的不透明度，从 `0` 到 `1`。
 * `colors` (`list[Color]`): 每种类别的一种颜色，至少与类别数量相同。
 * `scale` (`float`): 调整掩码大小的因子。

返回

 * `Tensor`: 一个与 `canvas` 形状相同的新张量，其中绘制了掩码。

##### draw_targets

```python
def draw_targets(canvas: Tensor, targets: Tensor, alpha: float, colors: list[Color], scale: float = 1.0) -> Tensor:
```

在画布副本上绘制一批目标掩码。

对于每个图像，该方法将目标转换为
`bool`，因此每个非零值都标记一个类别的像素。[potentially_upscale_masks](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/utils.md)
按 `scale`
调整掩码大小，[draw_segmentation_targets](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/utils.md)
将它们混合到图像中。

> **示例**
> ```pycon
>>> import torch
>>> canvas = torch.zeros(1, 3, 2, 2, dtype=torch.uint8)
>>> target = torch.tensor([[[[1, 0], [0, 0]], [[0, 1], [1, 1]]]])
>>> viz = SegmentationVisualizer.draw_targets(
...     canvas, target, alpha=1.0, colors=["red", "blue"]
... )
>>> viz[0, :, 0, 0].tolist(), viz[0, :, 0, 1].tolist()
([255, 0, 0], [0, 0, 255])
```

参数

 * `canvas` (`Tensor`): 形状为 `[B, 3, H, W]` 的 `uint8` 图像。该方法不会更改它们。
 * `targets` (`Tensor`): 形状为 `[B, n_classes, h, w]` 的 one-hot 掩码。掩码在按 `scale` 调整大小后必须具有画布大小。
 * `alpha` (`float`): 掩码的不透明度，从 `0` 到 `1`。
 * `colors` (`list[Color]`): 每种类别的一种颜色，至少与类别数量相同。
 * `scale` (`float`): 调整掩码大小的因子。

返回

 * `Tensor`: 一个与 `canvas` 形状相同的新张量，其中绘制了掩码。

##### forward

```python
def forward(prediction_canvas: Tensor, target_canvas: Tensor, predictions: Tensor, target: Tensor | None) -> tuple[Tensor, Tensor]
| Tensor:
```

绘制预测掩码，并在给定目标掩码时绘制目标掩码。

该方法首先选择类别颜色。当列表中包含节点每个类别的一种颜色时，它使用 `colors`。否则，它使用 [BaseVisualizer.colormap](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/base_visualizer.md) 的颜色，并在第一次调用时记录警告。对于多个类别，`background_class` 随后获得 `background_color`。[draw_predictions](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/segmentation_visualizer.md) 和 [draw_targets](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/segmentation_visualizer.md) 按 `scale` 因子调整掩码大小并绘制它们。

参数

 * `prediction_canvas` (`Tensor`): 形状为 `[B, 3, H, W]` 的 `uint8` 图像，用于绘制预测。
 * `target_canvas` (`Tensor`): 形状为 `[B, 3, H, W]` 的 `uint8` 图像，用于绘制目标。
 * `predictions` (`Tensor`): 形状为 `[B, n_classes, h, w]` 的 logits，节点的主要输出。
 * `target` (`Tensor | None`): 形状为 `[B, n_classes, h, w]` 的 one-hot 掩码，即 `segmentation` 标签。当批次没有此类标签时为 `None`。

返回

 * `tuple[Tensor, Tensor] | Tensor`: 当 `target` 为 `None` 时为预测图像，否则为 `(targets, predictions)` 对。每个图像的形状与其画布相同。

#### 属性

##### required_labels

[forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/segmentation_visualizer.md) 的 `target` 参数的标签。

[BaseAttachedModule.get_parameters](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md) 读取此集合以获取 [forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/segmentation_visualizer.md) 的 `target` 参数，该参数没有标签后缀。在 `anomaly_detection` 节点上，该集合仅包含 `"segmentation"`，因此 `target` 接收异常掩码。在其他节点上，它包含任务的标签。当可视化工具没有任务时，该属性会引发 `RuntimeError`。

##### supported_tasks

## 属性

### log_disable
