# 演示

MMOCR 为示例和应用，以 [ocr.py](https://github.com/open-mmlab/mmocr/blob/main/mmocr/utils/ocr.py) 脚本形式，提供了方便使用的 API。

该 API 可以通过命令行执行，也可以在 python 脚本内调用。在该 API 里，MMOCR 里的所有模型能以独立模块的形式被调用或串联。它还支持将 [Tesseract](https://tesseract-ocr.github.io/) 作为文字检测或识别的一个组件调用。

---

## 案例一：文本检测

<div align="center">
    <img src="https://raw.githubusercontent.com/open-mmlab/mmocr/main/demo/resources/text_det_pred.jpg"/><br>
</div>
<br>

**注：** 使用 TextSnake 检测模型对图像上的文本进行检测，结果用 json 格式的文件（默认）导出，并保存可视化的文件。

- 命令行执行：

```shell
python mmocr/utils/ocr.py demo/demo_text_det.jpg --output demo/det_out.jpg --det TextSnake --recog None --export demo/
```

- Python 调用：

```python
from mmocr.utils.ocr import MMOCR

# 导入模型到内存
ocr = MMOCR(det='TextSnake', recog=None)

# 推理
results = ocr.readtext('demo/demo_text_det.jpg', output='demo/det_out.jpg', export='demo/')
```

## 案例二：文本识别

<div align="center">
    <img src="https://raw.githubusercontent.com/open-mmlab/mmocr/main/demo/resources/text_recog_pred.jpg"/><br>
</div>
<br>

**注：** 使用 CRNN_TPS 识别模型对多张图片进行批量识别。*批处理的尺寸设置为 10，以防内存溢出引起的 CUDA 运行时错误。*

- 命令行执行：

```shell
python mmocr/utils/ocr.py %INPUT_FOLDER_PATH% --det None --recog CRNN_TPS --batch-mode --single-batch-size 10 --output %OUPUT_FOLDER_PATH%
```

- Python 调用：

```python
from mmocr.utils.ocr import MMOCR

# 导入模型到内存
ocr = MMOCR(det=None, recog='CRNN_TPS')

# 推理
results = ocr.readtext(%INPUT_FOLDER_PATH%, output = %OUTPUT_FOLDER_PATH%, batch_mode=True, single_batch_size = 10)
```

## 案例三：文本检测+识别

<div align="center">
    <img src="https://raw.githubusercontent.com/open-mmlab/mmocr/main/demo/resources/demo_ocr_pred.jpg"/><br>
</div>
<br>

**注：** 使用 PANet_IC15（默认）检测模型和 SAR（默认）识别模型，对 demo/demo_text_det.jpg 图片执行 ocr（检测+识别）推理，在终端打印结果并展示可视化结果。

- 命令行执行：

```shell
python mmocr/utils/ocr.py demo/demo_text_ocr.jpg --print-result --imshow
```

:::{note}

当用户从命令行执行脚本时，默认配置文件都会保存在 `configs/` 目录下。用户可以通过指定 `config_dir` 的值来自定义读取配置文件的文件夹。

:::

- Python 调用：

```python
from mmocr.utils.ocr import MMOCR

# 导入模型到内存
ocr = MMOCR()

# 推理
results = ocr.readtext('demo/demo_text_ocr.jpg', print_result=True, imshow=True)
```

---

## 案例 4： 文本检测+识别+关键信息提取

<div align="center">
    <img src="https://raw.githubusercontent.com/open-mmlab/mmocr/main/demo/resources/demo_kie_pred.png"/><br>
</div>
<br>

**注：** 首先，使用 PS_CTW 检测模型和 SAR 识别模型，进行端到端的 ocr （检测+识别）推理，然后对得到的结果，使用 SDMGR 模型提取关键信息（KIE），并展示可视化结果。

- 命令行执行：

```shell
python mmocr/utils/ocr.py demo/demo_kie.jpeg  --det PS_CTW --recog SAR --kie SDMGR --print-result --imshow
```

:::{note}

当用户从命令行执行脚本时，默认配置文件都会保存在 `configs/` 目录下。用户可以通过指定 `config_dir` 的值来自定义读取配置文件的文件夹。

:::

- Python 调用：

```python
from mmocr.utils.ocr import MMOCR

# 导入模型到内存
ocr = MMOCR(det='PS_CTW', recog='SAR', kie='SDMGR')

# 推理
results = ocr.readtext('demo/demo_kie.jpeg', print_result=True, imshow=True)
```

---

## API 参数

该 API 有多个可供使用的参数列表。下表是 python 接口的参数。

**MMOCR():**

| 参数           | 类型               | 默认值     | 描述                                                                                     |
| -------------- | ------------------ | ---------- | ---------------------------------------------------------------------------------------- |
| `det`          | 参考 **模型** 章节 | PANet_IC15 | 文本检测算法                                                                             |
| `recog`        | 参考 **模型** 章节 | SAR        | 文本识别算法                                                                             |
| `kie` [1]      | 参考 **模型** 章节 | None       | 关键信息提取算法                                                                         |
| `config_dir`   | str                | configs/   | 用于存放所有配置文件的文件夹路径                                                         |
| `det_config`   | str                | None       | 指定检测模型的自定义配置文件路径                                                         |
| `det_ckpt`     | str                | None       | 指定检测模型的自定义参数文件路径                                                         |
| `recog_config` | str                | None       | 指定识别模型的自定义配置文件路径                                                         |
| `recog_ckpt`   | str                | None       | 指定识别模型的自定义参数文件路径                                                         |
| `kie_config`   | str                | None       | 指定关键信息提取模型的自定义配置路径                                                     |
| `kie_ckpt`     | str                | None       | 指定关键信息提取的自定义参数文件路径                                                     |
| `device`       | str                | None       | 推理时使用的设备标识, 支持 `torch.device` 所包含的所有设备字符. 例如, 'cuda:0' 或 'cpu'. |

[1]: `kie` 当且仅当同时指定了文本检测和识别模型时才有效。

:::{note}

mmocr 为了方便使用提供了预置的模型配置和对应的预训练权重，用户可以通过指定 `det` 和/或 `recog` 值来指定使用，这种方法等同于分别单独指定其对应的 `*_config` 和 `*_ckpt`。需要注意的是，手动指定 `*_config` 和 `*_ckpt` 会覆盖 `det` 和/或 `recog` 指定模型预置的配置和权重值。 同理 `kie`， `kie_config` 和 `kie_ckpt` 的参数设定逻辑相同。

:::

### readtext()

| 参数                | 类型                    | 默认值   | 描述                                                                  |
| ------------------- | ----------------------- | -------- | --------------------------------------------------------------------- |
| `img`               | str/list/tuple/np.array | **必填** | 图像，文件夹路径，np array 或 list/tuple （包含图片路径或 np arrays） |
| `output`            | str                     | None     | 可视化输出结果 - 图片路径或文件夹路径                                 |
| `batch_mode`        | bool                    | False    | 是否使用批处理模式推理 [1]                                            |
| `det_batch_size`    | int                     | 0        | 文本检测的批处理大小（设置为 0 则与待推理图片个数相同）               |
| `recog_batch_size`  | int                     | 0        | 文本识别的批处理大小（设置为 0 则与待推理图片个数相同）               |
| `single_batch_size` | int                     | 0        | 仅用于检测或识别使用的批处理大小                                      |
| `export`            | str                     | None     | 存放导出图片结果的文件夹                                              |
| `export_format`     | str                     | json     | 导出的结果文件格式                                                    |
| `details`           | bool                    | False    | 是否包含文本框的坐标和置信度的值                                      |
| `imshow`            | bool                    | False    | 是否在屏幕展示可视化结果                                              |
| `print_result`      | bool                    | False    | 是否展示每个图片的结果                                                |
| `merge`             | bool                    | False    | 是否对相邻框进行合并 [2]                                              |
| `merge_xdist`       | float                   | 20       | 合并相邻框的最大x-轴距离                                              |

[1]: `batch_mode` 需确保模型兼容批处理模式（见下表模型是否支持批处理）。

[2]: `merge` 只有同时运行检测+识别模式，参数才有效。

以上所有参数在命令行同样适用，只需要在参数前简单添加两个连接符，并且将下参数中的下划线替换为连接符即可。
（*例如：* `det_batch_size` 变成了 `--det-batch-size`）

对于布尔类型参数，添加在命令中默认为true。
（*例如：* `python mmocr/utils/ocr.py demo/demo_text_det.jpg --batch_mode --print_result` 意为 `batch_mode` 和 `print_result` 的参数值设置为 `True`）

---

## 模型

**文本检测：**

| 名称          |                                                                           引用                                                                           | `batch_mode` 推理支持 |
| ------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------------: |
| DB_r18        |            [链接](https://mmocr.readthedocs.io/en/latest/textdet_models.html#real-time-scene-text-detection-with-differentiable-binarization)            |          :x:          |
| DB_r50        |            [链接](https://mmocr.readthedocs.io/en/latest/textdet_models.html#real-time-scene-text-detection-with-differentiable-binarization)            |          :x:          |
| DRRG          |                                         [链接](https://mmocr.readthedocs.io/en/latest/textdet_models.html#drrg)                                          |          :x:          |
| FCE_IC15      |             [链接](https://mmocr.readthedocs.io/en/latest/textdet_models.html#fourier-contour-embedding-for-arbitrary-shaped-text-detection)             |          :x:          |
| FCE_CTW_DCNv2 |             [链接](https://mmocr.readthedocs.io/en/latest/textdet_models.html#fourier-contour-embedding-for-arbitrary-shaped-text-detection)             |          :x:          |
| MaskRCNN_CTW  |                                      [链接](https://mmocr.readthedocs.io/en/latest/textdet_models.html#mask-r-cnn)                                       |          :x:          |
| MaskRCNN_IC15 |                                      [链接](https://mmocr.readthedocs.io/en/latest/textdet_models.html#mask-r-cnn)                                       |          :x:          |
| MaskRCNN_IC17 |                                      [链接](https://mmocr.readthedocs.io/en/latest/textdet_models.html#mask-r-cnn)                                       |          :x:          |
| PANet_CTW     | [链接](https://mmocr.readthedocs.io/en/latest/textdet_models.html#efficient-and-accurate-arbitrary-shaped-text-detection-with-pixel-aggregation-network) |  :heavy_check_mark:   |
| PANet_IC15    | [链接](https://mmocr.readthedocs.io/en/latest/textdet_models.html#efficient-and-accurate-arbitrary-shaped-text-detection-with-pixel-aggregation-network) |  :heavy_check_mark:   |
| PS_CTW        |                                        [链接](https://mmocr.readthedocs.io/en/latest/textdet_models.html#psenet)                                         |          :x:          |
| PS_IC15       |                                        [链接](https://mmocr.readthedocs.io/en/latest/textdet_models.html#psenet)                                         |          :x:          |
| Tesseract     |                                                         [链接](https://tesseract-ocr.github.io/)                                                         |  :heavy_check_mark:   |
| TextSnake     |                                       [链接](https://mmocr.readthedocs.io/en/latest/textdet_models.html#textsnake)                                       |  :heavy_check_mark:   |

**文本识别：**

| 名称          |                                                                                              引用                                                                                              | `batch_mode` 推理支持 |
| ------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------------: |
| ABINet        |           [链接](https://mmocr.readthedocs.io/en/latest/textrecog_models.html#read-like-humans-autonomous-bidirectional-and-iterative-language-modeling-for-scene-text-recognition)            |  :heavy_check_mark:   |
| CRNN          | [链接](https://mmocr.readthedocs.io/en/latest/textrecog_models.html#an-end-to-end-trainable-neural-network-for-image-based-sequence-recognition-and-its-application-to-scene-text-recognition) |          :x:          |
| CRNN_TPS      |                                                  [链接](https://mmocr.readthedocs.io/en/latest/textrecog_models.html#crnn-with-tps-based-stn)                                                  |  :heavy_check_mark:   |
| NRTR_1/16-1/8 |                                                           [链接](https://mmocr.readthedocs.io/en/latest/textrecog_models.html#nrtr)                                                            |  :heavy_check_mark:   |
| NRTR_1/8-1/4  |                                                           [链接](https://mmocr.readthedocs.io/en/latest/textrecog_models.html#nrtr)                                                            |  :heavy_check_mark:   |
| RobustScanner |                     [链接](https://mmocr.readthedocs.io/en/latest/textrecog_models.html#robustscanner-dynamically-enhancing-positional-clues-for-robust-text-recognition)                      |  :heavy_check_mark:   |
| SAR           |                     [链接](https://mmocr.readthedocs.io/en/latest/textrecog_models.html#show-attend-and-read-a-simple-and-strong-baseline-for-irregular-text-recognition)                      |  :heavy_check_mark:   |
| SAR_CN *      |                     [链接](https://mmocr.readthedocs.io/en/latest/textrecog_models.html#show-attend-and-read-a-simple-and-strong-baseline-for-irregular-text-recognition)                      |  :heavy_check_mark:   |
| SATRN         |                                                           [链接](https://mmocr.readthedocs.io/en/latest/textrecog_models.html#satrn)                                                           |  :heavy_check_mark:   |
| SATRN_sm      |                                                           [链接](https://mmocr.readthedocs.io/en/latest/textrecog_models.html#satrn)                                                           |  :heavy_check_mark:   |
| SEG           |                                                  [链接](https://mmocr.readthedocs.io/en/latest/textrecog_models.html#segocr-simple-baseline)                                                   |          :x:          |
| Tesseract     |                                                                            [链接](https://tesseract-ocr.github.io/)                                                                            |  :heavy_check_mark:   |

:::{note}

SAR_CN 是唯一支持中文字符识别的模型，并且它需要一个中文字典。以便推理能成功运行，请先从 [这里](https://mmocr.readthedocs.io/en/latest/textrecog_models.html#chinese-dataset) 下载辞典。

:::

**关键信息提取：**

| 名称                                                                                                                                 | `batch_mode` 支持  |
| ------------------------------------------------------------------------------------------------------------------------------------ | :----------------: |
| [SDMGR](https://mmocr.readthedocs.io/en/latest/kie_models.html#spatial-dual-modality-graph-reasoning-for-key-information-extraction) | :heavy_check_mark: |

## 其他需要注意

- 执行检测+识别的推理（端到端 ocr），需要同时定义 `det` 和 `recog` 参数
- 如果只需要执行检测，则 `recog` 参数设置为 `None`。
- 如果只需要执行识别，则 `det` 参数设置为 `None`。
- `details` 参数仅在端到端的 ocr 模型有效。
- `det_batch_size` 和 `recog_batch_size` 指定了在同时间传递给模型的图片数量。为了提高推理速度，应该尽可能设置你能设置的最大值。最大的批处理值受模型复杂度和 GPU 的显存大小限制。
- MMOCR 目前通过 [`tesserocr`](https://github.com/sirfz/tesserocr) 调用 Tesseract 的 API.

如果你对新特性有任何建议，请随时开一个 issue，甚至可以提一个 PR:)
