# precision_seg_bbox_head

Python API: `luxonis_train.nodes.heads.precision_seg_bbox_head`

YOLOv8 实例分割头，它预测共享原型集上的掩码系数。

## 类

### PrecisionSegmentBBoxHead

精确实例分割和检测头。

该头将掩码添加到
[PrecisionBBoxHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/precision_bbox_head.md)
的框中。每个检测都从共享原型集中获取一个掩码。

 * `输入:`: * `inputs` (`list[Tensor]`): 每个尺度的 [B, Ci, Hi, Wi]，输入节点的最后 `n_heads` 个输出
 * `输出:`: * 训练: * `features` (`list[Tensor]`): 每个尺度的 [B, 4⋅regmax + nclasses, Hi, Wi]，logits
       * `prototypes` (`Tensor`): [B, nmasks, 2H0, 2W0]
       * `mask_coefficients` (`Tensor`): [B, nmasks, N]，N = ∑iHiWi
    * 评估: * `features` (`list[Tensor]`): 每个尺度的 [B, 4⋅regmax + nclasses, Hi, Wi]，logits
       * `prototypes` (`Tensor`): [B, nmasks, 2H0, 2W0]
       * `mask_coefficients` (`Tensor`): [B, nmasks, N]
       * `boundingbox` (`list[Tensor]`): 每张图像的 [Mi, 6]，`[x1, y1, x2, y2, score, class]`，像素
       * `instance_segmentation` (`list[Tensor]`): 每张图像的 [Mi, H, W]，二进制
       * `detections_pre_nms` (`Tensor`): [B, N, 5 + nclasses + nmasks]，仅在请求时
    * 导出: * `boundingbox` (`list[Tensor]`): 每个尺度的 [B, 5 + nclasses, Hi, Wi]，DFL 解码
       * `masks` (`list[Tensor]`): 每个尺度的 [B, nmasks, Hi, Wi]，掩码系数
       * `prototypes` (`Tensor`): [B, nmasks, 2H0, 2W0]

> **参考**
> * 来源：重新实现了 [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)。
 * 许可证：Apache-2.0 (本项目)

> **注意**
> 每个尺度在其 [PreciseDecoupledBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md) 旁边获得一个掩码分支。该分支为每个锚点预测 `n_masks` 个掩码系数。[SegProto](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md) 从第一个输入特征图构建 `n_masks` 个原型，分辨率是其两倍。在评估模式下，NMS 保留每个框的系数。然后 [refine_and_apply_masks](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/precision_seg_bbox_head.md) 将原型与系数结合，并将掩码裁剪到框中。它还将掩码调整为模型输入图像的大小。当像素值大于 `0` 时，该像素在掩码中。此条件等同于 σ(x) > 0.5，其中 σ 是 sigmoid。训练模式和导出模式跳过 NMS 和 [refine_and_apply_masks](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/precision_seg_bbox_head.md)。导出模式的 `masks` 输出包含掩码系数。

 * `变体:`: 无。通过 `params` 配置节点。

> **示例**
> 配置中 `model.nodes` 部分的节点条目：

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

 * `兼容:`: * 必需标签: * `boundingbox`
       * `instance_segmentation`
    * 使用者:
      [InstanceSegmentationModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/instance_segmentation/v1/model.md)
    * 损失:
      [PrecisionDFLSegmentationLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/precision_dfl_segmentation_loss.md)
    * 指标: *
      [ConfusionMatrix](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/confusion_matrix/confusion_matrix.md)
       * [MeanAveragePrecision](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/mean_average_precision/mean_average_precision.md)
       * [PrecisionRecallCurve](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/precision_recall_curve.md)
    * 可视化器:
      [InstanceSegmentationVisualizer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/instance_segmentation_visualizer.md)
    * 导出解析器: `YOLOExtendedParser`

#### 方法

##### init

```python
def __init__(n_heads: Literal[2, 3, 4] = 3, n_masks: int = 32, n_proto: int = 64, conf_thres: float = 0.25, iou_thres: float = 0.45, max_det: int = 300, **kwargs):
```

初始化掩码分支和原型生成器。

