# ocr_ctc_head

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

OCR 头，用于预测 CTC 的每个序列步骤的字符类别分数。

## 类

### OCRCTCHead

OCR CTC 序列分类头。

 * `输入:`: * `inputs` (`Tensor`): [B, C, 1, T]
 * `输出:`: * 训练、评估: * `ocr` (`Tensor`): [B, T, nclasses] logits，类别 `0` 为空白
    * 导出: * `ocr` (`Tensor`): [B, T, nclasses] softmax 概率

> **参考**
> * 来源: 改编自 [PaddlePaddle/PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR) (Apache-2.0)。
 * 许可证: Apache-2.0

> **注意事项**
> 该头移除了特征图的高度轴，因此高度必须为 `1`。每个 T 列成为序列的一个步骤。一个线性层将每个步骤映射到类别 logits。使用 `mid_channels` 时，两个线性层之间有一个 ReLU 来完成此操作。

类别来自 `alphabet`，而不是数据集。nclasses 是
[out_channels](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ocr_ctc_head.md)。类别
`0` 是 CTC 空白。`alphabet` 的唯一字符按排序顺序排列。如果 `ignore_unknown=False`，则最后一个类别是
`"<UNK>"`。[CTCLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/ctc_loss.md)
和
[OCRAccuracy](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/ocr_accuracy.md)
使用
[encoder](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ocr_ctc_head.md)
对文本标签进行编码。[OCRVisualizer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/ocr_visualizer.md)
使用
[decoder](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ocr_ctc_head.md)
解码预测。

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

> **另请参阅**
> * [PaddleOCR 的 CTC 头](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppocr/modeling/heads/rec_ctc_head.py)

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

```yaml
- name: OCRCTCHead
  inputs: [SVTRNeck]
  params:
    alphabet: ["a", "b", "c"]
```

 * `兼容:`: * 附加索引: `-1`，输入节点的最后一个输出
    * 所需标签: `metadata/text`
    * 使用者:
      [OCRRecognitionModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/ocr_recognition/v1/model.md)
    * 损失:
      [CTCLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/ctc_loss.md)
    * 指标:
      [OCRAccuracy](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/ocr_accuracy.md)
    * 可视化工具:
      [OCRVisualizer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/ocr_visualizer.md)
    * 导出解析器: `ClassificationSequenceParser`

#### 方法

##### init

```python
def __init__(alphabet: list[str], ignore_unknown: bool = True, mid_channels: int | None = None, return_feats: bool = False, **kwargs):
```

构建编码器、解码器和线性层。

