mirrors
/
mmocr
mirror of https://github.com/open-mmlab/mmocr.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
mmocr/demo/README_zh-CN.md

249 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 演示
MMOCR 为示例和应用，以 [ocr.py](https://github.com/open-mmlab/mmocr/blob/main/mmocr/utils/ocr.py) 脚本形式，提供了方便使用的 API。
该 API 可以通过命令行执行，也可以在 python 脚本内调用。
---
## 案例一：文本检测
<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: |
| [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: |
| [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: |
| [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: |
| [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: |
| [CRNN_TPS](https://mmocr.readthedocs.io/en/latest/textrecog_models.html#crnn-with-tps-based-stn) | :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 的显存大小限制。
如果你对新特性有任何建议，请随时开一个 issue，甚至可以提一个 PR:)
Reference in New Issue View Git Blame Copy Permalink