# instance_segmentation_visualizer

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

绘制实例掩码及其边界框。

## 类

### InstanceSegmentationVisualizer

实例分割预测和目标的视觉化工具。

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

 * `输入:`: * `prediction_canvas`, `target_canvas` (`Tensor`): [B, 3, H, W]
    * `boundingbox` (`list[Tensor]`): 每张图像 [Mi, 6]，`[x1, y1, x2, y2, conf, class]`，像素
    * `instance_segmentation` (`list[Tensor]`): 每张图像 [Mi, H, W]，二值
    * `target_boundingbox` (`Tensor | None`): [N, 6]，`[batch, class, x, y, w, h]`，`xywh` 归一化
    * `target_instance_segmentation` (`Tensor | None`): [N, H, W]，每个目标框一个
 * `输出:`: * `Tensor | tuple[Tensor, Tensor]`: [B, 3, H, W]，当给定两个目标时为 `(targets, predictions)` 对

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

> **注意**
> 使用 `torchvision` 叠加掩码，并在顶部绘制每个掩码的边界框。视觉化工具存储 `fill`、`font` 和 `font_size` 选项，但不使用它们。

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

```yaml
- name: PrecisionSegmentBBoxHead
  inputs: [RepPANNeck]
  visualizers:
    - name: InstanceSegmentationVisualizer
```

 * `兼容:`: * 使用者:
   [InstanceSegmentationModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/instance_segmentation/v1/model.md)
    * 节点:
      [PrecisionSegmentBBoxHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/precision_seg_bbox_head.md)

#### 方法

##### init

```python
def __init__(labels: dict[int, str] | list[str] | None = None, draw_labels: bool = True, draw_scores: bool = False, colors: dict[str, Color] | list[Color] | None = None, fill: bool = False, width: int | None = None, font: str | None = None, font_size: int | None = None, alpha: float = 0.6, **kwargs):
```

初始化视觉化工具并解析类名和颜色。

参数

 * `labels` (`dict[int, str] | list[str] | None`): 要绘制的类名。字典将类索引映射到名称。列表按位置映射。当 `None` 或为空时，名称来自节点的 `classes`，因此视觉化工具需要一个 `node`。
 * `draw_labels` (`bool`): 是否在每个框旁边绘制类名。适用于预测和目标。
 * `draw_scores` (`bool`): 是否在每个预测框的标签中写入置信度，保留两位小数。仅适用于预测。如果没有 `draw_labels`，标签就是置信度本身。
 * `colors` (`dict[str, Color] | list[Color] | None`): 掩码和边界框的颜色。字典将类名映射到颜色。列表按类索引映射。当 `None` 时，每个类从
   [get_color](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/utils.md)
   获取一个不同的颜色，以其索引为种子。
 * `fill` (`bool`): 绘制方法不读取它。
 * `width` (`int | None`): 边界框的线宽，以像素为单位。当 `None` 或 `0` 时，宽度是较小画布边长百分之一，向下取整，且至少为 `1`。
 * `font` (`str | None`): 绘制方法不读取它。
 * `font_size` (`int | None`): 绘制方法不读取它。
 * `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, pred_bboxes: list[Tensor], pred_masks: list[Tensor], width: int | None, label_dict: Mapping[int, str], color_dict: dict[str, Color], draw_labels: bool, draw_scores: bool, alpha: float, scale: float = 1.0) -> Tensor:
```

在画布图像的副本上绘制批次的预测掩码和边界框。

对于每张图像，该方法将边界框坐标乘以 `scale`，并使用最近邻插值将掩码大小调整为 `scale`。它使用 `torchvision.utils.draw_segmentation_masks` 叠加掩码。然后使用
`torchvision.utils.draw_bounding_boxes`
在顶部绘制边界框。每个掩码和边界框都获得其类别的颜色。[get_prediction_labels](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/utils.md)
构建边界框标签。

当 `torchvision` 对图像引发 `ValueError` 时，该方法会记录警告并保持该图像在 `canvas` 中的原样。掩码大小与画布大小不匹配是其中一个原因。

