Technical Article

HotPDF Chinese and Multilingual OCR with RapidOCR in Delphi

A Russian invoice run through a recogniser that loads the Cyrillic model but still reads the Chinese character dictionary comes back as rows of perfectly valid Han characters. Every line is well-formed UTF-8, every line lands in the searchable text layer, and a search for any word printed on the page finds nothing. The model did its job. A CTC recogniser never outputs characters, only class numbers, and the dictionary file is the one thing that maps class 1,204 to a glyph

Three related failures sit close by, and a Latin-script demo shows none of them: every line losing its final character, English text arriving without word spacing, and Arabic text boxes coming back in left-to-right order. Each traces to a dictionary rule, a loop boundary or a sort order that is easy to get almost right. All four start at the same point: the step that turns a language tag into a model and a dictionary

RapidOCR language presets in HotPDF: one tag, one pinned pair

In HotPDF, THPDFRapidOCRDLLOptions.ForLanguage turns a language tag into options that point at <profile>/recognition.onnx and <profile>/dictionary.txt below your model directory. Everything else comes from THPDFRapidOCRDLLOptions.Default: the shared detector, the optional angle classifier, one thread, a 16,777,216-pixel budget per request and a 60-second timeout. The tag is lowercased, underscores become hyphens and surrounding whitespace is trimmed, so 'zh_TW', 'ZH-tw' and ' zh-tw ' resolve to the same profile

Matching runs against an explicit alias list, with no prefix matching. 'zh-Hant-TW' and 'zh-MO' are accepted because they are listed; 'pt-AO' is not, and ForLanguage raises EArgumentException before any file is opened. That strictness is deliberate. A prefix rule would quietly send 'zh-Hant-SG' or some future tag to whichever profile shares its first two letters, and with Chinese the first two letters do not tell you the script

HotPDF ForLanguage profile resolution for THPDFRapidOCRDLLOptions: tags like zh_TW, ZH-tw and zh-TW are normalised and matched against nine listed profiles, each pinning a recognition model and dictionary that are always set together, while an unlisted tag raises EArgumentException before any model loads
one tag selects one pinned model-dictionary pair; the detector, classifier and budgets stay shared, and an unknown tag fails fast instead of loading anything
ProfileLanguagesExample tagsBox order in a row
chSimplified Chinese and Englishzh, zh-CN, zh-Hans, chi_simLeft to right
chinese_chtTraditional Chinesezh-TW, zh-HK, zh-Hant, chi_traLeft to right
enEnglishen, en-US, en-GB, engLeft to right
latinFrench, German, Spanish, Portuguese, Italian, Dutch, Turkishfr, de, es-419, pt-BR, trLeft to right
japanJapaneseja, ja-JP, jpnLeft to right
koreanKoreanko, ko-KR, korLeft to right
cyrillicRussian, Ukrainian, Bulgarian, Belarusianru, ru-RU, uk, bgLeft to right
arabicArabic, Persian, Urduar, ar-SA, fa, urRight to left
devanagariHindi, Marathi, Nepalihi, mr, neLeft to right

The adapter never downloads anything. Model files are provisioned once with the bundled helper, for example tools/Install-RapidOCRModels.ps1 -Destination C:/OCR/models -Language ch,chinese_cht,cyrillic, or -Language All for all nine profiles. The helper puts the shared detector and classifier at the root filenames Default expects and each profile in its own folder. Engine creation, the DLL boundary and threading are covered in the article on the in-process RapidOCR DLL; with the files in place, a Simplified Chinese scan becomes searchable like this

uses
  SysUtils, HPDFDoc, HPDFRapidOCRRecognition;

procedure MakeChineseScanSearchable(const SourceFile, TargetFile: string);
var
  Doc: THotPDF;
  Engine: IHPDFOCREngine;
  Models: THPDFRapidOCRDLLOptions;
  Layer: THPDFOCRTextLayerOptions;
  Info: THPDFOCRTextLayerInfo;
