# keypoints

Python API: `luxonis_train.utils.keypoints`

关键点的数学辅助函数。

该模块包含关键点 sigma、对象关键点相似度以及关键点和边界框之间的转换。

## 函数

### compute_pose_oks

```python
def compute_pose_oks(predictions: Tensor, targets: Tensor, sigmas: Tensor, gt_bboxes: Tensor | None = None, pose_area: Tensor | None = None, eps: float = 1e-09, area_factor: float = 0.53, use_cocoeval_oks: bool = True) -> Tensor:
```

计算每个目标-预测对的对象关键点相似度。

对于一张图像，目标 t 和预测 p 的相似度是 t 的可见关键点上此项的平均值：

exp⎛⎝ − (d2i)/(2 (2σi)2 A)⎞⎠

在该项中，di 是两个关键点 i 之间的距离，σi 是关键点 i 的 sigma。A 是 t 的姿态区域。当目标关键点的第三个值大于 `0` 时，该关键点可见。没有可见关键点的目标相似度为 `0`。当 `use_cocoeval_oks` 设置为
`False` 时，指数为 − d2i ⁄ (2(A**σi)2)。

> **参考**
> * COCO 关键点评估：[https://cocodataset.org/#keypoints-eval](https://cocodataset.org/#keypoints-eval)
 * `pycocotools/cocoeval.py` 中的
   `computeOks`：[https://github.com/cocodataset/cocoapi/blob/8c9bcc3cf640524c4c20a9c40e89cb6a2f2fa0e9/PythonAPI/pycocotools/cocoeval.py#L229](https://github.com/cocodataset/cocoapi/blob/8c9bcc3cf640524c4c20a9c40e89cb6a2f2fa0e9/PythonAPI/pycocotools/cocoeval.py#L229)

> **示例**
> ```pycon
>>> import torch
>>> targets = torch.tensor([[[[0.5, 0.5, 2.0]]]])
>>> sigmas = torch.tensor([0.05])
>>> gt_bboxes = torch.tensor([[[0.0, 0.0, 1.0, 1.0]]])
>>> exact = torch.tensor([[[[0.5, 0.5, 1.0]]]])
>>> oks = compute_pose_oks(exact, targets, sigmas, gt_bboxes=gt_bboxes)
>>> oks.round(decimals=3).tolist()
[[[1.0]]]
```

```pycon
>>> far = torch.tensor([[[[5.0, 5.0, 1.0]]]])
>>> oks = compute_pose_oks(far, targets, sigmas, gt_bboxes=gt_bboxes)
>>> oks.round(decimals=3).tolist()
[[[0.0]]]
```

参数

 * `predictions` (`Tensor`): 预测的关键点，形状为 `[N, M2, n_keypoints, 3]`。函数只读取每个关键点的前两个值 `x` 和 `y`。
 * `targets` (`Tensor`): 目标关键点，形状为 `[N, M1, n_keypoints, 3]`，格式为 `(x, y, visibility)`。
 * `sigmas` (`Tensor`): 每个关键点一个 sigma，形状为 `[n_keypoints]`。
 * `gt_bboxes` (`Tensor | None`): 目标框，形状为 `[N, M1, 4]`，采用 `xyxy` 格式。它们的面积乘以 `area_factor` 即为姿态区域。函数仅在 `pose_area` 为 `None` 时读取它们。
 * `pose_area` (`Tensor | None`): 每个目标的姿态区域，形状为 `[N, M1, 1, 1]`。`None` 表示从 `gt_bboxes` 计算。
 * `eps` (`float`): 一个小的常数，函数将其添加到面积和可见计数中。它防止除以零。
 * `area_factor` (`float`): 将框面积缩放到姿态区域的因子。
 * `use_cocoeval_oks` (`bool`): 当为 `True` 时，使用 COCO 评估代码的公式。当为 `False` 时，使用上面的另一个公式。

返回

 * `Tensor`: 相似度，形状为 `[N, M1, M2]`，范围为 `[0, 1]`。

抛出

 * `ValueError`: 当 `pose_area` 和 `gt_bboxes` 都为 `None` 时。

### get_center_keypoints

```python
def get_center_keypoints(bboxes: Tensor, *, height: int = 1, width: int = 1) -> Tensor:
```

为每个边界框创建一个中心关键点。

FOMO 损失和对象关键点相似度度量使用框中心作为 FOMO 任务的关键点目标。该任务没有标注的关键点。

> **示例**
> ```pycon
>>> import torch
>>> bboxes = torch.tensor([[0.0, 1.0, 0.25, 0.5, 0.5, 0.25]])
>>> get_center_keypoints(bboxes).tolist()
[[0.0, 0.5, 0.625, 2.0]]
>>> get_center_keypoints(bboxes, height=200, width=100).tolist()
[[0.0, 50.0, 125.0, 2.0]]
```

参数

 * `bboxes` (`Tensor`): 边界框，形状为 `[N, 6]`，列为 `(batch_index, class, x, y, w, h)`。`x` 和 `y` 是归一化的左上角，`w` 和 `h` 是归一化的大小。
 * `height` (`int`): 缩放 `y` 的高度，例如图像或热图的高度。`1` 保持坐标归一化。
 * `width` (`int`): 缩放 `x` 的宽度，例如图像或热图的宽度。`1` 保持坐标归一化。

返回

 * `Tensor`: 关键点，形状为 `[N, 4]`，列为 `(batch_index, x, y, visibility)`，位于 `bboxes` 的设备和 dtype 上。`x` 和 `y` 是按 `width` 和 `height`
   缩放的框中心。可见性始终为 `2`。

### get_sigmas

```python
def get_sigmas(sigmas: list[float] | None, n_keypoints: int, caller_name: str | None = None) -> Tensor:
```

验证给定的关键点 sigma 或创建默认值。

sigma 是
[compute_pose_oks](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/keypoints.md)
中对象关键点相似度的每个关键点尺度。当 `sigmas` 为 `None` 时，函数选择默认值：

 * 对于 `17` 个关键点，它返回 COCO 人体 sigma 并记录警告。
 * 对于任何其他计数，它为每个关键点返回 `0.04` 并记录信息消息。

> **示例**
> ```pycon
>>> get_sigmas([0.1, 0.2], 2).shape
torch.Size([2])
```

```pycon
>>> get_sigmas([0.1], 2)
Traceback (most recent call last):
ValueError: The length of the sigmas list must be the same ...
```

参数

 * `sigmas` (`list[float] | None`): 每个关键点一个 sigma。`None` 选择默认值。
 * `n_keypoints` (`int`): 关键点的数量。
 * `caller_name` (`str | None`): 调用者的名称，用作日志和错误消息的前缀。`None` 不添加前缀。

返回

 * `Tensor`: sigma，作为形状为 `[n_keypoints]` 的 `float32` 张量。

抛出

 * `ValueError`: 当给定 `sigmas` 且其长度与 `n_keypoints` 不同时。

### insert_class

```python
def insert_class(keypoints: Tensor, bboxes: Tensor) -> Tensor:
```

将每个边界框的类别索引插入其关键点中。

> **示例**
> ```pycon
>>> import torch
>>> keypoints = torch.tensor([[0.0, 0.5, 0.5, 2.0]])
>>> bboxes = torch.tensor([[0.0, 3.0, 0.1, 0.1, 0.2, 0.2]])
>>> insert_class(keypoints, bboxes).tolist()
[[0.0, 3.0, 0.5, 0.5, 2.0]]
```

参数

 * `keypoints` (`Tensor`): 关键点，形状为 `[N, 1 + 3K]`，其中 `K` 是关键点的数量。批次索引在第一列，后跟 `(x, y, visibility)` 三元组。
 * `bboxes` (`Tensor`): 边界框，形状为 `[N, 6]`，实例顺序相同，类别索引在第二列。

返回

 * `Tensor`: 关键点，形状为 `[N, 2 + 3K]`，类别索引作为第二列插入。
