# precision_dfl_segmentation_loss

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

YOLOv8 检测损失，带有一个用于实例分割的掩码项。

## 类

### PrecisionDFLSegmentationLoss

[PrecisionSegmentBBoxHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/precision_seg_bbox_head.md)
的实例分割损失。

该损失在
[PrecisionDFLDetectionLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/precision_dfl_detection_loss.md)
的基础上添加了一个掩码项。对于每个正锚点，损失根据锚点的掩码系数和头部的原型构建掩码 logits。二元交叉熵将这些 logits 与分配框的目标掩码进行比较，仅在该框内部进行比较。

 * `输入:`: * `features` (`list[Tensor]`): 每个尺度的 [B, 4**reg*max + nclasses, Hi, Wi]，距离 bin logits 后跟类别 logits
    * `prototypes` (`Tensor`): [B, nmasks, 2H*0, 2W*0]
    * `mask_coefficients` (`Tensor`): [B, nmasks, N]，用于所有尺度的 N 个锚点
    * `target_boundingbox` (`Tensor`): [Ngt, 6]，`[batch_index, class, x, y, w, h]`，`xywh` 归一化，`x` 和 `y` 在左上角
    * `target_instance_segmentation` (`Tensor`): [Ngt, H, W]，每个目标框一个掩码，顺序相同
 * `输出:`: * `Tensor`: 标量总损失
    * `dict[str, Tensor]`: 标量子损失 `class`、`iou`、`dfl`、`seg`，已分离且不带权重
 * `公式:`: Lcls、Liou 和 Ldfl 项与
   [PrecisionDFLDetectionLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/precision_dfl_detection_loss.md)
   相同。P 是批次中所有图像中的正锚点集。对于锚点 a，掩码 logit 图 ma = ∑kca, k pk 是原型 pk 的总和，由锚点的掩码系数 ca, k 加权。原型的大小为 h×w。ga 是分配框的目标掩码，大小为 h×w。Aa
   是该框面积占图像面积的比例。cropa 将框外的像素设置为 `0`： Lseg = (1)/(|P|)∑a ∈ P(1)/(Aa h**w)∑x, ycropa(BCE(ma, ga))x, y L = λclsLcls + λboxLiou +
   λdflLdfl + λboxLseg 掩码项使用框权重 `bbox_loss_weight`。

