Technisch artikel

Tesseract-DLL-OCR in Delphi: de C API in-process aansluiten

Een recognition-time-out van 5000 ms op een in-process Tesseract-aanroep betekent niet dat de aanroep na vijf seconden terugkomt. Met een grote meertalige modelset kan de aanroepende thread ruim voorbij die markering in de native library blijven, want de progress monitor die de deadline afdwingt wordt gepolst terwijl woorden worden herkend, en zowel het laden van modellen als de paginalay-outanalyse gebeuren vóór de eerste poll. Die kloof, een cancel-callback waarvan het C-returntype één byte is, en een iterator die geheugen uitdeelt dat je nooit mag vrijgeven: dat is het echte werk van de Tesseract C API aan Delphi knopen. De rest is loodgieterswerk

De Tesseract-DLL aansluiten op een HotPDF-tekstlaag

HotPDF biedt het in-process-pad aan als HPDFCreateTesseractDLLOCREngine in de unit HPDFTesseractRecognition. De factory laadt een Tesseract-DLL die de C API exporteert, bedient TessBaseAPIInit2, TessBaseAPIRecognize en de result-iterator, en geeft een IHPDFOCREngine terug. THotPDF.ApplyLoadedOCRTextLayer neemt die engine en voegt een onzichtbare, doorzoekbare Unicode-tekstlaag toe aan gescande pagina's, dezelfde aanroep die elke HotPDF-OCR-engine doorloopt

De factory valideert gretig. Het DLL-bestand en de tessdata-map moeten bestaan. De taalidentificator mag alleen ASCII-letters, cijfers, _ en + bevatten, en elk model in een combinatie als chi_sim+eng heeft een bijpassend .traineddata-bestand nodig. Alle 21 vereiste exports moeten resolvbaar zijn voordat je een engine terugkrijgt. Configuratiefouten gooien een EArgumentException, met een ontbrekende export of model bij naam gemeld; een DLL die niet laadt gooit een EOSError met de Windows-foutcode en de hint om architectuur en dependencies te controleren

uses
  SysUtils, HPDFDoc, HPDFTesseractRecognition;

procedure MakeSearchable(const SourceFile, TargetFile: string);
var
  Doc: THotPDF;
  Engine: IHPDFOCREngine;
  Options: THPDFOCRTextLayerOptions;
  Info: THPDFOCRTextLayerInfo;
begin
  // Een Win64-applicatie heeft een 64-bit DLL nodig; de bestandsnaam hangt van je build af,
  // en zijn dependency-DLL's gaan in dezelfde map
  Engine := HPDFCreateTesseractDLLOCREngine('C:\OCR\Win64\libtesseract.dll',
    'C:\OCR\tessdata', 'chi_sim+eng');   // gebruikt 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
    // Een lege paginalijst betekent elke pagina; pagina's die al tekst dragen worden overgeslagen
    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 zet PageSegMode op tpsAuto, EngineMode op temDefault, TimeoutMilliseconds op 60.000 en MaxPixels op 16.777.216. Dat pixelbudget komt eerder in de knel dan mensen verwachten. Een US Letter-pagina op de default 300 DPI rendert naar 2550 × 3300 pixels, ruwweg 8,4 miljoen, en past. Til dezelfde pagina naar 600 DPI: hij wordt 5100 × 6600, zo'n 33,7 miljoen pixels, en de engine weigert hem met Invalid Tesseract DLL OCR request or pixel budget voordat Tesseract de afbeelding ooit te zien krijgt. Verhoog MaxPixels (het plafond is 67.108.864) of blijf op 300 DPI, wat voor lopende tekst ruim voldoende is; per zijde geldt ook een grens van 32.767 pixels

De DLL wordt geladen met LoadLibraryEx en de zoekvlaggen voor de eigen map van de DLL plus de default veilige mappen. De image-libraries waar Tesseract van afhangt kunnen dus ernaast staan, en je hoeft nooit PATH aan te raken of op de huidige map te vertrouwen. HotPDF bundelt of downloadt geen OCR-runtime en geen taalmodel; beide voorzie je zelf