父类构建框分支。每个尺度的掩码分支有两个 `3x3`
[ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
层，带有批归一化和 SiLU。接着是一个 `1x1` 卷积，输出通道数为 `n_masks`。每个掩码分支的隐藏宽度是 `n_masks` 和 `in_channels[0] // 4` 中较大的一个。`in_channels[0]`
是第一个尺度的通道数。[SegProto](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
也读取第一个特征图。

参数

 * `n_heads` (`Literal[2, 3, 4]`): 尺度数量。头部读取输入节点的最后 `n_heads` 个输出。`attach_index` 参数替换此选择。它必须选择一个范围或 `"all"`。整数索引会使构造函数引发
   `TypeError`。当头部获得的输出较少时，它会记录警告并使用该数量。当 `attach_index` 选择更多输出时，构造函数会引发 `ValueError`。默认为 `3`。
 * `n_masks` (`int`): 原型掩码的数量。它也是每个锚点的掩码系数数量。默认为 `32`。
 * `n_proto` (`int`):
   [SegProto](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
   原型生成器的隐藏通道数。默认为 `64`。
 * `conf_thres` (`float`): NMS 仅保留最大类别分数高于此值的框。该值必须在 `[0, 1]` 之间。默认为 `0.25`。
 * `iou_thres` (`float`): 当一个框与同类别且分数更高的框的 IoU 高于此值时，NMS 会移除该框。该值必须在 `[0, 1]` 之间。默认为 `0.45`。
 * `max_det` (`int`): NMS 为每张图像保留的最大框数。默认为 `300`。
 * `**kwargs`:
   [PrecisionBBoxHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/precision_bbox_head.md)
   的关键字参数，例如 `reg_max`，以及
   [BaseNode](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
   的关键字参数。它们必须包含 `original_in_shape`、通过 `input_shapes` 或 `in_sizes` 的输入大小，以及通过 `n_classes` 或 `dataset_metadata` 的类别计数。

##### forward

```python
def forward(inputs: list[Tensor]) -> Packet[Tensor]:
```

运行分支并返回当前模式的数据包。

每个
[PreciseDecoupledBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
返回一个尺度的特征、类别 logits 和距离 bin
logits。[SegProto](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
从第一个特征图构建原型。每个尺度的掩码分支预测其锚点的掩码系数。导出模式优先于训练模式。数据包取决于模式：

 * 导出模式：`"boundingbox"` 为每个尺度保存一个形状为 `[B, 5 + n_classes, H_i, W_i]` 的映射。其通道是步幅单位的距离 `(l, t, r, b)`、最大类别分数和类别分数。当 `reg_max` 大于 `1`
   时，[DFL](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
   解码距离。分数是 sigmoid 概率。`"masks"` 为每个尺度保存形状为 `[B, n_masks, H_i, W_i]` 的掩码系数。`"prototypes"` 保存形状为 `[B, n_masks, 2 * H_0, 2 * W_0]`
   的原型。
 * 训练模式：`"features"` 为每个尺度保存形状为 `[B, 4 * reg_max + n_classes, H_i, W_i]` 的回归和类别 logits。`"prototypes"`
   与导出模式相同。`"mask_coefficients"` 保存所有 `N` 个锚点的系数，形状为 `[B, n_masks, N]`，其中 N = ∑iHiWi。
 * 评估模式：训练模式的键和 NMS 结果。`"boundingbox"` 为每张图像保存一个形状为 `[M_i, 6]` 的张量。每行是 `[x1, y1, x2, y2, score,
   class]`，角点在模型输入图像的像素中。`"instance_segmentation"` 保存这些框的掩码，形状为 `[M_i, H, W]`，值为 `0` 和 `1`。`H` 和 `W` 来自
   `original_in_shape`。对于没有框的图像，`M_i` 为 `0`，掩码张量的数据类型为 `uint8`。在调用
   [BaseDetectionHead.request_detections_pre_nms](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/base_detection_head.md)
   后，数据包还包含 NMS 输入 `"detections_pre_nms"`，形状为 `[B, N, 5 + n_classes + n_masks]`。

> **示例**
> 一个新的头部处于训练模式：

```pycon
>>> import torch
>>> from torch import Size
>>> from luxonis_train.nodes import PrecisionSegmentBBoxHead
>>> sizes = [Size([1, 8, 16, 16]), Size([1, 16, 8, 8])]
>>> head = PrecisionSegmentBBoxHead(
...     n_heads=2,
...     n_masks=4,
...     n_proto=8,
...     n_classes=2,
...     input_shapes=[{"features": sizes}],
...     original_in_shape=Size([3, 64, 64]),
... )
>>> out = head([torch.zeros(size) for size in sizes])
>>> out["prototypes"].shape, out["mask_coefficients"].shape
(torch.Size([1, 4, 32, 32]), torch.Size([1, 4, 320]))
```

对于零输入，一个新的头部会给每个类别一个低于 `conf_thres` 的分数。在评估模式下，NMS 因此不保留任何框和掩码：

```pycon
>>> out = head.eval()([torch.zeros(size) for size in sizes])
>>> boxes, masks = out["boundingbox"], out["instance_segmentation"]
>>> boxes[0].shape, masks[0].shape
(torch.Size([0, 6]), torch.Size([0, 64, 64]))
```

参数

 * `inputs` (`list[Tensor]`): 每个尺度的一个特征图，形状为 `[B, C_i, H_i, W_i]`。`H_0` 和 `W_0` 是第一个映射的高度和宽度。

返回

 * `Packet[Tensor]`: 当前模式的数据包，包含描述中给出的键。

#### 属性

##### export_output_names

导出模型的输出名称。

导出模型中头部有 `2 * n_heads + 1` 个输出。ONNX 导出按输出键对它们进行排序。默认名称遵循此顺序：

 * `output1_yolov8` 到 `output{n_heads}_yolov8` 用于 `"boundingbox"` 映射。
 * `output1_masks` 到 `output{n_heads}_masks` 用于 `"masks"` 系数。
 * `protos_output` 用于 `"prototypes"`。

仅当 `export_output_names` 参数包含恰好 `n_heads` 个名称时，它才会替换默认名称。每次给出默认名称时，头部都会记录警告。该值从不为 `None`。

警告： 包含 `n_heads` 个名称的参数的名称数量少于导出模型的输出数量。因此，ONNX 导出会记录警告并忽略这些名称。NN Archive 仍然将这 `n_heads` 个名称列为头部的输出。

> **示例**
> 一个具有两个尺度的头部给出五个默认名称。该示例关闭了日志记录器，因此不显示警告：

```pycon
>>> from loguru import logger
>>> from torch import Size
>>> from luxonis_train.nodes import PrecisionSegmentBBoxHead
>>> sizes = [Size([1, 8, 16, 16]), Size([1, 16, 8, 8])]
>>> head = PrecisionSegmentBBoxHead(
...     n_heads=2,
...     n_classes=2,
...     input_shapes=[{"features": sizes}],
...     original_in_shape=Size([3, 64, 64]),
... )
>>> logger.disable("luxonis_train")
>>> head.export_output_names
['output1_yolov8', 'output2_yolov8', 'output1_masks',
 'output2_masks', 'protos_output']
>>> logger.enable("luxonis_train")
```

##### parser

##### proto

##### segmentation_heads

## 函数

### refine_and_apply_masks

```python
def refine_and_apply_masks(mask_prototypes: Tensor, predicted_masks: Tensor, bounding_boxes: Tensor, height: int, width: int, upsample: bool = False) -> Tensor:
```

构建每个检测的掩码并将其裁剪到其框中。

检测的掩码是 ∑kckPk，其中 Pk 是原型 k，ck 是检测的掩码系数 k。该函数将框从图像大小缩放到原型大小。它将每个框外部的掩码像素设置为零。使用 `upsample`，它通过双线性插值将掩码调整为 `height` 乘以 `width`。当像素值 x
> 0 时，该像素在掩码中。此条件等同于 σ(x) > 0.5，其中 σ 是 sigmoid。插值可以使掩码稍微超出其框。

> **示例**
> 框覆盖 `8x8` 图像的左上角四分之一，因此掩码保留 `4x4` 原型的左上角四分之一：

```pycon
>>> import torch
>>> prototypes = torch.ones(1, 4, 4)
>>> coefficients = torch.tensor([[1.0]])
>>> boxes = torch.tensor([[0.0, 0.0, 4.0, 4.0]])
>>> masks = refine_and_apply_masks(
...     prototypes, coefficients, boxes, height=8, width=8
... )
>>> masks[0].int().tolist()
[[1, 1, 0, 0], [1, 1, 0, 0], [0, 0, 0, 0], [0, 0, 0, 0]]
>>> refine_and_apply_masks(
...     prototypes, coefficients, boxes, 8, 8, upsample=True
... ).shape
torch.Size([1, 8, 8])
```

参数

 * `mask_prototypes` (`Tensor`): 原型掩码，形状为 `[n_masks, h, w]`。
 * `predicted_masks` (`Tensor`): 每个检测的掩码系数，形状为 `[N, n_masks]`。
 * `bounding_boxes` (`Tensor`): 每个检测的 `xyxy` 框，在 `height` 乘以 `width` 图像的像素中，形状为 `[N, 4]`。
 * `height` (`int`): 图像高度，以像素为单位。
 * `width` (`int`): 图像宽度，以像素为单位。
 * `upsample` (`bool`): 是否将掩码调整为 `height` 乘以 `width`。默认为 `False`。

返回

 * `Tensor`: 值为 `0` 和 `1` 的浮点掩码张量。使用 `upsample` 时，其形状为 `[N, height, width]`，不使用时为 `[N, h, w]`。当 `predicted_masks` 或
   `bounding_boxes` 没有行时，函数返回形状为 `[0, height, width]` 的 `uint8` 张量。
