# bbox_visualizer

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

绘制边界框、类别标签和分数。

## 类

### BBoxVisualizer

可视化边界框预测和目标。

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

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

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

> **注意事项**
> 使用 `torchvision` 和本地标签/颜色辅助函数绘制框。可视化器存储 `fill`、`font` 和 `font_size` 选项，但不使用它们。

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

```yaml
- name: EfficientBBoxHead
  inputs: [RepPANNeck]
  visualizers:
    - name: BBoxVisualizer
```

 * `兼容:`: *
   由以下使用：[DetectionModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/detection/v1/model.md)
    * 节点： *
      [EfficientBBoxHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/efficient_bbox_head.md)
       * [PrecisionBBoxHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/precision_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, **kwargs):
```

初始化可视化器并解析类名和颜色。

参数

 * `labels` (`dict[int, str] | list[str] | None`): 要绘制的类名。字典将类索引映射到名称。列表按位置映射。当为 `None` 或为空时，名称来自节点的 `classes`，因此可视化器需要一个 `node`。
 * `draw_labels` (`bool`): 是否在每个框旁边绘制类名。默认为 `True`。
 * `draw_scores` (`bool`): 是否在标签中写入每个预测框的置信度，保留两位小数。仅适用于预测。如果没有 `draw_labels`，则标签仅为置信度。默认为 `False`。
 * `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`): 绘图方法不读取它。默认为 `False`。
 * `width` (`int | None`): 框的线宽，以像素为单位。当为 `None` 或 `0` 时，宽度是较小画布边长百分之一，向下取整，且至少为 `1`。
 * `font` (`str | None`): 绘图方法不读取它。默认为 `None`。
 * `font_size` (`int | None`): 绘图方法不读取它。默认为 `None`。
 * `**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: list[Tensor], scale: float = 1.0) -> Tensor:
```

在画布图像的副本上绘制一批预测框。

每个框都获得其类别的颜色。[get_prediction_labels](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/utils.md)
根据类名（如果设置了 `draw_labels`）和置信度（如果设置了 `draw_scores`）构建其标签。

当 `torchvision` 对图像引发 `ValueError` 时，该方法会记录警告并继续以输入画布作为输出。它会丢弃失败之前绘制的图像，并将剩余图像绘制到 `canvas` 中。

> **示例**
> ```pycon
>>> import torch
>>> visualizer = BBoxVisualizer(
...     labels=["cat"], colors=["red"], draw_labels=False
... )
>>> canvas = torch.zeros(1, 3, 8, 8, dtype=torch.uint8)
>>> boxes = [torch.tensor([[2.0, 2.0, 6.0, 6.0, 0.9, 0.0]])]
>>> viz = visualizer.draw_predictions(canvas, boxes)
>>> bool((viz[0, 0] == 255).any()), bool((viz[0, 1] == 255).any())
(True, False)
```

参数

 * `canvas` (`Tensor`): 形状为 `[B, 3, H, W]` 的 `uint8` 图像。
 * `predictions` (`list[Tensor]`): 每张图像一个张量，形状为 `[M_i, 6]`，行格式为 `[x1, y1, x2, y2, conf, class]`。坐标是未缩放图像的像素。
 * `scale` (`float`): 框坐标的乘数。传递缩放画布的因子。默认为 `1.0`。

返回

 * `Tensor`: 绘制了框的图像，与 `canvas` 形状相同。一个新张量，除非失败后，它就是 `canvas` 本身。

##### draw_targets

```python
def draw_targets(canvas: Tensor, targets: Tensor) -> Tensor:
```

在画布图像的副本上绘制一批目标框。

图像 `i` 的框是 `targets` 中第一列等于 `i` 的行。[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` 时获得其类名。

> **示例**
> ```pycon
>>> import torch
>>> visualizer = BBoxVisualizer(
...     labels=["cat"], colors=["red"], draw_labels=False
... )
>>> canvas = torch.zeros(1, 3, 8, 8, dtype=torch.uint8)
>>> targets = torch.tensor([[0, 0, 0.25, 0.25, 0.5, 0.5]])
>>> viz = visualizer.draw_targets(canvas, targets)
>>> viz.shape
torch.Size([1, 3, 8, 8])
>>> bool((viz[0, 0] == 255).any()), bool((viz[0, 1] == 255).any())
(True, False)
```

参数

 * `canvas` (`Tensor`): 形状为 `[B, 3, H, W]` 的 `uint8` 图像。该方法不修改它。
 * `targets` (`Tensor`): 形状为 `[N, 6]` 的框，行格式为 `[batch_index, class, x, y, w, h]`。坐标是归一化到 `[0, 1]` 的 `xywh`。

返回

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

##### forward

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

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

> **示例**
> ```pycon
>>> import torch
>>> visualizer = BBoxVisualizer(labels=["cat"], colors=["red"])
>>> canvas = torch.zeros(1, 3, 8, 8, dtype=torch.uint8)
>>> boxes = [torch.tensor([[2.0, 2.0, 6.0, 6.0, 0.9, 0.0]])]
>>> visualizer(canvas, canvas, boxes, None).shape
torch.Size([1, 3, 8, 8])
>>> targets = torch.tensor([[0, 0, 0.25, 0.25, 0.5, 0.5]])
>>> len(visualizer(canvas, canvas, boxes, targets))
2
```

参数

 * `prediction_canvas` (`Tensor`): 形状为 `[B, 3, H, W]` 的 `uint8` 图像，用于绘制预测。
 * `target_canvas` (`Tensor`): 形状为 `[B, 3, H, W]` 的 `uint8` 图像，用于绘制目标。
 * `predictions` (`list[Tensor]`): 每张图像一个张量，形状为 `[M_i, 6]`，行格式为 `[x1, y1, x2, y2, conf, class]`，以像素为单位。[draw_predictions](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/bbox_visualizer.md) 按 `scale` 因子缩放它们。
 * `targets` (`Tensor | None`): 形状为 `[N, 6]` 的框，行格式为 `[batch_index, class, x, y, w, h]`，`xywh` 归一化到 `[0, 1]`。当批次没有 `boundingbox` 标签时为 `None`。

返回

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

#### 属性

##### supported_tasks
