# keypoint_visualizer

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

绘制关键点、连接它们的骨架以及它们所属的框。

## 类

### KeypointVisualizer

实例关键点及其边界框的可视化工具。

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

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

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

> **注意**
> 使用 [BBoxVisualizer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/bbox_visualizer.md) 绘制框，然后在其上方绘制关键点、可选的骨架线和可选的关键点索引。`FOMO` 任务在 `supported_tasks` 中，但 [FOMOHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/fomo_head.md) 在其数据包中没有 `boundingbox` 键。在该节点上，[BaseVisualizer.run](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/base_visualizer.md) 会引发 `RuntimeError`。

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

```yaml
- name: EfficientKeypointBBoxHead
  inputs: [RepPANNeck]
  visualizers:
    - name: KeypointVisualizer
```

 * `兼容:`: *
   使用者：[KeypointDetectionModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/keypoint_detection/v1/model.md)
    * 节点: *
      [EfficientKeypointBBoxHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/efficient_keypoint_bbox_head.md)
       * [FOMOHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/fomo_head.md)

#### 方法

##### init

```python
def __init__(visibility_threshold: float = 0.5, connectivity: list[tuple[int, int]] | None = None, visible_color: Color = 'red', nonvisible_color: Color | None = None, radius: int | None = None, draw_indices: bool = False, **kwargs):
```

初始化可视化工具并存储关键点选项。

参数

 * `visibility_threshold` (`float`):
   可见预测关键点的最低置信度。[draw_predictions](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/keypoint_visualizer.md)
   说明了可视化工具如何绘制其他关键点。
 * `connectivity` (`list[tuple[int, int]] | None`): 用于连接线的关键点索引对，即骨架。适用于预测和目标。`None` 不绘制任何线。
 * `visible_color` (`Color`): 可见预测关键点和所有目标关键点的颜色。例如 `"red"` 或 RGB 元组。
 * `nonvisible_color` (`Color | None`): 低于 `visibility_threshold` 的预测关键点的颜色。当为 `None` 时，可视化工具不会在它们的坐标处绘制它们。
 * `radius` (`int | None`): 关键点的半径，以像素为单位。当为 `None`
   时，[forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/keypoint_visualizer.md)
   会根据每个画布的大小选择它。
 * `draw_indices` (`bool`):
   是否在每个关键点旁边写入其索引。[draw_targets](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/keypoint_visualizer.md)
   说明了何时这会为目标关键点引发 `RuntimeError`。
 * `**kwargs`: 转发给
   [BBoxVisualizer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/bbox_visualizer.md)
   的关键字参数，例如 `labels`、`colors`、`width`、`scale` 和 `node`。

##### draw_keypoint_indices_pil

```python
def draw_keypoint_indices_pil(canvas: Tensor, keypoints: Tensor, offset: tuple[int, int] = (7, 7), colors: Color = 'red') -> Tensor:
```

使用 PIL 在每个关键点旁边写入其索引。

该方法将 `keypoints` 展平为 `(x, y, visibility)` 行，并按顺序从 `0` 开始编号。对于多个实例，编号不会为每个实例重新开始。它不读取可见性。

该方法将每个标签居中于其关键点，然后通过 `offset` 移动它。移动方向从一行到下一行循环：左下、右下、右上和左上。

> **示例**
> ```pycon
>>> import torch
>>> canvas = torch.zeros(3, 32, 32, dtype=torch.uint8)
>>> keypoints = torch.tensor([[16.0, 16.0, 1.0]])
>>> viz = KeypointVisualizer.draw_keypoint_indices_pil(
...     canvas, keypoints
... )
>>> viz.dtype, viz.shape
(torch.float32, torch.Size([3, 32, 32]))
>>> bool(viz[0].any()), bool(viz[1].any())
(True, False)
```

参数

 * `canvas` (`Tensor`): 形状为 `[3, H, W]` 的 `uint8` 图像。PIL 会对浮点图像引发 `TypeError`。
 * `keypoints` (`Tensor`): 每个关键点有三个值的像素关键点，例如 `[M, K, 3]` 或 `[M, 3 * K]`。该方法调用 `view`，因此无法将其视为 `[-1, 3]` 的张量会引发 `RuntimeError`。
 * `offset` (`tuple[int, int]`): 标签的垂直和水平偏移，以像素为单位。
 * `colors` (`Color`): 文本颜色。

返回

 * `Tensor`: CPU 上形状为 `[3, H, W]` 的新 `float32` 图像，值为 `0` 到 `255`，并绘制了索引。

##### draw_predictions