Wat het DLL-pad anders maakt dan tesseract.exe

Dezelfde recognizer is ook bereikbaar via de externe tesseract.exe-adapter die een BMP schrijft en TSV parset. Beide adapters voeden één tekstlaag-pipeline, dus coördinaatmapping, confidence-filtering en de all-or-nothing-commit gedragen zich identiek. Het verschil zit in hoe pixels erin gaan, hoe woorden eruit komen, en wat er gebeurt als de recognizer zich misdraagt

Aspecttesseract.exe-adapterTesseract-DLL-adapter
FactoryHPDFCreateTesseractOCREngineHPDFCreateTesseractDLLOCREngine
Pixels erinBMP-bestand in een privé tijdelijke map8-bit grijswaardenbuffer in het geheugen
Woorden eruitWoordniveau-TSV, afgekapt op 64 MiBResult-iterator, UTF-8 per woord
BaselinesNiet in de TSV; de pipeline schat zeDoorgegeven vanuit TessPageIteratorBaseline
Paginasegmentatie en engine-modusTHPDFTesseractOptions-overload, verstuurd als --psm en --oemTHPDFTesseractOptions, verstuurd naar TessBaseAPISetPageSegMode en TessBaseAPIInit2
PixelbudgetMaxPixels als opties worden meegegevenMaxPixels altijd, plus 32.767 pixels per zijde
Time-outHard: het childproces wordt beëindigdCoöperatief: Tesseract moet het zelf merken
Crash- en geheugenisolatieApart procesGeen, het deelt jouw adresruimte

Eén kostenpost blijft bij de DLL. Elke Recognize-aanroep maakt zijn eigen API-instantie aan en draait TessBaseAPIInit2, dus de taalmodellen worden per pagina geïnitialiseerd. De bestandscache neemt de rand eraf, maar met een grote meertalige modelset blijft het de grootste vaste kostenpost per pagina, en hij wordt op de recognition-deadline verrekend. De in-process RapidOCR-DLL-engine kiest het tegenovergestelde en houdt zijn ONNX-modellen resident gedurende de levensduur van de engine, terwijl de grensproblemen (C ABI, geleende buffers, native werk dat je niet kunt onderbreken) tot dezelfde familie behoren

Welke hoort er dan in productie? Voor een desktop-tool of een batchklus die een paar honderd scans verwerkt is de DLL de betere keuze: geen processtart per pagina, geen tijdelijke bitmap op schijf, en echte baselines voor scheve regels. Een langlopende server die PDF's van vreemden accepteert blijft beter op tesseract.exe, want een native crash of uit de hand gelopen allocatie neemt daar één childproces neer in plaats van je service

Waarom kan Delphi de Tesseract-monitorstructuur niet kopiëren?

Delphi kan Tesseracts progress monitor niet veilig spiegelen, want ETEXT_DESC draagt interne velden die per Tesseract-build verschillen. Een record dat met de hand uit één header is vertaald, zet de cancel-callback en de deadline op de offsets die die header toevallig gebruikte. Draai het tegen een andere build en Tesseract leest je callback-pointer uit een veld dat inmiddels iets anders betekent, of vindt de deadline helemaal niet, en de herkenning loopt gewoon door tot het einde

De HotPDF-adapter behandelt de monitor daarom als opake pointer en raakt hem alleen aan via geëxporteerde functies: TessMonitorCreate, TessMonitorSetCancelThis, TessMonitorSetCancelFunc, TessMonitorSetDeadlineMSecs en TessMonitorDelete. De schets hieronder is je eigen bindingcode, geen HotPDF-API; zijn declaraties matchen de declaraties die de adapter met GetProcAddress resolved

