# unet

Python API: `luxonis_train.nodes.blocks.unet`

U-Net 的编码器和解码器块，带或不带跳跃连接。

## 类

### BaseDecoder

解码器的基类，镜像
[SimpleEncoder](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md)。

解码器在编码器乘数前添加 `1` 并反向遍历列表。每对相邻条目提供一个解码器步骤。该步骤将大小加倍，并将第一个条目的通道映射到第二个条目的通道。对于 `[1, 2]`，步骤将 `2 * base_width` 通道映射到 `base_width`，然后将
`base_width` 映射到 `base_width`。然后 `3x3` 卷积将 `base_width` 通道映射到 `out_channels`。

每个步骤都使用 `align_corners=True` 的 `"simple_upsample"`，并在其
[UpBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md)
中使用批归一化。该类未定义
`forward`。[SimpleDecoder](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md)
和
[UNetDecoder](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md)
添加了它。

#### 方法

##### init

```python
def __init__(base_width: int, out_channels: int, encoder_width_multipliers: list[float], n_convolutions: int, block: type[SimpleDecoderBlock | UNetDecoderBlock]):
```

构建解码器步骤和输出卷积。

参数

 * `base_width` (`int`): 编码器的 `base_hidden_channels`。
 * `out_channels` (`int`): 输出通道数。
 * `encoder_width_multipliers` (`list[float]`): 编码器的 `width_multipliers`。
 * `n_convolutions` (`int`): 每个步骤堆栈中 `3x3`
   [ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
   层的数量。
 * `block` (`type[SimpleDecoderBlock | UNetDecoderBlock]`): 解码器步骤的类。

#### 属性

##### blocks

解码器步骤，从小到大。

##### final_conv

`3x3` 输出卷积。

### BaseDecoderBlock

解码器步骤的基类：一个
[UpBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md)
和一个
[ConvStack](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)。

该类未定义
`forward`。[SimpleDecoderBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md)
和
[UNetDecoderBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md)
添加了它。

#### 方法

##### init

```python
def __init__(in_channels: int, out_channels: int, conv_in_channels: int, kernel_size: int, use_norm: bool, align_corners: bool, upsample_mode: Literal['simple_upsample', 'conv_upsample', 'conv_transpose'], n_repeats: int):
```

构建上采样块和卷积堆栈。

参数

 * `in_channels` (`int`): 输入通道数。
 * `out_channels` (`int`): 上采样块和堆栈的输出通道数。
 * `conv_in_channels` (`int`): 堆栈的输入通道数。
 * `kernel_size` (`int`):
   [UpBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md)
   的核大小。只有 `"conv_transpose"` 使用它。
 * `use_norm` (`bool`):
   [UpBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md)
   的 `3x3`
   [ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
   是否有批归一化。堆栈始终有批归一化。
 * `align_corners` (`bool`):
   [UpBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md)
   中插值的 `align_corners` 选项。
 * `upsample_mode` (`Literal['simple_upsample', 'conv_upsample', 'conv_transpose']`):
   [UpBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md)
   的上采样方法。因子为 `2`。
 * `n_repeats` (`int`): 堆栈中 `3x3`
   [ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
   层的数量。

#### 属性

##### conv

上采样后的卷积堆栈。

##### up

对输入进行上采样的块。

### EncoderBlock

编码器步骤，包含一个可选的 `2x2` 最大池化和一个
[ConvStack](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)。

> **示例**
> ```pycon
>>> import torch
>>> from luxonis_train.nodes.blocks import EncoderBlock
>>> x = torch.zeros(1, 3, 16, 16)
>>> EncoderBlock(3, 8, n_repeats=2)(x).shape
torch.Size([1, 8, 8, 8])
>>> EncoderBlock(3, 8, n_repeats=2, max_pool=False)(x).shape
torch.Size([1, 8, 16, 16])
```

#### 方法

##### init

```python
def __init__(in_channels: int, out_channels: int, n_repeats: int, *, max_pool: bool = True):
```

构建池化和卷积堆栈。

参数

 * `in_channels` (`int`): 输入通道数。
 * `out_channels` (`int`): 输出通道数。
 * `n_repeats` (`int`): 堆栈中 `3x3` [ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md) 层的数量。
 * `max_pool` (`bool`): 在堆栈之前，是否通过步长为 `2` 的 `2x2` 最大池化将大小减半。否则，该步骤保持大小不变。

### SimpleDecoder

[SimpleDecoderBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md) 步骤的解码器，没有跳跃连接。

解码器接收 [SimpleEncoder](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md) 的输出，其 `base_hidden_channels` 等于 `base_width` 且乘数相同。当编码器的输入大小可被 2n 整除时，其中 n 是乘数数量，它会恢复编码器的输入大小。[SimpleEncoder](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md) 的示例展示了这对。

#### 方法

##### init

```python
def __init__(base_width: int, out_channels: int, encoder_width_multipliers: list[float], n_convolutions: int = 2):
```

构建解码器步骤和输出卷积。

参数

 * `base_width` (`int`): 编码器的 `base_hidden_channels`。
 * `out_channels` (`int`): 输出通道数。
 * `encoder_width_multipliers` (`list[float]`): 编码器的 `width_multipliers`。
 * `n_convolutions` (`int`): 每个步骤堆栈中 `3x3` [ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md) 层的数量。
 * `block`: 解码器步骤的类。

##### forward

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

运行解码器步骤和输出卷积。

参数

 * `x` (`Tensor`): [SimpleEncoder](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md) 的输出，形状为 `[B, C, h, w]`，其中 C = ⌊m⋅wb⌋。这里 m 是最后一个乘数，wb 是 `base_width`。

返回

 * `Tensor`: 形状为 `[B, out_channels, h * 2^n, w * 2^n]` 的输出，其中 `n` 是乘数数量。

### SimpleDecoderBlock

没有跳跃连接的解码器步骤。

该步骤将输入上采样 `2` 倍，并在结果上运行 [ConvStack](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)。

#### 方法

##### init

```python
def __init__(in_channels: int, out_channels: int, kernel_size: int, use_norm: bool, align_corners: bool, upsample_mode:
Literal['simple_upsample', 'conv_upsample', 'conv_transpose'], n_repeats: int):
```

构建上采样块和卷积堆栈。

堆栈将 `out_channels` 通道映射到 `out_channels`。

参数

 * `in_channels` (`int`): 输入通道数。
 * `out_channels` (`int`): 输出通道数。
 * `kernel_size` (`int`): [UpBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md) 的核大小。只有 `"conv_transpose"` 使用它。
 * `use_norm` (`bool`): [UpBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md) 的 `3x3` [ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md) 是否有批归一化。
 * `align_corners` (`bool`): [UpBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md) 中插值的 `align_corners` 选项。
 * `upsample_mode` (`Literal['simple_upsample', 'conv_upsample', 'conv_transpose']`): [UpBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md) 的上采样方法。
 * `n_repeats` (`int`): 堆栈中 `3x3` [ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md) 层的数量。

##### forward

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

上采样输入并运行卷积堆栈。

参数

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

返回

 * `Tensor`: 对于插值模式，输出形状为 `[B, out_channels, 2H, 2W]`。[UpBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md) 为 `"conv_transpose"` 提供大小。

### SimpleEncoder

[EncoderBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md) 步骤的编码器，返回最后一个特征图。

编码器为 `width_multipliers` 的每个条目设置一个步骤，并为最后一个条目再设置一个步骤。条目 m 的步骤具有 ⌊m⋅c⌋ 个输出通道，其中 c 是 `base_hidden_channels`。第一步保持大小不变。后面的每个步骤都将其减半并向下取整。对于 n 个条目，输出比输入小 2n 倍。[RecSubNet](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/recsubnet/recsubnet.md) 将编码器与 [SimpleDecoder](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md) 配对。

> **示例**
> ```pycon
>>> import torch
>>> from luxonis_train.nodes.blocks import (
...     SimpleDecoder,
...     SimpleEncoder,
... )
>>> encoder = SimpleEncoder(3, 8, [1, 2])
>>> len(encoder)
3
>>> features = encoder(torch.zeros(1, 3, 16, 16))
>>> features.shape
torch.Size([1, 16, 4, 4])
>>> SimpleDecoder(8, 3, [1, 2])(features).shape
torch.Size([1, 3, 16, 16])
```

#### 方法

##### init

```python
def __init__(in_channels: int, base_hidden_channels: int, width_multipliers: list[float], n_convolutions: int = 2):
```

构建编码器步骤。

参数

 * `in_channels` (`int`): 输入通道数。
 * `base_hidden_channels` (`int`): 基础宽度。每个步骤都将其乘以 `width_multipliers` 的对应条目。
 * `width_multipliers` (`list[float]`): 每个步骤的宽度因子。空列表将导致构造函数引发 `IndexError`。
 * `n_convolutions` (`int`): 每个步骤中 `3x3`
   [ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
   层的数量。

### UNetDecoder

[UNetDecoderBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md)
步骤的解码器，带跳跃连接。

解码器接收
[UNetEncoder](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md)
的特征图，其 `base_hidden_channels` 等于 `base_width`
且乘数相同。[forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md)
从列表中移除最后一个图，如示例所示。

> **示例**
> ```pycon
>>> import torch
>>> from luxonis_train.nodes.blocks import UNetDecoder, UNetEncoder
>>> encoder = UNetEncoder(3, 8, [1, 2])
>>> decoder = UNetDecoder(8, 2, [1, 2])
>>> features = encoder(torch.zeros(1, 3, 16, 16))
>>> decoder(features).shape
torch.Size([1, 2, 16, 16])
>>> len(features)
2
```

#### 方法

##### init

```python
def __init__(base_width: int, out_channels: int, encoder_width_multipliers: list[float], n_convolutions: int = 2):
```

构建解码器步骤和输出卷积。

参数

 * `base_width` (`int`): 编码器的 `base_hidden_channels`。
 * `out_channels` (`int`): 输出通道数。
 * `encoder_width_multipliers` (`list[float]`): 编码器的 `width_multipliers`。
 * `n_convolutions` (`int`): 每个步骤堆栈中 `3x3` [ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md) 层的数量。
 * `block`: 解码器步骤的类。

##### forward

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

解码 [UNetEncoder](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md) 的特征图。

该方法从 `inputs` 中弹出最小的图并从它开始。然后每个步骤将下一个剩余的图作为其跳跃连接，从小到大。

警告： 该方法会移除 `inputs` 的最后一个元素。

参数

 * `inputs` (`list[Tensor]`): [UNetEncoder](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md) 的特征图，从大到小。列表中的图数量必须比解码器步骤多一个。否则 `zip` 会引发 `ValueError`。

返回

 * `Tensor`: 形状为 `[B, out_channels, H, W]` 的输出，其中 `H` 和 `W` 是第一个图的大小。

### UNetDecoderBlock

带编码器跳跃连接的解码器步骤。

该步骤将输入上采样 `2` 倍，并沿通道轴连接跳跃特征图。然后它在结果上运行 [ConvStack](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)。跳跃特征图必须具有 `in_channels` 通道和上采样输入的大小。

> **示例**
> ```pycon
>>> import torch
>>> from luxonis_train.nodes.blocks import UNetDecoderBlock
>>> block = UNetDecoderBlock(
...     in_channels=8,
...     out_channels=4,
...     kernel_size=3,
...     use_norm=True,
...     align_corners=True,
...     upsample_mode="simple_upsample",
...     n_repeats=1,
... )
>>> x, skip_x = torch.zeros(1, 8, 4, 4), torch.zeros(1, 8, 8, 8)
>>> block(x, skip_x).shape
torch.Size([1, 4, 8, 8])
```

#### 方法

##### init

```python
def __init__(in_channels: int, out_channels: int, kernel_size: int, use_norm: bool, align_corners: bool, upsample_mode: Literal['simple_upsample', 'conv_upsample', 'conv_transpose'], n_repeats: int):
```

构建上采样块和卷积堆栈。

堆栈将 `in_channels + out_channels` 通道映射到 `out_channels`。

参数

 * `in_channels` (`int`): 输入和跳跃特征图的通道数。
 * `out_channels` (`int`): 输出通道数。
 * `kernel_size` (`int`):
   [UpBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md)
   的核大小。只有 `"conv_transpose"` 使用它。
 * `use_norm` (`bool`):
   [UpBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md)
   的 `3x3`
   [ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
   是否有批归一化。
 * `align_corners` (`bool`):
   [UpBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md)
   中插值的 `align_corners` 选项。
 * `upsample_mode` (`Literal['simple_upsample', 'conv_upsample', 'conv_transpose']`):
   [UpBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md)
   的上采样方法。
 * `n_repeats` (`int`): 堆栈中 `3x3`
   [ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
   层的数量。

##### forward

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

上采样 `x`，连接 `skip_x`，并运行堆栈。

参数

 * `x` (`Tensor`): 形状为 `[B, in_channels, H, W]` 的输入。
 * `skip_x` (`Tensor`): 形状为 `[B, in_channels, 2H, 2W]` 的编码器特征图。

返回

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

### UNetEncoder

[SimpleEncoder](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md)，返回每个步骤的特征图。

[UNetDecoder](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/unet.md)
接收列表并将这些图用作跳跃连接。[DiscSubNetHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/discsubnet_head/discsubnet_head.md)
将两者配对。

> **示例**
> ```pycon
>>> import torch
>>> from luxonis_train.nodes.blocks import UNetEncoder
>>> encoder = UNetEncoder(3, 8, [1, 2])
>>> features = encoder(torch.zeros(1, 3, 16, 16))
>>> [tuple(feature.shape) for feature in features]
[(1, 8, 16, 16), (1, 16, 8, 8), (1, 16, 4, 4)]
```

#### 方法

##### forward

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

按顺序运行步骤并收集每个输出。

参数

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

返回

 * `list[Tensor]`: 每个步骤的一个特征图，从大到小。步骤 `i` 的图的高度和宽度是 `x` 的 2i 倍。

### UpBlock

通过 `stride` 上采样，然后是一个 `3x3` [ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)。

`upsample_mode` 选择上采样方式：

 * `"conv_transpose"`: 一个 `torch.nn.ConvTranspose2d`，从 `in_channels` 到 `out_channels`，带有 `kernel_size`、`stride` 且无填充。输出大小为 (H − 1)⋅s + k，其中步长为 s，核大小为 k。
 * `"simple_upsample"`: 一个 `torch.nn.Upsample`，通过 `stride` 上采样。然后 [ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md) 将 `in_channels` 映射到 `out_channels`。
 * `"conv_upsample"`: 相同的 `torch.nn.Upsample`，然后是一个 `1x1` `torch.nn.Conv2d`，从 `in_channels` 到 `out_channels`。

[ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md) 保持大小不变并输出 `out_channels` 通道。

> **示例**
> ```pycon
>>> import torch
>>> from luxonis_train.nodes.blocks import UpBlock
>>> x = torch.zeros(1, 8, 4, 4)
>>> options = {
...     "kernel_size": 2,
...     "use_norm": True,
...     "align_corners": False,
... }
>>> UpBlock(8, 4, "conv_transpose", **options)(x).shape
torch.Size([1, 4, 8, 8])
>>> UpBlock(8, 4, "conv_upsample", **options)(x).shape
torch.Size([1, 4, 8, 8])
```

#### 方法

##### init

```python
def __init__(in_channels: int, out_channels: int, upsample_mode: Literal['simple_upsample', 'conv_upsample', 'conv_transpose'], kernel_size: int, use_norm: bool, align_corners: bool, stride: int = 2, activation: nn.Module | bool | None = True, interpolation_mode: Literal['nearest', 'linear', 'bilinear', 'bicubic', 'trilinear'] = 'bilinear'):
```

构建上采样层和卷积块。

参数

 * `in_channels` (`int`): 输入通道数。
 * `out_channels` (`int`): 输出通道数。
 * `upsample_mode` (`Literal['simple_upsample', 'conv_upsample', 'conv_transpose']`): 上采样方法。类描述列出了每种方法的层。
 * `kernel_size` (`int`): 转置卷积的核大小。其他方法忽略它。
 * `use_norm` (`bool`):
   [ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
   是否有批归一化。
 * `align_corners` (`bool`): `torch.nn.Upsample` 的 `align_corners` 选项。`"conv_transpose"` 忽略它。
 * `stride` (`int`): 上采样因子。
 * `activation` (`nn.Module | bool | None`):
   [ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
   的激活函数。`True` 选择 `torch.nn.ReLU`。`False` 或 `None` 选择 `torch.nn.Identity`。
 * `interpolation_mode` (`Literal['nearest', 'linear', 'bilinear', 'bicubic', 'trilinear']`): `torch.nn.Upsample`
   的模式。`"conv_transpose"` 忽略它。警告： 只有 `"bilinear"` 和 `"bicubic"` 适用于 4D 输入。`"nearest"` 拒绝任何 `align_corners` 值。`"linear"` 需要 3D
   输入，`"trilinear"` 需要 5D 输入。
