Article technique

Tesseract DLL in-process en Delphi : binding de l'API C

Un timeout de reconnaissance de 5 000 ms sur un appel Tesseract en process ne signifie pas que l'appel revient après cinq secondes. Avec un grand jeu de modèles multilingues, le thread appelant peut rester dans la bibliothèque native bien au-delà de ce repère, parce que le moniteur de progression qui fait respecter l'échéance est interrogé pendant la reconnaissance des mots, et que le chargement des modèles et l'analyse de la mise en page ont tous deux lieu avant la première interrogation. Cet écart, un callback d'annulation dont le type de retour C tient sur un octet, et un itérateur qui distribue de la mémoire que vous ne devez jamais libérer, constituent le vrai travail du binding de l'API C de Tesseract vers Delphi. Le reste, c'est de la plomberie

Brancher la DLL Tesseract dans une couche de texte HotPDF

HotPDF expose le chemin en process via HPDFCreateTesseractDLLOCREngine dans l'unité HPDFTesseractRecognition. La factory charge une DLL Tesseract qui exporte l'API C, pilote TessBaseAPIInit2, TessBaseAPIRecognize et l'itérateur de résultats, et renvoie un IHPDFOCREngine. THotPDF.ApplyLoadedOCRTextLayer prend ce moteur et ajoute une couche de texte Unicode invisible et cherchable aux pages scannées, le même appel que traverse chaque moteur OCR de HotPDF

La factory valide tôt. Le fichier DLL et le répertoire tessdata doivent exister. L'identifiant de langue ne peut contenir que des lettres ASCII, des chiffres, _ et +, et chaque modèle d'une combinaison comme chi_sim+eng a besoin de son fichier .traineddata correspondant. Les 21 exports requis doivent tous se résoudre avant que vous ne receviez un moteur. Les erreurs de configuration lèvent EArgumentException, avec l'export ou le modèle manquant signalé par son nom ; une DLL qui refuse de se charger lève EOSError portant le code d'erreur Windows et une invite à vérifier l'architecture et les dépendances

uses
  SysUtils, HPDFDoc, HPDFTesseractRecognition;

procedure MakeSearchable(const SourceFile, TargetFile: string);
var
  Doc: THotPDF;
  Engine: IHPDFOCREngine;
  Options: THPDFOCRTextLayerOptions;
  Info: THPDFOCRTextLayerInfo;
begin
  // Une application Win64 a besoin d'une DLL 64 bits ; le nom de fichier dépend de votre build,
  // et ses DLL de dépendances vont dans le même dossier
  Engine := HPDFCreateTesseractDLLOCREngine('C:\OCR\Win64\libtesseract.dll',
    'C:\OCR\tessdata', 'chi_sim+eng');   // utilise 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
    // Une liste de pages vide signifie toutes les pages ; les pages portant déjà du texte sont sautées
    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 règle PageSegMode sur tpsAuto, EngineMode sur temDefault, TimeoutMilliseconds sur 60 000 et MaxPixels sur 16 777 216. Ce budget de pixels mord plus tôt qu'on ne le croit. Une page US Letter aux 300 DPI par défaut se rend en 2 550 × 3 300 pixels, environ 8,4 millions, et passe. Supposez que vous montiez la même page à 600 DPI : elle devient 5 100 × 6 600, à peu près 33,7 millions de pixels, et le moteur la refuse avec Invalid Tesseract DLL OCR request or pixel budget avant même que Tesseract ne voie l'image. Montez MaxPixels (le plafond est 67 108 864) ou restez à 300 DPI, ce qui suffit largement au texte courant ; chaque côté est aussi plafonné à 32 767 pixels

La DLL est chargée avec LoadLibraryEx et les flags de recherche pour le propre dossier de la DLL plus les répertoires sûrs par défaut. Les bibliothèques d'images dont Tesseract dépend peuvent donc reposer à côté d'elle, et vous n'avez jamais à toucher PATH ni à compter sur le répertoire courant. HotPDF ne livre ni ne télécharge de runtime OCR ni aucun modèle de langue ; vous provisionnez les deux