```python
def draw_predictions(canvas: Tensor, predictions: list[Tensor], draw_indices: bool = False, nonvisible_color: Color | None = None,
visible_color: Color = 'red', visibility_threshold: float = 0.5, radius: int | None = None, scale: float = 1.0, **kwargs) ->
Tensor:
```

在画布图像的副本上绘制批次的预测关键点。

对于每张图像，该方法将坐标乘以 `scale`。置信度低于 `visibility_threshold` 的关键点是不可见的。然后，该方法使用 `torchvision.utils.draw_keypoints` 分两步绘制关键点：

 * 第一步以 `visible_color` 绘制可见关键点，并将其钳制到图像中。它将每个不可见的关键点移动到左上角 `(0, 0)` 并在那里绘制。
 * 第二步仅在设置了 `nonvisible_color` 时运行。它以该颜色绘制不可见的关键点，并且不钳制它们。它将每个可见关键点移动到 `(0, 0)` 并在那里绘制。

当设置了 `draw_indices` 时，每一步还会使用 [draw_keypoint_indices_pil](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/keypoint_visualizer.md) 以该步骤的颜色在其使用的位置写入关键点索引。

> **示例**
> 可见关键点保持其坐标：

```pycon
>>> import torch
>>> canvas = torch.zeros(1, 3, 16, 16, dtype=torch.uint8)
>>> keypoints = [torch.tensor([[[8.0, 8.0, 0.9]]])]
>>> viz = KeypointVisualizer.draw_predictions(
...     canvas, keypoints, radius=1
... )
>>> viz[0, :, 8, 8].tolist(), viz[0, :, 0, 0].tolist()
([255, 0, 0], [0, 0, 0])
```

低于 `visibility_threshold` 的关键点移动到左上角：

```pycon
>>> hidden = [torch.tensor([[[8.0, 8.0, 0.1]]])]
>>> viz = KeypointVisualizer.draw_predictions(
...     canvas, hidden, radius=1
... )
>>> viz[0, :, 8, 8].tolist(), viz[0, :, 0, 0].tolist()
([0, 0, 0], [255, 0, 0])
```

参数

 * `canvas` (`Tensor`): 形状为 `[B, 3, H, W]` 的 `uint8` 图像。该方法不修改它。
 * `predictions` (`list[Tensor]`): 每张图像一个张量，形状为 `[M_i, K, 3]`。每个关键点是 `(x, y, confidence)`。坐标是未缩放图像的像素。
 * `draw_indices` (`bool`): 是否在每个关键点旁边写入其索引。
 * `nonvisible_color` (`Color | None`): 第二步的颜色。`None` 跳过第二步。
 * `visible_color` (`Color`): 第一步的颜色。`kwargs` 中的 `colors` 键会替换关键点的颜色，但不会替换索引的颜色。
 * `visibility_threshold` (`float`): 可见关键点的最低置信度。
 * `radius` (`int | None`): 关键点的半径，以像素为单位。当为 `None` 时，`torchvision` 会对至少有一个关键点的图像引发 `TypeError`。
 * `scale` (`float`): 坐标的乘数。传递缩放画布的因子。
 * `**kwargs`: `torchvision.utils.draw_keypoints` 的关键字参数，例如 `connectivity` 和 `width`。

返回

 * `Tensor`: 形状与 `canvas` 相同的新张量，并绘制了关键点。

##### draw_targets

```python
def draw_targets(canvas: Tensor, targets: Tensor, draw_indices: bool = False, colors: Color = 'red', **kwargs) -> Tensor:
```

在画布图像的副本上绘制批次的目标关键点。

图像 `i` 的关键点是 `targets` 中第一列等于 `i` 的行。[draw_keypoint_labels](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/utils.md) 将它们从归一化坐标转换为像素坐标，并使用画布大小和 `torchvision.utils.draw_keypoints` 绘制它们。它绘制每个关键点，无论其可见性如何。

> **示例**
> ```pycon
>>> import torch
>>> canvas = torch.zeros(1, 3, 16, 16, dtype=torch.uint8)
>>> targets = torch.tensor([[0, 0.5, 0.5, 2.0]])
>>> viz = KeypointVisualizer.draw_targets(
...     canvas, targets, radius=1
... )
>>> viz[0, :, 8, 8].tolist(), viz[0, :, 0, 0].tolist()
([255, 0, 0], [0, 0, 0])
```

