# blocks

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

MicroNet 主干网络的块。

## 类

### ChannelShuffle

通道混洗，用于交错组的通道。

该模块将通道分成 `groups` 个大小相等的组。输出首先获取每个组的第一个通道，然后是每个组的第二个通道，依此类推。混洗后的分组卷积会读取所有组的通道。当 `groups` 等于 `1` 或通道数时，顺序不变。

> **示例**
> ```pycon
>>> import torch
>>> x = torch.arange(6.0).view(1, 6, 1, 1)
>>> ChannelShuffle(3)(x).flatten().tolist()
[0.0, 2.0, 4.0, 1.0, 3.0, 5.0]
```

#### 方法

##### init

```python
def __init__(groups: int):
```

存储组的数量。

参数

 * `groups` (`int`): 组的数量。输入通道数必须是它的倍数。

##### forward

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

交错组的通道。

参数

 * `x` (`Tensor`): 形状为 `[B, C, H, W]` 的输入。`C` 必须是 `groups` 的倍数。否则，重塑会引发 `RuntimeError`。

返回

 * `Tensor`: 通道顺序已更改的输入，形状相同。

### DepthSpatialSepConv

因子分解的深度卷积，用于扩展通道。

一个 `in_channels` 组的 k×1 卷积将通道乘以 `expand[0]` 并沿高度应用步幅。一个每个输入通道一个组的 1×k 卷积将通道乘以 `expand[1]` 并沿宽度应用步幅。每个卷积后都有一个批归一化。卷积没有偏置，块没有激活。

> **示例**
> ```pycon
>>> import torch
>>> conv = DepthSpatialSepConv(4, (2, 3), kernel_size=3, stride=2)
>>> conv(torch.zeros(1, 4, 9, 9)).shape
torch.Size([1, 24, 5, 5])
```

#### 方法

##### init

```python
def __init__(in_channels: int, expand: tuple[int, int], kernel_size: int, stride: int):
```

初始化两个深度卷积。

参数

 * `in_channels` (`int`): 输入通道数。
 * `expand` (`tuple[int, int]`): k×1 和 1×k 卷积的通道乘数。该块有 `in_channels * expand[0] * expand[1]` 个输出通道。
 * `kernel_size` (`int`): 核大小 k。填充为 `kernel_size // 2`。
 * `stride` (`int`): 沿高度和宽度的步幅。

##### forward

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

应用两个卷积及其批归一化。

参数

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

返回

 * `Tensor`: 形状为 `[B, in_channels * expand[0] * expand[1], H', W']` 的输出。对于奇数 `kernel_size`，`H'` 是 `ceil(H / stride)`，`W'` 是
   `ceil(W / stride)`。

#### 属性

##### conv

### DYShiftMax

MicroNet 的动态 Shift-Max 激活。

激活将每个通道与下一个组的一个通道混合。移位输入 x̃ 对于组 `g` 的通道 `c`，取组 `g + 1` 的通道 `c + 1`。两个索引都环绕。对于 2 个组中的 8 个通道，x̃ 的通道 `0` 取通道
`5`，即第二个组的第二个通道。对于两个分支，输出为

y = max(a1x + b1x̃, a2x + b2x̃)

对于一个分支，输出为 y = a1x + b1x̃。

一个挤压网络从输入计算系数。它将每个通道沿高度和宽度平均。两个线性层之间有一个 `ReLU`，然后是一个硬 sigmoid。该模块将结果从 `[0, 1]` 映射到 `[-2, 2]`，并添加偏移量 `init_a` 和
`init_b`。每个系数对于每个样本都有 `out_channels` 个值。

> **示例**
> ```pycon
>>> import torch
>>> act = DYShiftMax(8, 8, groups=2)
>>> act(torch.ones(2, 8, 4, 4)).shape
torch.Size([2, 8, 4, 4])
```

#### 方法

##### init