begin
  // ch/recognition.onnx + ch/dictionary.txt, shared detector and classifier
  Models := THPDFRapidOCRDLLOptions.ForLanguage('zh-CN');
  // models load here; reuse the engine across documents
  Engine := HPDFCreateRapidOCRDLLOCREngine(
    'C:\OCR\Win64\HotPDFRapidOCR.dll', 'C:\OCR\models', Models);
  Doc := THotPDF.Create(nil);
  try
    Doc.AutoLaunch := False;
    if Doc.LoadFromFile(SourceFile) < 1 then
      raise Exception.Create('Cannot load ' + SourceFile);
    Layer := THPDFOCRTextLayerOptions.Default;  // 300 DPI, MinimumConfidence 0.5
    // empty page list = every page; SkipPagesWithText leaves text pages alone
    if not Doc.ApplyLoadedOCRTextLayer([], Engine, Layer, Info) then
      raise Exception.Create(string(Info.Diagnostic));
    Writeln(string(Info.EngineName), ': ', Info.AcceptedWordCount,
      ' lines, ', Info.UniqueScalarCount, ' distinct characters');
    Doc.SaveLoadedDocument(TargetFile);
  finally
    Doc.Free;
  end;
end;

Two numbers in that output need reading carefully. The native pipeline reports one result per detected text line, so AcceptedWordCount counts lines here, and MinimumConfidence is compared with the mean character confidence of the whole line: a line averaging 0.45 is dropped as a unit. UniqueScalarCount is the number of distinct Unicode scalars the text layer had to map into its font and ToUnicode table. A page of Chinese body text should push that figure well past the few dozen scalars a Latin page needs; a count in Latin territory on a Chinese scan usually means the wrong profile is loaded

Why does switching only the recognition model produce garbage?

Because the model and the dictionary are two halves of one lookup table, and only the dictionary knows what the indices mean. Point RecognitionModel at cyrillic/recognition.onnx while CharacterDictionary still names the Chinese file, and the model emits valid Cyrillic indices that the old dictionary translates into random Han characters. ForLanguage always sets both fields together. Hand-built options should follow the same rule: never change one without the other

The obvious guard, comparing the dictionary size with the model output width, is necessary and still not enough. Two dictionaries can hold the same number of entries in a different order, and an off-by-one shifts every character by one position. The HotPDF RapidOCR DLL therefore checks twice while the factory initialises the recogniser. The model's output class count must equal the dictionary entries plus two. Then, if the ONNX file embeds a character metadata list, each dictionary line is compared with it in order. Either mismatch makes HPDFCreateRapidOCRDLLOCREngine raise EInvalidOperation with the native diagnostic, so the error surfaces at startup and not in a customer's archive

The "plus two" comes from the class layout. Class 0 is the CTC blank, classes 1 to N are the dictionary lines in file order, and the final class is a space. Some dictionaries carry their own single-space entry as well, and that line has to survive exactly as it is. Here a well-meaning Trim does real damage: it turns the space entry into an empty string and shifts or breaks the table. The DLL strips a trailing carriage return so CRLF files load, and rejects a UTF-8 byte order mark, an empty line, or an entry containing a tab or a stray carriage return

HotPDF CTC class table layout for RapidOCR dictionaries: class 0 is the blank, classes 1 to N are the dictionary lines in file order with any lone space entry kept, and the final class is a space, giving N plus 2 output classes that the factory verifies against the model, metadata included
the dictionary is the only thing turning class indices into characters, so its size, order and space entry are verified before a single page is recognised

If you maintain your own dictionaries, a pre-flight check in your build or deployment script catches these problems before the engine does. The function below is your own code, written to mirror the rules above

// Your own helper, not a HotPDF API: builds the class table a CTC
// recogniser expects and rejects the dictionary defects the DLL rejects
uses
  SysUtils, IOUtils;

function BuildCTCClassTable(const FileName: string): TArray<string>;
var
  Text, Entry: string;
  Lines: TArray<string>;
  I, Last: Integer;