参数

 * `alphabet` (`list[str]`): 头预测的字符。编码器对其进行排序，并将空白类放在它们之前。每个字符只能出现一次。
 * `ignore_unknown` (`bool`): 编码器是否删除 `alphabet` 中不存在的标签字符。如果为 `False`，编码器将字符映射到额外的类别 `"<UNK>"`，因此头会预测多一个类别。
 * `mid_channels` (`int | None`): 两个线性层之间的隐藏特征数量。`None` 表示从 `in_channels` 到
   [out_channels](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ocr_ctc_head.md)
   的一个线性层。
 * `return_feats` (`bool`): 头将值存储在 `return_feats`
   属性中。[forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ocr_ctc_head.md)
   不读取它，因此该值无效。
 * `**kwargs`:
   [BaseNode](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
   的关键字参数。它们必须包含 `input_shapes` 或 `in_sizes`。

引发

 * `ValueError`: 当 `alphabet` 包含重复字符时。

##### forward

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

计算序列每个步骤的类别分数。

该方法移除高度轴并将宽度轴移动到通道轴之前。特征图的每一列都是一个步骤。线性层将每个步骤的 `C` 通道映射到类别 logits。在导出模式下，该方法对类别应用 softmax。

> **示例**
> 字母表 `["b", "a"]` 给出三个类别: 空白、`"a"` 和 `"b"`。

```pycon
>>> import torch
>>> from torch import Size
>>> from luxonis_train.nodes import OCRCTCHead
>>> head = OCRCTCHead(
...     alphabet=["b", "a"],
...     input_shapes=[{"features": [Size([1, 8, 1, 4])]}],
... )
>>> head(torch.zeros(1, 8, 1, 4)).shape
torch.Size([1, 4, 3])
>>> head.export = True
>>> probabilities = head(torch.zeros(1, 8, 1, 4))
>>> torch.allclose(probabilities.sum(dim=-1), torch.tensor(1.0))
True
```

参数

 * `x` (`Tensor`): 形状为 `[B, C, 1, T]` 的特征图。如果高度不是 `1`，`permute` 会引发 `RuntimeError`。

返回

 * `Tensor`: 形状为 `[B, T, out_channels]` 的 logits。在导出模式下，相同形状的 softmax
   概率。[BaseNode.run](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
   将结果放在 `"ocr"` 键下。

##### get_custom_head_config

```python
def get_custom_head_config(self) -> Params:
```

返回头的 NN Archive 元数据。

[BaseHead.get_head_config](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/base_head.md)
将结果合并到元数据中。结果的 `"classes"` 和 `"n_classes"`
键替换数据集中的值。[BaseHead.get_head_config](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/base_head.md)
仍然首先读取数据集的类名，因此它需要 `dataset_metadata`。

> **示例**
> ```pycon
>>> from torch import Size
>>> from luxonis_train.nodes import OCRCTCHead
>>> head = OCRCTCHead(
...     alphabet=["b", "a"],
...     ignore_unknown=False,
...     input_shapes=[{"features": [Size([1, 8, 1, 4])]}],
... )
>>> config = head.get_custom_head_config()
>>> [str(char) for char in config["classes"]]
['', 'a', 'b', '<UNK>']
>>> config["n_classes"], config["ignored_indexes"]
(4, [0])
```

返回

 * `Params`: 包含这些键的字典。 * `"classes"` 包含 [encoder](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ocr_ctc_head.md) 的字母表，空白 `""` 在最前面。
    * `"n_classes"` 包含 [out_channels](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ocr_ctc_head.md)。
    * `"is_softmax"` 为 `True`，因为导出的模型应用了 softmax。
    * `"concatenate_classes"` 为 `True`。
    * `"ignored_indexes"` 为 `[0]`，即空白的索引。
    * `"remove_duplicates"` 为 `True`。

##### initialize_weights

```python
def initialize_weights(method: str | None = None):
```

初始化线性层。

该方法首先使用 `method` 调用 [BaseNode.initialize_weights](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)。然后，它从 [ − 1 ⁄ √(nin), 1 ⁄ √(nin)] 上的均匀分布中抽取每个 `torch.nn.Linear` 的权重和偏置。nin 是层的输入特征数量。这些是 PyTorch 默认初始化 `torch.nn.Linear` 的边界。

参数

 * `method` (`str | None`): [BaseNode.initialize_weights](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md) 的方法。使用 `mid_channels` 时，`"yolo"` 使线性层之间的 ReLU 就地运行。其他值不会改变任何东西。

#### 属性

##### block

##### decoder

将预测转换为文本的解码器。

它应用 softmax 并获取每个步骤中最可能的类别。它删除空白类别 `0` 和每个重复前一个类别的类别。对于每个序列，它返回文本和保留字符的平均概率。对于空文本，平均值为 `NaN`。[OCRVisualizer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/ocr_visualizer.md) 和 [BaseHead.annotate](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/base_head.md) 使用它。

##### encoder

将文本标签转换为类别索引的编码器。

[CTCLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/ctc_loss.md) 和 [OCRAccuracy](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/ocr_accuracy.md) 使用它。它的字母表以索引 `0` 处的空白 `""` 开头。`alphabet` 的排序唯一字符紧随其后。如果 `ignore_unknown` 为 `False`，则 `"<UNK>"` 是最后一个条目。

##### export_output_names

导出模型中输出的名称。

该值始终为 `["output_ocr_ctc"]`。该属性忽略 `export_output_names` 参数。

##### in_channels

附加输入的通道数。

它是 [in_sizes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md) 倒数第三个维度，因此带或不带批处理维度的形状会给出相同的值。大小列表给出通道计数列表。

引发

 * `RuntimeError`: 当 [in_sizes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md) 找不到输入大小时。
 * `ValueError`: 当 [attach_index](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md) 不适合大小时。

##### out_channels

头预测的类别数。

它是 [encoder](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ocr_ctc_head.md) 字母表的长度: 空白、`alphabet` 的唯一字符，以及当 `ignore_unknown` 为 `False` 时的 `"<UNK>"`。

##### parser