Ce que le chemin DLL change face à tesseract.exe

Le même reconnaisseur est aussi accessible par l'adaptateur tesseract.exe externe qui écrit un BMP et analyse du TSV. Les deux adaptateurs alimentent un seul pipeline de couche de texte, si bien que la correspondance de coordonnées, le filtrage par confiance et le commit tout-ou-rien se comportent à l'identique. Ce qui change, c'est la façon dont les pixels entrent, dont les mots sortent, et ce qui arrive quand le reconnaisseur se comporte mal

AspectAdaptateur tesseract.exeAdaptateur DLL Tesseract
FactoryHPDFCreateTesseractOCREngineHPDFCreateTesseractDLLOCREngine
Pixels en entréeFichier BMP dans un répertoire temporaire privéTampon en niveaux de gris 8 bits en mémoire
Mots en sortieTSV au niveau du mot, plafonné à 64 MioItérateur de résultats, UTF-8 par mot
Lignes de baseAbsentes du TSV ; le pipeline les estimeTransmises par TessPageIteratorBaseline
Segmentation de page et mode moteurSurcharge de THPDFTesseractOptions, envoyée en --psm et --oemTHPDFTesseractOptions, envoyée à TessBaseAPISetPageSegMode et TessBaseAPIInit2
Budget de pixelsMaxPixels quand des options sont passéesMaxPixels toujours, plus 32 767 pixels par côté
TimeoutDur : le processus enfant est terminéCoopératif : Tesseract doit s'en apercevoir
Isolation crash et mémoireProcessus séparéAucune, il partage votre espace d'adressage

Un coût reste attaché à la DLL. Chaque appel Recognize crée sa propre instance d'API et exécute TessBaseAPIInit2, si bien que les modèles de langue sont initialisés pour chaque page. Le cache de fichiers atténue la recharge, mais avec un grand jeu de modèles multilingues cela reste le coût fixe le plus lourd par page, et c'est facturé à l'échéance de reconnaissance. Le moteur DLL RapidOCR en process fait le choix opposé et garde ses modèles ONNX résidents pour la durée de vie du moteur, tandis que les problèmes de frontière (ABI C, tampons empruntés, travail natif impossible à interrompre) appartiennent à la même famille

Alors, lequel part en production ? Pour un outil de bureau ou un job par lots qui travaille quelques centaines de scans, la DLL est le meilleur choix : pas de lancement de processus par page, pas de bitmap temporaire sur disque, et de vraies lignes de base pour les lignes inclinées. Un serveur de longue durée qui accepte des PDF d'inconnus doit rester sur tesseract.exe, parce qu'un crash natif ou une allocation folle y emporte un processus enfant au lieu de votre service

Pourquoi Delphi ne peut-il pas copier la structure moniteur de Tesseract ?

Delphi ne peut pas refléter sûrement le moniteur de progression de Tesseract, parce que ETEXT_DESC transporte des champs internes qui varient selon les builds de Tesseract. Un enregistrement traduit à la main depuis un en-tête donné place le callback d'annulation et l'échéance aux offsets que cet en-tête utilisait. Exécutez-le contre un build différent et Tesseract lit votre pointeur de callback dans un champ qui signifie désormais autre chose, ou ne trouve jamais l'échéance, et la reconnaissance tourne simplement jusqu'au bout

L'adaptateur HotPDF traite donc le moniteur comme un pointeur opaque et ne le touche qu'à travers des fonctions exportées : TessMonitorCreate, TessMonitorSetCancelThis, TessMonitorSetCancelFunc, TessMonitorSetDeadlineMSecs et TessMonitorDelete. Le croquis ci-dessous est votre propre code de binding plutôt qu'une API HotPDF ; ses déclarations correspondent à celles que l'adaptateur résout avec GetProcAddress