begin
  Text := TEncoding.UTF8.GetString(TFile.ReadAllBytes(FileName));
  if (Text <> '') and (Text[1] = #$FEFF) then
    raise EArgumentException.Create('Dictionary must be UTF-8 without a BOM');
  Lines := Text.Split([#10]);
  Last := High(Lines);
  if (Last >= 0) and (Lines[Last] = '') then
    Dec(Last);                                   // newline at end of file
  if Last < 0 then
    raise EArgumentException.Create('Dictionary is empty');
  SetLength(Result, Last + 3);
  Result[0] := '';                               // class 0: CTC blank
  for I := 0 to Last do
  begin
    Entry := Lines[I];
    if (Entry <> '') and (Entry[Length(Entry)] = #13) then
      SetLength(Entry, Length(Entry) - 1);       // CRLF: drop the CR only
    if (Entry = '') or (Pos(#9, Entry) > 0) or (Pos(#13, Entry) > 0) then
      raise EArgumentException.CreateFmt('Invalid dictionary line %d', [I + 1]);
    Result[I + 1] := Entry;                      // never Trim: ' ' is a class
  end;
  Result[Last + 2] := ' ';                       // final class: space
  // Length(Result) must equal the model output class count
end;

Greedy CTC decoding and its three boundary traps

Greedy CTC decoding picks the highest-scoring class at each time step, collapses consecutive repeats into one character and drops the blank. The blank is what lets a genuinely doubled letter survive. A recognition model reads a text line as a sequence of narrow vertical slices, and for each slice it outputs a probability for every class. A line containing AA中 might produce the argmax sequence A A blank A 中 space: the first two A steps collapse into one, the blank separates it from the next A, and the output is AA中 with the trailing space intact. Without the blank rule, book and bok would decode identically

HotPDF GreedyCTCDecode walkthrough: six time steps vote argmax classes A, A, blank, A, a Han character and space, consecutive repeats collapse, the blank resets the repeat guard so a genuinely doubled letter survives, and three boundary bugs silently drop word spacing, the last character, or doubled characters
the decoder is a dozen lines and every boundary matters: include the last class, include the last step, and let only a blank separate repeats

A decoder that short invites off-by-one mistakes, and each mistake produces its own recognisable symptom. Stop the inner argmax loop one class early and the space class can never win, so every English or Latin line comes back as one long word and phrase search stops working. Stop the outer loop one time step early and the last character of every line disappears, which on a two-character label is half the text. Forget to let a blank reset the repeat guard and doubled characters collapse: ll in hello, or the reduplicated 谢谢. If you write a decoder for a custom pipeline, these three cases make a compact test set. The HotPDF decoder covers the last class and the last step, keeps blank-separated repeats, and rejects scores that are not finite or fall outside 0 to 1, plus any class count that disagrees with the dictionary

// Illustration for your own pipeline, not a HotPDF API: greedy CTC
// decoding with correct boundaries. Scores holds Steps * Classes
// probabilities, one row per time step
function GreedyCTCDecode(const Scores: array of Single;
  Steps, Classes: Integer; const Characters: array of string): string;
var
  Step, C, Best, Previous: Integer;
  BestScore: Single;
begin
  if (Classes < 3) or (Length(Characters) <> Classes) or
    (Length(Scores) <> Steps * Classes) then
    raise EArgumentException.Create('Model output does not match the dictionary');
  Result := '';
  Previous := 0;                            // class 0 is the CTC blank
  for Step := 0 to Steps - 1 do             // include the last time step
  begin
    Best := 0;
    BestScore := Scores[Step * Classes];
    for C := 1 to Classes - 1 do            // include the last class (space)
      if Scores[Step * Classes + C] > BestScore then
      begin
        Best := C;
        BestScore := Scores[Step * Classes + C];
      end;
    if (Best <> 0) and (Best <> Previous) then
      Result := Result + Characters[Best];
    Previous := Best;                       // a blank resets the repeat guard
  end;
end;

Beam search with a language model can resolve some ambiguous slices that greedy decoding gets wrong, at a real cost in speed and in a second set of files to version. For printed documents rendered at 300 DPI, greedy decoding is the right default, and the decoder is the wrong place to compensate for what the model cannot see. The same applies to character substitution tables. If a model reads an accented letter as its base letter, patching the output with a replacement table repairs one language and breaks another. A wrong character in a searchable layer is worse than a missing one, because search finds the wrong document instead of no document, so the recognised text goes into the PDF exactly as the model produced it

How are text lines ordered for right-to-left Arabic?

The DLL sorts detected text boxes top to bottom, groups boxes into one row when they overlap vertically by at least half the smaller box height, and orders each row left to right, or right to left when RightToLeft is set. The characters inside a recognised line are never reversed. Row grouping matters because detectors often split one visual line into several boxes, a label and a value separated by a wide gap for instance, and a plain top-coordinate sort would interleave them with the next line whenever their tops differ by a pixel or two

The Arabic profile is the only one where ForLanguage sets RightToLeft := True, which makes the DLL order each row by the boxes' right edges, starting from the right margin. That is the whole effect. The text the model returns for a line is already in Unicode logical order, the order an Arabic reader reads and types it, and that is also the order PDF text extraction and search expect. Reversing the string so it "looks right" in the Delphi debugger would break search, copy and paste, and screen readers. Bidirectional display and glyph shaping belong to the PDF viewer

One engine serves one language profile, and there is no automatic script detection. A document that mixes scripts needs one engine per profile, each applied to its own pages. ApplyLoadedOCRTextLayer takes an explicit page list and commits each call as its own transaction, so a failure on the Arabic pages rolls back that call without touching the Chinese layer already written

uses
  SysUtils, HPDFDoc, HPDFRapidOCRRecognition;

function CreateRapidEngine(const Tag: string): IHPDFOCREngine;
var
  Models: THPDFRapidOCRDLLOptions;
begin
  // raises EArgumentException for an unlisted tag, before any model loads
  Models := THPDFRapidOCRDLLOptions.ForLanguage(Tag);
  Models.MaxPixels := 33554432;          // room for A3 pages at 300 DPI
  Result := HPDFCreateRapidOCRDLLOCREngine(
    'C:\OCR\Win64\HotPDFRapidOCR.dll', 'C:\OCR\models', Models);
end;

procedure OCRMixedArchive(Doc: THotPDF);
var
  Chinese, Arabic: IHPDFOCREngine;
  Layer: THPDFOCRTextLayerOptions;
  Info: THPDFOCRTextLayerInfo;
begin
  Chinese := CreateRapidEngine('zh-TW');  // chinese_cht profile
  Arabic := CreateRapidEngine('ar-SA');   // arabic profile, RightToLeft = True
  Layer := THPDFOCRTextLayerOptions.Default;
  if not Doc.ApplyLoadedOCRTextLayer([0, 1, 2], Chinese, Layer, Info) then
    raise Exception.Create(string(Info.Diagnostic));
  if not Doc.ApplyLoadedOCRTextLayer([3], Arabic, Layer, Info) then
    raise Exception.Create(string(Info.Diagnostic));
end;

The MaxPixels line is there for a reason. The default budget of 16,777,216 pixels per request covers A4 and US Letter at 300 DPI with room to spare. An A3 sheet at 300 DPI works out to about 3508 by 4961 pixels, roughly 17.4 million, so that request is refused and Info.Diagnostic reports an invalid request or pixel budget. Raise MaxPixels up to the 67,108,864 ceiling, or lower THPDFOCRTextLayerOptions.DPI for large formats. Right-to-left ordering goes through the DLL export HPDFRapidOCRSetReadingDirection, which the adapter looks up only when RightToLeft is set; a DLL build without that export still serves the left-to-right profiles, and creating an Arabic engine with it raises EArgumentException naming the missing export

Pinned model packs and what a custom pair must pass

The HotPDF RapidOCR DLL links a statically built ONNX Runtime, so it reads the ONNX file format versions that runtime understands and nothing newer. Recent model exports can target a newer format; such a file is rejected at engine creation with a native diagnostic. That pairing is why each language pack points at one specific recogniser and dictionary that load and pass the class checks under the bundled runtime, and why the packs are never "latest"

Install-RapidOCRModels.ps1 enforces the pairing on disk. Every file in its manifest carries a SHA256 hash. An existing file with a different hash stops the install and is left in place for you to move or remove, and each download is written under a temporary name and moved into position only after its hash matches. That blocks the quiet version of the dictionary problem: someone copies a newer recognition.onnx into a profile folder by hand, the class count happens to match, and the first sign of trouble is a customer saying search cannot find words they can plainly see. If you install with -SkipClassifier, set UseAngleClassifier := False in the options, because Default expects the classifier file and engine creation checks that it exists

The recogniser also checks the model's input shape at load time. It accepts NCHW float input with a fixed height of 32 or 48 pixels, or a dynamic height, which it runs at 48. A model exported with any other fixed height fails engine creation with "Unsupported recognition model input or output shape"

For a script none of the nine profiles cover, RecognitionModel and CharacterDictionary can point at your own files, and every check above still applies. A mismatched pair fails at engine creation, in your test run. For pages where no RapidOCR profile fits, the Tesseract adapter for searchable PDF plugs into the same ApplyLoadedOCRTextLayer call, and for machine-printed ASCII forms the built-in template-matching OCR engine needs no model files at all

Language presets, the native RapidOCR adapter and the OCR text layer are all included in the HotPDF Delphi PDF Component for Delphi, C++Builder and Windows FPC/Lazarus projects