技术文章

HotPDF 进程内调用 Tesseract C API 的 Delphi 绑定

进程内 Tesseract 调用上设 5,000 ms 识别期限,不等于五秒后调用就会回来。模型集一大、语言一多,调用线程在原生库里待的时间可以远超这个数:强制执行期限的进度 monitor 只在词识别期间被轮询,而模型加载和页面版面分析都发生在第一次轮询之前。这段缝隙、一个 C 返回类型只有单字节的取消回调、一个交出你绝不可释放的内存的迭代器,才是把 Tesseract C API 绑定到 Delphi 的真正工作量,其余都是管道活

把 Tesseract DLL 接进 HotPDF 文本层

HotPDF 以 HPDFTesseractRecognition 单元里的 HPDFCreateTesseractDLLOCREngine 暴露进程内这条路。工厂加载一个导出 C API 的 Tesseract DLL,驱动 TessBaseAPIInit2、TessBaseAPIRecognize 和结果迭代器,返回一个 IHPDFOCREngine。THotPDF.ApplyLoadedOCRTextLayer 接收这个引擎,给扫描页面加一层不可见、可搜索的 Unicode 文本——每个 HotPDF OCR 引擎走的都是同一个调用

工厂迫不及待地校验:DLL 文件与 tessdata 目录必须存在;语言标识符只能含 ASCII 字母、数字、_ 和 +,chi_sim+eng 这类组合里的每个模型都得有对应的 .traineddata 文件;全部 21 个必需导出必须可解析,然后才还你一个引擎。配置错误抛 EArgumentException,缺失的导出或模型按名字报告;加载不了的 DLL 抛 EOSError,带 Windows 错误码和一句“检查架构与依赖”的提示

uses
  SysUtils, HPDFDoc, HPDFTesseractRecognition;

procedure MakeSearchable(const SourceFile, TargetFile: string);
var
  Doc: THotPDF;
  Engine: IHPDFOCREngine;
  Options: THPDFOCRTextLayerOptions;
  Info: THPDFOCRTextLayerInfo;
begin
  // Win64 应用需要 64 位 DLL;文件名取决于你的构建,
  // 依赖 DLL 放同一个文件夹
  Engine := HPDFCreateTesseractDLLOCREngine('C:\OCR\Win64\libtesseract.dll',
    'C:\OCR\tessdata', 'chi_sim+eng');   // 用 THPDFTesseractOptions.Default
  Doc := THotPDF.Create(nil);
  try
    Doc.AutoLaunch := False;
    if Doc.LoadFromFile(SourceFile) < 1 then
      raise Exception.Create('Cannot load ' + SourceFile);
    Options := THPDFOCRTextLayerOptions.Default;   // 300 DPI,MinimumConfidence 0.5
    // 空页面列表 = 全部页面;已有文本的页面跳过
    if not Doc.ApplyLoadedOCRTextLayer([], Engine, Options, Info) then
      raise Exception.Create(string(Info.Diagnostic));
    Writeln(string(Info.EngineName), ': ', Info.AcceptedWordCount,
      ' words accepted, ', Info.DroppedWordCount, ' dropped');
    Doc.SaveLoadedDocument(TargetFile);
  finally
    Doc.Free;
  end;
end;

THPDFTesseractOptions.Default 把 PageSegMode 设为 tpsAuto,EngineMode 设为 temDefault,TimeoutMilliseconds 设为 60,000,MaxPixels 设为 16,777,216。像素预算比人们预想的咬得早:US Letter 页面在默认 300 DPI 下渲染成 2,550 × 3,300 像素、约 840 万,装得下;同一页提到 600 DPI 就是 5,100 × 6,600、约 3,370 万像素,引擎在 Tesseract 见到图像之前就以 Invalid Tesseract DLL OCR request or pixel budget 拒收。要么调高 MaxPixels(上限 67,108,864),要么留在 300 DPI——对正文它绰绰有余;每一维也另有 32,767 像素的上限

DLL 用 LoadLibraryEx 加载,搜索标志覆盖 DLL 自身文件夹加默认安全目录,所以 Tesseract 依赖的图像库可以放在它旁边,永远不必碰 PATH、也不依赖当前目录。HotPDF 不捆绑、也不下载任何 OCR 运行时或语言模型;两者都由你准备

与 tesseract.exe 相比,DLL 这条路改变了什么

同一个识别器也能通过写 BMP、解析 TSV 的外部 tesseract.exe 适配器用上。两个适配器喂养同一条文本层流水线,坐标映射、置信度过滤和全有或全无提交表现完全一致;不同的是像素怎么进、词怎么出,以及识别器行为不端时会发生什么