HotPDF Tesseract DLL-monitorhandling: het kopiëren van de versieafhankelijke ETEXT_DESC-record zet de cancel-callback en deadline op verkeerde offsets en faalt stilletjes, terwijl HotPDF de monitor als opaak behandelt, TessMonitorCreate, TessMonitorSetCancelThis, TessMonitorSetCancelFunc en TessMonitorSetDeadlineMSecs bedient, en de cdecl-callback exceptionvrij houdt
Een opake pointer plus vijf exports is het hele contract; de callback blijft een Booleaanse waarde van één byte die alleen een vlag en een klok leest
type
  // C: typedef bool (*TessCancelFunc)(void *cancel_this, int words);
  TTessCancelFunc = function(CancelThis: Pointer; Words: Integer): Boolean; cdecl;
  TTessMonitorCreate = function: Pointer; cdecl;   // ETEXT_DESC*, nooit gedereferenceerd
  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;

  // Eigen jobstatus, geen HotPDF-type
  TOCRJob = record
    CancelRequested: Boolean;
    DeadlineTick: UInt64;
  end;
  POCRJob = ^TOCRJob;

function ShouldCancel(CancelThis: Pointer; Words: Integer): Boolean; cdecl;
begin
  // Draait op Tesseracts stack: lees een vlag en de klok, gooi nooit een exception
  Result := (CancelThis = nil) or POCRJob(CancelThis)^.CancelRequested or
    (GetTickCount64 >= POCRJob(CancelThis)^.DeadlineTick);
end;

// Gebruik, met de functiepointers geresolved door GetProcAddress:
//   Monitor := MonitorCreate();
//   try
//     MonitorSetCancelThis(Monitor, @Job);
//     MonitorSetCancelFunc(Monitor, ShouldCancel);
//     MonitorSetDeadlineMSecs(Monitor, RemainingMs);
//     RC := BaseAPIRecognize(API, Monitor);
//   finally
//     MonitorDelete(Monitor);
//   end;

De schets typt de callback als Boolean, één byte in zowel Delphi als Free Pascal, wat matcht met de C bool in TessCancelFunc. De vier-byte Windows-BOOL en Delphi's LongBool lijken uitwisselbaar en zijn een ander type: schrijft de ene kant één byte en leest de andere er vier, dan zijn de bovenste drie bytes wat het register toevallig bevatte, en kan een false als true aankomen. TessPageIteratorBoundingBox geeft een int terug, op de Pascal-kant gedeclareerd als Integer, dus lees het C-type van elke returnwaarde in plaats van één regel voor de hele API aan te nemen

De callback gooit ook nooit iets. Een Delphi-exception die door Tesseracts C++-frames unwindt is ongedefinieerd gedrag. De HotPDF-callback leest alleen het cancellation token en een monotone GetTickCount64-waarde, en de adapter zet de uitkomst na terugkeer van TessBaseAPIRecognize om in een cancellation- of time-out-diagnostic. Die check draait hij of de native returncode nu 0 was of niet

Welke native pointers bezit de Delphi-kant?

De HotPDF Tesseract-DLL-adapter bezit drie native objecten per aanvraag (de API-instantie, de monitor en de result-iterator) en leent al het andere. Elke Recognize-aanroep maakt zijn eigen set aan en geeft die vrij in een finally-blok in vaste volgorde: eerst TessResultIteratorDelete, dan TessMonitorDelete, dan TessBaseAPIDelete. Het vrijgeven van de engine-interface roept FreeLibrary aan op de DLL