```python
def __init__(in_channels: int, out_channels: int, init_a: tuple[float, float] = (0.0, 0.0), init_b: tuple[float, float] = (0.0,
0.0), use_relu: bool = True, groups: int = 6, reduction: int = 4, expansion: bool = False):
```

初始化挤压网络和通道移位。

参数

 * `in_channels` (`int`): 输入通道数。它必须是组数的倍数。
 * `out_channels` (`int`): 每个系数的通道数。[forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/micronet/blocks.md) 需要它等于 `in_channels` 或 `1`。当为 `1` 时，样本的所有通道共享每个系数。
 * `init_a` (`tuple[float, float]`): a1 和 a2 的偏移量。[forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/micronet/blocks.md) 将 `init_a[0]` 添加到 a1。它不读取 `init_a[1]`，因为它将 `init_b[1]` 添加到 a2。
 * `init_b` (`tuple[float, float]`): b1 和 b2 的偏移量。`init_b[1]` 也用于 a2。
 * `use_relu` (`bool`): `True` 选择两个分支及其最大值，一种动态形式的 `ReLU`。`False` 选择一个没有最大值的分支。
 * `groups` (`int`): 用于移位的通道组数。当为 `1` 时，移位将通道移动一个位置。
 * `reduction` (`int`): 挤压网络隐藏层的 `in_channels` 的除数。该模块将 `in_channels // reduction` 四舍五入到最接近的 `4` 的倍数，最小为 `4`。当四舍五入下降超过 10% 时，它会添加 `4`。
 * `expansion` (`bool`): 当 `True` 且 `groups` 不为 `1` 时，组数为 `in_channels // groups`。然后 `groups` 是每个组中的通道数。

##### forward

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

使用输入的系数应用激活。

参数

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

返回

 * `Tensor`: 激活后的输入，形状相同。

#### 属性

##### avg_pool

##### fc

### MicroBlock

MicroNet 的基本块。

该块将输入扩展到 `in_channels * expand_ratio[0] * expand_ratio[1]` 个通道。`groups_1` 和 `groups_2` 选择三种布局之一：

 * lite 块，当 `groups_1[0]` 为 `0` 时。一个 [DepthSpatialSepConv](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/micronet/blocks.md) 扩展通道并应用步幅。一个分组的 1×1 卷积将它们投影到 `out_channels`。
 * transition 块，当 `groups_2[1]` 为 `0` 且 `groups_1[0]` 不为 `0` 时。一个分组的 1×1 卷积扩展通道。该块没有深度卷积，也没有投影。其输出保留扩展的通道。
 * full 块，在所有其他情况下。一个分组的 1×1 卷积扩展通道。一个没有扩展的 [DepthSpatialSepConv](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/micronet/blocks.md) 应用步幅。第二个分组的 1×1 卷积将通道投影到 `out_channels`。

每个卷积都有一个批归一化，没有偏置。一个 [DYShiftMax](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/micronet/blocks.md)、一个 `ReLU6` 或没有激活跟随每个 1×1 卷积和每个 [DepthSpatialSepConv](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/micronet/blocks.md)，如 `dy_shift` 所选。[ChannelShuffle](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/micronet/blocks.md) 层混合组的通道。当 `stride` 为 `1` 且 `out_channels` 等于 `in_channels` 时，该块将其输入添加到其输出。

> **示例**
> ```pycon
>>> import torch
>>> x = torch.zeros(2, 8, 16, 16)
>>> lite = MicroBlock(
...     8, 16, stride=2, groups_1=(0, 8), groups_2=(4, 4)
... )
>>> lite(x).shape
torch.Size([2, 16, 8, 8])
```

过渡块在其层中忽略 `out_channels` 和 `stride`：

```pycon
>>> transition = MicroBlock(
...     8,
...     16,
...     stride=2,
...     expand_ratio=(1, 6),
...     groups_1=(4, 4),
...     groups_2=(0, 0),
... )
>>> transition(x).shape
torch.Size([2, 48, 16, 16])
```

