# atss_assigner

Python API: `luxonis_train.assigners.atss_assigner`

自适应训练样本选择，通过自适应 IoU 阈值选择每个真实框的正锚点。

## 类

### ATSSAssigner

自适应训练样本选择 (ATSS) 分配器。

分配器根据锚点的几何形状从每个真实框中选择正锚点。它只读取预测框以缩放分配的分数。对于每个真实框，它执行以下步骤：

 * 在每个金字塔级别上，它选择最多 `topk` 个锚点，这些锚点的中心最接近框的中心。这些锚点是候选锚点。
 * 它计算每个候选锚点与框之间的 IoU。框的阈值是 μ + σ，即这些 IoU 的平均值加上标准差。
 * 它保留 IoU 高于阈值且中心在框内的候选锚点。

对于多个框保持为正的锚点，它会分配给与该锚点框具有最高 IoU 的框。有关详细信息，请参阅
[luxonis_train.assigners.utils.fix_collisions](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/assigners/utils.md)。

[AdaptiveDetectionLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/adaptive_detection_loss.md)
在前 `n_warmup_epochs` 个 epoch 中使用此分配器。在这些 epoch 之后，它使用
[TaskAlignedAssigner](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/assigners/tal_assigner.md)。

> **参考**
> * [通过自适应训练样本选择弥合基于锚点和无锚点检测之间的差距](https://arxiv.org/pdf/1912.02424.pdf)
 * 该实现改编自 [PPYOLOE_pytorch](https://github.com/Nioolek/PPYOLOE_pytorch/blob/master/ppyoloe/assigner/atss_assigner.py) 和
   [TOOD](https://github.com/fcjian/TOOD/blob/master/mmdet/core/bbox/assigners/atss_assigner.py) 的代码。

#### 方法

##### init

```python
def __init__(n_classes: int, topk: int = 9):
```

初始化 ATSS 分配器。

参数

 * `n_classes` (`int`): 数据集中的类别数量。标签 `n_classes` 在输出中标记背景锚点。
 * `topk` (`int`): 在每个金字塔级别上为每个真实框选择的候选锚点的最大数量。如果一个框在所有级别上的候选锚点少于三个，则没有候选锚点通过阈值。

##### forward

```python
def forward(anchor_bboxes: Tensor, n_level_bboxes: list[int], gt_labels: Tensor, gt_bboxes: Tensor, mask_gt: Tensor, pred_bboxes: Tensor) -> tuple[Tensor, Tensor, Tensor, Tensor, Tensor]:
```

将每个锚点分配给真实框或背景。

所有框都采用 `xyxy` 格式并使用相同的单位。只有 `mask_gt` 设置为 `1` 的框才能获得正锚点。

> **示例**
> 该框与第一个锚点框的 IoU 为 `0.64`。阈值约为 `0.5`，因此只有第一个锚点是正的。预测框等于锚点框，因此该锚点的分数也为 `0.64`。

```pycon
>>> import torch
>>> assigner = ATSSAssigner(n_classes=2, topk=4)
>>> anchors = torch.tensor(
...     [
...         [0.0, 0.0, 4.0, 4.0],
...         [4.0, 0.0, 8.0, 4.0],
...         [0.0, 4.0, 4.0, 8.0],
...         [4.0, 4.0, 8.0, 8.0],
...     ]
... )
>>> gt_labels = torch.tensor([[[1.0]]])
>>> gt_bboxes = torch.tensor([[[0.0, 0.0, 5.0, 5.0]]])
>>> mask_gt = torch.tensor([[[1.0]]])
>>> labels, bboxes, scores, mask, gt_idx = assigner(
...     anchors, [4], gt_labels, gt_bboxes, mask_gt, anchors[None]
... )
>>> labels.tolist()
[[1, 2, 2, 2]]
>>> mask.tolist()
[[True, False, False, False]]
>>> [round(s, 2) for s in scores[0, 0].tolist()]
[0.0, 0.64]
```

参数

 * `anchor_bboxes` (`Tensor`): 锚点框，形状为 `[n_anchors, 4]`，按级别排序。
 * `n_level_bboxes` (`list[int]`): 每个金字塔级别上的锚点数量。总和必须等于 `n_anchors`。
 * `gt_labels` (`Tensor`): 每个真实框的类别索引，形状为 `[bs, n_max_boxes, 1]`。
 * `gt_bboxes` (`Tensor`): 真实框，形状为 `[bs, n_max_boxes, 4]`。
 * `mask_gt` (`Tensor`): `1` 表示真实框，`0` 表示填充槽，形状为 `[bs, n_max_boxes, 1]`。
 * `pred_bboxes` (`Tensor`): 预测框，形状为 `[bs, n_anchors, 4]`。预测框与其分配框之间的 IoU 会缩放分配的分数。

返回

 * `tuple[Tensor, Tensor, Tensor, Tensor, Tensor]`: 五个张量。 * `assigned_labels` (`[bs, n_anchors]`, `int64`) 包含分配框的类别，或 `n_classes`
   表示背景锚点。
    * `assigned_bboxes` (`[bs, n_anchors, 4]`) 包含分配的框。只有正锚点处的值有意义。
    * `assigned_scores` (`[bs, n_anchors, n_classes]`) 包含一个独热类别向量，该向量由预测框与分配框之间的 IoU 缩放。背景锚点为零。
    * `mask_positive` (`[bs, n_anchors]`, `bool`) 在具有分配框的锚点处为 `True`。
    * `assigned_gt_idx` (`[bs, n_anchors]`, `int64`) 包含 `gt_bboxes` 维度 `1` 上分配框的索引，背景锚点为 `0`。 当 `n_max_boxes` 为 `0`
      时，每个锚点都是背景。在这种情况下，`mask_positive` 和 `assigned_gt_idx` 是 `float32` 零。