Gestion du moniteur par la DLL Tesseract de HotPDF : copier l'enregistrement ETEXT_DESC dépendant de la version place le callback d'annulation et l'échéance à de mauvais offsets et échoue en silence, tandis que HotPDF traite le moniteur comme opaque, pilote TessMonitorCreate, TessMonitorSetCancelThis, TessMonitorSetCancelFunc et TessMonitorSetDeadlineMSecs, et garde le callback cdecl sans exception
Un pointeur opaque plus cinq exports, voilà tout le contrat ; le callback reste un Boolean d'un octet qui ne lit qu'un flag et une horloge
type
  // C: typedef bool (*TessCancelFunc)(void *cancel_this, int words);
  TTessCancelFunc = function(CancelThis: Pointer; Words: Integer): Boolean; cdecl;
  TTessMonitorCreate = function: Pointer; cdecl;   // ETEXT_DESC*, jamais déréférencé
  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;

  // Votre propre état de job, pas un type HotPDF
  TOCRJob = record
    CancelRequested: Boolean;
    DeadlineTick: UInt64;
  end;
  POCRJob = ^TOCRJob;

function ShouldCancel(CancelThis: Pointer; Words: Integer): Boolean; cdecl;
begin
  // Tourne sur la pile de Tesseract : lisez un flag et l'horloge, ne levez jamais
  Result := (CancelThis = nil) or POCRJob(CancelThis)^.CancelRequested or
    (GetTickCount64 >= POCRJob(CancelThis)^.DeadlineTick);
end;

// Utilisation, avec les pointeurs de fonction résolus par GetProcAddress :
//   Monitor := MonitorCreate();
//   try
//     MonitorSetCancelThis(Monitor, @Job);
//     MonitorSetCancelFunc(Monitor, ShouldCancel);
//     MonitorSetDeadlineMSecs(Monitor, RemainingMs);
//     RC := BaseAPIRecognize(API, Monitor);
//   finally
//     MonitorDelete(Monitor);
//   end;

Le croquis type le callback comme Boolean, un octet aussi bien en Delphi qu'en Free Pascal, ce qui correspond au bool C de TessCancelFunc. Le BOOL Windows à quatre octets et le LongBool Delphi paraissent interchangeables et sont un autre type : quand un côté écrit un seul octet et que l'autre en lit quatre, les trois octets hauts valent ce que le registre contenait avant, et un faux peut arriver comme vrai. TessPageIteratorBoundingBox renvoie un int, déclaré Integer côté Pascal, alors lisez le type C de chaque valeur de retour au lieu de supposer une règle unique pour toute l'API

Le callback ne lève jamais non plus. Une exception Delphi se déroulant à travers les frames C++ de Tesseract est un comportement indéfini. Le callback HotPDF ne lit que le token d'annulation et une valeur monotone GetTickCount64, et l'adaptateur transforme le résultat en diagnostic d'annulation ou de timeout après le retour de TessBaseAPIRecognize. Il fait cette vérification que le code de retour natif soit 0 ou non

Quels pointeurs natifs le côté Delphi possède-t-il ?

L'adaptateur Tesseract DLL de HotPDF possède trois objets natifs par requête (l'instance d'API, le moniteur et l'itérateur de résultats) et emprunte tout le reste. Chaque appel Recognize crée son propre jeu et le libère dans un bloc finally dans un ordre fixe : TessResultIteratorDelete, puis TessMonitorDelete, puis TessBaseAPIDelete. Libérer l'interface du moteur appelle FreeLibrary sur la DLL

