JSON 与 C ABI 任务中的外部 OCR

ocr.layer 操作接受 builtin-ascii、tesseract-cli、tesseract-dll、rapidocr-cli 和 rapidocr-dll；省略 engine 时保留内置 ASCII 默认值

能力发现会列出这些受支持的适配器，但并不断言外部程序、库、语言数据或 ONNX 模型已经安装在执行主机上

Tesseract 示例

{"schemaVersion":1,"type":"ocr.layer","pages":[0],"dpi":300,
 "minimumConfidence":0.7,"skipPagesWithText":true,"replaceExisting":false,
 "engine":"tesseract-cli",
 "engineOptions":{"executablePath":"C:/OCR/tesseract.exe",
   "tessDataDirectory":"C:/OCR/tessdata","language":"eng",
   "pageSegMode":6,"engineMode":3,"timeoutMilliseconds":30000,
   "maxPixels":16777216}}

把这个对象放进文件任务的 operations 数组并补上 input 与 output 路径，或者拿着已加载的句柄和 binary/result 回调直接传给 hpdf_document_execute_json_v1

引擎	必需的 engineOptions	可选的 engineOptions
builtin-ascii	无	engineOptions 必须缺失或为空对象
tesseract-cli	executablePath、tessDataDirectory	language、pageSegMode、engineMode、timeoutMilliseconds、maxPixels
tesseract-dll	libraryPath、tessDataDirectory	language、pageSegMode、engineMode、timeoutMilliseconds、maxPixels
rapidocr-cli	pythonExecutable、bridgeScript、modelDirectory	detectionModel、recognitionModel、classificationModel、characterDictionary、fontPath、useAngleClassifier、intraOpThreads、interOpThreads、timeoutMilliseconds、maxPixels
rapidocr-dll	libraryPath、modelDirectory	language、detectionModel、recognitionModel、classificationModel、characterDictionary、useAngleClassifier、rightToLeft、threads、timeoutMilliseconds、maxPixels

选项与本地资源

外部引擎要求显式提供对象类型的 engineOptions；未知键、错误的 JSON 类型、含 NUL 的路径或语言字符串、以及为空的必填值都会被拒绝

Tesseract 默认 language=eng、pageSegMode=3 和 engineMode=3；分割模式 0 和 2 无法识别文本，会被拒绝，其余直到 13 的模式都接受

engineMode 接受 0 到 3；trained-data 文件必须支持所选模式，而 eng+fra 这类多语言 Tesseract 语言表达式需要对应的本地模型

RapidOCR CLI 使用原生 THPDFRapidOCROptions.Default 的模型名，并把两个线程上限默认为 1；它接受显式提供的字典与字体路径，所配置的 bridge 必须实现本地 TSV 契约

RapidOCR DLL 从 THPDFRapidOCRDLLOptions.ForLanguage(language) 起步，默认 ch；语言档案决定识别模型、字典和阅读方向，显式选项可以覆盖这些选择

模型文件名按原生适配器的规则在 modelDirectory 下解析；库的位数必须与宿主进程一致，而 CLI 引擎作为独立本地进程运行

这些资源需要显式供给和选择；该操作不会安装引擎、下载模型、搜索任意可执行文件，也不会使用远程 OCR 服务

预算与取消

timeoutMilliseconds 默认 60,000，接受 1 到 3,600,000 的整数；实际生效的适配器超时受 budget.timeMilliseconds 封顶

maxPixels 默认 16,777,216，接受 1 到 67,108,864 的整数；实际生效的上限取请求值、budget.pixels 和 budget.memoryBytes / 16 三者的最小值

引擎实际生效的像素上限同样约束识别前的 OCR 页面渲染；单词、内容和 UTF-16 文本预算受该操作的内存配额封顶

这些限制约束的是已配置的缓冲区和操作资源；外部 DLL 的模型分配并不构成严格的进程 RSS 配额

原生调用在渲染和识别期间借用 Document.OperationCancellationToken；C 回调取消在协作式的操作、输入与输出检查点轮询，正在运行的外部引擎可以继续跑到超时或下一个回调检查点

本地 CLI 失败、无效或不完整的 TSV 输出、适配器超时都会使该操作被拒绝；已配置的操作时间与像素限制仍保留结构化的 budget 失败类别

输出与事务行为

结果会报告 engine、recognizedPages、skippedPages、acceptedWords 和 droppedWords；engine 字段是原生适配器的描述性名称

minimumConfidence 必须是 0 到 1 之间的数字，skipPagesWithText 与 replaceExisting 必须是 JSON 布尔值

被接受的 Unicode 单词会变成带 ToUnicode 映射和源页面几何信息的不可见文本；扫描图像保留在输出中，除非调用方有意发布到同一路径，源文件保持不变

文件任务在失败时保留既有目标文件，并通过同目录 staging 文件发布；C ABI 的变更在 PDF 字节和 JSON 结果交付都成功之后才提交，失败即回滚，已交付的字节由调用方处置

验收

Tests/Delphi/Run-JobOCRTests.ps1 在 Win32 和 Win64 上覆盖四个适配器分发档案、畸形配置、像素与耗时预算、部分单词拒绝、进程失败、超时，以及目标/源文件保护

提供真实的 Tesseract 可执行文件和模型路径即可演练实际识别；独立的 pypdf 和 MuPDF 阅读器验证 Unicode 可搜索文本和未变化的可见扫描像素，可选的真实 Win64 ABI DLL 检查则验证部分回调与失败操作的回滚

参见 document operations、Tesseract adapters、local RapidOCR models、native RapidOCR libraries 以及 searchable OCR text layers