Shortcuts

注意

您正在阅读 MMOCR 0.x 版本的文档。MMOCR 0.x 会在 2022 年末开始逐步停止维护,建议您及时升级到 MMOCR 1.0 版本,享受由 OpenMMLab 2.0 带来的更多新特性和更佳的性能表现。阅读 MMOCR 1.0 的维护计划发版日志代码文档 以了解更多。

安装

环境依赖

  • Linux | Windows | macOS

  • Python 3.7

  • PyTorch 1.6 或更高版本

  • torchvision 0.7.0

  • CUDA 10.1

  • NCCL 2

  • GCC 5.4.0 或更高版本

准备环境

注解

如果你已经在本地安装了 PyTorch,请直接跳转到安装步骤

第一步 下载并安装 Miniconda.

第二步 创建并激活一个 conda 环境:

conda create --name openmmlab python=3.8 -y
conda activate openmmlab

第三步 依照官方指南,安装 PyTorch。

在 GPU 平台上:

conda install pytorch torchvision -c pytorch

在 CPU 平台上:

conda install pytorch torchvision cpuonly -c pytorch

安装步骤

我们建议大多数用户采用我们的推荐方式安装 MMOCR。倘若你需要更灵活的安装过程,则可以参考自定义安装一节。

推荐步骤

第一步 使用 MIM 安装 MMCV.

pip install -U openmim
mim install mmcv-full

第二步MMDetection 以依赖库的形式安装。

pip install mmdet

第三步 安装 MMOCR.

情况1: 若你需要直接运行 MMOCR 或在其基础上进行开发,则通过源码安装:

git clone https://github.com/open-mmlab/mmocr.git
cd mmocr
pip install -r requirements.txt
pip install -v -e .
# "-v" 会让安装过程产生更详细的输出
# "-e" 会以可编辑的方式安装该代码库,你对该代码库所作的任何更改都会立即生效

情况2:如果你将 MMOCR 作为一个外置依赖库使用,通过 pip 安装即可:

pip install mmocr

第四步(可选) 如果你需要使用与 albumentations 有关的变换,比如 ABINet 数据流水线中的 Albu,请使用以下命令安装依赖:

# 若 MMOCR 通过源码安装
pip install -r requirements/albu.txt
# 若 MMOCR 通过 pip 安装
pip install albumentations>=1.1.0 --no-binary qudida,albumentations

注解

我们建议在安装 albumentations 之后检查当前环境,确保 opencv-pythonopencv-python-headless 没有同时被安装,否则有可能会产生一些无法预知的错误。如果它们不巧同时存在于环境当中,请卸载 opencv-python-headless 以确保 MMOCR 的可视化工具可以正常运行。

查看 albumentations 的官方文档以获知详情。

检验

根据安装方式的不同,我们提供了两个可以验证安装正确性的方法。若 MMOCR 的安装无误,你在这一节完成后应当能看到以图片和文字形式表示的识别结果,示意如下:



# 识别结果
[{'filename': 'demo_text_det', 'text': ['yther', 'doyt', 'nan', 'heraies', '188790', 'cadets', 'army', 'ipioneered', 'and', 'icottages', 'land', 'hall', 'sgardens', 'established', 'ithis', 'preformer', 'social', 'octavial', 'hill', 'pm', 'ct', 'lof', 'aborought']}]

若从源码安装 MMOCR

在 MMOCR 的目录运行以下命令:

python mmocr/utils/ocr.py --det DB_r18 --recog CRNN demo/demo_text_det.jpg --imshow

若以包形式安装 MMOCR

第一步 下载必要的配置,权重和图片:

mim download mmocr --config dbnet_r18_fpnc_1200e_icdar2015 --dest .
mim download mmocr --config crnn_academic_dataset --dest .
wget https://raw.githubusercontent.com/open-mmlab/mmocr/main/demo/demo_text_det.jpg

取决于你的网络环境,下载过程可能会持续几十秒或者更长。一切就绪后,当前目录树应当包含以下文件:

├── crnn_academic-a723a1c5.pth
├── crnn_academic_dataset.py
├── dbnet_r18_fpnc_1200e_icdar2015.py
├── dbnet_r18_fpnc_sbn_1200e_icdar2015_20210329-ba3ab597.pth
└── demo_text_det.jpg

第二步 在 Python 解释器中运行以下代码:

from mmocr.utils.ocr import MMOCR
ocr = MMOCR(recog='CRNN', recog_ckpt='crnn_academic-a723a1c5.pth', recog_config='crnn_academic_dataset.py', det='DB_r18', det_ckpt='dbnet_r18_fpnc_sbn_1200e_icdar2015_20210329-ba3ab597.pth', det_config='dbnet_r18_fpnc_1200e_icdar2015.py')
ocr.readtext('demo_text_det.jpg', imshow=True)

