# transformer_segmentation_head

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

Transformer 主干网络补丁 token 上的分割头。

## 类

### TransformerSegmentationHead

用于 Transformer 特征图的语义分割头。

[DINOv3 论文](https://arxiv.org/abs/2508.10104) 的 6.3.2 节在主干网络上放置了一个没有注入的 ViT-Adapter 和一个 Mask2Former 解码器。此头将 Mask2Former
替换为一个小型卷积解码器。[DinoV3](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/dinov3/dinov3.md)
在其 `return_sequence` 参数为 `False` 时，提供 `depth` 个分辨率相同的特征图。

 * `输入:`: * `inputs` (`list[Tensor]`): 每个图 [B, Ci, hi, wi]，任意分辨率
 * `输出:`: * `segmentation` (`Tensor`): [B, nclasses, H, W] logits

> **参考**
> * 来源：本项目。
 * 许可证：Apache-2.0（本项目）

> **注意事项**
> 一个 `1x1` 卷积、一个批归一化和一个 ReLU 将每个特征图投影到 `256` 个通道。头部将每个投影图的大小调整为图像高度和宽度的四分之一，并对这些图进行平均。然后，一个带有 ReLU 的 `3x3` 卷积和一个 `1x1` 卷积为每个类别提供一个 logit 图。最后一次调整将 logits 调整为图像大小。所有调整都是双线性的。该模式不改变输出键或形状。这包括导出模式。

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

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

```yaml
- name: TransformerSegmentationHead
  inputs: [DinoV3]
```

 * `兼容:`: * 附加索引：`"all"`，输入节点的所有输出
    * 所需标签：`segmentation`
    * 损失： *
      [BCEWithLogitsLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/bce_with_logits.md)
       * [CrossEntropyLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/cross_entropy.md)
       * [OHEMLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/ohem_loss.md)
       * [SigmoidFocalLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/sigmoid_focal_loss.md)
       * [SmoothBCEWithLogitsLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/smooth_bce_with_logits.md)
       * [SoftmaxFocalLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/softmax_focal_loss.md)
    * 指标： *
      [Accuracy](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md)
       * [ConfusionMatrix](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/confusion_matrix/confusion_matrix.md)
       * [DiceCoefficient](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/dice_coefficient.md)
       * [F1Score](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md)
       * [JaccardIndex](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md)
       * [MIoU](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/mean_iou.md)
       * [Precision](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md)
       * [Recall](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md)
    * 可视化工具：[SegmentationVisualizer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/segmentation_visualizer.md)
    * 导出解析器：`SegmentationParser`

#### 方法

##### init

```python
def __init__(**kwargs: Any):
```

构建解码器和每个特征图的一个投影。

构造函数从其大小的索引 `1` 读取每个图的通道数。因此，每个大小必须具有 `[B, C_i, h_i, w_i]` 的形式。

该类将
[BaseNode.in_sizes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
注释为列表。整数 `attach_index` 选择一个输出，因此
[BaseNode.in_sizes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
是一个单一大小。因此，这样的 `attach_index` 会使构造函数引发
[IncompatibleError](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/exceptions.md)。

参数

 * `**kwargs` (`Any`):
   [BaseNode](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
   的关键字参数。它们必须通过 `input_shapes` 或 `in_sizes` 包含输入大小，并通过 `n_classes` 或 `dataset_metadata`
   包含类别计数。[forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/transformer_segmentation_head.md)
   还需要 `original_in_shape`。

##### forward

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

将特征图解码为分割 logits。

`H` 和 `W` 是 `original_in_shape` 中的图像大小。该方法执行以下步骤：

 * 将每个特征图投影到 `256` 个通道。
 * 将每个投影图的大小调整为 `[H // 4, W // 4]`。
 * 对调整大小后的图进行平均。
 * 应用解码器，生成 `n_classes` 个通道。
 * 将 logits 的大小调整为 `[H, W]`。

两次调整都使用双线性插值。

> **示例**
> ```pycon
>>> import torch
>>> from torch import Size
>>> from luxonis_train.nodes import TransformerSegmentationHead
>>> sizes = [Size([1, 24, 4, 4]), Size([1, 12, 8, 8])]
>>> head = TransformerSegmentationHead(
...     n_classes=3,
...     input_shapes=[{"features": sizes}],
...     original_in_shape=Size([3, 64, 64]),
... )
>>> head([torch.zeros(size) for size in sizes]).shape
torch.Size([1, 3, 64, 64])
```

参数

 * `x` (`list[Tensor]`): 特征图，每个形状为 `[B, C_i, h_i, w_i]`，按构造函数输入大小的顺序排列。这些图可以具有不同的大小。

返回

 * `Tensor`: 形状为 `[B, n_classes, H, W]` 的 logits。[BaseNode.run](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md) 将它们放在 `"segmentation"` 键下。

#### 属性

##### head

##### in_sizes

附加输入的大小。

该属性使用适用的第一个规则：

 1. `in_sizes` 构造函数参数（如果已设置）。
 2. 唯一输入数据包的 `"features"` 条目。
 3. 该数据包的唯一条目。
 4. 该数据包中键与 `forward` 参数名称匹配的条目。它们的大小必须相等，并且该属性使用第一个。

规则 2 到 4 通过 [get_attached](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md) 传递条目。结果是整数 [attach_index](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md) 的单一大小，以及 `"all"` 或范围的列表大小。具有多个输入或形状不符合规则的节点必须改为读取 [input_shapes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)。

> **示例**
> ```pycon
>>> from torch import Size, Tensor
>>> from luxonis_train.nodes import BaseNode
>>> class Node(BaseNode, register=False):
...     def forward(self, x: list[Tensor]) -> list[Tensor]:
...         return x
>>> shapes = [
...     {"features": [Size([2, 8, 64, 64]), Size([2, 16, 32, 32])]}
... ]
>>> node = Node(input_shapes=shapes)
>>> node.attach_index
'all'
>>> node.in_sizes
[torch.Size([2, 8, 64, 64]), torch.Size([2, 16, 32, 32])]
>>> node.in_channels, node.in_height, node.in_width
([8, 16], [64, 32], [64, 32])
```

引发

 * `RuntimeError`: 当 `input_shapes` 缺失或不包含恰好一个数据包时。当没有键匹配 `forward` 参数时，或者当匹配的大小不同时。当
   [attach_index](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
   为 `None` 且条目为列表时。
 * `ValueError`: 当
   [attach_index](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
   不符合大小时。

##### n_classes

节点任务的类别数。

`n_classes` 构造函数参数优先。如果没有它，该值来自
[dataset_metadata](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
中
[task_name](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
的值。

引发

 * `RuntimeError`: 当构造函数既没有 `n_classes` 也没有 `dataset_metadata` 时。
 * `ValueError`: 当数据集中没有名为
   [task_name](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
   的任务时。

##### parser

##### projections