HotPDF Tesseract DLL-objecteigendom per Recognize-aanroep: de result-iterator, monitor en API-instantie worden in die volgorde binnen finally vrijgegeven, de page iterator vanuit TessResultIteratorGetPageIterator is een geleende view die nooit mag worden vrijgegeven, en GetUTF8Text-strings worden gekopieerd en via TessDeleteText teruggegeven
Drie objecten in eigendom, al het restant geleend: geef vrij in de vaste volgorde, geef de page iterator nooit dubbel vrij, en meng nooit allocators
  • TessResultIteratorGetPageIterator geeft een view op de result-iterator terug in plaats van een nieuw object. De adapter gebruikt hem voor TessPageIteratorBoundingBox en TessPageIteratorBaseline en geeft hem nooit vrij; hem ook nog verwijderen zou hetzelfde geheugen twee keer vrijgeven
  • TessResultIteratorGetUTF8Text geeft een string terug die door de eigen runtime van de DLL is gealloceerd. De adapter decodeert hem en geeft hem via TessDeleteText terug in een finally-blok, want FreeMem in Pascal zou hem op de verkeerde heap vrijgeven
  • Woordtekst gaat eerst door strikte UTF-8-decodering met een lengtecontrole. Een woord met stuurtekens, misvormde UTF-8, een vak buiten de afbeelding, een omgekeerde rechthoek of een confidence buiten 0–100 laat de aanvraag falen; de adapter plakt het niet even bij
  • Tekst per aanvraag is afgekapt op 1.048.576 UTF-16-code-eenheden, en het woordaantal moet in het budget passen dat ApplyLoadedOCRTextLayer per pagina naar beneden doorgeeft

De confidence komt binnen als 0–100 en wordt geschaald naar 0–1, dus THPDFOCRTextLayerOptions.MinimumConfidence betekent voor elke engine hetzelfde. Meldt Tesseract een baseline, dan worden beide eindpunten doorgegeven, en voor een voornamelijk verticaal woord wordt de vakbreedte als teksthoogte gebruikt. Zonder baseline valt de tekstlaag-pipeline terug op zijn geometrische schatting, precies zoals bij TSV-invoer

Enum-opties op bereik controleren voordat ze de DLL bereiken

De factory kopieert de ruwe bytes van PageSegMode en EngineMode naar een Integer voordat hij ze op bereik controleert. Een compiler mag aannemen dat een enum-variabele altijd een gedeclareerde waarde bevat, dus een test als Ord(X) > Ord(High(T)) die direct tegen de enum is geschreven kan naar een constante false worden gevouwen. Die ordinalen bereiken de DLL als kale integers: THPDFTesseractPageSegMode volgt Tesseracts paginasegmentatienummering van 0 tot 13 en THPDFTesseractEngineMode zijn engine-modusnummering van 0 tot 3. Een optiesrecord dat met FillChar is leeggemaakt, uit een stream is gelezen of vanuit C++Builder via een integer-cast is gevuld, kan een byte als 200 meedragen, en het valideren van de kopie zet dat bij factorytijd om in een EArgumentException. De factory weigert ook tpsOSDOnly en tpsAutoOnly, die geen woorden teruggeven, en eist osd.traineddata voor tpsAutoOSD en tpsSparseTextOSD

Wat garandeert de recognition-timeout eigenlijk?

De Tesseract-DLL-time-out is coöperatief: HotPDF kan zijn eigen werk stoppen en Tesseract vragen te stoppen, maar hij kan native code niet dwingen terug te keren. De klok begint zodra Recognize begint, dus grijswaardenconversie en modelinitialisatie trekken op hetzelfde budget als de herkenning zelf. De adapter controleert verstreken tijd en het cancellation token elke 64 rijen tijdens de grijswaardenconversie, na initialisatie en vóór elk woord bij het aflopen van de resultaten. Net vóór TessBaseAPIRecognize geeft hij de resterende milliseconden door aan TessMonitorSetDeadlineMSecs

De kloof zit in de native aanroepen zelf. Tesseract raadpleegt zijn monitor alleen tijdens woordherkenning, dus binnen TessBaseAPIInit2 of de paginalay-outanalyse kan een trage modellading of een pathologische lay-out voorbij de deadline draaien voordat de time-out wordt gemeld. Ook de pixel- en uitvoerbudgetten begrenzen het eigen geheugengebruik van de native library niet. Heb je een werker nodig die je zonder meer kunt neerschieten, dan is de procesadapter het gereedschap voor die klus