参数

 * `canvas` (`Tensor`): 形状为 `[B, 3, H, W]` 的 `uint8` 图像。该方法不修改它。
 * `targets` (`Tensor`): 形状为 `[N, 1 + 3 * K]` 的关键点，行格式为 `[batch_index, x_1, y_1, v_1, ..., v_K]`。坐标归一化到 `[0, 1]`。
 * `draw_indices` (`bool`): 是否使用
   [draw_keypoint_indices_pil](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/keypoint_visualizer.md)
   在每个关键点旁边写入其索引。当图像有多个实例且 `K` 大于 `1` 时，该方法会因 `RuntimeError` 而失败。
 * `colors` (`Color`): 关键点和索引的颜色。
 * `**kwargs`: `torchvision.utils.draw_keypoints` 的关键字参数，例如 `radius` 和 `connectivity`。

返回

 * `Tensor`: 形状与 `canvas` 相同的新张量，并绘制了关键点。

##### forward

```python
def forward(prediction_canvas: Tensor, target_canvas: Tensor, keypoints: list[Tensor], boundingbox: list[Tensor], target_keypoints: Tensor | None, target_boundingbox: Tensor | None, **kwargs) -> tuple[Tensor, Tensor] | Tensor:
```

绘制预测框和关键点，并在给定目标时绘制目标。

[BBoxVisualizer.draw_predictions](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/bbox_visualizer.md)
绘制框，[draw_predictions](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/keypoint_visualizer.md)
在其上方绘制关键点。当设置了 `target_boundingbox`
时，[BBoxVisualizer.draw_targets](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/bbox_visualizer.md)
绘制目标框。当设置了 `target_keypoints`
时，[draw_targets](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/keypoint_visualizer.md)
以 `visible_color` 在其上方绘制目标关键点。

当 `radius` 为 `None` 时，半径来自每个画布的大小。当两边都小于 `96` 像素时为 `1`，当一边大于 `512` 像素时为 `5`，否则为 `2`。

> **示例**
> ```pycon
>>> import torch
>>> visualizer = KeypointVisualizer(
...     labels=["person"], colors=["red"]
... )
>>> canvas = torch.zeros(1, 3, 16, 16, dtype=torch.uint8)
>>> boxes = [torch.tensor([[2.0, 2.0, 14.0, 14.0, 0.9, 0.0]])]
>>> keypoints = [torch.tensor([[[8.0, 8.0, 0.9]]])]
>>> visualizer(canvas, canvas, keypoints, boxes, None, None).shape
torch.Size([1, 3, 16, 16])
>>> targets = torch.tensor([[0, 0.5, 0.5, 2.0]])
>>> len(
...     visualizer(canvas, canvas, keypoints, boxes, targets, None)
... )
2
```

参数

 * `prediction_canvas` (`Tensor`): 形状为 `[B, 3, H, W]` 的 `uint8` 图像，用于绘制预测。
 * `target_canvas` (`Tensor`): 形状为 `[B, 3, H, W]` 的 `uint8` 图像，用于绘制目标。
 * `keypoints` (`list[Tensor]`): 每张图像一个张量，形状为 `[M_i, K, 3]`。每个关键点是 `(x, y, confidence)`，其中 `x` 和 `y` 以像素为单位。[draw_predictions](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/keypoint_visualizer.md) 按 `scale` 因子缩放坐标。
 * `boundingbox` (`list[Tensor]`): 每张图像一个张量，形状为 `[M_i, 6]`，行格式为 `[x1, y1, x2, y2, conf, class]`，以像素为单位。[BBoxVisualizer.draw_predictions](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/bbox_visualizer.md) 按 `scale` 因子缩放它们。
 * `target_keypoints` (`Tensor | None`): 形状为 `[N, 1 + 3 * K]` 的关键点，行格式为 `[batch_index, x_1, y_1, v_1, ..., v_K]`。坐标归一化到 `[0, 1]`。当批次没有 `keypoints` 标签时为 `None`。
 * `target_boundingbox` (`Tensor | None`): 形状为 `[N, 6]` 的框，行格式为 `[batch_index, class, x, y, w, h]`，`xywh` 归一化到 `[0, 1]`。当批次没有 `boundingbox` 标签时为 `None`。
 * `**kwargs`: `torchvision.utils.draw_keypoints` 的关键字参数，例如 `width`。该方法将它们传递给 [draw_predictions](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/keypoint_visualizer.md) 和 [draw_targets](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/keypoint_visualizer.md)。该方法也按名称传递的键（例如 `radius` 或 `connectivity`）会引发 `TypeError`。[BaseVisualizer.run](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/base_visualizer.md) 不传递任何参数。

返回

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

#### 属性

##### supported_tasks
