# precision_dfl_detection_loss

Python API: `luxonis_train.attached_modules.losses.precision_dfl_detection_loss`

YOLOv8 检测损失：分类、边界框回归和回归 bin 上的分布焦点损失。

## 类

### BBoxLoss

正锚点的 CIoU 和分布焦点损失项。

[PrecisionDFLDetectionLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/precision_dfl_detection_loss.md)
和
[PrecisionDFLSegmentationLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/precision_dfl_segmentation_loss.md)
将其用于 `iou` 和 `dfl` 项。P 是正锚点的集合。锚点 a 具有预测框 ba、目标框 b̂a 和权重 wa，即其目标类别分数的总和。S 是
[forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/precision_dfl_detection_loss.md)
接收的 `total_score` 归一化器：

Liou = (1)/(S)∑a ∈ Pwa(1 − CIoU(ba, b̂a))

Ldfl = (1)/(S)∑a ∈ Pwa DFLa

DFLa 是锚点到目标框四边的平均
[DFLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/precision_dfl_detection_loss.md)。

#### 方法

##### init

```python
def __init__(reg_max: int = 16):
```

初始化损失及其 DFL 部分。

参数

 * `reg_max` (`int`): 框每侧的距离 bin 数量。当 `reg_max` 为 `1` 或更小时，损失没有 DFL 部分。

##### forward

```python
def forward(pred_dist: Tensor, pred_bboxes: Tensor, anchors: Tensor, targets: Tensor, scores: Tensor, total_score: Tensor, fg_mask: Tensor) -> tuple[Tensor, Tensor]:
```

计算 CIoU 项和 DFL 项。

`pred_bboxes`、`anchors` 和 `targets` 必须使用一个单位，即一个距离 bin 的大小。DFL 项将每个目标距离裁剪到 `[0, reg_max - 1.01]`。CIoU 项不裁剪框。

> **示例**
> 预测框等于目标框，因此 CIoU 项为 `0`。均匀 bin logits 给出 DFL 项 ln4：

```pycon
>>> import torch
>>> loss = BBoxLoss(reg_max=4)
>>> anchors = torch.tensor([[2.5, 2.5]])
>>> boxes = torch.tensor([[[1.5, 1.5, 3.5, 3.5]]])
>>> pred_dist = torch.zeros(1, 1, 16)
>>> scores, total = torch.ones(1, 1, 1), torch.tensor(1.0)
>>> fg_mask = torch.tensor([[True]])
>>> iou, dfl = loss(
...     pred_dist, boxes, anchors, boxes, scores, total, fg_mask
... )
>>> round(iou.item(), 4), round(dfl.item(), 4)
(0.0, 1.3863)
```

参数

 * `pred_dist` (`Tensor`): 形状为 `[B, N, 4 * reg_max]` 的距离 bin logits。
 * `pred_bboxes` (`Tensor`): 形状为 `[B, N, 4]` 的预测 `xyxy` 框，从 `pred_dist` 解码。
 * `anchors` (`Tensor`): 形状为 `[N, 2]` 的锚点中心 `(x, y)`。
 * `targets` (`Tensor`): 形状为 `[B, N, 4]` 的分配 `xyxy` 目标框。
 * `scores` (`Tensor`): 形状为 `[B, N, n_classes]` 的分配类别分数。
 * `total_score` (`Tensor`): 归一化器 S。检测损失将 `scores` 的总和（至少为 `1`）作为 Python 数字传递。
 * `fg_mask` (`Tensor`): 形状为 `[B, N]` 的正锚点的布尔掩码。

返回

 * `tuple[Tensor, Tensor]`: 标量 CIoU 项和标量 DFL 项。如果没有 DFL 部分，DFL 项是形状为 `[1]` 的零张量。

#### 属性

##### dist_loss

### DFLoss

框侧距离 bin 上的分布焦点损失 (DFL)。

目标距离 y 是 bin yl = ⌊y⌋ 和 yr = yl + 1 之间的实数。使用 bin 上的 softmax 概率 p，损失为

DFL = − ((yr − y)logpyl + (y − yl)logpyr)