维度tesseract.exe 适配器Tesseract DLL 适配器
工厂HPDFCreateTesseractOCREngineHPDFCreateTesseractDLLOCREngine
像素输入私有临时目录里的 BMP 文件内存中的 8 位灰度缓冲
词输出词级 TSV,上限 64 MiB结果迭代器,每词 UTF-8
基线TSV 里没有;流水线自行估算从 TessPageIteratorBaseline 透传
页面分割与引擎模式THPDFTesseractOptions 重载,以 --psm 与 --oem 发送THPDFTesseractOptions,送进 TessBaseAPISetPageSegMode 与 TessBaseAPIInit2
像素预算传了选项时才有 MaxPixels始终有 MaxPixels,外加每边 32,767 像素
超时硬超时:终止子进程协作式:Tesseract 得自己察觉
崩溃与内存隔离独立进程没有,共享你的地址空间

有一项成本留在 DLL 这边。每次 Recognize 调用都创建自己的 API 实例并跑 TessBaseAPIInit2,语言模型因此每一页都初始化一遍。文件缓存能缓解重载,但在大型多语言模型集上它仍是每页最大的一笔固定成本,而且计入识别期限。进程内 RapidOCR DLL 引擎选的是相反路线,ONNX 模型在引擎生命周期内常驻;边界问题(C ABI、借用缓冲、不可打断的原生工作)则属于同一家族

那么生产环境该用哪个?桌面工具或啃几百份扫描件的批处理作业,DLL 更合适:每页不起进程、磁盘上不留临时位图、倾斜的行还有真基线。接收陌生人 PDF 的长期运行服务器,应该留在 tesseract.exe 上——那里的原生崩溃或失控分配,带走的是一个子进程,不是你的服务

为什么 Delphi 不能照抄 Tesseract 的 monitor 结构体

Delphi 没法安全镜像 Tesseract 的进度 monitor,因为 ETEXT_DESC 带着随构建变化的内部字段。照一个头文件手工翻译来的记录,会把取消回调和期限放到那个头文件恰好使用的偏移上。换一个构建去跑,Tesseract 就会从一个现在装着别的东西的字段里读你的回调指针,或者压根找不到期限,识别就这么一路跑到头

所以 HotPDF 适配器把 monitor 当作不透明指针,只通过导出函数碰它:TessMonitorCreate、TessMonitorSetCancelThis、TessMonitorSetCancelFunc、TessMonitorSetDeadlineMSecs 和 TessMonitorDelete。下面的示意是你自己的绑定代码而非 HotPDF API;它的声明与适配器用 GetProcAddress 解析的一致

HotPDF 的 Tesseract DLL monitor 处理:照抄随版本变化的 ETEXT_DESC 记录会把取消回调与期限放到错误偏移并无声失败,HotPDF 则把 monitor 当不透明指针,通过 TessMonitorCreate、TessMonitorSetCancelThis、TessMonitorSetCancelFunc 与 TessMonitorSetDeadlineMSecs 驱动,并保持 cdecl 回调无异常
一个不透明指针加五个导出就是全部契约;回调保持为单字节 Boolean,只读一个标志和一个时钟
type
  // C: typedef bool (*TessCancelFunc)(void *cancel_this, int words);
  TTessCancelFunc = function(CancelThis: Pointer; Words: Integer): Boolean; cdecl;
  TTessMonitorCreate = function: Pointer; cdecl;   // ETEXT_DESC*,永不解引用
  TTessMonitorDelete = procedure(Monitor: Pointer); cdecl;
  TTessMonitorSetCancelFunc = procedure(Monitor: Pointer; Func: TTessCancelFunc); cdecl;
  TTessMonitorSetCancelThis = procedure(Monitor, CancelThis: Pointer); cdecl;
  TTessMonitorSetDeadlineMSecs = procedure(Monitor: Pointer; MSecs: Integer); cdecl;
  TTessBaseAPIRecognize = function(Handle, Monitor: Pointer): Integer; cdecl;

  // 你自己的作业状态,不是 HotPDF 类型
  TOCRJob = record
    CancelRequested: Boolean;
    DeadlineTick: UInt64;
  end;
  POCRJob = ^TOCRJob;

function ShouldCancel(CancelThis: Pointer; Words: Integer): Boolean; cdecl;
begin
  // 跑在 Tesseract 的栈上:只读标志和时钟,绝不抛异常
  Result := (CancelThis = nil) or POCRJob(CancelThis)^.CancelRequested or
    (GetTickCount64 >= POCRJob(CancelThis)^.DeadlineTick);
end;