HotPDF Tesseract DLL-coöperatieve time-outanatomie: de klok begint zodra Recognize begint en dekt grijswaardenconversie, TessBaseAPIInit2 en lay-outanalyse, maar de monitor wordt alleen geraadpleegd tijdens woordherkenning, dus modelladingen en lay-out kunnen voorbij de deadline draaien voordat HotPDF otlsEngineError of otlsCancelled meldt
Een deadline hier is een verzoek, geen garantie: init en lay-outanalyse kunnen lang duren, en een werker die je echt kunt neerschieten heeft de procesadapter nodig

Paginasegmentatie is waar de DLL-adapter zijn geld verdient op lastige invoer. Formulieren, labels en gescande tabellen met verspreide velden herkennen vaak beter met tpsSparseText dan met automatische segmentatie, die kolommen en alinea's probeert samen te stellen die er niet zijn. De time-out hieronder is kort voor een formulierpagina en moet nog steeds de modelinitialisatie dekken

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;  // verspreide velden, geen kolomassemblage
  TessOptions.EngineMode := temLSTMOnly;     // heeft LSTM-modellen in tessdata nodig
  TessOptions.TimeoutMilliseconds := 20000;  // inclusief modelinitialisatie
  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;

Een time-out komt naar boven als otlsEngineError met Tesseract DLL OCR timed out in de diagnostic. Een token dat via THPDFOCRTextLayerOptions.CancellationToken is gezet komt als otlsCancelled naar boven. In beide gevallen herkent ApplyLoadedOCRTextLayer eerst elke geselecteerde pagina voordat de commit begint, dus een mislukking op pagina 40 van 50 laat het geladen document precies zoals het was. tpsSingleLine, tpsSingleBlock en tpsSparseText veranderen alleen de segmentatie; geen van hen rechte een scheve scan

Free Pascal en Lazarus: oude pixels en verdwenen Chinees

Beide Tesseract-factory's werken in Windows Free Pascal- en Lazarus Win32- en Win64-builds zodra het Lazarus-pakket voor de doelarchitectuur is herbouwd; de algemene port staat in HotPDF op Free Pascal en Lazarus Win64. Invoerverwerking is waar FPC zich anders gedraagt

Een LCL-TBitmap die via scanlines wordt beschreven kan zijn raw image bijwerken zonder het Windows-bitmaphandle te verversen, waardoor GetDIBits op dat handle de oude pixels teruggeeft. Het symptoom is verbluffend: tekst die rechtstreeks op een bitmap wordt getekend wordt herkend, een pagina die via scanlines wordt gerenderd levert geen woorden op. Onder FPC leest de DLL-adapter een formaatbewuste snapshot via CreateIntfImage, dat rekening houdt met het pixelformaat en de rijvolgorde van de raw image. De Delphi-build houdt het GetDIBits-pad aan op een privé 24-bit kopie, en geen van beide builds wijzigt de bitmap van de aanroeper

De tesseract.exe-adapter ontmoet een ander probleem. De TStringList van FPC bewaart ANSI-strings, dus het toewijzen van gedecodeerde UTF-8-TSV-tekst aan Lines.Text laat elk Chinees of supplementary-plane-teken vallen dat de systeem-ANSI-codepagina niet kan representeren. Het FPC-pad houdt de TSV als UTF-8-bytes vast, stript de BOM op byteniveau en decodeert elk woord zelfstandig naar UnicodeString. De DLL-adapter ontmoet het probleem nooit, want hij decodeert elk woord rechtstreeks uit de iterator

De Tesseract-DLL-adapter wordt meegeleverd naast de procesadapters en de ingebouwde OCR-engine in HotPDF voor Delphi, C++Builder en Free Pascal. Edities en downloads staan op de pagina van de HotPDF Delphi PDF-component