当 bin yl 的概率为 yr − y 且 bin yr 的概率为 y − yl 时，损失最低。

#### 方法

##### init

```python
def __init__(reg_max: int = 16):
```

初始化损失。

参数

 * `reg_max` (`int`): 框每侧的距离 bin 数量。

#### 属性

##### reg_max

### PrecisionDFLDetectionLoss

[PrecisionBBoxHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/precision_bbox_head.md)
的边界框损失，框侧具有分布焦点损失。

损失从头的距离 bin
解码每个锚点的框。[TaskAlignedAssigner](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/assigners/tal_assigner.md)
然后选择正锚点，并为每个锚点提供目标框和目标类别分数。其他锚点的目标类别分数为 `0`。损失有三个项：

 * 所有锚点类别 logits 上的二元交叉熵；
 * 正锚点框上的 CIoU 损失；
 * 正锚点距离 bin 上的分布焦点损失 (DFL)。

[BBoxLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/precision_dfl_detection_loss.md)
计算最后两项。

 * `输入:`: * `features` (`list[Tensor]`): 每个尺度的 [B, 4**reg*max + nclasses, Hi, Wi]，距离 bin logits 后跟类别 logits
    * `target` (`Tensor`): [Ngt, 6]，`[batch_index, class, x, y, w, h]`，`xywh` 归一化，`x` 和 `y` 在左上角
 * `输出:`: * `Tensor`: 标量总损失
    * `dict[str, Tensor]`: 标量子损失 `class`、`iou`、`dfl`，已分离且不带权重
 * `公式:`: 总和遍历批次中所有图像的所有尺度的锚点。对于锚点 a 和类别 c，za, c 是类别 logit，t̂a, c 是分配器中的分数。P 是正锚点的集合。ba 是预测框，b̂a 是分配框，两者都以锚点步幅的单位表示。每个正锚点具有权重 wa =
   ∑ct̂a, c，归一化器为 S = max(∑awa, 1)： Lcls = (1)/(S)∑a∑cBCE(za, c, t̂a, c) Liou = (1)/(S)∑a ∈ Pwa(1 − CIoU(ba, b̂a)) Ldfl =
   (1)/(S)∑a ∈ Pwa DFLa L = λclsLcls + λboxLiou + λdflLdfl DFLa 是框四边的平均
   [DFLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/precision_dfl_detection_loss.md)。权重
   λ 是 `class_loss_weight`、`bbox_loss_weight` 和 `dfl_loss_weight`。当没有锚点为正时，Liou 和 Ldfl 为 `0`。

