OCR（光学字符识别）

OCR 用于将扫描件、图片型 PDF 或混合文档中的图像文字识别为可搜索或可编辑文本。本文介绍 OCR 模块的适用场景、前置条件、主要接口和基本接入方式。

如需快速搭建资源目录并运行随包示例，请参阅 OCR 示例配置及运行指南。如需通过命令行执行 OCR 任务，请参阅 OCR 命令工具。

适用场景

OCR 适合以下场景：

• 扫描件、图片型 PDF 的文本识别
• 需要生成可搜索 PDF 或可编辑 PDF 的归档与检索场景
• 需要将识别后的内容继续输出为 Word、Excel、PowerPoint、HTML 等格式
• 服务端批量处理、离线处理或多进程处理任务

系统要求与前置条件

• 平台：Windows、Linux x64
• 授权：需要包含 OCR 模块权限的授权码
• 资源：需要准备 OCR 专项工具资源包或 OCR 运行资源目录

OCR 资源包的获取方式、资源目录结构和示例运行步骤，已在 OCR 示例配置及运行指南 中说明。使用 OCR API 或 OCR 命令工具前，需要先完成资源目录准备。

主要接口

OCR 模块的主要接口如下：

接口类	作用
OCREngine	初始化和释放 OCR 引擎，设置语言、日志和 OCR 回调
OCR	执行 OCR 处理，包括单页识别、整文档识别、批量识别和识别后格式转换
OCRConfig	配置 OCR 处理参数，例如图片检测、去噪、纠偏、分辨率和置信度
OCRCallback	接收取消处理回调，并可通过 IsImageIgnored() 跳过指定图片对象
OCRProgressCallback	接收 OCR 进度通知
OCRSettingData	为 OCRPDFDocuments() 提供文档、页码范围、输出类型和配置参数

典型接入流程

OCR API 的常见接入流程如下：

1. 完成 Foxit PDF SDK 初始化
2. 准备 OCR 资源目录并初始化 OCREngine
3. 设置语言，例如 English 或多语言组合
4. 按场景设置 OCRConfig
5. 调用 OCRPDFPage、OCRPDFDocument 或 OCRConvertTo
6. 保存处理后的文档或转换结果

完整可运行示例请参阅 SDK 包中的 /examples/simple_demo/ocr/ocr.cpp。以下代码片段与该示例的调用方式保持一致，省略了授权初始化、输入输出目录准备等通用代码：

#include "include/addon/ocr/fs_ocr.h"

using namespace foxit;
using namespace foxit::addon::ocr;

void RunOCR(const wchar_t* input_file,
            const wchar_t* output_file,
            const wchar_t* ocr_resource_path) {
  // Foxit PDF SDK should have been initialized before OCR starts.
  OCREngine::Initialize(ocr_resource_path);
  OCREngine::SetLanguages(L"English");

  PDFDoc doc(input_file);
  if (doc.Load() != foxit::e_ErrSuccess) {
    return;
  }

  OCRConfig config;
  config.is_detect_pictures = true;
  config.is_remove_noise = true;
  config.is_correct_skew = true;
  config.is_auto_overwrite_resolution = false;
  config.resolution_to_overwrite = 300;
  config.confidence = 30;

  OCR ocr;
  ocr.OCRPDFDocument(doc, false, config);
  doc.SaveAs(output_file, PDFDoc::e_SaveFlagNoOriginal);

  OCREngine::Release();
}

输出类型

OCR 结果主要有两类：

• 可搜索 PDF：保留页面视觉效果，新增可检索文本层
• 可编辑 PDF：将识别结果写回文档内容，便于后续编辑

如果需要将 OCR 结果进一步输出为 Office 或 HTML，可使用 OCRConvertTo。

配置能力

OCR 的常用配置能力主要包括：

• 图像检测：通过 is_detect_pictures 控制是否检测图片区域
• 图像预处理：通过 is_remove_noise、is_correct_skew 控制去噪与纠偏
• 识别策略：通过 is_enable_text_extraction_mode 控制文本提取模式
• 处理方式：通过 is_sequentially_process 控制顺序处理或自动并行处理
• 分辨率控制：通过 is_auto_overwrite_resolution、resolution_to_overwrite 控制分辨率覆盖策略
• 结果过滤：通过 confidence 控制识别结果的置信度阈值

在常见场景中，可参考以下配置思路：

• 原始图像噪点较多：保持 is_remove_noise = true
• 页面有倾斜：保持 is_correct_skew = true
• 更关注尽可能提取文字：评估开启 is_enable_text_extraction_mode
• 需要严格控制识别可信度：提高 confidence
• 已知原图分辨率不准确：关闭 is_auto_overwrite_resolution 并设置 resolution_to_overwrite
• 批量多文档任务：优先评估 OCRPDFDocuments

对于单进程任务，可使用默认方式初始化 OCREngine。对于服务端批量处理或多进程任务，可评估使用 OCREngine::Initialize(ocr_resource_path, true) 以启用 shared CPU cores mode。

何时使用 OCR API，何时使用 OCR 命令工具

可按接入方式选择：

• 需要把 OCR 纳入业务流程、任务编排或应用界面中：使用 OCR API
• 需要快速验证效果、执行批量任务或从外部程序直接调用：使用 OCR 命令工具

如果当前目标是先验证资源目录、授权和运行环境是否正确，可先从 OCR 示例配置及运行指南 开始。