Propriété des objets natifs par appel Recognize dans la DLL Tesseract de HotPDF : l'itérateur de résultats, le moniteur et l'instance d'API sont possédés et libérés dans cet ordre dans un finally, l'itérateur de page de TessResultIteratorGetPageIterator est une vue empruntée à ne jamais libérer, et les chaînes GetUTF8Text sont copiées et restituées via TessDeleteText
Trois objets possédés, tout le reste emprunté : libérez dans l'ordre fixe, ne libérez jamais deux fois l'itérateur de page, et ne mélangez jamais les allocateurs
  • TessResultIteratorGetPageIterator renvoie une vue sur l'itérateur de résultats plutôt qu'un nouvel objet. L'adaptateur l'utilise pour TessPageIteratorBoundingBox et TessPageIteratorBaseline et ne le libère jamais ; le supprimer aussi libérerait la même mémoire deux fois
  • TessResultIteratorGetUTF8Text renvoie une chaîne allouée par le runtime propre de la DLL. L'adaptateur la décode et la rend via TessDeleteText dans un bloc finally, parce que FreeMem Pascal la libérerait sur le mauvais tas
  • Le texte des mots passe par un décodage UTF-8 strict avec contrôle de longueur d'abord. Un mot avec caractères de contrôle, UTF-8 malformé, une boîte hors de l'image, un rectangle inversé ou une confiance hors de 0–100 fait échouer la requête ; l'adaptateur ne rafistole pas
  • Le texte par requête est plafonné à 1 048 576 unités de code UTF-16, et le compte de mots doit tenir dans le budget que ApplyLoadedOCRTextLayer transmet avec chaque page

La confiance arrive en 0–100 et est ramenée à 0–1, si bien que THPDFOCRTextLayerOptions.MinimumConfidence signifie la même chose pour chaque moteur. Quand Tesseract rapporte une ligne de base, les deux points d'extrémité sont transmis, et pour un mot essentiellement vertical la largeur de boîte sert de hauteur de texte. Sans ligne de base, le pipeline de couche de texte retombe sur son estimation géométrique, exactement comme pour une entrée TSV

Contrôle des bornes des options d'énumération avant qu'elles n'atteignent la DLL

La factory copie les octets bruts de PageSegMode et EngineMode dans un Integer avant d'en vérifier les bornes. Un compilateur est en droit de supposer qu'une variable d'énumération ne contient toujours qu'une valeur déclarée, si bien qu'un test comme Ord(X) > Ord(High(T)) écrit directement contre l'énumération peut être replié en faux constant. Ces ordinaux atteignent la DLL comme de simples entiers : THPDFTesseractPageSegMode suit la numérotation de segmentation de page de Tesseract de 0 à 13 et THPDFTesseractEngineMode sa numérotation de mode moteur de 0 à 3. Un enregistrement d'options effacé avec FillChar, lu depuis un flux, ou rempli depuis C++Builder via un cast entier peut porter un octet comme 200, et la validation de la copie transforme cela en EArgumentException au moment de la factory. La factory rejette aussi tpsOSDOnly et tpsAutoOnly, qui ne renvoient aucun mot, et exige osd.traineddata pour tpsAutoOSD et tpsSparseTextOSD

Que garantit réellement le timeout de reconnaissance ?

Le timeout de la DLL Tesseract est coopératif : HotPDF peut arrêter son propre travail et demander à Tesseract de s'arrêter, mais il ne peut pas forcer du code natif à revenir. L'horloge démarre au début de Recognize, si bien que la conversion en niveaux de gris et l'initialisation des modèles puisent dans le même budget que la reconnaissance elle-même. L'adaptateur vérifie le temps écoulé et le token d'annulation toutes les 64 lignes pendant la conversion en niveaux de gris, après l'initialisation, et avant chaque mot en parcourant les résultats. Juste avant TessBaseAPIRecognize, il passe les millisecondes restantes à TessMonitorSetDeadlineMSecs

L'écart se situe à l'intérieur des appels natifs. Tesseract ne consulte son moniteur que pendant la reconnaissance des mots, si bien qu'à l'intérieur de TessBaseAPIInit2 ou de l'analyse de mise en page, un chargement de modèle lent ou une mise en page pathologique peut dépasser l'échéance avant que le timeout ne soit signalé. Les budgets de pixels et de sortie ne plafonnent pas non plus la consommation mémoire propre de la bibliothèque native. Quand il vous faut un worker que l'on peut tuer carrément, l'adaptateur process est l'outil pour cela

