# ocr

Python API: `luxonis_train.utils.ocr`

文本与 OCR 头预测的类别索引之间的 CTC 编码器和解码器。

## 类

### OCRDecoder

贪婪 CTC 解码器，将类别分数转换为文本。

解码器在序列的每个步骤中选择最可能的类别。它会丢弃被忽略的类别，并且可以选择性地丢弃重复前一步骤类别的步骤。解码器的调用会运行
[decode](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/ocr.md)。

#### 方法

##### init

```python
def __init__(char_to_int: dict, ignored_tokens: list[int] | None = None, is_remove_duplicate: bool = True):
```

反转字符映射并存储选项。

参数

 * `char_to_int` (`dict`): 每个字符的类别索引，如
   [OCREncoder](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/ocr.md)
   所构建。
 * `ignored_tokens` (`list[int] | None`): 要丢弃的类别索引。`None` 选择 `[0]`，即 CTC 空白。空列表保留所有类别。
 * `is_remove_duplicate` (`bool`): 是否丢弃类别与前一步骤类别相同的步骤。

##### decode

```python
def decode(preds: Tensor) -> list[tuple[str, float]]:
```

将每个序列的类别分数解码为文本。

该方法对类别应用 softmax，并在每个步骤中选择最可能的类别。它会丢弃类别在 `ignored_tokens` 中的每个步骤。如果 `is_remove_duplicate` 为
`True`，它还会丢弃类别与前一步骤类别相同的步骤。比较时也会使用前一步骤，即使该步骤已被丢弃。因此，两个相同字符之间的空白会保留这两个字符。

> **示例**
> ```pycon
>>> import torch
>>> from luxonis_train.utils import OCRDecoder
>>> decoder = OCRDecoder({"": 0, "a": 1, "b": 2})
>>> classes = torch.tensor([[1, 1, 0, 1, 2]])
>>> logits = torch.nn.functional.one_hot(classes, 3) * 10.0
>>> text, confidence = decoder.decode(logits)[0]
>>> text, round(confidence, 3)
('aab', 1.0)
```

参数

 * `preds` (`Tensor`): 形状为 `[B, T, n_classes]` 的 logits。

返回

 * `list[tuple[str, float]]`: 每个序列一个 `(text, confidence)` 对。置信度是保留步骤的平均概率，对于空文本为 `nan`。

### OCREncoder

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

类别 `0` 是 CTC 空白 `""`。其后是字母表中排序的唯一字符。如果 `ignore_unknown=False`，则 `"<UNK>"` 是最后一个类别。编码器的调用会运行 [encode](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/ocr.md)。

> **示例**
> ```pycon
>>> import torch
>>> from luxonis_train.utils import OCREncoder
>>> encoder = OCREncoder(["b", "a"])
>>> [str(char) for char in encoder.alphabet], encoder.n_classes
(['', 'a', 'b'], 3)
>>> codes = torch.tensor([[ord("b"), ord("x"), ord("a"), 0]])
>>> encoder.encode(codes).tolist()
[[2, 1, 0, 0]]
>>> strict_encoder = OCREncoder(["b", "a"], ignore_unknown=False)
>>> strict_encoder.encode(codes).tolist()
[[2, 3, 1, 0]]
```

#### 方法

##### init

```python
def __init__(alphabet: list[str], ignore_unknown: bool = True):
```

构建字母表和每个字符的类别索引。

参数

 * `alphabet` (`list[str]`): 标签的字符。编码器会对其进行排序并丢弃重复项。
 * `ignore_unknown` (`bool`):
   [encode](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/ocr.md)
   是否丢弃不在 `alphabet` 中的字符。如果为 `False`，编码器会添加类别 `"<UNK>"` 并将此类字符映射到它。

##### encode

```python
def encode(targets: Tensor) -> Tensor:
```

将标签的字符代码转换为类别索引。

值 `0` 是填充，并给出空白类别 `0`。如果 `ignore_unknown` 为 `True`，该方法会丢弃不在字母表中的字符。后面的字符会向左移动，`0` 会填充行的末尾。否则，该字符会获得 `"<UNK>"` 类别。

参数

 * `targets` (`Tensor`): 标签的 Unicode 码点，形状为 `[N, L]`。

返回

 * `Tensor`: 形状为 `[N, L]` 的类别索引，类型为 `int64`。

#### 属性

##### alphabet

每个类别的字符，按索引顺序排列。

空白 `""` 排在最前面。其后是排序的唯一字符，如果 `ignore_unknown` 为 `False`，则接着是 `"<UNK>"`。排序的字符是 `np.str_` 值。

##### char_to_int

每个字符的类别索引。

##### n_classes

类别数量，即
[alphabet](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/ocr.md)
的长度。
