# efficient_keypoint_bbox_loss

Python API: `luxonis_train.attached_modules.losses.efficient_keypoint_bbox_loss`

[EfficientKeypointBBoxHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/efficient_keypoint_bbox_head.md)
的类别、边界框和关键点损失。

## 类

### EfficientKeypointBBoxLoss

[EfficientKeypointBBoxHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/efficient_keypoint_bbox_head.md)
的类别、边界框和关键点损失。

 * `输入:`: * `features` (`list[Tensor]`): 每个尺度的 [B, Ci, Hi, Wi]
    * `class_scores` (`Tensor`): [B, N, nclasses] sigmoid 分数
    * `distributions` (`Tensor`): [B, N, 4]，以步长单位表示的 `(l, t, r, b)`
    * `keypoints_raw` (`Tensor`): [B, N, 3**n*keypoints]，每个关键点的原始 `(x, y, v)`
    * `target_boundingbox` (`Tensor`): [M, 6]，`[batch, class, x, y, w, h]`，`xywh` 归一化
    * `target_keypoints` (`Tensor`): [M, 1 + 3**n*keypoints]，`[batch, x, y, v, ...]`，`x` 和 `y` 归一化
 * `输出:`: * `Tensor`: 标量总损失
    * `dict[str, Tensor]`: 子损失 `class`、`iou`、`regression` 和 `visibility`，不含损失权重
 * `公式:`: 类别项 Lcls 和边界框项 Liou 是
   [AdaptiveDetectionLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/adaptive_detection_loss.md)
   的两个项，每个项都除以 max(S, 1)。S
   是分配分数的总和。预热后，[TaskAlignedAssigner](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/assigners/tal_assigner.md)
   也会读取关键点。它将其 IoU 乘以对象关键点相似度。预热
   [ATSSAssigner](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/assigners/atss_assigner.md)
   忽略关键点。 关键点项只读取正锚点集 P。对于锚点 a 和关键点 i，预测位置 (x̂a, i, ŷa, i) 来自
   [dist2kpts_noscale](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/efficient_keypoint_bbox_loss.md)。目标位置
   (xa, i, ya, i) 是分配实例的关键点，除以锚点的步长。两个位置都在网格单位中。当目标可见性高于 `0` 时，va, i 为 `1`，否则为 `0`： Lkpt = (1)/(|P|)∑a ∈ P(∑iva, i(1 − exp( − da,
   i)))/(∑iva, i)，da, i = ((x̂a, i − xa, i)2 + (ŷa, i − ya, i)2)/(2 (2σi)2 Aa) σi 是关键点 i 的 sigma，Aa 是分配边界框在网格单位中的面积乘以
   `area_factor`。代码将 `1e-9` 添加到 Aa 和 ∑iva, i 以防止除以零。可见性项 Lvis 是原始可见性 v̂a, i 和 va, i 之间所有正锚点的所有关键点的平均二元交叉熵（带 logits）。`viz_pw`
   是其正部分的权重。总损失为： L = λclsLcls + λiouLiou + λkptLkpt + λvisLvis λcls、λiou、λkpt 和 λvis 分别是
   `class_loss_weight`、`iou_loss_weight`、`regr_kpts_loss_weight` 和 `vis_kpts_loss_weight`。

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

> **注意**
> 该损失扩展了 [AdaptiveDetectionLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/adaptive_detection_loss.md)。第一次调用会构建锚点，与该类相同。没有正锚点的批次（例如没有实例的批次）会使关键点项和总损失都为 `nan`。对于没有实例的批次，损失还会记录一条调试消息。

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

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

 * `兼容:`: *
   由以下使用：[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)

#### 方法

##### init

```python
def __init__(n_warmup_epochs: int = 0, iou_type: IoUType = 'giou', reduction: Literal['sum', 'mean'] = 'mean', class_loss_weight: float = 0.5, iou_loss_weight: float = 7.5, viz_pw: float = 1.0, regr_kpts_loss_weight: float = 12, vis_kpts_loss_weight: float = 1.0, sigmas: list[float] | None = None, area_factor: float | None = None, **kwargs):
```

初始化边界框损失和关键点参数。

[AdaptiveDetectionLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/adaptive_detection_loss.md)
构建分配器和
[VarifocalLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/adaptive_detection_loss.md)。损失读取节点的步长、网格单元大小和网格单元偏移量。它还读取类别数量、关键点数量和输入图像大小。因此，损失需要一个节点：如果没有
`node`，[BaseAttachedModule.node](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md)
会引发 `RuntimeError`。边界框项的代码改编自 [PPYOLOE_pytorch](https://github.com/Nioolek/PPYOLOE_pytorch/blob/master/ppyoloe/models)。

参数

 * `n_warmup_epochs` (`int`): 从第 `0` 个 epoch 开始计算的 epoch 数量，这些 epoch 使用
   [ATSSAssigner](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/assigners/atss_assigner.md)。后续
   epoch 使用
   [TaskAlignedAssigner](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/assigners/tal_assigner.md)，它也读取关键点。
 * `iou_type` (`IoUType`): 边界框项的 IoU 变体：`"none"` 表示普通 IoU，`"giou"`、`"diou"`、`"ciou"` 或 `"siou"`。
 * `reduction` (`Literal['sum', 'mean']`): 该方法将其存储为 `self.reduction`。损失不读取它。
 * `class_loss_weight` (`float`): 类别项的因子 λcls。
 * `iou_loss_weight` (`float`): 边界框项的因子 λiou。
 * `viz_pw` (`float`): 可见性项中二元交叉熵正部分的权重。
 * `regr_kpts_loss_weight` (`float`): 关键点回归项的因子 λkpt。
 * `vis_kpts_loss_weight` (`float`): 可见性项的因子 λvis。
 * `sigmas` (`list[float] | None`): 每个关键点一个 sigma。`None` 选择 `17` 个关键点的 COCO 人体 sigmas，否则每个关键点为
   `0.04`。[get_sigmas](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/keypoints.md)
   记录选择。长度与关键点数量不符的列表会引发 `ValueError`。
 * `area_factor` (`float | None`): 在关键点回归项和
   [TaskAlignedAssigner](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/assigners/tal_assigner.md)
   中，将边界框面积缩放到姿态面积的因子。`None` 使用 `0.53` 并记录一条信息消息。
 * `**kwargs`: 转发给
   [AdaptiveDetectionLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/adaptive_detection_loss.md)
   的关键字参数，例如 `per_class_weights`、`skip_stal`、`final_loss_weight` 和 `node`。

##### dist2kpts_noscale

```python
def dist2kpts_noscale(anchor_points: Tensor, kpts: Tensor) -> Tensor:
```

解码锚点周围的原始关键点偏移量。

对于原始值 (tx, ty) 和锚点 (ax, ay)，解码后的位置是 (2tx + ax − 0.5, 2ty + ay − 0.5)。该方法保持每个关键点的第三个值不变。与
[EfficientKeypointBBoxHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/efficient_keypoint_bbox_head.md)
的解码不同，它不将位置乘以步长。该方法不改变 `kpts`。

参数

 * `anchor_points` (`Tensor`): 形状为 `[N, 2]` 的锚点，表示为 `(x, y)`。损失以网格单位传递它们。
 * `kpts` (`Tensor`): 形状为 `[B, N, n_keypoints, 3]` 的原始关键点值。

返回

 * `Tensor`: 解码后的关键点，形状与 `kpts` 相同，单位与 `anchor_points` 相同。

##### forward

```python
def forward(features: list[Tensor], class_scores: Tensor, distributions: Tensor, keypoints_raw: Tensor, target_boundingbox: Tensor, target_keypoints: Tensor) -> tuple[Tensor, dict[str, Tensor]]:
```

将锚点分配给实例并计算损失。

该方法将每个边界框的类别插入其关键点中。它将 `distributions` 解码为 `xyxy` 边界框，将 `keypoints_raw` 解码为关键点，两者都在锚点周围的网格单位中。它将目标转换为每个图像的填充张量，以输入图像的像素为单位。当前
epoch
的分配器然后将锚点与目标边界框匹配。[TaskAlignedAssigner](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/assigners/tal_assigner.md)
还会比较像素中的关键点。然后，该方法计算类别公式的四个项。对于没有实例的批次，该方法会记录一条调试消息。

参数

 * `features` (`list[Tensor]`): 头的特征图，每个尺度一个形状为 `[B, C_i, H_i, W_i]`。只有第一次调用使用它们来构建锚点。
 * `class_scores` (`Tensor`): 形状为 `[B, N, n_classes]` 的 Sigmoid 类别分数，用于所有尺度的 `N` 个锚点。
 * `distributions` (`Tensor`): 从每个锚点到其边界框的左、上、右和下侧的距离，形状为 `[B, N, 4]`，以步长单位表示。
 * `keypoints_raw` (`Tensor`): 形状为 `[B, N, 3 * n_keypoints]` 的原始关键点值。每个关键点都有原始的 `x` 和 `y` 偏移量以及一个可见性 logit。
 * `target_boundingbox` (`Tensor`): 形状为 `[M, 6]` 的 `boundingbox` 标签。每行包含批次索引、类别以及一个边界框的归一化 `x`、`y`、`w` 和 `h`。`x` 和 `y` 表示左上角。
 * `target_keypoints` (`Tensor`): 形状为 `[M, 1 + 3 * n_keypoints]` 的 `keypoints` 标签，行顺序与 `target_boundingbox`
   相同。每行包含批次索引，然后是每个关键点的归一化 `x` 和 `y` 以及可见性。

返回

 * `tuple[Tensor, dict[str, Tensor]]`: 总损失（标量）和子损失 `"class"`、`"iou"`、`"regression"` 和
   `"visibility"`。子损失是分离的项，不含其因子。当没有锚点为正时，总损失和两个关键点子损失为 `nan`。

#### 属性

##### gt_kpts_scale

##### node

##### supported_tasks