> **示例**
> ```pycon
>>> import torch
>>> canvas = torch.zeros(1, 3, 16, 16, dtype=torch.uint8)
>>> boxes = [torch.tensor([[4.0, 4.0, 12.0, 12.0, 0.9, 0.0]])]
>>> masks = torch.zeros(1, 16, 16, dtype=torch.uint8)
>>> masks[:, 4:12, 4:12] = 1
>>> viz = InstanceSegmentationVisualizer.draw_predictions(
...     canvas,
...     boxes,
...     [masks],
...     width=1,
...     label_dict={0: "cat"},
...     color_dict={"cat": (255, 0, 0)},
...     draw_labels=False,
...     draw_scores=False,
...     alpha=0.5,
... )
>>> viz[0, :, 8, 8].tolist(), viz[0, :, 0, 0].tolist()
([127, 0, 0], [0, 0, 0])
```

参数

 * `canvas` (`Tensor`): 形状为 `[B, 3, H, W]` 的 `uint8` 图像。该方法不修改它。
 * `pred_bboxes` (`list[Tensor]`): 每张图像一个张量，形状为 `[M_i, 6]`，行格式为 `[x1, y1, x2, y2, conf, class]`。坐标是未缩放图像的像素。
 * `pred_masks` (`list[Tensor]`): 每张图像一个张量，形状为 `[M_i, H_0, W_0]`，每个边界框一个二值掩码。`H_0` 和 `W_0` 是未缩放图像的大小。
 * `width` (`int | None`): 边界框的线宽，以像素为单位。当 `None` 或 `0` 时，宽度是较小画布边长百分之一，向下取整，且至少为 `1`。
 * `label_dict` (`Mapping[int, str]`): 类索引到类名。每个预测类都必须在此处有一个名称。
 * `color_dict` (`dict[str, Color]`): 类名到颜色。每个预测类都必须在此处有一种颜色。
 * `draw_labels` (`bool`): 是否在每个边界框的标签中写入类名。
 * `draw_scores` (`bool`): 是否在每个边界框的标签中写入置信度，保留两位小数。
 * `alpha` (`float`): 掩码的不透明度，从 `0`（透明）到 `1`（不透明）。
 * `scale` (`float`): 边界框坐标和掩码大小的乘数。传递缩放画布的因子。

返回

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

##### draw_targets

```python
def draw_targets(canvas: Tensor, target_bboxes: Tensor, target_masks: Tensor, width: int | None, label_dict: Mapping[int, str],
color_dict: dict[str, Color], draw_labels: bool, alpha: float, scale: float = 1.0) -> Tensor:
```

在画布图像的副本上绘制批次的目标掩码和边界框。

图像 `i` 的边界框和掩码是 `target_bboxes` 中批次索引等于 `i` 的行。该方法使用最近邻插值将掩码大小调整为 `scale` 并叠加它们。然后 [draw_bounding_box_labels](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/utils.md) 将边界框从归一化的 `xywh` 转换为像素 `xyxy`，并使用画布大小在顶部绘制它们。每个掩码和边界框都获得其类别的颜色，并且当设置 `draw_labels` 时，每个边界框都获得其类名。与 [draw_predictions](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/instance_segmentation_visualizer.md) 不同，此方法不捕获 `torchvision` 的 `ValueError`。

> **示例**
> ```pycon
>>> import torch
>>> canvas = torch.zeros(1, 3, 16, 16, dtype=torch.uint8)
>>> boxes = torch.tensor([[0, 0, 0.25, 0.25, 0.5, 0.5]])
>>> masks = torch.zeros(1, 16, 16, dtype=torch.uint8)
>>> masks[:, 4:12, 4:12] = 1
>>> viz = InstanceSegmentationVisualizer.draw_targets(
...     canvas,
...     boxes,
...     masks,
...     width=1,
...     label_dict={0: "cat"},
...     color_dict={"cat": (255, 0, 0)},
...     draw_labels=False,
...     alpha=1.0,
... )
>>> viz[0, :, 8, 8].tolist(), viz[0, :, 0, 0].tolist()
([255, 0, 0], [0, 0, 0])
```