Anatomie du timeout coopératif de la DLL Tesseract HotPDF : l'horloge démarre au début de Recognize et couvre la conversion en niveaux de gris, TessBaseAPIInit2 et l'analyse de mise en page, mais le moniteur n'est consulté que pendant la reconnaissance des mots, si bien que chargements de modèles et mise en page peuvent dépasser avant que HotPDF ne signale otlsEngineError ou otlsCancelled
Une échéance ici est une demande, pas une garantie : initialisation et analyse de mise en page peuvent durer, et un worker que l'on peut vraiment tuer exige l'adaptateur process

La segmentation de page est là où l'adaptateur DLL paie sur les entrées difficiles. Formulaires, étiquettes et tables scannées aux champs dispersés se reconnaissent souvent mieux avec tpsSparseText qu'avec la segmentation automatique, qui essaie d'assembler des colonnes et des paragraphes qui n'existent pas. Le timeout ci-dessous est court pour une page de formulaire et doit quand même couvrir l'initialisation des modèles

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;  // champs dispersés, pas d'assemblage de colonnes
  TessOptions.EngineMode := temLSTMOnly;     // requiert les modèles LSTM dans tessdata
  TessOptions.TimeoutMilliseconds := 20000;  // inclut l'initialisation des modèles
  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;

Un timeout se manifeste en otlsEngineError avec Tesseract DLL OCR timed out dans le diagnostic. Un token posé via THPDFOCRTextLayerOptions.CancellationToken se manifeste en otlsCancelled. Dans les deux cas, ApplyLoadedOCRTextLayer reconnaît chaque page sélectionnée avant de commencer le commit, si bien qu'un échec à la page 40 sur 50 laisse le document chargé exactement tel qu'il était. tpsSingleLine, tpsSingleBlock et tpsSparseText ne changent que la segmentation ; aucun ne redresse un scan incliné

Free Pascal et Lazarus : pixels périmés et chinois perdu

Les deux factories Tesseract fonctionnent en Free Pascal Windows et en builds Lazarus Win32 et Win64 une fois le paquet Lazarus reconstruit pour l'architecture cible ; le portage général est couvert dans HotPDF sur Free Pascal et Lazarus Win64. La gestion des entrées est là où FPC se comporte différemment

Un TBitmap LCL écrit par scanlines peut mettre à jour son image brute sans rafraîchir le handle de bitmap Windows, si bien que GetDIBits sur ce handle renvoie les vieux pixels. Le symptôme déroute : du texte dessiné directement sur un bitmap est reconnu, une page rendue par scanlines ne donne aucun mot. Sous FPC, l'adaptateur DLL lit un instantané conscient du format via CreateIntfImage, qui respecte le format de pixels et l'ordre des lignes de l'image brute. Le build Delphi garde le chemin GetDIBits sur une copie privée 24 bits, et aucun build ne modifie le bitmap de l'appelant

L'adaptateur tesseract.exe rencontre un problème différent. Le TStringList de FPC stocke des chaînes ANSI, si bien qu'affecter du texte TSV UTF-8 décodé à Lines.Text abandonne chaque caractère chinois ou du plan supplémentaire que la page de codes ANSI du système ne peut représenter. Le chemin FPC garde le TSV en octets UTF-8, retire la BOM au niveau octet et décode chaque mot vers UnicodeString par ses propres moyens. L'adaptateur DLL ne rencontre jamais le problème, puisqu'il décode chaque mot directement depuis l'itérateur

L'adaptateur Tesseract DLL se livre aux côtés des adaptateurs process et du moteur OCR intégré dans HotPDF pour Delphi, C++Builder et Free Pascal. Les éditions et téléchargements sont listés sur la page du composant HotPDF Delphi PDF