# efficient_keypoint_bbox_head

Python API: `luxonis_train.nodes.heads.efficient_keypoint_bbox_head`

YOLOv6 检测头，每个尺度都有一个关键点分支。

## 类

### EfficientKeypointBBoxHead

高效的目标和关键点检测头。

 * `输入:`: * `inputs` (`list[Tensor]`): 每个尺度 [B, Ci, Hi, Wi]
 * `输出:`: * 训练: * `features` (`list[Tensor]`): 每个尺度 [B, Ci, Hi, Wi]
       * `class_scores` (`Tensor`): [B, N, nclasses]
       * `distributions` (`Tensor`): [B, N, 4]，步幅单位的 `(l, t, r, b)`
       * `keypoints_raw` (`Tensor`): [B, N, 3**n*keypoints]
    * 评估: * `features` (`list[Tensor]`): 每个尺度 [B, Ci, Hi, Wi]
       * `class_scores` (`Tensor`): [B, N, nclasses]
       * `distributions` (`Tensor`): [B, N, 4]，步幅单位的 `(l, t, r, b)`
       * `keypoints_raw` (`Tensor`): [B, N, 3**n*keypoints]
       * `boundingbox` (`list[Tensor]`): 每张图像 [Mi, 6]，`[x1, y1, x2, y2, conf, class]`，像素
       * `keypoints` (`list[Tensor]`): 每张图像 [Mi, nkeypoints, 3]，`(x, y, conf)`，像素
       * `detections_pre_nms` (`Tensor`): [B, N, 5 + nclasses + 3**n*keypoints]，仅在请求时
    * 导出: * `boundingbox` (`list[Tensor]`): 每个尺度 [B, 5 + nclasses, Hi, Wi]
       * `keypoints` (`list[Tensor]`): 每个尺度 [B, 3n*keypoints, HiW*i]，`(x, y, conf)`，像素，`conf` 作为 logit

