OCR-D/ocrd_all

![CircleCI构建状态]([] ![MIT许可证]([] ![]([***]

该项目控制从源代码安装所有OCR-D模块（作为git子模块）。它包含一个Makefile，用于将这些模块安装到虚拟环境(venv)或Docker容器中。

（venv是一个本地用户目录，包含通过PATH和PYTHONHOME在当前shell环境中加载/卸载自身的shell脚本。）

• 前提条件
  • 空间要求
  • 语言环境
  • 系统包
• 使用方法
  • 目标
    • deps-ubuntu
    • modules
    • ocrd
    • all
    • fix-pip
    • docker
    • clean
    • show
    • help (默认目标)
    • [任意模块名称]
    • [任意可执行文件名称]
  • 变量
    • OCRD_MODULES
    • PYTHON
    • VIRTUAL_ENV
    • TMPDIR
    • PIP_OPTIONS
    • GIT_RECURSIVE
    • TESSERACT_MODELS
  • 示例
  • 结果
  • 持久化配置
  • Docker Hub
• 挑战
  • PyPI上没有发布/最新版本
  • 冲突的依赖要求
  • 系统要求

前提条件

空间要求

确保有足够的可用磁盘空间。推荐7 GiB或更多空间，用于存储所需的子模块、构建数据、临时数据、已安装的虚拟环境和pip缓存。

如果/tmp目录的可用空间少于5 GiB，可以在调用make时通过设置TMPDIR变量来覆盖临时文件的位置：

sh
TMPDIR=/path/to/my/tempdir make all

语言环境

接下来，（shell）环境必须具有基于Unicode的本地化。（否则，基于click的Python代码将无法工作，即大多数OCR-D CLI。）如今大多数安装都满足此条件，可以通过以下命令验证：

locale | fgrep .UTF-8

这应该显示几个LC_*变量。否则，可以全局选择另一个本地化...

sudo dpkg-reconfigure locales

...或者临时使用基于Unicode的POSIX语言环境：

export LC_ALL=C.UTF-8
export LANG=C.UTF-8

系统包

安装GNU make和git，如果要下载Tesseract模型，还需要wget。

# 在Debian / Ubuntu上：
sudo apt install make git wget

安装Python3开发和Python3虚拟环境的包：

# 在Debian / Ubuntu上：
sudo apt install python3-dev python3-venv

一些模块使用Tesseract库。如果您的发行版提供Tesseract 4.1或更高版本，请安装开发包：

# 在Debian / Ubuntu上：
sudo apt install libtesseract-dev

Ubuntu上Tesseract 5.0.0（alpha）的包可在PPA [***]

否则，或为了获取最新的Tesseract代码，也可以在本地构建。

其他模块将有额外的系统依赖项。

Ubuntu 18.04（或类似系统）上所有模块的系统依赖项也可以通过运行以下命令自动安装：

# 在Debian / Ubuntu上：
sudo apt install make git
sudo make deps-ubuntu

（您可以通过设置OCRD_MODULES 变量来定义_所有模块_的范围。）

使用方法

运行make时可选择带参数的变量和目标，如下所示：

make [PYTHON=python3] [VIRTUAL_ENV=./venv] [OCRD_MODULES="..."] [TARGET...]

目标

deps-ubuntu

为所有模块安装系统包。（依赖于_modules_。）

modules

下载/更新所有模块，但不安装任何内容。

ocrd

仅将OCR-D/core及其CLI ocrd安装到venv中。

all

将所有模块的可执行文件安装到venv中。（依赖于_modules_和_ocrd_。）

fix-pip

修复所有模块之间不兼容/不一致的pip依赖要求。

docker

（重新）为所有模块/可执行文件构建docker镜像。（依赖于_modules_。）

clean

删除venv和模块的构建目录。

show

打印venv目录、模块目录和可执行文件名称。

help (默认目标)

打印可用的目标和变量。

---

其他目标：

[任意模块名称]

下载/更新该模块，但不安装任何内容。

[任意可执行文件名称]

将该CLI安装到venv中。（依赖于该模块和_ocrd_。）

变量

OCRD_MODULES

覆盖要包含的git子模块列表。受此影响的目标包括：

• deps-ubuntu（减少要安装的系统包列表）
• modules（减少要检出/更新的模块列表）
• all（减少要安装的可执行文件列表）
• docker（减少要安装的可执行文件和模块列表）
• show（减少要打印的OCRD_MODULES和OCRD_EXECUTABLES列表）

PYTHON

要使用的Python二进制文件名称（至少需要python3）。

VIRTUAL_ENV

用于本地安装的目录前缀。

（在shell上激活虚拟环境时会自动设置。如果此处已存在venv，构建系统将重用它，否则将创建一个。）

TMPDIR

覆盖构建期间临时文件存储的默认路径（Unix上为/tmp）。

PIP_OPTIONS

向pip install命令添加额外选项，如-q、-v或-e。

（后者将以_可编辑模式_安装Python模块，即对源代码的任何更新将直接影响可执行文件。）

GIT_RECURSIVE

设置为--recursive以递归方式检出/更新所有模块。（这通常会安装额外的测试和模型。）

TESSERACT_MODELS

在与Tesseract一起安装的最小必需语言列表（eng equ osd）中添加更多模型。

示例

以下示例假设Tesseract的开发安装正常工作。要在本地构建最新的Tesseract，请先运行以下命令：

# 获取代码，构建并安装带有默认英语模型的Tesseract。
make tesseract

可选安装其他Tesseract模型。

# 从tessdata_fast下载模型到venv的tessdata目录。
make frk.traineddata
make script/Latin.traineddata
make script/Fraktur.traineddata

运行make ocrd或仅运行make将下载/更新并安装core模块，包括位于./venv下的虚拟Python 3环境中的ocrd CLI。

运行make ocrd-tesserocr-recognize将下载/更新ocrd_tesserocr模块并安装其CLI，包括venv中的ocrd-tesserocr-recognize。

运行make modules将下载/更新所有模块。

运行make all还会安装所有模块的可执行文件。

运行make all OCRD_MODULES="core tesseract ocrd_tesserocr ocrd_cis"仅安装这些模块的可执行文件。

结果

要使用构建的可执行文件，只需激活虚拟环境：

. ${VIRTUAL_ENV:-venv}/bin/activate
ocrd --help
ocrd-...

对于Docker镜像，以用户身份挂载数据路径运行：

docker run -it -u $(id -u):$(id -g) $PWD:/data ocrd/all
ocrd --help
ocrd-...

持久化配置

为了使选择永久生效，您可以将变量首选项（或任何自定义规则）放入local.mk。如果存在此文件，它将始终被包含。因此，您不必在命令行或shell环境中输入（和记住）它们。

例如，其内容可以是：

make
# 将所有内容限制为模块的子集
OCRD_MODULES = core ocrd_im6convert ocrd_cis ocrd_tesserocr tesserocr tesseract

# 使用非默认路径作为虚拟环境
VIRTUAL_ENV = $(CURDIR)/.venv

# 以可编辑模式安装（即引用git源的任何更新将直接影响可执行文件）
PIP_OPTIONS = -e

# 使用非默认临时存储
TMPDIR = $(CURDIR)/.tmp

# 为Tesseract安装更多语言/模型
TESSERACT_MODELS = deu frk script/Fraktur script/Latin

# 安装Tesseract的所有子模块以获取单元测试和训练工具
tesseract: GIT_RECURSIVE = --recursive

注意：当local.mk存在时，仍可以在命令行上覆盖变量，（即make all OCRD_MODULES=将再次为所有模块构建所有可执行文件），但不能从shell环境覆盖（即OCRD_MODULES= make all仍将使用local.mk中的值）。

Docker Hub

该项目可作为预构建的Docker镜像从Docker Hub的ocrd/all获取。您可以从三个标签中选择：minimum、medium和maximum。它们的区别在于包含的模块，maximum相当于使用默认（未设置）的OCRD_MODULES值运行make all。要在命令行上下载镜像：

sh
docker pull ocrd/all:minimum
# 或
docker pull ocrd/all:medium
# 或
docker pull ocrd/all:maximum

使用方法与您自己构建的镜像相同。

下表列出了哪个标签包含哪个模块：

挑战

此仓库提供了OCR-D集成中以下问题的解决方案。

PyPI上没有发布/最新版本

以下Python模块由于不同原因需要从代码安装：

• clstm（需要修改Python3代码）
• cor-asv-ann（PyPI上不可用）
• cor-asv-fst（PyPI上不可用）
• dinglehopper（PyPI上不可用）
• ocrd_cis（PyPI上不可用）
• tesserocr（PyPI上的版本太旧）

（通过从源代码安装解决。）

冲突的依赖要求

将所有包合并到一个venv中并不总是可行的。模块可能需要互斥的依赖包集。

pip甚至不会停止或解决冲突——它只会发出警告！

• Pillow:

  • ==5.4.1（ocrd_typegroups_classifier要求）
  • >=6.2.0（所有其他模块要求）

• Tensorflow:

  • tensorflow-gpu==1.14.0（ocrd_calamari和ocrd_anybaseocr要求）
  • tensorflow（cor-asv-ann和ocrd_keraslm要求）

  两者可以并行安装不同版本，但可能依赖于互斥的tensorboard和tensorflow_estimator集。

  此外，将来某些模块（但不是其他模块）可能依赖于tensorflow>=2.0，这同样不兼容。

• OpenCV:

  • opencv-python-headlesss（core和其他模块要求，避免引入X11库）
  • opencv-python（ocrd_anybaseocr要求）
  • ARM上的自定义构建...

• ...

（通过安装后的fix-pip临时解决。）

系统要求

并非所有模块都通过make deps-ubuntu公布其系统包要求。

• clstm：依赖于scons libprotobuf-dev protobuf-compiler libpng-dev libeigen3-dev swig
• tesseract（当从源代码而非PPA安装时）：依赖于libleptonica-dev等

（通过在此处的deps-ubuntu下维护这些要求解决。）