> **参考**
> * 来源：从 [Real-Time Flying Object Detection with YOLOv8](https://arxiv.org/abs/2305.09972)、[YOLOv6: A Single-Stage Object Detection Framework for Industrial Applications](https://arxiv.org/abs/2209.02976) 和 [PP-YOLOE: An evolved version of YOLO](https://arxiv.org/abs/2203.16250) 重新实现。
 * 许可证：Apache-2.0（本项目）

> **注意事项**
> `forward` 的第一次调用会缓存锚点、它们的步幅和图像比例。它从 `features` 的形状以及节点的 `stride`、`grid_cell_offset` 和 `original_in_shape` 计算它们。后续调用会重用缓存，因此每个批次必须具有第一个批次的特征图大小。分配器在输入图像的像素中工作。框和 DFL 项以步幅的单位工作。当节点的 `reg_max` 为 `1` 时，`dfl` 项始终为 `0`。当锚点为正时，它的形状为 `[1]`，总损失也是如此。

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

```yaml
- name: PrecisionBBoxHead
  inputs: [RepPANNeck]
  losses:
    - name: PrecisionDFLDetectionLoss
```

 * `兼容:`: *
   节点：[PrecisionBBoxHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/precision_bbox_head.md)

#### 方法

##### init

```python
def __init__(tal_topk: int = 10, class_loss_weight: float = 0.5, bbox_loss_weight: float = 7.5, dfl_loss_weight: float = 1.5, skip_stal: bool = False, **kwargs):
```

初始化分配器、框损失和类别损失。

损失从节点读取 `n_classes`、`original_in_shape`、`stride`、`grid_cell_size`、`grid_cell_offset` 和 `reg_max`。如果没有 `node`，构造函数会引发
`RuntimeError`。代码改编自 [PPYOLOE_pytorch](https://github.com/Nioolek/PPYOLOE_pytorch/blob/master/ppyoloe/models)。为了获得最佳结果，将每个权重乘以
`trainer.accumulate_grad_batches`。

参数

 * `tal_topk` (`int`):
   [TaskAlignedAssigner](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/assigners/tal_assigner.md)
   的 `topk`，每个目标框的最大正锚点数。分配器的指数是固定的：`alpha` 为 `0.5`，`beta` 为 `6.0`。
 * `class_loss_weight` (`float`): 分类项的权重。
 * `bbox_loss_weight` (`float`): CIoU 框项的权重。
 * `dfl_loss_weight` (`float`): DFL 项的权重。
 * `skip_stal` (`bool`): 是否在分配器中关闭小目标感知标签分配 (STAL)。当目标框的一侧短于最小步幅时，STAL 会将该侧的长度设置为第二小步幅的长度。分配器仅使用放大的框来查找框内的锚点。
 * `**kwargs`: 转发给
   [BaseLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/base_loss.md)
   的关键字参数，例如 `node` 和 `final_loss_weight`。

##### decode_bbox

```python
def decode_bbox(anchor_points: Tensor, pred_dist: Tensor) -> Tensor:
```

将距离 bin logits 解码为框。

对于每个框的每侧，该方法在 `reg_max` bin 上应用 softmax。侧的距离是这些概率下的预期 bin
索引。[dist2bbox](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/boundingbox.md)
然后将四个距离转换为锚点周围的框。当 `reg_max` 为 `1` 时，该方法也会解码 bin，此时每个距离都为 `0`。

参数

 * `anchor_points` (`Tensor`): 形状为 `[N, 2]` 的锚点中心 `(x,
   y)`。[forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/precision_dfl_detection_loss.md)
   以每个锚点步幅的单位传递它们。
 * `pred_dist` (`Tensor`): 形状为 `[B, N, 4 * reg_max]` 的距离 bin logits，侧面顺序为左、上、右、下。

返回

 * `Tensor`: 形状为 `[B, N, 4]` 的框，采用 `xyxy` 格式，以 `anchor_points` 的单位表示。

##### forward

```python
def forward(features: list[Tensor], target: Tensor) -> tuple[Tensor, dict[str, Tensor]]:
```

计算一个批次的检测损失。

该方法将 `features` 分割为距离 bin logits 和所有锚点的类别 logits。它将 `target` 填充到每个图像相同数量的框，并将框转换为 `xyxy`
像素。[decode_bbox](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/precision_dfl_detection_loss.md)
给出预测框。[TaskAlignedAssigner](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/assigners/tal_assigner.md)
读取类别概率和预测框的像素分离副本。`xyxy` 坐标总和为 `0` 或更少的目标框被视为填充。第一次调用会缓存锚点和图像比例，如类注释所述。

参数

 * `features` (`list[Tensor]`): 每个尺度一个张量，形状为 `[B, 4 * reg_max + n_classes, H_i, W_i]`。节点的 `features` 输出。
 * `target` (`Tensor`): 形状为 `[N_gt, 6]` 的目标框，行格式为 `[batch_index, class, x, y, w, h]`。坐标是归一化到 `[0, 1]` 的 `xywh`，`x` 和 `y` 在左上角。任务的
   `boundingbox` 标签。

返回

 * `tuple[Tensor, dict[str, Tensor]]`: 标量加权总损失，以及一个将 `"class"`、`"iou"` 和 `"dfl"` 映射到权重之前分离项的字典。当节点的 `reg_max` 为 `1` 且锚点为正时，总损失和
   `"dfl"` 的形状为 `[1]`。

#### 属性

##### assigner

##### bbox_loss

##### bce

##### gt_bboxes_scale

##### node

##### supported_tasks