> **参考**
> * 来源：重新实现了 [YOLOv6: A Single-Stage Object Detection Framework for Industrial Applications](https://arxiv.org/abs/2209.02976)。
 * 许可证：Apache-2.0（本项目）

> **注意**
> 该头为 [EfficientBBoxHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/efficient_bbox_head.md) 的每个尺度添加了一个关键点分支。它解码了尺度锚点周围的关键点。NMS 保留了它保留的每个框的关键点。

 * `变体:`: 无。通过 `params` 配置节点。

> **示例**
> 配置中 `model.nodes` 部分的节点条目：

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

 * `兼容:`: * 必需标签: * `boundingbox`
       * `keypoints`
    * 使用者:
      [KeypointDetectionModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/keypoint_detection/v1/model.md)
    * 损失:
      [EfficientKeypointBBoxLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/efficient_keypoint_bbox_loss.md)
    * 指标: *
      [ConfusionMatrix](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/confusion_matrix/confusion_matrix.md)
       * [MeanAveragePrecision](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/mean_average_precision/mean_average_precision.md)
       * [ObjectKeypointSimilarity](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/object_keypoint_similarity.md)
       * [PrecisionRecallCurve](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/precision_recall_curve.md)
    * 可视化器:
      [KeypointVisualizer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/keypoint_visualizer.md)
    * 导出解析器: `YOLOExtendedParser`
    * 预训练权重:
      [EfficientBBoxHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/efficient_bbox_head.md)
      的框分支，通过 `weights: download`

#### 方法

##### init

```python
def __init__(n_heads: Literal[2, 3, 4] = 3, conf_thres: float = 0.25, iou_thres: float = 0.45, max_det: int = 300, **kwargs):
```

初始化框头和关键点分支。

每个关键点分支都有两个 `3x3`
[ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
层，带有批归一化和 SiLU，然后是一个 `1x1` 卷积，输出通道数为 `3 * n_keypoints`。所有分支的隐藏层都有 `in_channels[0] // 4` 和 `3 * n_keypoints`
中较大的通道数。`in_channels[0]` 属于第一个尺度。

参数

 * `n_heads` (`Literal[2, 3, 4]`): 尺度数量。头读取输入节点的最后 `n_heads` 个输出。`attach_index`
   参数替换此选择。该值通常等于颈部输出的数量。当输入节点提供的输出较少时，头会记录警告并使用该数量。默认为 `3`。
 * `conf_thres` (`float`): NMS 仅保留最大类别分数高于此值的框。该值必须在 `[0, 1]` 之间。默认为 `0.25`。
 * `iou_thres` (`float`): 当一个框与同一类别且分数更高的框的 IoU 高于此值时，NMS 会移除该框。该值必须在 `[0, 1]` 之间。默认为 `0.45`。
 * `max_det` (`int`): NMS 为每张图像保留的最大框数。默认为 `300`。
 * `**kwargs`:
   [EfficientBBoxHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/efficient_bbox_head.md)
   的关键字参数，例如 `bias_init_p`，以及
   [BaseNode](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
   的关键字参数，例如 `n_classes`、`n_keypoints` 和 `input_shapes`。

##### forward

```python
def forward(inputs: list[Tensor]) -> Packet[Tensor]:
```

运行框和关键点分支并构建数据包。

框分支的工作方式与
[EfficientBBoxHead.forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/efficient_bbox_head.md)
相同。每个尺度的关键点分支读取该尺度的输入特征图。它预测每个锚点处每个关键点的原始值 (tx, ty, tc)。头使用网格单位的锚点 (ax, ay) 和尺度的步幅 s 对它们进行解码：

x = (2tx + ax − 0.5) s，y = (2ty + ay − 0.5) s，c = σ(tc)

导出模式优先于训练模式。数据包取决于模式：

 * 导出模式：`"boundingbox"` 与
   [EfficientBBoxHead.forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/efficient_bbox_head.md)
   相同，以及 `"keypoints"`，每个尺度有一个形状为 `[B, 3 * n_keypoints, H_i * W_i]` 的张量。该张量包含每个关键点的 x、y 和 tc。导出模式跳过 sigmoid。
 * 训练模式：`"features"`、`"class_scores"` 和 `"distributions"` 与
   [EfficientBBoxHead.forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/efficient_bbox_head.md)
   相同，以及 `"keypoints_raw"`，其原始值形状为 `[B, N, 3 * n_keypoints]`。
 * 评估模式：训练键和 NMS 结果。`"boundingbox"` 为每张图像保存一个形状为 `[M_i, 6]` 的张量，行格式为 `[x1, y1, x2, y2, score, class]`。`"keypoints"`
   保存这些框的解码关键点，形状为 `[M_i, n_keypoints, 3]`。每个关键点包含 (x, y, c)。对于没有框的图像，`M_i` 为 `0`。调用
   [BaseDetectionHead.request_detections_pre_nms](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/base_detection_head.md)
   后，数据包还包含 NMS 输入 `"detections_pre_nms"`，形状为 `[B, N, 5 + n_classes + 3 * n_keypoints]`。

> **示例**
> ```pycon
>>> import torch
>>> from torch import Size
>>> from luxonis_train.nodes import EfficientKeypointBBoxHead
>>> sizes = [Size([1, 8, 32, 32]), Size([1, 16, 16, 16])]
>>> head = EfficientKeypointBBoxHead(
...     n_heads=2,
...     n_classes=3,
...     n_keypoints=5,
...     input_shapes=[{"features": sizes}],
...     original_in_shape=Size([3, 256, 256]),
... )
>>> out = head([torch.zeros(size) for size in sizes])
>>> out["keypoints_raw"].shape
torch.Size([1, 1280, 15])
```

一个新的头给每个类别的分数都是 `0.01`，低于 `conf_thres`。因此，在评估模式下，NMS 不保留任何框和关键点：

```pycon
>>> out = head.eval()([torch.zeros(size) for size in sizes])
>>> out["boundingbox"][0].shape, out["keypoints"][0].shape
(torch.Size([0, 6]), torch.Size([0, 5, 3]))
```

参数

 * `inputs` (`list[Tensor]`): 每个尺度一个特征图，形状为 `[B, C_i, H_i, W_i]`。

返回

 * `Packet[Tensor]`: 当前模式的数据包。

##### get_custom_head_config

```python
def get_custom_head_config(self) -> Params:
```

返回 NN Archive 的 NMS 设置和步幅。

子类会向此字典添加自己的键，例如 `"subtype"`。

返回

 * `Params`: 包含键 `"iou_threshold"`、`"conf_threshold"`、`"max_det"` 和 `"strides"` 的字典。它们分别保存 `iou_thres`、`conf_thres`、`max_det` 和 `stride`，其中 `stride` 是一个列表，每个尺度包含一个整数。

#### 属性

##### export_output_names

导出模型的输出名称。

导出模型有 `2 * n_heads` 个输出。默认名称是框的 `output1_yolov6` 到 `output{n_heads}_yolov6`，然后是关键点的 `kpt_output1` 到 `kpt_output{n_heads}`。`export_output_names` 参数仅在它包含恰好 `n_heads` 个名称时替换它们。此时，该值包含的名称少于导出模型输出的名称。每次给出默认名称时，头都会记录警告。该值从不为 `None`。

##### keypoint_heads

##### parser
