External OCR in JSON and C ABI Jobs

The ocr.layer operation accepts builtin-ascii, tesseract-cli, tesseract-dll, rapidocr-cli, and rapidocr-dll; omitting engine preserves the built-in ASCII default

Capability discovery lists these supported adapters, without asserting that external programs, libraries, language data, or ONNX models are installed on the execution host

Tesseract example

{"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}}

Place this object in a file job's operations array and add input and output paths, or pass it directly to hpdf_document_execute_json_v1 with a loaded handle and binary/result callbacks

Options and local resources

External engines require an explicit object-valued engineOptions; unknown keys, incorrect JSON types, NUL-containing paths or language strings, and empty required values are rejected

Tesseract defaults to language=eng, pageSegMode=3, and engineMode=3; segmentation modes 0 and 2 do not recognise text and are rejected, whilst the remaining modes through 13 are accepted

engineMode accepts 0 through 3; trained-data files must support the chosen mode, and multilingual Tesseract language expressions such as eng+fra require the corresponding local models

RapidOCR CLI uses the native THPDFRapidOCROptions.Default model names and defaults both thread limits to 1; it accepts explicitly supplied dictionary and font paths, and the configured bridge must implement the local TSV contract

RapidOCR DLL starts with THPDFRapidOCRDLLOptions.ForLanguage(language), defaulting to ch; language profiles select recognition model, dictionary, and reading direction, and explicit options can override those selections

Model file names resolve under modelDirectory according to the native adapters; library bitness must match the host process, whilst a CLI engine runs as a separate local process

Provision and select these resources explicitly; the operation does not install engines, download models, search for arbitrary executables, or use a remote OCR service

Budgets and cancellation

timeoutMilliseconds defaults to 60,000 and accepts integers from 1 through 3,600,000; the effective adapter timeout is capped by budget.timeMilliseconds

maxPixels defaults to 16,777,216 and accepts integers from 1 through 67,108,864; its effective cap is the minimum of the requested value, budget.pixels, and budget.memoryBytes / 16

The effective engine pixel cap also limits OCR page rendering before recognition; word, content, and UTF-16 text budgets are capped by the operation's memory allowance

These limits bound configured buffers and operation resources; external DLL model allocation does not constitute a strict process-RSS quota

Native calls borrow Document.OperationCancellationToken for rendering and recognition; C callback cancellation is polled at cooperative operation, input, and output checkpoints, and a running external engine can continue until its timeout or the next callback checkpoint

Local CLI failures, invalid or incomplete TSV output, and adapter timeouts reject the operation; configured operation time and pixel limits retain the structured budget failure category

Output and transaction behaviour

The result reports engine, recognizedPages, skippedPages, acceptedWords, and droppedWords; the engine field contains the native adapter's descriptive name

minimumConfidence must be a number from 0 through 1, and skipPagesWithText and replaceExisting must be JSON Booleans

Accepted Unicode words become invisible text with ToUnicode mappings and source-page geometry; the scan image remains in the output, and the source file remains unchanged unless the caller intentionally publishes to that same file path

File jobs preserve an existing destination on failure and publish through a same-directory staging file; C ABI mutations commit after both PDF bytes and JSON result delivery succeed, with failure rollback and caller disposal of bytes already delivered

Acceptance

Tests/Delphi/Run-JobOCRTests.ps1 runs four adapter dispatch profiles, malformed configuration, pixel and elapsed-time budgets, partial-word rejection, process failure, timeout, and destination/source preservation on Win32 and Win64

Supplying actual Tesseract executable and model paths exercises live recognition; independent pypdf and MuPDF readers verify Unicode searchable text and unchanged visible scan pixels, whilst the optional real Win64 ABI DLL check verifies partial callbacks and failed-operation rollback

See document operations, Tesseract adapters, local RapidOCR models, native RapidOCR libraries, and searchable OCR text layers