> **参考**
> * 来源：重新实现了 [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（本项目）

> **注意**
> 当批次中没有正锚点时，`seg` 项和总损失为 NaN。掩码项除以正锚点的数量，即使该数量为 `0`。[PrecisionDFLDetectionLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/precision_dfl_detection_loss.md) 中关于锚点缓存和 `reg_max` 为 `1` 的注意事项也适用于此处。

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

```yaml
- name: PrecisionSegmentBBoxHead
  inputs: [RepPANNeck]
  losses:
    - name: PrecisionDFLSegmentationLoss
```

 * `兼容:`: *
   使用者：[InstanceSegmentationModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/instance_segmentation/v1/model.md)
    * 节点：[PrecisionSegmentBBoxHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/precision_seg_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):
```

使用检测项的设置初始化损失。

掩码项没有自己的设置。损失需要一个类型为
[PrecisionSegmentBBoxHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/precision_seg_bbox_head.md)
的 `node`。当配置使用预定义的
[InstanceSegmentationModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/instance_segmentation/v1/model.md)
且 `trainer.smart_cfg_auto_populate` 为 `True` 时，配置会更改这三个权重。它将每个权重设置为其默认值乘以 `trainer.accumulate_grad_batches`。这些值会替换模型 `loss_params`
中的权重。

参数

 * `tal_topk` (`int`):
   [TaskAlignedAssigner](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/assigners/tal_assigner.md)
   的 `topk`，每个目标框的最大正锚点数。
 * `class_loss_weight` (`float`): 分类项的权重。
 * `bbox_loss_weight` (`float`): CIoU 框项和掩码项的权重。
 * `dfl_loss_weight` (`float`): DFL 项的权重。
 * `skip_stal` (`bool`): 是否在分配器中关闭小目标感知标签分配 (STAL)。
 * `**kwargs`: 转发给
   [PrecisionDFLDetectionLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/precision_dfl_detection_loss.md)
   的关键字参数，例如 `node` 和 `final_loss_weight`。

##### compute_segmentation_loss

```python
def compute_segmentation_loss(fg_mask: Tensor, gt_masks: Tensor, gt_idx: Tensor, bboxes: Tensor, batch_ids: Tensor, proto: Tensor, pred_masks: Tensor) -> Tensor:
```

计算整个批次的掩码项。

对于图像的每个正锚点，该方法将掩码系数与原型相乘得到掩码 logits。它计算这些 logits 与分配框的目标掩码之间的二元交叉熵。它将框外的损失设置为
`0`。锚点的损失是所有掩码像素的平均值。该方法将此平均值除以框面积占图像面积的比例。没有正锚点的图像会添加一个零，该零取决于 `proto` 和 `pred_masks`，因此两者都保留在自动梯度图中。该方法读取
[forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/precision_dfl_segmentation_loss.md)
缓存的图像比例，因此
[forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/precision_dfl_segmentation_loss.md)
必须先运行。

参数

 * `fg_mask` (`Tensor`): 正锚点的布尔掩码，形状为 `[B, N]`。
 * `gt_masks` (`Tensor`): 所有图像的目标掩码，形状为 `[N_gt, h, w]`，原型大小。一个图像的掩码按其目标框的顺序排列。
 * `gt_idx` (`Tensor`): 对于每个锚点，其图像中分配框的索引，形状为 `[B, N]`。
 * `bboxes` (`Tensor`): 输入图像中 `xyxy` 像素的分配框，形状为 `[B, N, 4]`。
 * `batch_ids` (`Tensor`): 每个目标掩码的图像索引，形状为 `[N_gt, 1]`。
 * `proto` (`Tensor`): 掩码原型，形状为 `[B, n_masks, h, w]`。
 * `pred_masks` (`Tensor`): 掩码系数，形状为 `[B, N, n_masks]`。

返回

 * `Tensor`: 锚点损失的标量和，除以正锚点的数量。当 `fg_mask` 没有正锚点时为 `NaN`。

##### forward

```python
def forward(features: list[Tensor], prototypes: Tensor, mask_coefficients: Tensor, target_boundingbox: Tensor, target_instance_segmentation: Tensor) -> tuple[Tensor, dict[str, Tensor]]:
```

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

首先，该方法准备 `target_instance_segmentation`：

 * 当它为空时，该方法将其替换为形状为 `[0, h, w]` 的空张量，即原型大小。
 * 当其大小不是原型大小时，该方法使用最近邻插值将其大小调整为 `[h, w]`。

类别、框和 DFL 项与
[PrecisionDFLDetectionLoss.forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/precision_dfl_detection_loss.md)
中的相同。第一次调用以相同的方式缓存锚点和图像比例。该方法还保留每个锚点分配的目标框的索引。它将此索引和像素中的分配框传递给
[compute_segmentation_loss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/precision_dfl_segmentation_loss.md)。

参数

 * `features` (`list[Tensor]`): 每个尺度一个张量，形状为 `[B, 4 * reg_max + n_classes, H_i, W_i]`。节点的 `features` 输出。
 * `prototypes` (`Tensor`): 掩码原型，形状为 `[B, n_masks, h, w]`。节点的 `prototypes` 输出。
 * `mask_coefficients` (`Tensor`): 掩码系数，形状为 `[B, n_masks, N]`，用于所有尺度的 `N` 个锚点。节点的 `mask_coefficients` 输出。
 * `target_boundingbox` (`Tensor`): 目标框，形状为 `[N_gt, 6]`，行格式为 `[batch_index, class, x, y, w, h]`。坐标 `xywh` 归一化到 `[0, 1]`，`x` 和 `y`
   在左上角。任务的 `boundingbox` 标签。
 * `target_instance_segmentation` (`Tensor`): 目标掩码，形状为 `[N_gt, H, W]`，与 `target_boundingbox` 的每一行对应，顺序相同。任务的
   `instance_segmentation` 标签。

返回

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

#### 属性

##### node

##### supported_tasks
