# contextspatial

Python API: `luxonis_train.nodes.backbones.contextspatial`

BiSeNet V1 上下文空间骨干及其两条路径。

[SpatialPath](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/contextspatial.md)
保留图像的空间细节。[ContextPath](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/contextspatial.md)
运行另一个骨干以获得大的感受野。[ContextSpatial](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/contextspatial.md)
融合两条路径的输出。

## 类

### ContextPath

[ContextSpatial](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/contextspatial.md)
骨干之上的上下文路径。

该路径读取骨干的最后两个特征图。下面，`f16` 和 `f32` 是这些图，步长分别为 16 和 32。该路径执行以下步骤：

 1. 一个
    [AttentionRefinementBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
    将 `f16` 和 `f32` 中的每一个映射到 128 个通道。
 2. 一个全局平均池化和一个 `1x1`
    [ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
    将 `f32` 转换为每个图像的一个上下文向量。该路径将向量大小调整为 `f32` 的大小，并将其添加到精炼的 `f32` 中。
 3. 该路径将总和上采样 `2` 倍，应用一个 `3x3`
    [ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)，并将结果添加到精炼的
    `f16` 中。
 4. 该路径将第二个总和上采样 `2` 倍，并应用第二个 `3x3`
    [ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)。

步骤 2 到 4 的
[ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
层使用批归一化和 ReLU。所有大小调整都是双线性插值，并对齐角点。

注意力块和全局上下文层取决于骨干的通道数。因此，该路径在第一次
[forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/contextspatial.md)
调用中创建它们。在此调用之前，该路径的状态字典不包含它们。

#### 方法

##### init

```python
def __init__(backbone: nn.Module):
```

存储骨干并构建固定层。

固定层是两个上采样层和两个 `3x3`
精炼块。[forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/contextspatial.md)
构建其他层。

参数

 * `backbone` (`nn.Module`): 返回特征图序列的模块。该路径读取最后两个条目。它们必须具有步长 16 和 32。

##### forward

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

精炼最后两个骨干图并合并它们。

第一次调用还会创建两个注意力块和全局上下文层。它从骨干输出中读取它们的输入通道。新层使用 PyTorch 的默认设备和 dtype，而不是 `x` 的设备和 dtype。它们在训练状态下启动，即使路径处于评估状态也是如此。

> **示例**
> ```pycon
>>> import torch
>>> from luxonis_train.nodes import MobileNetV2
>>> path = ContextPath(MobileNetV2())
>>> hasattr(path, "arm16")
False
>>> [tuple(t.shape) for t in path(torch.zeros(2, 3, 64, 64))]
[(2, 128, 8, 8), (2, 128, 4, 4)]
>>> hasattr(path, "arm16")
True
```

参数

 * `x` (`Tensor`): 骨干的输入，形状为 `[B, C, H, W]`。步长为 32 的图，上采样 `2` 倍后，必须具有步长为 16 的图的大小。`H` 和 `W` 的所有 32 的倍数都满足此条件。在训练状态下，`B` 必须大于 `1`。原因是全局池化后的每个批归一化都会看到每个图像的一个值。

返回

 * `tuple[Tensor, Tensor]`: 两个具有 128 个通道的图。第一个是最终合并的图，大小是步长为 16 的图的两倍。第二个是精炼的步长为 32 的分支，经过上采样和 `3x3` [ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md) 后，大小与步长为 16 的图相同。当 `H` 和 `W` 是 `32` 的倍数时，形状为 `[B, 128, H / 8, W / 8]` 和 `[B, 128, H / 16, W / 16]`。

#### 属性

##### arm16

##### arm32

##### backbone

##### global_context

##### refine16

##### refine32

##### up16

##### up32

### ContextSpatial

BiSeNet V1 骨干，融合了空间路径和上下文路径。

该节点在同一图像上运行两条路径并融合它们的输出：

 * [SpatialPath](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/contextspatial.md) 保留细节。它以输入大小的 1/8 提供 128 个通道。
 * [ContextPath](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/contextspatial.md) 运行上下文骨干并精炼其最后两个特征图。它也以输入大小的 1/8 提供 128 个通道。
 * 一个 [FeatureFusionBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md) 将这两个图融合为 256 个通道。

[BiSeNetHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/bisenet_head.md) 可以读取融合的图。

 * `输入:`: * `inputs` (`Tensor`): [B, 3, H, W]
 * `输出:`: * `features` (`list[Tensor]`): [B, 256, H ⁄ 8, W ⁄ 8]

> **参考**
> * 来源：重新实现自 [BiSeNet: Bilateral Segmentation Network for Real-time Semantic Segmentation](https://arxiv.org/abs/1808.00897)。
 * 许可证：Apache-2.0 (本项目)

> **注意**
> 该节点为 3 个输入通道构建 [SpatialPath](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/contextspatial.md)。上下文骨干的最后两个特征图必须具有步长 16 和 32。然后，H 和 W 的所有 32 的倍数都适用。其他大小可能会导致特征图大小不同，PyTorch 随后会引发 `RuntimeError`。在训练状态下，批次必须包含多于一个图像。原因是全局池化后的每个批归一化都会看到每个图像的一个值。[ContextPath](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/contextspatial.md) 在第一次前向调用中创建其注意力精炼块和全局上下文层。在此调用之前，节点的状态字典不包含它们。

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

> **另请参阅**
> [The BiseNetv1 repository](https://github.com/taveraantonio/BiseNetv1)

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

```yaml
- name: ContextSpatial
```

 * `兼容:`: * 附加索引：`-1`，输入节点的最后一个输出

#### 方法

##### init

```python
def __init__(context_backbone: str | nn.Module = 'MobileNetV2', backbone_kwargs: Kwargs | None = None, **kwargs):
```

构建两条路径和特征融合块。

参数

 * `context_backbone` (`str | nn.Module`): [ContextPath](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/contextspatial.md) 的骨干。字符串命名 [luxonis_train.registry.NODES](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/registry.md) 中的一个节点。构造函数使用 `backbone_kwargs` 和 `kwargs` 构建该节点。未知名称会使注册表引发 `KeyError`。模块按原样传递给 [ContextPath](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/contextspatial.md)。骨干必须返回特征图序列，并且最后两个条目必须具有步长 16 和 32。默认为 `"MobileNetV2"`。
 * `backbone_kwargs` (`Kwargs | None`): 骨干节点的关键字参数。构造函数仅在 `context_backbone` 是字符串时读取它们。它将 `kwargs` 合并到此字典中，并且 `kwargs` 中的键会替换此处的相同键。非空字典会就地更改，因此调用者会看到合并的键。`None` 和空字典从一个新的空字典开始。
 * `**kwargs`: 转发给 [BaseNode](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md) 的关键字参数。从名称构建的骨干也会获得它们。

##### forward

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

将空间细节与精炼的上下文特征融合。

[SpatialPath](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/contextspatial.md) 和 [ContextPath](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/contextspatial.md) 都以输入大小的 1/8 提供 128 个通道。[FeatureFusionBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md) 将这两个图连接起来并融合为 256 个通道。该节点忽略 [ContextPath](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/contextspatial.md) 的第二个输出。

> **示例**
> ```pycon
>>> import torch
>>> from luxonis_train.nodes import ContextSpatial
>>> node = ContextSpatial()
>>> [tuple(t.shape) for t in node(torch.zeros(2, 3, 64, 64))]
[(2, 256, 8, 8)]
```

非 32 的倍数大小也可以工作：

```pycon
>>> [tuple(t.shape) for t in node(torch.zeros(2, 3, 62, 94))]
[(2, 256, 8, 12)]
```

参数

 * `inputs` (`Tensor`): 形状为 `[B, 3, H, W]` 的图像批次。`H` 和 `W` 的所有 32 的倍数都适用。其他大小可能会导致特征图大小不同，PyTorch 随后会引发 `RuntimeError`。在训练状态下，`B`
   必须大于 `1`。否则，批归一化会引发 `ValueError`。

返回

 * `list[Tensor]`: 包含一个融合特征图的列表，形状为 `[B, 256, ceil(H / 8), ceil(W / 8)]`。

#### 属性

##### context_path

##### ffm

##### spatial_path

### SpatialPath

[ContextSpatial](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/contextspatial.md)
的空间路径，保留图像细节。

三个带步长的
[ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
层将输入大小减小到其 1/8。第一层具有 `7x7` 内核，其他两层具有 `3x3` 内核。它们每个都具有步长 `2` 和 64 个输出通道。然后，一个 `1x1`
[ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
将结果映射到 `out_channels`。每层都使用批归一化和 ReLU。

> **示例**
> ```pycon
>>> import torch
>>> path = SpatialPath(3, 128)
>>> path(torch.zeros(1, 3, 64, 64)).shape
torch.Size([1, 128, 8, 8])
```

#### 方法

##### init

```python
def __init__(in_channels: int, out_channels: int):
```

初始化四个卷积。

参数

 * `in_channels` (`int`): 输入通道数。
 * `out_channels` (`int`): 输出通道数。

##### forward

```python
def forward(x: Tensor) -> Tensor:
```

将 `x` 的大小减小到其 1/8 并映射其通道。

参数

 * `x` (`Tensor`): 形状为 `[B, in_channels, H, W]` 的输入。

返回

 * `Tensor`: 形状为 `[B, out_channels, ceil(H / 8), ceil(W / 8)]` 的输出。

#### 属性

##### conv_1x1

##### conv_3x3_1

##### conv_3x3_2

##### conv_7x7
