高级功能

控制unpaper

OCRmyPDF 使用 unpaper 来提供 --clean--clean-final 参数的实现。 unpaper 提供了多种图像处理过滤器来改善图像质量。

默认情况下,OCRmyPDF 仅使用 unpaper 参数,这些参数被发现在几乎所有文件上使用都是安全的,而无需在之后检查文件的每一页。特别是当仅使用 --clean 时,因为这会指示 OCRmyPDF 仅在 OCR 之前清理图像,而不是最终图像。

然而,如果您希望使用unpaper中更激进的选项,您可以使用--unpaper-args '...'来覆盖OCRmyPDF的默认设置,并将其他参数传递给unpaper。此选项将参数转发给unpaper,而无需了解该程序认为哪些参数是有效的。参数字符串必须如下例所示进行引用。不能包含文件名参数。OCRmyPDF将假定它可以将中间图像的输入和输出文件名附加到--unpaper-args字符串中。

在这个例子中,我们告诉unpaper期望在一张纸(图像)上有两页文本,这种情况通常发生在扫描书籍的两页对开页时。unpaper使用这些信息来独立地对每页进行去斜处理,并清理两页的边距。

ocrmypdf --clean --clean-final --unpaper-args '--layout double' input.pdf output.pdf
ocrmypdf --clean --clean-final --unpaper-args '--layout double --no-noisefilter' input.pdf output.pdf

警告

一些 unpaper 功能会重新定位图像中的文本。 建议使用 --clean-final 来避免这个问题。

警告

一些 unpaper 功能会导致消耗或生成多个输入或输出文件。OCRmyPDF 要求 unpaper 消耗一个文件并生成一个文件;如果不满足此假设,将会导致错误。

注意

unpaper 使用未压缩的 PBM/PGM/PPM 文件作为其中间文件。对于大图像或文档,它可能会占用大量的临时磁盘空间。

OCR选项的控制

OCRmyPDF 提供了许多功能来控制 OCR 引擎 Tesseract 的行为。

当跳过OCR时

如果PDF中的某个页面似乎包含文本,默认情况下OCRmyPDF将退出而不修改PDF。这是为了确保之前已经进行过OCR处理或“天生数字化”而非扫描的PDF不会被处理。

如果发出--skip-text,则不会对已经有文本的页面进行图像处理或OCR。页面将被复制到输出中。这对于包含“原生数字”和扫描内容的文档,或者使用OCRMmyPDF来规范化和转换为PDF/A而不考虑其内容的情况可能很有用。

如果发出--redo-ocr,则会执行详细的文本分析。 文本被分类为可见或不可见。不可见文本(OCR) 被剥离。然后创建每页的图像,并屏蔽掉可见文本。 页面图像被发送进行OCR,任何额外的文本都 作为OCR插入。如果文件包含文本和包含文本的位图图像的混合, OCRmyPDF将在不破坏现有文本的情况下定位图像中的额外文本。一些PDF OCR解决方案将文本渲染为 技术上可打印或以某种方式可见,可能是通过绘制它然后 在其上绘制。OCRmyPDF无法区分这种类型的OCR 文本和真实文本,因此它不会被“重做”。

如果发出--force-ocr,则所有页面将被栅格化为图像,丢弃任何隐藏的OCR文本,栅格化任何可打印的文本,并将表单字段或交互式对象展平为其视觉表示。这对于重新进行OCR、修复带有损坏字符映射的OCR文本(文本可选择但不可搜索)以及销毁已编辑的信息非常有用。

时间和图像大小限制

默认情况下,OCRmyPDF 允许 tesseract 每页运行三分钟(180 秒)。对于现代硬件来说,这通常足以在合理大小的页面上找到所有文本。

如果跳过了某个页面,它将在没有OCR的情况下插入。如果请求了预处理,将插入预处理后的图像层。

如果你想调整OCR所花费的时间,可以更改 --tesseract-timeout。你也可以使用--skip-big自动跳过超过一定兆像素的图像。(一张300 DPI,8.5×11英寸的页面图像是8.4兆像素。)