#### 方法

##### init

```python
def __init__(in_channels: int, out_channels: int, kernel_size: int = 3, stride: int = 1, expand_ratio: tuple[int, int] = (2, 2), groups_1: tuple[int, int] = (0, 6), groups_2: tuple[int, int] = (1, 1), dy_shift: tuple[int, int, int] = (2, 0, 1), reduction_factor: int = 1, init_a: tuple[float, float] = (1.0, 1.0), init_b: tuple[float, float] = (0.0, 0.0)):
```

构建 lite、transition 或 full 布局的层。

参数

 * `in_channels` (`int`): 输入通道数。
 * `out_channels` (`int`): lite 或 full 块的输出通道数。transition 块的层不读取它。残差检查在所有布局中都读取它。
 * `kernel_size` (`int`):
   [DepthSpatialSepConv](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/micronet/blocks.md)
   的核大小 k，它是一个 k×1 和一个 1×k 卷积。transition 块忽略它。
 * `stride` (`int`):
   [DepthSpatialSepConv](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/micronet/blocks.md)
   的步幅。transition 块的层忽略它。
 * `expand_ratio` (`tuple[int, int]`): 扩展的两个通道乘数。lite 块在其
   [DepthSpatialSepConv](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/micronet/blocks.md)
   的每一半中应用一个乘数。其他布局在扩展 1×1 卷积中应用乘积。
 * `groups_1` (`tuple[int, int]`): 第一个值是扩展 1×1 卷积的组数。`0` 选择 lite 块。第二个值设置投影前
   [DYShiftMax](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/micronet/blocks.md)
   层的组数，以及第一个激活后
   [ChannelShuffle](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/micronet/blocks.md)
   的组数。在 full 块的深度卷积后的
   [DYShiftMax](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/micronet/blocks.md)
   中，当值不为 `1` 时，组数是扩展通道数除以该值。在 transition 块中，该值设置其唯一的
   [DYShiftMax](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/micronet/blocks.md)
   的组数。
 * `groups_2` (`tuple[int, int]`): 第一个值是投影 1×1 卷积的组数。第二个值设置最后一个
   [DYShiftMax](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/micronet/blocks.md)
   和其后
   [ChannelShuffle](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/micronet/blocks.md)
   的组数。当 `groups_1[0]` 不为 `0` 时，`0` 选择 transition 块。
 * `dy_shift` (`tuple[int, int, int]`): 扩展卷积后、深度卷积后和投影后的激活。在前两个位置，正值选择
   [DYShiftMax](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/micronet/blocks.md)，其他值选择
   `ReLU6`。`2` 选择两个分支，其他正值选择一个分支。在最后一个位置，正值选择一个单分支
   [DYShiftMax](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/micronet/blocks.md)，其他值选择无激活。lite
   块忽略第一个值。transition 块只读取最后一个值，用于其扩展后的激活。在 lite 或 full 块中，非 `0` 值也会在激活后添加一个
   [ChannelShuffle](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/micronet/blocks.md)。在
   lite 块中，第二个值添加一个 `C // 2` 组，其中 `C` 是扩展通道数。在 full 块中，前两个值在深度激活后共享一个。当两个值都不为 `0` 时，它有 `C // 4` 组；当只有一个不为 `0` 时，它有 `C // 2`
   组。最后一个值添加一个 `out_channels // 2` 组。在 lite 块中，只有当 `out_channels` 为偶数时才这样做。
 * `reduction_factor` (`int`):
   [DYShiftMax](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/micronet/blocks.md)
   的挤压网络的缩减。激活使用 `8 * reduction_factor` 的 `reduction`。lite 块的最后一个激活使用 `4 * reduction_factor`。当 `out_channels` 小于扩展通道数时，full
   块的最后一个激活也使用。
 * `init_a` (`tuple[float, float]`):
   [DYShiftMax](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/micronet/blocks.md)
   中输入权重的偏移量。扩展后和深度卷积后的激活使用它们。最后一个激活和 transition 块的激活使用 `(1.0, 0.0)`。
 * `init_b` (`tuple[float, float]`):
   [DYShiftMax](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/micronet/blocks.md)
   中移位输入权重的偏移量。与 `init_a` 相同的激活使用它们。其他使用 `(0.0, 0.0)`。