// 用法,函数指针由 GetProcAddress 解析:
//   Monitor := MonitorCreate();
//   try
//     MonitorSetCancelThis(Monitor, @Job);
//     MonitorSetCancelFunc(Monitor, ShouldCancel);
//     MonitorSetDeadlineMSecs(Monitor, RemainingMs);
//     RC := BaseAPIRecognize(API, Monitor);
//   finally
//     MonitorDelete(Monitor);
//   end;

示意把回调类型写成 Boolean——在 Delphi 和 Free Pascal 里都是一个字节,正好匹配 TessCancelFunc 里的 C bool。四字节的 Windows BOOL 和 Delphi LongBool 看着能互换,其实是另一个类型:一边写单个字节、另一边读四个时,高三个字节是寄存器里恰好残留的任何东西,false 可能以 true 的面目到达。TessPageIteratorBoundingBox 返回 int,Pascal 侧声明为 Integer——逐个读返回值的 C 类型,别假设整个 API 一个约定

回调也从不抛异常。Delphi 异常穿过 Tesseract 的 C++ 栈帧展开是未定义行为。HotPDF 的回调只读取消令牌和一个单调的 GetTickCount64 值,适配器在 TessBaseAPIRecognize 返回之后把结果转成取消或超时诊断,而且无论原生返回码是不是 0 都做这项检查

Delphi 侧拥有哪些原生指针

HotPDF 的 Tesseract DLL 适配器每个请求拥有三个原生对象(API 实例、monitor 和结果迭代器),其余全部借用。每次 Recognize 调用创建自己的一套,并在 finally 块里按固定顺序释放:TessResultIteratorDelete,然后 TessMonitorDelete,然后 TessBaseAPIDelete。释放引擎接口会对 DLL 调 FreeLibrary

HotPDF 的 Tesseract DLL 每次 Recognize 调用的对象所有权:结果迭代器、monitor 与 API 实例被拥有并在 finally 内按此顺序释放,TessResultIteratorGetPageIterator 给出的页面迭代器是绝不可释放的借用视图,GetUTF8Text 字符串拷贝后经 TessDeleteText 归还
三个对象被拥有,其余全是借用:按固定顺序释放,绝不二次释放页面迭代器,绝不混用分配器
  • TessResultIteratorGetPageIterator 返回的是结果迭代器内部的视图,不是新对象。适配器用它做 TessPageIteratorBoundingBox 和 TessPageIteratorBaseline,从不释放;再删一次就会把同一块内存释放两遍
  • TessResultIteratorGetUTF8Text 返回 DLL 自己运行时分配的字符串。适配器解码它,并在 finally 块里经 TessDeleteText 归还,因为 Pascal 的 FreeMem 会在错误的堆上释放它
  • 词文本先做长度检查、再经严格 UTF-8 解码。带控制字符、畸形 UTF-8、框跑出图像、矩形颠倒或置信度落在 0–100 之外的词让整个请求失败;适配器不替它打补丁
  • 每次请求的文本上限 1,048,576 个 UTF-16 码元,词数必须装得下 ApplyLoadedOCRTextLayer 随每页下发的预算

置信度以 0–100 到达,缩放到 0–1,所以 THPDFOCRTextLayerOptions.MinimumConfidence 对每个引擎含义一致。Tesseract 报告基线时,两个端点都透传;以竖排为主的词,用框宽当文本高度。没有基线时,文本层流水线回退到几何估算——对 TSV 输入也正是这么做的

枚举选项进 DLL 之前先做范围检查

工厂把 PageSegMode 和 EngineMode 的原始字节先拷进 Integer 再做范围检查。编译器有权假设枚举变量总持有已声明的值,所以直接对枚举写的 Ord(X) > Ord(High(T)) 这类测试可能被折叠成常量 false。这些序数以普通整数的身份进 DLL:THPDFTesseractPageSegMode 沿用 Tesseract 0 到 13 的页面分割编号,THPDFTesseractEngineMode 沿用 0 到 3 的引擎模式编号。用 FillChar 清过、从流里读出、或从 C++Builder 经整数强转传来的选项记录,都可能带着 200 这样的字节;校验拷贝,就在工厂时刻把它变成 EArgumentException。工厂还拒收不产词的 tpsOSDOnly 和 tpsAutoOnly,并要求 tpsAutoOSD 与 tpsSparseTextOSD 配有 osd.traineddata

识别超时到底保证什么

Tesseract DLL 的超时是协作式的:HotPDF 能停下自己的工作、请求 Tesseract 停下,但没法强迫原生代码返回。时钟从 Recognize 开始计时,所以灰度转换和模型初始化与识别本身花的是同一份预算。适配器在灰度转换期间每 64 行、初始化之后、以及遍历结果的每个词之前,检查已用时间和取消令牌。就在 TessBaseAPIRecognize 之前,把剩余毫秒交给 TessMonitorSetDeadlineMSecs

