# blocks

Python API: `luxonis_train.nodes.backbones.ddrnet.blocks`

DDRNet 骨干网络的块。

[BasicDDRBackbone](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/ddrnet/blocks.md)
包含主干和 `layer1` 到 `layer4` 阶段。
[DAPPM](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/ddrnet/blocks.md)
以多个尺度池化最深层的特征。
[make_layer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/ddrnet/blocks.md)
将残差块堆叠成一个阶段。

> **参考**
> * 改编自：[super-gradients](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/training/models/segmentation_models/ddrnet.py)
 * 原始代码：[ydhongHIT/DDRNet](https://github.com/ydhongHIT/DDRNet)
 * 论文：[用于道路场景实时精确语义分割的深度双分辨率网络](https://arxiv.org/pdf/2101.06085.pdf)
 * 许可证：[Apache License 2.0](https://github.com/Deci-AI/super-gradients/blob/master/LICENSE.md)

## 类

### BasicDDRBackbone

DDRNet 的主干和类 ResNet 阶段。

主干是两个 `3x3`
[ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
层。每个层都有步长 `2`、偏置、批归一化和 ReLU。
[make_layer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/ddrnet/blocks.md)
从 `block` 构建阶段。此列表给出了每个部分的输出通道和输出高度，对于高度为 `H` 的输入。宽度遵循相同的比例。

 * `stem`：`stem_channels` 通道，在 `H / 4`。
 * `layer1`：`stem_channels` 通道，在 `H / 4`。
 * `layer2`：`2 * stem_channels` 通道，在 `H / 8`。
 * `layer3`：一个 `torch.nn.ModuleList`，包含 `max(layer3_repeats, 1)` 个阶段，在 `H / 16` 处有 `4 * stem_channels` 个通道。只有第一个阶段的步长为 `2`。
 * `layer4`：`8 * stem_channels` 通道，在 `H / 32`。

该类未实现 `forward`，因此调用模块会引发 `NotImplementedError`。
[DDRNet](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/ddrnet/ddrnet.md)
逐一调用主干和阶段，并将其高分辨率分支放在 `layer3` 和 `layer4` 旁边。

#### 方法

##### init

```python
def __init__(block: type[nn.Module], stem_channels: int, layers: list[int], in_channels: int, layer3_repeats: int = 1):
```

构建主干和四个阶段。

参数

 * `block` (`type[nn.Module]`)：每个阶段的块类，例如
   [ResNetBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/resnet.md)。
   [make_layer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/ddrnet/blocks.md)
   列出了该类必须接受的参数。
 * `stem_channels` (`int`)：主干和 `layer1` 的输出通道数。`layer2`、`layer3` 和 `layer4` 的通道数分别是其 2、4 和 8 倍。
 * `layers` (`list[int]`)：`layer1`、`layer2`、每个 `layer3` 阶段和 `layer4` 中的块数。骨干网络读取前四个条目。
 * `in_channels` (`int`)：输入通道数。
 * `layer3_repeats` (`int`)：`layer3` 阶段的数量。小于 `1` 的值仍会构建一个阶段。默认为 `1`。

##### get_backbone_output_number_of_channels

```python
def get_backbone_output_number_of_channels(self) -> dict[str, int]:
```

返回后续阶段的输出通道数。

该方法通过主干和所有阶段运行形状为 `[1, in_channels, 320, 320]` 的随机 CPU 张量，因此骨干网络必须在 CPU 上。它读取 `layer2` 之后、最后一个 `layer3` 阶段之后和 `layer4` 之后的通道维度。运行从
PyTorch 的全局随机生成器中抽取。在训练状态下，运行还会更新批归一化的运行统计信息。

> **示例**
> ```pycon
>>> from luxonis_train.nodes.blocks import ResNetBlock
>>> backbone = BasicDDRBackbone(
...     ResNetBlock,
...     stem_channels=8,
...     layers=[1, 1, 1, 1],
...     in_channels=3,
... )
>>> backbone.get_backbone_output_number_of_channels()
{'layer2': 16, 'layer3': 32, 'layer4': 64}
```

返回

 * `dict[str, int]`：键为 `"layer2"`、`"layer3"` 和 `"layer4"` 的通道计数。

#### 属性

##### layer1

##### layer2

##### layer3

##### layer4

##### stem

### DAPPM

DDRNet 的深度聚合金字塔池化模块 (DAPPM)。

该块在相同的输入上运行一个 [DAPPMBranch](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/ddrnet/blocks.md) 和一系列 [MergeDAPPMBranch](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/ddrnet/blocks.md) 层。每个合并分支添加其前面分支的输出。该块沿通道轴连接所有分支的输出。批归一化、ReLU 和 `1x1` 卷积将其压缩到 `out_channels`。批归一化、ReLU 和 `1x1` 卷积的快捷方式将输入映射到 `out_channels`。输出是压缩映射和快捷方式的总和。

> **示例**
> ```pycon
>>> import torch
>>> spp = DAPPM(
...     in_channels=8,
...     branch_channels=4,
...     out_channels=16,
...     kernel_sizes=[1, 5, 9, 17, 0],
...     strides=[1, 2, 4, 8, 0],
... )
>>> len(spp.branches)
4
>>> spp(torch.zeros(1, 8, 16, 16)).shape
torch.Size([1, 16, 16, 16])
```

#### 方法

##### init

```python
def __init__(in_channels: int, branch_channels: int, out_channels: int, kernel_sizes: list[int], strides: list[int], interpolation_mode: str = 'bilinear'):
```

初始化分支、压缩和快捷方式。

参数

 * `in_channels` (`int`)：输入通道数。
 * `branch_channels` (`int`)：每个分支的输出通道数。
 * `out_channels` (`int`)：输出通道数。
 * `kernel_sizes` (`list[int]`)：每个分支的核大小。第一个条目配置
   [DAPPMBranch](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/ddrnet/blocks.md)。其他每个条目配置一个
   [MergeDAPPMBranch](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/ddrnet/blocks.md)。
 * `strides` (`list[int]`)：每个分支的步长，按 `kernel_sizes` 的顺序。
   [DAPPMBranch](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/ddrnet/blocks.md)
   解释了值 `0`、`1` 和更大的值。
 * `interpolation_mode` (`str`)：`torch.nn.functional.interpolate` 在每个分支中用于调整大小的模式。默认为 `"bilinear"`。

引发

 * `IndexError`：当 `kernel_sizes` 或 `strides` 为空时。
 * `ValueError`：当 `kernel_sizes` 和 `strides` 长度不同时。

##### forward

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

以每个尺度池化 `x` 并融合结果。

参数

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

返回

 * `Tensor`：形状为 `[B, out_channels, H, W]` 的输出。

#### 属性

##### branches

##### compression

##### shortcut

##### start_branch

### DAPPMBranch

[DAPPM](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/ddrnet/blocks.md)
块的一个池化分支。

该分支应用批归一化、可选的下采样、ReLU 和 `1x1` 卷积到 `branch_channels`。然后
[UpscaleOnline](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
将结果调整为输入的高度和宽度。`stride` 选择下采样：

 * `0`：全局平均池化到 `1x1`。
 * `1`：无下采样。
 * 大于 `1`：使用核大小 `kernel_size`、步长 `stride` 和填充 `stride` 的深度可分离卷积。

> **示例**
> ```pycon
>>> import torch
>>> branch = DAPPMBranch(8, kernel_size=5, stride=2, branch_channels=4)
>>> branch(torch.zeros(1, 8, 16, 16)).shape
torch.Size([1, 4, 16, 16])
```

#### 方法

##### init

```python
def __init__(in_channels: int, kernel_size: int, stride: int, branch_channels: int, interpolation_mode: str = 'bilinear'):
```

初始化下采样层和上采样。

参数

 * `in_channels` (`int`)：输入通道数。
 * `kernel_size` (`int`)：深度可分离卷积的核大小。仅当 `stride` 大于 `1` 时才使用。
 * `stride` (`int`)：选择下采样。`0` 选择全局平均池化，`1` 选择无下采样，更大的值选择具有此步长的深度可分离卷积。
 * `branch_channels` (`int`)：输出通道数。
 * `interpolation_mode` (`str`)：`torch.nn.functional.interpolate` 用于调整到输入大小的模式。默认为 `"bilinear"`。

##### forward

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

在 `x` 上运行分支并将输出调整为 `[H, W]`。

参数

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

返回

 * `Tensor`：形状为 `[B, branch_channels, H, W]` 的输出。

#### 属性

##### down_scale

##### up_scale

### MergeDAPPMBranch

一个 [DAPPM](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/ddrnet/blocks.md) 分支，它合并了前一个分支的输出。

该分支计算 [DAPPMBranch](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/ddrnet/blocks.md) 输出并将其添加到前一个分支的输出中。然后，批归一化、ReLU 和 `3x3` 卷积处理总和。卷积保持 `branch_channels`。

> **示例**
> ```pycon
>>> import torch
>>> branch = MergeDAPPMBranch(
...     8, kernel_size=5, stride=2, branch_channels=4
... )
>>> previous = torch.zeros(1, 4, 16, 16)
>>> branch(torch.zeros(1, 8, 16, 16), previous).shape
torch.Size([1, 4, 16, 16])
```

#### 方法

##### init

```python
def __init__(in_channels: int, kernel_size: int, stride: int, branch_channels: int, interpolation_mode: str = 'bilinear'):
```

初始化分支层和合并层。

参数

 * `in_channels` (`int`)：输入通道数。
 * `kernel_size` (`int`)：深度可分离卷积的核大小。仅当 `stride` 大于 `1` 时才使用。
 * `stride` (`int`)：选择下采样。`0` 选择全局平均池化，`1` 选择无下采样，更大的值选择具有此步长的深度可分离卷积。
 * `branch_channels` (`int`)：输出通道数。前一个分支的输出必须具有相同的数量。
 * `interpolation_mode` (`str`)：`torch.nn.functional.interpolate` 用于调整到输入大小的模式。默认为 `"bilinear"`。

##### forward

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

在 `x` 上运行分支并合并前一个分支的输出。

参数

 * `x`
   (`Tensor`)：[DAPPM](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/ddrnet/blocks.md)
   块的输入，形状为 `[B, in_channels, H, W]`。
 * `skip_x` (`Tensor`)：前一个分支的输出，形状为 `[B, branch_channels, H, W]`。

返回

 * `Tensor`：形状为 `[B, branch_channels, H, W]` 的输出。

#### 属性

##### process

## 函数

### make_layer

```python
def make_layer(block: type[nn.Module], in_channels: int, channels: int, n_blocks: int, stride: int = 1, expansion: int = 1) -> nn.Sequential:
```

将 `n_blocks` 个残差块堆叠成一个阶段。

该函数为每个块调用 `block` 一次。每次调用都将输入通道和 `channels` 作为位置参数传递，并将 `stride`、`final_relu` 和 `expansion` 作为关键字参数传递。第一个块获取 `in_channels` 和
`stride`。其他块获取 `channels * expansion` 输入通道和步长 `1`。最后一个块获取 `final_relu=False`，其他每个块获取 `final_relu=True`。因此，阶段输出没有最终的 ReLU。小于 `1` 的
`n_blocks` 值仍会构建一个块。

> **示例**
> ```pycon
>>> import torch
>>> from luxonis_train.nodes.blocks import ResNetBlock
>>> stage = make_layer(ResNetBlock, 8, 16, n_blocks=3, stride=2)
>>> [type(block.final_relu).__name__ for block in stage]
['ReLU', 'ReLU', 'Identity']
>>> stage(torch.zeros(1, 8, 8, 8)).shape
torch.Size([1, 16, 4, 4])
```

参数

 * `block` (`type[nn.Module]`)：块类，例如 [ResNetBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/resnet.md) 或 [ResNetBottleneck](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/resnet.md)。它必须接受上述参数并输出 `channels * expansion` 通道。
 * `in_channels` (`int`)：第一个块的输入通道数。
 * `channels` (`int`)：每个块的隐藏通道数。
 * `n_blocks` (`int`)：块数。
 * `stride` (`int`)：第一个块的步长。默认为 `1`。
 * `expansion` (`int`)：每个块的扩展因子。默认为 `1`。

返回

 * `nn.Sequential`：按顺序排列的块。该阶段输出 `channels * expansion` 通道。