自定义安装

CUDA 版本

安装 PyTorch 时,需要指定 CUDA 版本。如果您不清楚选择哪个,请遵循我们的建议:

  • 对于 Ampere 架构的 NVIDIA GPU,例如 GeForce 30 series 以及 NVIDIA A100,CUDA 11 是必需的。

  • 对于更早的 NVIDIA GPU,CUDA 11 是向前兼容的,但 CUDA 10.2 能够提供更好的兼容性,也更加轻量。

请确保你的 GPU 驱动版本满足最低的版本需求,参阅这张表

注解

如果按照我们的最佳实践进行安装,CUDA 运行时库就足够了,因为我们提供相关 CUDA 代码的预编译,你不需要进行本地编译。 但如果你希望从源码进行 MMCV 的编译,或是进行其他 CUDA 算子的开发,那么就必须安装完整的 CUDA 工具链,参见 NVIDIA 官网,另外还需要确保该 CUDA 工具链的版本与 PyTorch 安装时 的配置相匹配(如用 conda install 安装 PyTorch 时指定的 cudatoolkit 版本)。

不使用 MIM 安装 MMCV

MMCV 包含 C++ 和 CUDA 扩展,因此其对 PyTorch 的依赖比较复杂。MIM 会自动解析这些 依赖,选择合适的 MMCV 预编译包,使安装更简单,但它并不是必需的。

要使用 pip 而不是 MIM 来安装 MMCV,请遵照 MMCV 安装指南。 它需要你用指定 url 的形式手动指定对应的 PyTorch 和 CUDA 版本。

举个例子,如下命令将会安装基于 PyTorch 1.10.x 和 CUDA 11.3 编译的 mmcv-full。

pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10/index.html

在 CPU 环境中安装

MMOCR 可以仅在 CPU 环境中安装,在 CPU 模式下,你可以完成训练(需要 MMCV 版本 >= 1.4.4)、测试和模型推理等所有操作。

在 CPU 模式下,MMCV 中的以下算子将不可用:

  • Deformable Convolution

  • Modulated Deformable Convolution

  • ROI pooling

  • SyncBatchNorm

如果你尝试使用用到了以上算子的模型进行训练、测试或推理,程序将会报错。以下为可能受到影响的模型列表:

算子 模型
Deformable Convolution/Modulated Deformable Convolution DBNet (r50dcnv2), DBNet++ (r50dcnv2), FCENet (r50dcnv2)
SyncBatchNorm PANet, PSENet

通过 Docker 使用 MMOCR

我们提供了一个 Dockerfile 文件以建立 docker 镜像 。

# build an image with PyTorch 1.6, CUDA 10.1
docker build -t mmocr docker/

使用以下命令运行。

docker run --gpus all --shm-size=8g -it -v {实际数据目录}:/mmocr/data mmocr

对 MMCV 和 MMDetection 的版本依赖

为了确保代码实现的正确性,MMOCR 每个版本都有可能改变对 MMCV 和 MMDetection 版本的依赖。请根据以下表格确保版本之间的相互匹配。

MMOCR MMCV MMDetection
main 1.3.8 \<= mmcv \<= 1.7.0 2.21.0 \<= mmdet \<= 3.0.0
0.6.3 1.3.8 \<= mmcv \<= 1.7.0 2.21.0 \<= mmdet \<= 3.0.0
0.6.1, 0.6.2 1.3.8 \<= mmcv \<= 1.7.0 2.21.0 \<= mmdet \<= 3.0.0
0.6.0 1.3.8 \<= mmcv \<= 1.6.0 2.21.0 \<= mmdet \<= 3.0.0
0.5.0 1.3.8 \<= mmcv \<= 1.5.0 2.14.0 \<= mmdet \<= 3.0.0
0.4.0, 0.4.1 1.3.8 \<= mmcv \<= 1.5.0 2.14.0 \<= mmdet \<= 2.20.0
0.3.0 1.3.8 \<= mmcv \<= 1.4.0 2.14.0 \<= mmdet \<= 2.20.0
0.2.1 1.3.8 \<= mmcv \<= 1.4.0 2.13.0 \<= mmdet \<= 2.20.0
0.2.0 1.3.4 \<= mmcv \<= 1.4.0 2.11.0 \<= mmdet \<= 2.13.0
0.1.0 1.2.6 \<= mmcv \<= 1.3.4 2.9.0 \<= mmdet \<= 2.11.0
Read the Docs v: latest
Versions
latest
stable
dev-1.x
Downloads
pdf
html
epub
On Read the Docs
Project Home
Builds

Free document hosting provided by Read the Docs.