OCRmyPDF 实战手册从基础 OCR 到 v17 新特性的完整操作指南【免费下载链接】OCRmyPDFOCRmyPDF adds an OCR text layer to scanned PDF files, allowing them to be searched项目地址: https://gitcode.com/GitHub_Trending/oc/OCRmyPDF本文为 OCRmyPDF 仓库自带 Cookbook 文档的成文版。围绕一条命令加参数这一核心工作方式它系统覆盖了 OCRmyPDF 的日常用法添加 OCR 层、选择输出类型PDF / PDF/A / 无输出、图像预处理旋转、去背景、倾斜校正、清理、非英语识别、sidecar 文本提取、--pages页码级控制、--mode处理模式以及 v17 引入的光栅化器选择与无 Ghostscript 的 PDF/A 转换。读完本文你可以针对具体扫描件任务组合出恰当的命令行参数并理解每个参数在源码中的实际默认值与校验规则。基础用法OCRmyPDF 自带帮助这是查询全部参数的第一入口ocrmypdf --help添加 OCR 层并转换为 PDF/A最典型的用法是把扫描件加上 OCR 文本层默认输出 PDF/A用于长期归档的标准 PDF 子集ocrmypdf input.pdf output.pdf添加 OCR 层并输出标准 PDF如果不需要 PDF/A 合规性可用--output-type pdf输出普通 PDFocrmypdf --output-type pdf input.pdf output.pdf--output-type在源码中被校验为auto / pdfa / pdf / pdfa-1 / pdfa-2 / pdfa-3 / none七个取值见 OcrOptions.validate_output_type其中none表示不产生 PDF 输出常用于只提取 sidecar 文本的场景。将彩色/灰度图像统一转成 JPEG 的 PDF/Aocrmypdf --output-type pdfa --pdfa-image-compression jpeg input.pdf output.pdf该参数属于 Ghostscript 选项组pdfa_image_compression字段定义于 src/ocrmypdf/_options.py只在经 Ghostscript 产出 PDF/A 时生效。用优化器降低 JPEG 质量压缩输出中 JPEG 体积的推荐方式是使用优化器optimizer而不是去调 Ghostscript 自身的 JPEG 参数ocrmypdf --optimize 2 --jpeg-quality 60 input.pdf output.pdf文档强调优化器不依赖--output-type无论输出是普通 PDF 还是 Ghostscript 产出的 PDF/A 都会生效。从源码可以印证这一点optimize()函数中若用户未显式指定--jpeg-quality会按优化等级自动补默认值——低于-O3时用内置的默认 JPEG 质量-O3时直接降到 40见 src/ocrmypdf/optimize.py。完整的优化等级说明见 docs/optimizer.md。原地修改文件ocrmypdf myfile.pdf myfile.pdf输入输出同名即原地修改。文件只在 OCRmyPDF 成功完成后才会被覆盖失败时原文件保持不动。页面旋转校正OCRmyPDF 会为每一页尝试自动纠正方向这对混排了横版与竖版页面的扫描作业尤其有用ocrmypdf --rotate-pages myfile.pdf myfile.pdf阈值参数--rotate-pages-threshold控制旋转的激进程度。它的含义是OCR 引擎认为应当改变方向相对于保持原样的置信度比值。默认值比较保守——从源码看默认阈值为14.0src/ocrmypdf/_defaults.py且合法范围被校验器限制在 0 到 1000 之间src/ocrmypdf/_options.py。处理时页面方向的置信度只有达到或超过该阈值才会真正执行旋转src/ocrmypdf/_pipeline.py。调低阈值例如2.0→ 更多页面被旋转但同时误报更多调高阈值 → 只有引擎非常有把握时才旋转。建议先带-v1运行一次查看每一页的置信度日志再为特定文件挑选合适的阈值。注意区分两个概念--rotate-pages用于基本角度错了整页横/竖颠倒或差 90°的情况--deskew用于页面只是略微偏离水平线的情况比如照片斜了 3°。非英语 OCR除非显式指定OCRmyPDF 默认假设文档是英语默认语言eng定义于 src/ocrmypdf/_defaults.py。语言用错会显著降低识别质量ocrmypdf -l fra LeParisien.pdf LeParisien.pdf ocrmypdf -l engfra Bilingual-English-French.pdf Bilingual-English-French.pdf指定的每一种语言都必须已安装对应的语言包安装方式见 docs/languages.md。另外Tesseract 引擎本身没有语言检测能力未知语言必须手动指定。Sidecar同时输出 OCR 文本文件ocrmypdf --sidecar output.txt input.pdf output.pdf这会产生两个文件PDF 与同目录下的output.txt。使用 sidecar 时要注意它的边界sidecar 只包含OCR 识别出来的文本文档中原本就存在的数字文本digital text不会出现在 sidecar 里若使用了--pagessidecar 只包含实际执行了 OCR 的那些页因--skip-big、--tesseract-timeout等原因被跳过的页不会写入 sidecar若不想生成 PDF 只想要文本可设--output-typenone并把输出文件名设为-重定向到标准输出若需要提取 PDF 中全部文本无论来源请使用 Poppler 的pdftotext或pdfgrep这类工具。sidecar字段在选项模型中类型为路径或文件对象src/ocrmypdf/_options.py。对图片而不是 PDF 做 OCR方案一直接用 Tesseract如果起点是图片可以直接用 Tesseract 把图片转成带文本层的 PDFtesseract my-image.jpg output-prefix pdf# 多张图片用包含文件名列表的文本文件 tesseract text-file-containing-list-of-image-filenames.txt output-prefix pdfTesseract 的 PDF 输出质量相当不错——OCRmyPDF 内部在某些情况下也复用了它。但 Tesseract 缺少 OCRmyPDF 的诸多能力如图像预处理、元数据控制和 PDF/A 生成。方案二img2pdf 管道用 img2pdf 之类的工具先把图片无损地封装进 PDF再把结果管道给 OCRmyPDF-表示从标准输入读取img2pdf my-images*.jpg | ocrmypdf - myfile.pdf这是多张图片的推荐路线img2pdf 生成的 PDF 不对图像做任何转码保留了原始像素质量。方案三OCRmyPDF 直接吃单张图片ocrmypdf --image-dpi 300 image.png myfile.pdfOCRmyPDF 可以直接把单张图片转成 PDF 并 OCR。若图片的分辨率DPI信息缺失或错误用--image-dpi覆盖1 英寸 2.54 厘米1 dpi 0.39 dpcm。注意多张图片必须走 img2pdf 路线。不推荐的方案不建议用 ImageMagick 或 Ghostscript 把图片转 PDF它们可能悄悄对图像转码或降采样且不一定给出警告——而输入图像分辨率错误会直接损害 OCR 质量见下文提升 OCR 质量。图像预处理OCRmyPDF 可以按需对每一页做图像处理且所有页应用完全相同的处理。文档建议处理完人工抽查因为这些操作可能移除有价值的内容尤其是低质量扫描件。五个开关参数作用--rotate-pages判定每页正确方向并旋转基本角度错误时--remove-background检测并去除灰度/彩色图中的噪点背景单色图像会被忽略不要用在含彩色照片的文档上可能把照片一起删掉--deskew校正扫描倾斜把页面旋转回正--clean用 unpaper 在 OCR 前清理页面不改变最终输出降低 OCR 去背景噪声里找字的概率--clean-final用 unpaper 清理后把清理过的页插入最终输出务必逐页复查确认未误删重要内容两条重要提示图像处理通常会把 PDF 页面栅格化为图像可能损失质量--clean-final与--remove-background的算法存在局限部分图像上会留下可见瑕疵用完后应目检文件。在源码中这些步骤对应 src/ocrmypdf/_pipeline.py 里的preprocess_remove_background、preprocess_deskew、preprocess_clean等预处理函数--clean-final会自动连带开启--clean选项校验器中显式处理见 src/ocrmypdf/_options.py。示例OCR 并校正倾斜ocrmypdf --deskew input.pdf output.pdf各图像处理开关可以任意组合且书写顺序无关紧要——OCRmyPDF 始终以固定顺序执行流水线rotate旋转→ remove background去背景→ deskew倾斜校正→ clean清理ocrmypdf --deskew --clean --rotate-pages input.pdf output.pdf只处理不 OCR--ocr-engine none把--ocr-engine none设为无 OCR 引擎时OCRmyPDF 只做图像处理或直接做 PDF/A 转换跳过识别ocrmypdf --ocr-engine none --deskew --output-type pdfa input.pdf output.pdf版本沿革上有两点需要注意v17.0.0 起--ocr-engine none是关闭 OCR 的推荐写法。此前社区惯用的--tesseract-timeout 0惯用法已不再推荐因为项目正把 Tesseract 从默认引擎位置上挪开v14.1.0 起--tesseract-timeout 0不再连带禁掉 Tesseract 的其他用途例如 deskew 的倾斜角度估计。如需单独控制非 OCR 操作的超时用--tesseract-non-ocr-timeout。移除 PDF 中的 OCR 文本层若只想删掉不可见的 OCR 文本层、同时保持页面像素级原样不栅格化、不动图像、输出更小使用--mode stripocrmypdf --mode strip input.pdf output.pdf典型场景某份 PDF 的 OCR 结果根本不可用只想把糟粕清掉。其边界要清楚--mode strip只移除以PDF 文本渲染模式 3不可见绘制的文本——这正是 OCRmyPDF 及多数 OCR 工具叠加可搜索层的方式某些 OCR 产品以及OCRmyPDF v2.2 及更早版本采用绘制可见文本 上层盖不透明图像的旧方案。那种文本属于页面可见内容strip 无法在不改变外观的前提下移除它若必须连同可见文本一起剥离只能把整页栅格化成图像袋子PDF——代价是每页重建为图像文件通常变大、矢量内容丢失ocrmypdf --ocr-engine none --force-ocr input.pdf output.pdf不 OCR 只优化图像ocrmypdf --ocr-engine none --optimize 3 --skip-text input.pdf output.pdf这条组合拳用于纯粹的体积优化跳过 OCR、跑满优化等级 3。v17 新特性选择光栅化器v17.0.0 起OCRmyPDF 支持用 pypdfium2 或 Ghostscript 把 PDF 页面栅格化成图像。pypdfium2 通常更快可用时优先选用# 自动选择默认- 可用时优先 pypdfium ocrmypdf --rasterizer auto input.pdf output.pdf # 显式使用 pypdfium2需 pip install pypdfium2 ocrmypdf --rasterizer pypdfium input.pdf output.pdf # 显式使用 Ghostscript ocrmypdf --rasterizer ghostscript input.pdf output.pdf源码中的校验器确认--rasterizer只接受auto / ghostscript / pypdfium三个取值src/ocrmypdf/_options.py默认值为auto。不依赖 Ghostscript 的 PDF/Av17.0.0 起只要安装了 verapdfOCRmyPDF 可以在不经过 Ghostscript的情况下产出 PDF/A先做投机性转换再用 verapdf 校验合规。这条路更快也绕开了 Ghostscript 的一些限制# 投机转换 verapdf 校验默认行为 ocrmypdf --output-type auto input.pdf output.pdf # 显式要求基于 Ghostscript 的 PDF/A 转换 ocrmypdf --output-type pdfa input.pdf output.pdf用--mode取代旧标志v17.0.0 引入的--mode短形式-m把三种 OCR 行为合并进一个选项# 取代 --skip-text ocrmypdf --mode skip input.pdf output.pdf # 取代 --force-ocr ocrmypdf --mode force input.pdf output.pdf # 取代 --redo-ocr ocrmypdf --mode redo input.pdf output.pdf # 短形式 ocrmypdf -m skip input.pdf output.pdf旧标志作为别名继续可用。这一点从源码可确认选项模型里force_ocr/skip_text/redo_ocr已成为mode的向后兼容属性src/ocrmypdf/_options.py且在模型构建前有一个专门的校验器把旧布尔标志翻译成ProcessingMode枚举、并检测互相冲突的写法src/ocrmypdf/_options.py。此外还有前文用到的strip模式。mode还有兼容性约束redo 模式与--deskew、--clean-final、--remove-background互斥这些选项会改变文件外观源码中有显式校验报错src/ocrmypdf/_options.py。只处理指定页ocrmypdf --pages 2,3,13-17 input.pdf output.pdf语法要点连字符-表示页码区间逗号分隔页码想带空格写列表时整体加引号--pages 2, 3, 5, 7特殊记号end不区分大小写指最后一页--pages 3-end表示从第 3 页到最后一页--pages end表示只处理最后一页。ocrmypdf --pages 3-end input.pdf output.pdf ocrmypdf --pages end input.pdf output.pdf行为细节部分由源码印证页码列表有重复或重叠时 OCRmyPDF 会告警重复项会自动去重因为底层真正生效的是页码集合见 src/ocrmypdf/_options.py 中的页码解析逻辑end会被延迟到知道总页数后再解析使用文档自身的印刷页码如书前置部分的罗马数字是不被考虑的——OCRmyPDF 只从文件开头数虚拟纸张页码乱序书写没关系OCRmyPDF 会自动排序。一个重要陷阱--pages只限制图像处理与 OCR 的作用范围。文件级操作——优化全部图像/页面、转换 PDF/A——默认仍然作用于整个文件。若只想 OCR 标题页、其余尽量不动应同时关掉这些全文件步骤ocrmypdf --pages 1 --output-type pdf --optimize 0 input.pdf output.pdf重做已有的 OCR对用其他 OCR 软件、或旧版 OCRmyPDF / Tesseract 处理过的文件重新 OCR使用--redo-ocr正常情况下OCRmyPDF 遇到已含 OCR 的文件会直接报错退出ocrmypdf --redo-ocr input.pdf output.pdf适用场景吃下 Tesseract 新版本的识别精度提升重跑存量文件。该模式不栅格化不会降质或丢矢量内容混合文件纯数字文本 OCR 层并存中数字文本被忽略只替换 OCR 层因为不改变外观它与图像处理选项--deskew、--clean-final、--remove-background不兼容有些旧格式无法识别OCRmyPDF v2.2 及更早产物是可见文本 不透明图像覆盖的内部结构这种 OCR无法被检测也无法被替换若--redo-ocr不适用退路是--force-ocr强制把所有页栅格化后重做 OCR代价是可能降质、丢失矢量内容。提升 OCR 质量图像预处理本身就是提升质量的手段--rotate-pages与--deskew保证 OCR 开始前页面方向正确--remove-background与--clean减少背景噪声对识别的干扰--oversample DPI在 OCR 前把图像重采样到更高分辨率也可能改善结果该参数合法范围为 0–5000 DPI见 src/ocrmypdf/_options.py。反过来输入图像分辨率标注错误会直接拉低 OCR 质量——因为 OCRmyPDF 依据 DPI 推算每个像素可能对应的字号范围DPI 错了字号候选区间也就错了。这也是前文不推荐 ImageMagick/Ghostscript 转图的根本原因。PDF 优化OCR 完成后OCRmyPDF 默认会对 PDF 内图像做无损优化即使没有发现可 OCR 的文本优化照样执行。--optimize N短形式-O控制优化等级N取值 0–3类比 GCC 编译器优化等级默认-O1源码中optimize: int 1见 src/ocrmypdf/_options.py等级含义-O0关闭大部分优化-O1默认无损优化把图像转成更高效的编码、压缩未压缩对象、启用对象流-O2加上有损优化与颜色量化-O3更激进的优化目标更小、图像质量目标更低ocrmypdf --optimize 3 in.pdf out.pdf # 目标尽量小各等级的完整行为含 JBIG2、pngquant、fast web view 等见 docs/optimizer.md。个别用户可能考虑开启有损 JBIG2见 docs/jbig2.md。最后一条提醒即使--optimize 1纯无损档图像处理与 PDF/A 转换本身也可能引入有损变换优化等级不能替你保证零损失。数字签名 PDFOCRmyPDF 不能一边保留数字签名一边加 OCR 层二者不可兼得默认行为拒绝修改任何带签名的 PDF无论其他参数如何设置用--invalidate-digital-signatures可覆盖此行为——顾名思义所有数字签名都会被作废用数字证书加密的文档 OCRmyPDF 根本无法打开版本沿革v14.4.0 之前的 OCRmyPDF 会不告而废文档中已有的数字签名处理旧作业时要留意。小结OCRmyPDF 的 Cookbook 本质上是一张参数组合表日常任务是input.pdf output.pdf加少量开关扫描件质量差时叠加--rotate-pages --deskew --remove-background --clean存量重跑用--redo-ocr纯瘦身用--ocr-engine none --optimize 3 --skip-text。所有参数的默认值与取值约束都能在 src/ocrmypdf/_options.py 的OcrOptions模型和 src/ocrmypdf/_defaults.py 中核对图像预处理的具体执行顺序可在 src/ocrmypdf/_pipeline.py 中追溯——这使本文每个命令行示例都有源码级依据可查。【免费下载链接】OCRmyPDFOCRmyPDF adds an OCR text layer to scanned PDF files, allowing them to be searched项目地址: https://gitcode.com/GitHub_Trending/oc/OCRmyPDF创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考