# object_keypoint_similarity

Python API: `luxonis_train.attached_modules.metrics.object_keypoint_similarity`

对象关键点相似度，IoU 的关键点对应物。

该指标将每张图像的预测姿态与目标姿态配对，并平均配对的相似度。关键点的 sigma 设置了关键点容忍的距离。

## 类

### ObjectKeypointSimilarity

配对姿态的平均对象关键点相似度。

 * `输入:`: * `keypoints` (`list[Tensor]`): 每张图像的 [Mi, nkeypoints, 3]，`(x, y, conf)`
   以像素为单位。[FOMOHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/fomo_head.md)
   给出 [Mi, 1, 4]。只有 `x` 和 `y` 计数。
    * `target_boundingbox` (`Tensor`): [N, 6]，`[batch, class, x, y, w, h]`，归一化。
    * `target_keypoints` (`Tensor | None`): [N, 1 + 3nkeypoints]，`[batch, x, y, v, ...]`，归一化。`Tasks.FOMO` 不读取它。
 * `输出:`: * `Tensor`: `[0, 1]` 中的标量
 * `公式:`:
   [compute_pose_oks](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/keypoints.md)
   给出目标姿态和一张图像的预测姿态的每对相似度。目标的姿态面积是其框的像素面积的 `area_factor` 倍。匈牙利算法配对姿态，使相似度之和最大。一张图像的分数是其配对的平均相似度。该指标返回图像的平均分数。

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

> **注意**
> * 该指标跳过没有目标的图像。
 * 没有配对的姿态不会降低其图像的分数。有目标但没有预测的图像得分为 `0`。
 * 对于 `Tasks.FOMO`，目标框的中心是目标关键点。

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

```yaml
- name: FOMOHead
  inputs: [EfficientRep]
  metrics:
    - name: ObjectKeypointSimilarity
```

 * `兼容:`: * 使用者:
   [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__(sigmas: list[float] | None = None, area_factor: float | None = None, use_cocoeval_oks: bool = True, **kwargs):
```

初始化指标并解析 sigma。

构造函数读取
[BaseAttachedModule.n_keypoints](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md)，因此模块需要一个节点。当
`sigmas`
没有每个关键点的值时，[get_sigmas](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/keypoints.md)
会引发 `ValueError`。

参数

 * `sigmas` (`list[float] | None`): 每个关键点的一个 sigma。较大的 sigma 容忍较大的距离。`None` 选择 `17` 个关键点的 COCO 人体 sigma，否则每个关键点选择
   `0.04`。[get_sigmas](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/keypoints.md)
   然后记录选择。
 * `area_factor` (`float | None`): 将目标框面积缩放到姿态面积的因子。`None` 选择 `0.53` 并记录一条信息消息。
 * `use_cocoeval_oks` (`bool`): 当为 `True` 时，使用 COCO 评估代码的公式。当为 `False` 时，使用 COCO
   关键点定义的公式。[compute_pose_oks](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/keypoints.md)
   显示了两种公式。
 * `**kwargs`: 转发给
   [BaseMetric](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/base_metric.md)
   的关键字参数，例如 `node`。

##### compute

```python
def compute(self) -> Tensor:
```

配对每张图像存储的姿态并平均分数。

类文档字符串描述了配对和分数。该方法还将 `sigmas` 移动到指标的设备。

> **示例**
> 第一张图像有两个目标和一个精确预测。没有配对的目标不计数，因此图像得分为 `1`。第二张图像没有预测，得分为 `0`：

```pycon
>>> import torch
>>> from torch import Size
>>> from luxonis_train.nodes import EfficientKeypointBBoxHead
>>> head = EfficientKeypointBBoxHead(
...     n_heads=1,
...     n_classes=1,
...     n_keypoints=1,
...     input_shapes=[{"features": [Size([1, 8, 8, 8])]}],
...     original_in_shape=Size([3, 100, 100]),
... )
>>> metric = ObjectKeypointSimilarity(
...     node=head, sigmas=[0.04], area_factor=0.53
... )
>>> boxes = torch.tensor([[0.0, 0.0, 0.1, 0.1, 0.2, 0.2]] * 3)
>>> boxes[2, 0] = 1.0
>>> keypoints = torch.tensor(
...     [
...         [0.0, 0.2, 0.2, 2.0],
...         [0.0, 0.6, 0.6, 2.0],
...         [1.0, 0.2, 0.2, 2.0],
...     ]
... )
>>> exact = torch.tensor([[[20.0, 20.0, 1.0]]])
>>> metric.update([exact, torch.zeros(0, 1, 3)], boxes, keypoints)
>>> metric.compute().item()
0.5
```

返回

 * `Tensor`: 存储图像的平均分数，`[0, 1]` 中的标量。当没有图像有目标时，它为 `0`。

##### update

```python
def update(keypoints: list[Tensor], target_boundingbox: Tensor, target_keypoints: Tensor | None = None):
```

将一个批次的目标缩放到像素并存储它们。

对于每个有目标的图像，该方法存储预测的关键点、像素中的目标关键点以及每个目标的姿态面积。[BaseAttachedModule.original_in_shape](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md)
的高度和宽度缩放归一化值。

参数

 * `keypoints` (`list[Tensor]`): 每张图像的预测关键点，形状为 `[M_i, n_keypoints,
   3]`，以像素为单位。[FOMOHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/fomo_head.md)
   给出形状 `[M_i, 1, 4]`。只有 `x` 和 `y` 计数。
 * `target_boundingbox` (`Tensor`): 批次的目标框，形状为 `[N, 6]`，表示为 `[batch, class, x, y, w, h]`，具有归一化值。
 * `target_keypoints` (`Tensor | None`): 批次的目标关键点，形状为 `[N, 1 + 3 * n_keypoints]`，表示为 `[batch, x, y, v, ...]`，具有归一化坐标。对于
   `Tasks.FOMO`，该方法使用目标框的中心代替。

引发

 * `ValueError`: 当 `target_keypoints` 为 `None` 且任务不是 `Tasks.FOMO` 时。

#### 属性

##### pred_keypoints

##### scales

##### supported_tasks

##### target_keypoints