# Allow 300 seconds for OCR; skip any page larger than 50 megapixels
ocrmypdf --tesseract-timeout 300 --skip-big 50 bigfile.pdf output.pdf

大图像的OCR

Tesseract 对处理的图像大小有内部限制。默认情况下, --tesseract-downsample-large-images 是启用的,OCRmyPDF 会将图像缩小以适应 Tesseract 的限制。(这些限制通常只在扫描超大尺寸媒体(如大型地图或蓝图,尺寸超过 110 厘米或 43 英寸)且在高 DPI 时遇到。)可以使用 --no-tesseract-downsample-large-images 禁用此功能。

--tesseract-downsample-above Npixels 调整图像将被下采样的阈值。默认情况下,只有超过Tesseract内部限制的图像才会被下采样(任一维度超过32767像素)。

您还需要将--tesseract-timeout设置得足够高,以允许处理。

只有发送用于OCR的图像会被下采样。原始图像会被保留。

# Allow 600 seconds for OCR on huge images
ocrmypdf --tesseract-timeout 600 \
    --tesseract-downsample-large-images \
    bigfile.pdf output.pdf

# Downsample images above 5000 pixels on the longest dimension to
# 5000 pixels
ocrmypdf --tesseract-timeout 120 \
    --tesseract-downsample-large-images \
    --tesseract-downsample-above 5000 \
    bigfile.pdf output_downsampled_ocr.pdf

覆盖默认的tesseract

OCRmyPDF 检查系统中的 PATH 以查找 tesseract 二进制文件。

一些影响Tesseract行为的相关环境变量包括:

TESSDATA_PREFIX

覆盖Tesseract数据文件的路径。这可以允许同时安装“最佳”和“快速”训练数据集。OCRmyPDF不管理此环境变量。

OMP_THREAD_LIMIT

控制Tesseract将使用的线程数。如果未设置此环境变量,OCRmyPDF将管理它。

例如,如果您有一个Tesseract的开发版本,不希望使用系统安装,您可以按如下方式启动OCRmyPDF:

env \
    PATH=/home/user/src/tesseract/api:$PATH \
    TESSDATA_PREFIX=/home/user/src/tesseract \
    ocrmypdf input.pdf output.pdf

在这个例子中,TESSDATA_PREFIX 是必需的,用于将 Tesseract 重定向到其“tessdata”文件的备用文件夹。

覆盖其他支持程序

除了tesseract,OCRmyPDF还使用了以下外部二进制文件:

  • gs (Ghostscript)

  • unpaper

  • pngquant

  • jbig2

在每种情况下,OCRmyPDF 都会搜索 PATH 环境变量以定位二进制文件。通过修改 PATH 环境变量,您可以覆盖 OCRmyPDF 使用的二进制文件。

更改Tesseract配置变量

你可以通过配置文件覆盖Tesseract的默认控制参数

例如,此配置将禁用当前语言的Tesseract字典。通常情况下,字典有助于插值不清楚的单词,但如果文档不包含许多单词(例如,零件编号列表),它可能会干扰OCR。

创建一个名为“no-dict.cfg”的文件,内容如下:

load_system_dawg 0
language_model_penalty_non_dict_word 0
language_model_penalty_non_freq_dict_word 0

然后按如下方式运行 ocrmypdf(以及其他所需的参数):

ocrmypdf --tesseract-config no-dict.cfg input.pdf output.pdf

警告

某些控制参数的组合会破坏Tesseract或破坏OCRmyPDF对Tesseract输出的假设。

更改页面分割模式

指令 --tesseract-pagesegmode Nmode 将所需的页面分割模式传递给 Tesseract OCR。默认值为 3。

当您知道PDF应该以特定方式进行分析时,页面分割可以提高OCR结果,例如页面仅包含一行文本的PDF。对于绝大多数用户来说,更改页面分割模式只会使情况变得更糟。

截至2024年6月,Tesseract页面分割模式为:

ID

描述

0

仅进行方向和脚本检测(OSD)。

1

使用OSD进行自动页面分割。

2

