# utils

Python API: `luxonis_train.assigners.utils`

[ATSSAssigner](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/assigners/atss_assigner.md)
和
[TaskAlignedAssigner](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/assigners/tal_assigner.md)
共享的辅助函数。

这些辅助函数查找每个框内的锚点，解决多个框的重叠锚点，并计算一批图像的 IoU。

## 函数

### batch_iou

```python
def batch_iou(batch1: Tensor, batch2: Tensor) -> Tensor:
```

计算每个图像中每对框之间的 IoU。

该函数为批处理中的每个图像调用一次
[bbox_iou](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/boundingbox.md)。

> **示例**
> ```pycon
>>> import torch
>>> batch1 = torch.tensor([[[0.0, 0.0, 2.0, 2.0]]])
>>> batch2 = torch.tensor(
...     [[[0.0, 0.0, 2.0, 2.0], [0.0, 0.0, 4.0, 2.0]]]
... )
>>> batch_iou(batch1, batch2).tolist()
[[[1.0, 0.5]]]
```

参数

 * `batch1` (`Tensor`): `xyxy` 格式的框，形状为 `[bs, N, 4]`。
 * `batch2` (`Tensor`): `xyxy` 格式的框，形状为 `[bs, M, 4]`。

返回

 * `Tensor`: IoU 值，形状为 `[bs, N, M]`。`[b, i, j]` 处的值是 `batch1[b, i]` 和 `batch2[b, j]` 之间的 IoU。

### candidates_in_gt

```python
def candidates_in_gt(anchor_centers: Tensor, gt_bboxes: Tensor, eps: float = 1e-09) -> Tensor:
```

标记每个框内中心点的锚点。

当中心点到框的四条边的距离都大于 `eps` 时，该中心点在框内。在边上的中心点在框外。

> **示例**
> ```pycon
>>> import torch
>>> centers = torch.tensor([[1.0, 1.0], [3.0, 3.0], [2.0, 0.0]])
>>> boxes = torch.tensor([[0.0, 0.0, 2.0, 2.0], [0.0, 0.0, 4.0, 4.0]])
>>> candidates_in_gt(centers, boxes).tolist()
[[1.0, 0.0, 0.0], [1.0, 1.0, 0.0]]
```

参数

 * `anchor_centers` (`Tensor`): 锚点中心 `(x, y)`，形状为 `[n_anchors, 2]`。
 * `gt_bboxes` (`Tensor`): `xyxy` 格式的框，形状为 `[n_boxes, 4]`。分配器将所有图像的真实框作为扁平张量给出，因此 `n_boxes` 是 `bs * n_max_boxes`。
 * `eps` (`float`): 中心点与框的每条边之间的距离必须超过的值。

返回

 * `Tensor`: 形状为 `[n_boxes, n_anchors]` 且数据类型与 `gt_bboxes` 相同的掩码。`1` 表示中心点在框内。

### fix_collisions

```python
def fix_collisions(mask_pos: Tensor, overlaps: Tensor, n_max_boxes: int) -> tuple[Tensor, Tensor, Tensor]:
```

解决多个框的重叠锚点。

这样的锚点归属于重叠度最高的框。搜索范围覆盖图像的所有 `n_max_boxes` 个框，而不仅仅是锚点为正的框。其他锚点的掩码不变。

> **示例**
> 第二个锚点对两个框都为正。它与第二个框的重叠度更高。

```pycon
>>> import torch
>>> mask_pos = torch.tensor([[[1.0, 1.0, 0.0], [0.0, 1.0, 0.0]]])
>>> overlaps = torch.tensor([[[0.9, 0.3, 0.1], [0.2, 0.6, 0.0]]])
>>> gt_idx, mask_pos_sum, mask_pos = fix_collisions(
...     mask_pos, overlaps, 2
... )
>>> gt_idx.tolist()
[[0, 1, 0]]
>>> mask_pos_sum.tolist()
[[1.0, 1.0, 0.0]]
>>> mask_pos.tolist()
[[[1.0, 0.0, 0.0], [0.0, 1.0, 0.0]]]
```

参数

 * `mask_pos` (`Tensor`): 正掩码，形状为 `[bs, n_max_boxes, n_anchors]`。`1` 表示锚点对某个框为正。
 * `overlaps` (`Tensor`): 每个框和锚点的重叠度，形状为 `[bs, n_max_boxes,
   n_anchors]`。[ATSSAssigner](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/assigners/atss_assigner.md)
   给出与锚框的
   IoU。[TaskAlignedAssigner](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/assigners/tal_assigner.md)
   给出与预测框的 IoU，如果它获得关键点，则乘以对象关键点相似度。
 * `n_max_boxes` (`int`): 每张图像的框槽数量，即 `mask_pos` 的维度 `1` 的大小。

返回

 * `tuple[Tensor, Tensor, Tensor]`: 三个张量。 * `assigned_gt_idx` (`[bs, n_anchors]`, `int64`) 存储每个锚点的框索引，没有框的锚点为 `0`。
    * `mask_pos_sum` (`[bs, n_anchors]`) 存储每个锚点的框数量，`0` 或 `1`。
    * `mask_pos` (`[bs, n_max_boxes, n_anchors]`) 是正掩码，每个锚点最多有一个框。
