进程内 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 适配器 |
|---|---|---|
| 工厂 | HPDFCreateTesseractOCREngine | HPDFCreateTesseractDLLOCREngine |
| 像素输入 | 私有临时目录里的 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 解析的一致
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
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 时,进程适配器才是那个工具
页面分割是 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