自动页面分割,但没有OSD或OCR。(未实现)

3

全自动页面分割,但没有OSD。(默认)

4

假设有一列大小可变的文本。

5

假设有一个垂直对齐的文本块。

6

假设有一个统一的文本块。

7

将图像视为单行文本。

8

将图像视为单个单词。

9

将图像视为圆圈中的单个单词。

10

将图像视为单个字符。

11

稀疏文本。尽可能多地找到文本,不按特定顺序。

12

带有OSD的稀疏文本。

13

原始行。将图像视为单行文本,绕过特定于Tesseract的技巧。

模式 0、1、2 和 12(所有启用方向和脚本检测的模式)与 OCRmyPDF 不兼容,OCRmyPDF 在 OCR 的单独步骤中执行 OSD。它们的使用可能会干扰 --rotate-pages 和其他功能。

目前无法在使用OCRmyPDF通过Tesseract时使用高级Tesseract OCR功能,例如创建OCR信息。

更改PDF渲染器

rasterizing

将PDF转换为图像以进行显示。

rendering

从其他数据(如现有的PDF)创建新的PDF。

OCRmyPDF 有以下这些 PDF 渲染器:sandwichhocr。可以使用 --pdf-renderer 来选择渲染器。默认是 auto,它让 OCRmyPDF 自动选择使用的渲染器。目前,auto 总是选择 hocr

hocr 渲染器

在版本16.0.0中已更改。

在两种渲染器中,都会渲染一个仅包含文本的层,并将其叠加(覆盖)到原始PDF页面上,或者叠加到原始PDF页面的新光栅化版本上(当使用--force-ocr时)。通过这种方式,通常可以避免PDF信息的丢失。(您可能需要禁用PDF/A转换和优化,以消除所有有损转换。)

新hOCR渲染器当前使用的方法是对Tesseract的PDF渲染器的重新实现,使用了相同的无字形字体和一般理念,但修复了许多阻碍其发展的技术问题。新的hOCR提供了更好的文本定位准确性,避免了分词问题,并提供了更好的倾斜文本定位。

使用实验性API,也可以使用任何能够编辑hOCR文件的工具来编辑来自Tesseract的OCR输出。

此渲染器的旧版本不支持非拉丁语言,但现在已普遍支持。

sandwich 渲染器

sandwich 渲染器使用 Tesseract 的纯文本 PDF 功能,生成一个将 OCR 布局为不可见文本的 PDF 页面。

目前一些有问题的PDF查看器,如Mozilla PDF.js和macOS Preview,在分段其文本输出时存在问题,可能会将多个单词连在一起。它也没有实现从右到左的字体(阿拉伯语、希伯来语、波斯语)。此渲染器的输出无法编辑。sandwich渲染器被保留用于测试。

当使用像--deskew这样的图像预处理功能时,原始PDF将被渲染为完整页面,OCR层将放置在顶部。

渲染和光栅化选项

在版本14.3.0中添加。

--continue-on-soft-render-error 选项允许 OCRmyPDF 在页面无法栅格化/渲染时继续处理。这对于您试图从格式不正确的 PDF 中获取最佳 OCR 结果时非常有用,并且您愿意接受一些页面可能在视觉上与输入不匹配,并且可能无法很好地 OCR。

颜色转换策略

在版本15.0.0中添加。

OCRmyPDF 使用 Ghostscript 将 PDF 转换为 PDF/A。在某些情况下,这种转换需要进行颜色转换。默认策略是使用 LeaveColorUnchanged 策略进行转换,该策略尽可能保留原始颜色空间(某些罕见的颜色空间可能仍会被转换)。

通常文档扫描仪会在sRGB色彩空间中生成PDF,不需要进行转换,因此默认策略是合适的。

假设您有一个为专业印刷准备的文档,使用了分离或CMYK色彩空间,并且文本已转换为曲线。在这种情况下,您可能希望使用不同的颜色转换策略。--color-conversion-strategy 选项允许您选择不同的策略,例如 RGB

返回代码策略