缝隙在原生调用内部。Tesseract 只在词识别期间查询 monitor,所以 TessBaseAPIInit2 或页面版面分析里,一次缓慢的模型加载或病态版面可以在超时被报告之前就跑过期限。像素与输出预算也不封顶原生库自己的内存用量。需要一个能直接杀掉的 worker 时,进程适配器才是那个工具

HotPDF 的 Tesseract DLL 协作式超时剖析:时钟从 Recognize 开始、覆盖灰度转换、TessBaseAPIInit2 与版面分析,但 monitor 只在词识别期间被查询,所以模型加载与版面可能在 HotPDF 报出 otlsEngineError 或 otlsCancelled 之前就超期
这里的期限是请求,不是保证:init 与版面分析可能跑很久,真正能杀的 worker 需要进程适配器

页面分割是 DLL 适配器在别扭输入上回报的地方。字段散落的表单、标签和扫描表格,用 tpsSparseText 往往比自动分割识别得更好——后者总想拼装出根本不存在的栏和段落。下面的超时对一页表单来说很短,却仍要覆盖模型初始化

procedure OCRFormPages(Doc: THotPDF; const Pages: array of Integer);
var
  Engine: IHPDFOCREngine;
  TessOptions: THPDFTesseractOptions;
  LayerOptions: THPDFOCRTextLayerOptions;
  Info: THPDFOCRTextLayerInfo;
begin
  TessOptions := THPDFTesseractOptions.Default;
  TessOptions.PageSegMode := tpsSparseText;  // 字段散落,不拼栏
  TessOptions.EngineMode := temLSTMOnly;     // tessdata 里要有 LSTM 模型
  TessOptions.TimeoutMilliseconds := 20000;  // 含模型初始化
  Engine := HPDFCreateTesseractDLLOCREngine('C:\OCR\Win64\libtesseract.dll',
    'C:\OCR\tessdata', 'eng+deu', TessOptions);

  LayerOptions := THPDFOCRTextLayerOptions.Default;
  LayerOptions.MinimumConfidence := 0.6;
  if not Doc.ApplyLoadedOCRTextLayer(Pages, Engine, LayerOptions, Info) then
    case Info.Status of
      otlsCancelled:
        Writeln('OCR cancelled, document unchanged');
      otlsEngineError:
        if Pos('timed out', string(Info.Diagnostic)) > 0 then
          Writeln('Tesseract timed out, document unchanged')
        else
          Writeln('Tesseract failed: ', string(Info.Diagnostic));
    else
      Writeln(string(Info.Diagnostic));
    end;
end;

超时以 otlsEngineError 浮现,诊断里是 Tesseract DLL OCR timed out;经 THPDFOCRTextLayerOptions.CancellationToken 设置的令牌以 otlsCancelled 浮现。两种情况下,ApplyLoadedOCRTextLayer 都先把所有选中页识别完才开始提交,所以 50 页中的第 40 页失败,加载的文档分毫未动。tpsSingleLine、tpsSingleBlock 和 tpsSparseText 只改分割;没有一个能拉直倾斜的扫描件

Free Pascal 与 Lazarus:过期像素与丢失的中文

两个 Tesseract 工厂在 Windows Free Pascal 与 Lazarus 的 Win32、Win64 构建里都能工作,只要先为目标架构重建 Lazarus 包;通用移植见 HotPDF 在 Free Pascal 与 Lazarus Win64 上。输入处理才是 FPC 表现不同的地方

经 scanline 写入的 LCL TBitmap 可能更新了原始图像却没刷新 Windows 位图句柄,于是在那个句柄上 GetDIBits 返回旧像素。症状让人摸不着头脑:直接画到位图上的文字识别得好好的,经 scanline 渲染出来的页面却一个词都没有。FPC 下,DLL 适配器经 CreateIntfImage 读取格式感知的快照,尊重原始图像的像素格式与行序。Delphi 构建在私有 24 位副本上保留 GetDIBits 路径;两个构建都不修改调用者的位图

tesseract.exe 适配器遇上的是另一个问题。FPC 的 TStringList 存 ANSI 字符串,把解码后的 UTF-8 TSV 文本赋给 Lines.Text,系统 ANSI 代码页表示不了的每个中文或增补平面字符都会被丢掉。FPC 路径把 TSV 按 UTF-8 字节保存,在字节层面剥掉 BOM,逐词自行解码成 UnicodeString。DLL 适配器遇不到这个问题,因为它直接从迭代器逐词解码

Tesseract DLL 适配器与进程适配器、内置 OCR 引擎一起随 HotPDF 发布,面向 Delphi、C++Builder 和 Free Pascal。版本与下载见 HotPDF Delphi PDF component page