# tal_assigner

Python API: `luxonis_train.assigners.tal_assigner`

任务对齐分配器，它通过预测的类别分数和预测框的 IoU 一起选择正锚点。

## 类

### TaskAlignedAssigner

来自 TOOD 的任务对齐分配器 (TAL)。

分配器使用对齐度量为每个真实框的每个锚点评分：

t = sα⋅uβ

其中，s 是框的类别预测分数。重叠 u 是锚点预测框与真实框之间的 IoU。对于关键点，u 是此 IoU 乘以
[compute_pose_oks](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/keypoints.md)
中的对象关键点相似度。对于每个真实框，分配器执行以下步骤：

 * 它找到中心在框内的锚点。
 * 它最多保留 `topk` 个这些锚点，即 t 值最高的锚点。

如果一个锚点对多个框保持为正，则它归属于 u 值最高的框。有关详细信息，请参阅
[luxonis_train.assigners.utils.fix_collisions](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/assigners/utils.md)。正锚点的分配分数是
t，针对每个框进行归一化：

t̂ = (t)/(maxt)⋅maxu

两个最大值都取自框的正锚点。

小目标感知标签分配 (STAL) 有助于小对象获得正锚点。当 STAL 开启时，真实框中比最小步幅短的一侧将获得第二小步幅的长度。如果只有一个步幅，它将获得该步幅的长度。框的中心保持不变。分配器仅使用放大后的框来查找框内的锚点。

[AdaptiveDetectionLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/adaptive_detection_loss.md)
在其预热周期后使用此分配器。[PrecisionDFLDetectionLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/precision_dfl_detection_loss.md)
在所有周期中都使用它。

> **参考文献**
> * [TOOD: Task-aligned One-stage Object Detection](https://arxiv.org/pdf/2108.07755.pdf)
 * 该实现改编自 [PPYOLOE_pytorch](https://github.com/Nioolek/PPYOLOE_pytorch/blob/master/ppyoloe/assigner/tal_assigner.py) 的代码，该代码具有
   [Apache License, Version 2.0](https://github.com/Nioolek/PPYOLOE_pytorch/tree/master?tab=Apache-2.0-1-ov-file#readme)。

#### 方法

##### init

```python
def __init__(n_classes: int, topk: int = 13, alpha: float = 1.0, beta: float = 6.0, eps: float = 1e-09, strides: Sequence[int] | Tensor | None = None, skip_stal: bool = False):
```

初始化任务对齐分配器。

参数

 * `n_classes` (`int`): 数据集中的类别数量。标签 `n_classes` 在输出中标记背景锚点。
 * `topk` (`int`): 分配器为每个真实框选择的具有最高对齐度量的锚点数量。它不能大于锚点数量。
 * `alpha` (`float`): 对齐度量中类别分数 α 的指数。
 * `beta` (`float`): 对齐度量中重叠 u 的指数 β。
 * `eps` (`float`): 一个小值，用于防止分数归一化和对象关键点相似度中出现除以零的情况。
 * `strides` (`Sequence[int] | Tensor | None`): 检测头在像素中的步幅，例如 `[8, 16, 32]`。分配器对其进行排序并删除重复项。STAL 需要步幅，因此 `None` 或空值会关闭 STAL。
 * `skip_stal` (`bool`): `True` 关闭 STAL。当 `skip_stal` 为 `False` 且 `strides` 为 `None` 或为空时，分配器会记录警告并关闭 STAL。

##### forward

```python
def forward(pred_scores: Tensor, pred_bboxes: Tensor, anchor_points: Tensor, gt_labels: Tensor, gt_bboxes: Tensor, mask_gt: Tensor, pred_kpts: Tensor | None = None, gt_kpts: Tensor | None = None, sigmas: Tensor | None = None, area_factor: float | None = None) -> tuple[Tensor, Tensor, Tensor, Tensor, Tensor]:
```

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

所有框都采用 `xyxy` 格式。框、锚点和关键点使用相同的单位。STAL 将框大小与步幅进行比较，因此 STAL 需要像素单位的框。只有 `mask_gt` 设置为 `1` 的框才能获得正锚点。该方法在 `torch.no_grad`
下运行，因此输出没有梯度。

要将对象关键点相似度添加到对齐度量中，请提供 `pred_kpts`、`gt_kpts`、`sigmas` 和 `area_factor`。

> **示例**
> 该框包含前两个锚点的中心。两个预测框与它的 IoU 均为 `0.5`。第一个框具有更高的类别分数，因此它获得分数 `0.5`。

```pycon
>>> import torch
>>> assigner = TaskAlignedAssigner(
...     n_classes=2, topk=2, skip_stal=True
... )
>>> anchor_points = torch.tensor(
...     [[2.0, 2.0], [6.0, 2.0], [2.0, 6.0], [6.0, 6.0]]
... )
>>> pred_bboxes = torch.cat(
...     [anchor_points - 2, anchor_points + 2], -1
... )
>>> pred_scores = torch.tensor(
...     [[[0.1, 0.9], [0.2, 0.5], [0.3, 0.3], [0.9, 0.1]]]
... )
>>> gt_labels = torch.tensor([[[1.0]]])
>>> gt_bboxes = torch.tensor([[[0.0, 0.0, 8.0, 4.0]]])
>>> mask_gt = torch.tensor([[[1.0]]])
>>> labels, bboxes, scores, mask, gt_idx = assigner(
...     pred_scores,
...     pred_bboxes[None],
...     anchor_points,
...     gt_labels,
...     gt_bboxes,
...     mask_gt,
... )
>>> labels.tolist()
[[1, 1, 2, 2]]
>>> mask.tolist()
[[True, True, False, False]]
>>> [round(s, 2) for s in scores[0, :, 1].tolist()]
[0.5, 0.28, 0.0, 0.0]
```

参数

 * `pred_scores` (`Tensor`): 预测的类别概率，范围为 `[0, 1]`，形状为 `[bs, n_anchors, n_classes]`。损失函数给出类别 logits 的 sigmoid。
 * `pred_bboxes` (`Tensor`): 预测框，形状为 `[bs, n_anchors, 4]`。
 * `anchor_points` (`Tensor`): 锚点中心 `(x, y)`，形状为 `[n_anchors, 2]`。
 * `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_kpts` (`Tensor | None`): 预测关键点，形状为 `[bs, n_anchors, n_kpts, 3]`。分配器只读取 `x` 和 `y`。
 * `gt_kpts` (`Tensor | None`): 真实关键点，格式为 `(x, y, visibility)`，形状为 `[bs, n_max_boxes, n_kpts, 3]`。
 * `sigmas` (`Tensor | None`): 每个关键点一个 sigma，形状为 `[n_kpts]`。
 * `area_factor` (`float | None`): 将真实框面积缩放到姿态面积的因子。

返回

 * `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]`) 存储按归一化对齐度量 t̂ 缩放的独热类别向量。背景锚点为零。
    * `mask_positive` (`[bs, n_anchors]`, `bool`) 在分配了框的锚点处为 `True`。
    * `assigned_gt_idx` (`[bs, n_anchors]`, `int64`) 存储沿 `gt_bboxes` 维度 `1` 的分配框索引，背景锚点为 `0`。 当 `n_max_boxes` 为 `0` 时，每个锚点都是背景。

抛出

 * `ValueError`: 当 `pred_kpts`、`gt_kpts`、`sigmas` 和 `area_factor` 中部分为 `None` 而非全部为 `None` 时。