OCRmyPDF 将所有消息写入 stderrstdout 用于管道输出文件。stdin 用于管道输入文件。

OCRmyPDF 生成的返回代码被视为稳定用户界面的一部分。它们可以从 ocrmypdf.exceptions 导入。

Return codes

代码

名称

解释

0

ExitCode.ok

一切按预期工作。

1

ExitCode.bad_args

无效的参数,退出时出错。

2

ExitCode.input_file

输入文件似乎不是一个有效的PDF。

3

ExitCode.missing_dependency

OCRmyPDF所需的外部程序缺失。

4

ExitCode.invalid_output_pdf

创建了一个输出文件,但它似乎不是一个有效的PDF。该文件将可用。

5

ExitCode.file_access_error

运行 OCRmyPDF 的用户没有足够的权限来读取输入文件和写入输出文件。

6

ExitCode.already_done_ocr

文件似乎已经包含文本,因此可能不需要OCR。请参阅输出消息。

7

ExitCode.child_process_error

外部程序(子进程)中发生错误,OCRmyPDF 无法继续。

8

ExitCode.encrypted_pdf

输入的PDF已加密。OCRmyPDF不读取加密的PDF。请使用其他程序如qpdf来移除加密。

9

ExitCode.invalid_config

使用 --tesseract-config 将一个自定义配置文件转发给 Tesseract,但 Tesseract 拒绝了该文件。

10

ExitCode.pdfa_conversion_failed

创建了一个有效的PDF,但PDF/A转换失败。文件将可用。

15

ExitCode.other_error

发生了其他错误。

130

ExitCode.ctrl_c

程序通过按下Ctrl+C被中断。

更改临时存储位置

OCRmyPDF 在处理过程中会生成许多临时文件。

要更改临时文件的存储位置,请更改ocrmypdf环境的TMPDIR环境变量。(Python的tempfile.gettempdir()返回临时文件将存储的根目录。)例如,可以将TMPDIR重定向到一个大的RAM磁盘,以避免HDD/SSD的磨损,并可能提高性能。

在Windows上,使用TEMP环境变量代替。

调试中间文件

OCRmyPDF 通常将其中间结果保存到一个临时文件夹中,并在退出时删除该文件夹,无论成功还是失败。

如果在命令行中使用了--keep-temporary-files (-k)参数,OCRmyPDF将保留临时文件夹并打印其位置,无论成功还是失败。示例消息如下:

Temporary working files retained at:
/tmp/ocrmypdf.io.u20wpz07

当OCRmyPDF作为snap启动时,这对应于snap文件系统,例如:

/tmp/snap-private-tmp/snap.ocrmypdf/tmp/ocrmypdf.io.u20wpz07

此文件夹的组织结构是一个实现细节,可能会在版本之间发生变化。然而,一般的组织结构是,每页的工作文件以页码作为前缀(从第1页开始),中缀表示处理阶段,后缀表示文件类型。一些重要的文件包括:

  • _rasterize.png - 输入页面的外观

  • _ocr.png - 发送到Tesseract进行OCR处理的文件;根据参数的不同,这可能与展示的图像不同

  • _pp_deskew.png - 图像,经过去斜处理后

  • _pp_clean.png - 使用unpaper清理后的图像

  • _ocr_hocr.pdf - OCR文件;显示为带有嵌入的不可见文本的空白页面

  • _ocr_hocr.txt - OCR文本(不一定是页面上的所有文本,如果页面是混合格式)

  • fix_docinfo.pdf - 一个用于修复PDF DocumentInfo数据结构的临时文件

  • graft_layers.pdf - 渲染的PDF,带有附加的OCR层

  • pdfa.pdf - 转换为PDF/A后的graft_layers.pdf

  • pdfa.ps - Ghostscript 用于 PDF/A 转换的 PostScript 文件

  • optimize.pdf - 优化前生成的PDF

  • optimize.out.pdf - 由优化生成的PDF

  • origin - 输入文件

  • origin.pdf - 输入文件或转换为PDF的输入图像

  • images/* - 优化过程中提取的图像;这里的前缀表示PDF对象ID,而不是页码