##### forward

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

运行层，并为残差连接添加输入。

参数

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

返回

 * `Tensor`: 形状为 `[B, C, H', W']` 的输出。`C` 对于 lite 或 full 块是 `out_channels`，对于 transition 块是扩展的通道数。对于奇数 `kernel_size`，`H'` 是
   `ceil(H / stride)`，`W'` 是 `ceil(W / stride)`。transition 块保留 `H` 和 `W`。通过残差连接，输出是层输出和 `inputs` 的和。对于 transition 块，除非扩展通道数等于
   `in_channels`，否则此和会引发 `RuntimeError`。

#### 属性

##### layers

### SpatialSepConvSF

带通道混洗的空间可分离卷积。

一个 k×1 卷积将输入映射到 `outs[0]` 个通道，并沿高度应用步幅。一个 `outs[0]` 组的 1×k 卷积将通道乘以 `outs[1]`，并沿宽度应用步幅。每个卷积后都有一个批归一化。一个 `outs[0]` 组的
[ChannelShuffle](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/micronet/blocks.md)
结束该块。卷积没有偏置，块没有激活。

> **示例**
> ```pycon
>>> import torch
>>> conv = SpatialSepConvSF(3, (4, 2), kernel_size=3, stride=2)
>>> conv(torch.zeros(1, 3, 32, 32)).shape
torch.Size([1, 8, 16, 16])
```

#### 方法

##### init

```python
def __init__(in_channels: int, outs: tuple[int, int], kernel_size: int, stride: int):
```

初始化两个卷积和通道混洗。

参数

 * `in_channels` (`int`): 输入通道数。
 * `outs` (`tuple[int, int]`): 通道布局。第一个值是 k×1 卷积的输出通道数。它也是 1×k 卷积和混洗的组数。第二个值是 1×k 卷积的通道乘数。
 * `kernel_size` (`int`): 核大小 k。填充为 `kernel_size // 2`。
 * `stride` (`int`): 沿高度和宽度的步幅。

##### forward

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

应用卷积、批归一化和混洗。

参数

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

返回

 * `Tensor`: 形状为 `[B, outs[0] * outs[1], H', W']` 的输出。对于奇数 `kernel_size`，`H'` 是 `ceil(H / stride)`，`W'` 是 `ceil(W / stride)`。

#### 属性

##### conv

### Stem

MicroNet 的 Stem。

Stem 是一个核大小为 `3` 的 [SpatialSepConvSF](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/micronet/blocks.md)，后跟一个原地 `ReLU6`。

> **示例**
> ```pycon
>>> import torch
>>> stem = Stem(3, stride=2, outs=(3, 2))
>>> stem(torch.zeros(1, 3, 32, 32)).shape
torch.Size([1, 6, 16, 16])
```

#### 方法

##### init

```python
def __init__(in_channels: int, stride: int, outs: tuple[int, int] = (4, 4)):
```

初始化卷积和激活。

参数

 * `in_channels` (`int`): 输入通道数。
 * `stride` (`int`): 沿高度和宽度的步幅。
 * `outs` (`tuple[int, int]`):
   [SpatialSepConvSF](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/micronet/blocks.md)
   的通道布局。第一个值是 3×1 卷积的输出通道数及其后的组数。第二个值是通道乘数。Stem 有 `outs[0] * outs[1]` 个输出通道。

##### forward

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

应用卷积和 `ReLU6`。

参数

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

返回

 * `Tensor`: 形状为 `[B, outs[0] * outs[1], ceil(H / stride), ceil(W / stride)]` 的输出，值为 `[0, 6]`。

#### 属性

##### stem