参数

 * `canvas` (`Tensor`): 形状为 `[B, 3, H, W]` 的 `uint8` 图像。该方法不修改它。
 * `target_bboxes` (`Tensor`): 形状为 `[N, 6]` 的边界框，行格式为 `[batch_index, class, x, y, w, h]`。坐标是归一化到 `[0, 1]` 的 `xywh`。
 * `target_masks` (`Tensor`): 形状为 `[N, H_0, W_0]` 的二值掩码，每个目标边界框一个。`H_0` 和 `W_0` 是未缩放图像的大小。
 * `width` (`int | None`): 边界框的线宽，以像素为单位。当 `None` 或 `0` 时，宽度是较小画布边长百分之一，向下取整，且至少为 `1`。
 * `label_dict` (`Mapping[int, str]`): 类索引到类名。每个目标类都必须在此处有一个名称。
 * `color_dict` (`dict[str, Color]`): 类名到颜色。每个目标类都必须在此处有一种颜色。
 * `draw_labels` (`bool`): 是否在每个边界框旁边写入类名。
 * `alpha` (`float`): 掩码的不透明度，从 `0`（透明）到 `1`（不透明）。
 * `scale` (`float`): 掩码大小的乘数。传递缩放画布的因子。

返回

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

##### forward

```python
def forward(prediction_canvas: Tensor, target_canvas: Tensor, boundingbox: list[Tensor], instance_segmentation: list[Tensor], target_boundingbox: Tensor | None, target_instance_segmentation: Tensor | None) -> tuple[Tensor, Tensor] | Tensor:
```

绘制预测掩码和边界框，以及给定目标。

[draw_predictions](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/instance_segmentation_visualizer.md)
绘制预测，[draw_targets](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/instance_segmentation_visualizer.md)
绘制目标。两者都使用构造函数的选项和 `scale` 因子。

> **示例**
> ```pycon
>>> import torch
>>> visualizer = InstanceSegmentationVisualizer(
...     labels=["cat"], colors=["red"]
... )
>>> canvas = torch.zeros(1, 3, 16, 16, dtype=torch.uint8)
>>> boxes = [torch.tensor([[4.0, 4.0, 12.0, 12.0, 0.9, 0.0]])]
>>> masks = torch.zeros(1, 16, 16, dtype=torch.uint8)
>>> masks[:, 4:12, 4:12] = 1
>>> visualizer(canvas, canvas, boxes, [masks], None, None).shape
torch.Size([1, 3, 16, 16])
>>> targets = torch.tensor([[0, 0, 0.25, 0.25, 0.5, 0.5]])
>>> len(visualizer(canvas, canvas, boxes, [masks], targets, masks))
2
```

参数

 * `prediction_canvas` (`Tensor`): 形状为 `[B, 3, H, W]` 的 `uint8` 图像，用于绘制预测。
 * `target_canvas` (`Tensor`): 形状为 `[B, 3, H, W]` 的 `uint8` 图像，用于绘制目标。
 * `boundingbox` (`list[Tensor]`): 每张图像一个张量，形状为 `[M_i, 6]`，行格式为 `[x1, y1, x2, y2, conf, class]`，以像素为单位。
 * `instance_segmentation` (`list[Tensor]`): 每张图像一个张量，形状为 `[M_i, H_0, W_0]`，每个边界框一个二值掩码。`H_0` 和 `W_0` 是 `scale` 调整大小之前的图像大小。
 * `target_boundingbox` (`Tensor | None`): 形状为 `[N, 6]` 的边界框，行格式为 `[batch_index, class, x, y, w, h]`，`xywh` 归一化到 `[0, 1]`。当批次没有 `boundingbox` 标签时为 `None`。
 * `target_instance_segmentation` (`Tensor | None`): 形状为 `[N, H_0, W_0]` 的二值掩码，每个目标边界框一个。当批次没有 `instance_segmentation` 标签时为 `None`。

返回

 * `tuple[Tensor, Tensor] | Tensor`: 当 `target_boundingbox` 和 `target_instance_segmentation` 都设置时，返回绘制图像的 `(targets, predictions)` 对；否则只返回预测图像。

#### 属性

##### supported_tasks
