Article technique

RapidOCR in-process HotPDF : OCR DLL native en Delphi

TerminateThread a l’air du moyen évident d’arrêter un appel OCR qui tourne sur une page scannée depuis plus longtemps que votre interface n’est prête à attendre. La documentation Windows explique pourquoi ce n’en est pas un : si le thread ciblé tient le verrou de tas du processus, ce verrou n’est jamais libéré, et la prochaine allocation sur n’importe quel autre thread peut bloquer pour toujours. Une fois l’OCR dans votre propre processus, le seul arrêt sûr est coopératif, à des points de contrôle entre les étapes d’inférence, et c’est le prix du chargement des modèles ONNX une seule fois en les gardant chauds

L’alternative que la plupart des équipes Delphi essaient d’abord est un processus enfant. Un worker Python par page peut être tué à tout moment, ce qui est séduisant, mais chaque appel démarre un interpréteur, importe son runtime, et charge les modèles de détection et de reconnaissance avant de lire un pixel. Imaginez un job d’archive de 500 pages : ce travail de démarrage s’exécute 500 fois, et le déploiement inclut désormais un environnement Python à côté d’un exécutable natif

Un PDF cherchable depuis des scans avec HPDFCreateRapidOCRDLLOCREngine

HotPDF exécute RapidOCR en process via HPDFCreateRapidOCRDLLOCREngine, déclarée dans l’unité HPDFRapidOCRRecognition. La factory charge HotPDFRapidOCR.dll, initialise une seule fois les modèles ONNX de détection, de classification d’angle optionnelle et de reconnaissance, et renvoie un IHPDFOCREngine. Ce moteur se branche sur THotPDF.ApplyLoadedOCRTextLayer exactement comme les autres moteurs OCR : le document rend chaque page, la DLL exécute l’inférence CPU dessus, et le résultat est validé comme couche de texte Unicode invisible. Pas de Python, pas de processus enfant. L’adaptateur est livré pour les builds Delphi, C++Builder et FPC/Lazarus sous Windows

La validation a lieu dans la factory, avant que toute page ne soit touchée. Chaque fichier modèle et dictionnaire doit se résoudre, HPDFRapidOCRAbiVersion doit renvoyer 1, et les exports requis doivent exister avant que HPDFRapidOCRCreate ne construise les modèles. Les erreurs de configuration lèvent EArgumentException ; un modèle qui refuse de se charger lève EInvalidOperation avec le diagnostic propre de la DLL, par exemple un dictionnaire qui ne correspond pas au modèle de reconnaissance

Séquence de validation de la factory DLL RapidOCR de HotPDF pour HPDFCreateRapidOCRDLLOCREngine : les chemins et fichiers de modèles doivent exister, HPDFRapidOCRAbiVersion doit renvoyer 1, les exports requis doivent se résoudre, et HPDFRapidOCRCreate doit initialiser les modèles, avec EArgumentException ou EInvalidOperation levées tôt avant tout lancement de reconnaissance, la seconde portant le texte de diagnostic natif
la validation est précoce à dessein : les problèmes de configuration lèvent avant toute initialisation de modèle, donc un mauvais chemin ou une mauvaise ABI n’atteint jamais une échéance de reconnaissance
uses
  SysUtils, HPDFTypes, HPDFDoc, HPDFRapidOCRRecognition;

procedure MakeSearchable(const SourceFile, TargetFile: string);
var
  Doc: THotPDF;
  Engine: IHPDFOCREngine;
  Options: THPDFOCRTextLayerOptions;
  Info: THPDFOCRTextLayerInfo;
begin
  // Les modèles se chargent ici, hors de toute échéance de reconnaissance.
  // Les noms relatifs de THPDFRapidOCRDLLOptions.Default se
  // résolvent par rapport au dossier de modèles
  Engine := HPDFCreateRapidOCRDLLOCREngine(
    'C:\OCR\Win64\HotPDFRapidOCR.dll', 'C:\OCR\models');
  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
    // liste de pages vide = toutes les pages ; SkipPagesWithText est vrai par défaut
    if not Doc.ApplyLoadedOCRTextLayer([], Engine, Options, Info) then
      raise Exception.Create(string(Info.Diagnostic));
    Writeln(string(Info.EngineName), ': ', Info.AcceptedWordCount,
      ' lines accepted, ', Info.DroppedWordCount, ' dropped');
    Doc.SaveLoadedDocument(TargetFile);
  finally
    Doc.Free;
  end;
end;

THPDFRapidOCRDLLOptions.Default désigne ch_PP-OCRv3_det_infer.onnx, ch_PP-OCRv3_rec_infer.onnx, ch_ppocr_mobile_v2.0_cls_infer.onnx et ppocr_keys_v1.txt, avec un thread CPU, une limite d’entrée de 16 777 216 pixels et une échéance de 60 000 ms par appel de reconnaissance. Pour les autres scripts, THPDFRapidOCRDLLOptions.ForLanguage garde ces défauts et échange contre <profile>/recognition.onnx plus <profile>/dictionary.txt pour l’un des neuf profils, du chinois traditionnel et du cyrillique à l’arabe et au devanagari. Chaque moteur lit une langue ; choisissez le profil par page ou par document. La raison pour laquelle le modèle et le dictionnaire voyagent toujours en paire est traitée dans les modèles multilingues RapidOCR et les dictionnaires CTC dans HotPDF

Le moteur se déclare comme RapidOCR (native DLL) dans Info.EngineName. Journalisez cette chaîne. Quand le même service fait aussi tourner l’adaptateur process OCR Tesseract externe ou le moteur OCR intégré à appariement de gabarits, c’est le moyen le plus rapide de savoir quel reconnaisseur a produit une page mauvaise

Pourquoi l’ABI C ne parle-t-elle qu’en int32_t et octets UTF-8 ?

La frontière HotPDFRapidOCR.dll utilise des entiers à largeur fixe, des pointeurs bruts et des longueurs en octets explicites, parce que Delphi, C++Builder et Free Pascal ne partagent rien avec MSVC au-delà de la convention d’appel C. Une std::string, un std::vector ou une exception C++ transporte une disposition mémoire et un modèle de déroulement qui appartiennent à un compilateur et à une bibliothèque runtime donnés, et laisser l’un d’eux traverser vers du code Pascal finit en pile corrompue ou en bloc de tas libéré par le mauvais allocateur

La version d’ABI 1 tient en une courte liste de règles. Chaque export est cdecl et renvoie un statut int32_t : 1 pour le succès, 0 pour l’échec. Toute fonction qui peut échouer prend un tampon de diagnostic dont l’appelant est propriétaire et sa taille en octets, et la DLL y écrit un message UTF-8 terminé par NUL et tronqué pour tenir. À l’intérieur de la DLL, chaque corps d’export est dans un try avec à la fois catch (const std::exception &) et catch (...). Une erreur ONNX Runtime, une assertion OpenCV ou un dictionnaire malformé devient statut 0 plus texte

ExportRôleQuand l’adaptateur le résout
HPDFRapidOCRAbiVersionRenvoie 1 ; toute autre valeur est rejetéeJuste après le chargement de la DLL
HPDFRapidOCRCreateCharge les modèles de détection, de classification optionnelle, de reconnaissance et le dictionnaireDans la factory
HPDFRapidOCRRecognizeTraite un bitmap et émet un callback par ligne de texteDans la factory
HPDFRapidOCRDestroyLibère l’instance de modèlesDans la factory
HPDFRapidOCRSetReadingDirectionOrdre de lignes droite à gauche optionnelSeulement quand RightToLeft est activé

L’export de sens de lecture est résolu paresseusement à dessein, si bien qu’une DLL construite sans lui sert quand même toute requête gauche à droite. L’adaptateur charge la bibliothèque avec LoadLibraryEx et des flags de recherche qui couvrent le propre dossier de la DLL plus les répertoires sûrs par défaut ; des dépendances ONNX Runtime ou OpenCV placées à côté de HotPDFRapidOCR.dll se trouvent sans toucher PATH. Les chemins de modèles et de dictionnaires traversent la frontière en UTF-8, et la DLL les convertit avec MultiByteToWideChar en mode strict avant d’ouvrir les fichiers via les API à caractères larges. Un répertoire de modèles sous C:\Users\Łukasz ou un nom d’utilisateur cyrillique s’ouvre normalement

Une règle vit dans les fichiers de build plutôt que dans l’en-tête. La DLL lie ONNX Runtime et OpenCV statiquement, et le projet CMake choisit par défaut la CRT release statique (/MT). Mélangez avec des bibliothèques statiques compilées contre /MD et vous récoltez des erreurs d’édition de liens si vous avez de la chance, deux tas indépendants sinon. Provisionnez des bibliothèques construites pour le même mode CRT que la DLL

Que se passe-t-il entre un TBitmap et une ligne de texte ?

HotPDF remet à la DLL une copie BGR de haut en bas indépendante de la page rendue, et la DLL renvoie un callback par ligne reconnue. Le texte de ce callback est emprunté : le pointeur n’est valable que jusqu’au retour du callback, si bien que l’adaptateur le copie sur place

Côté Delphi, l’instantané vient d’un TBitmap privé forcé en pf24bit et lu avec GetDIBits en utilisant un biHeight négatif. Cela donne des lignes de haut en bas alignées sur quatre octets, et le stride voyage vers la DLL en argument explicite. Côté FPC, l’adaptateur lit via CreateIntfImage. Le bitmap de l’appelant n’est jamais modifié. Les contrôles de taille s’exécutent avant l’allocation de la copie : au plus 32 767 pixels par côté, et pas plus de MaxPixels au total, à 16 777 216 par défaut et montable à 67 108 864

Pipeline DLL RapidOCR de HotPDF du bitmap à la couche de texte : l’adaptateur prend la page en instantané pf24bit BGR de haut en bas, la DLL comble, détecte, ordonne et reconnaît les découpes, livre un callback par ligne avec texte UTF-8 emprunté, boîte et confiance, et l’adaptateur valide chaque ligne avant le commit de la couche de texte
les pixels traversent l’ABI une fois en instantané, les lignes reviennent un callback à la fois, et rien n’atteint la couche cherchable tant que chaque contrôle n’est pas passé

À l’intérieur de la DLL, l’image reçoit une bordure blanche de 50 pixels, les régions de texte sont détectées avec le grand côté réduit à 1 024 pixels au plus, et les boîtes sont triées en lignes horizontales. Avec le classificateur d’angle activé, une découpe n’est tournée de 180 degrés que si le score tête-en-bas dépasse 0,9, ce qui empêche une prédiction faible de retourner des mots courts. Chaque ligne arrive ensuite comme un const char*, un compte d’octets, une boîte entière en pixels de l’image d’origine et la confiance moyenne des caractères. L’adaptateur est strict sur ce qu’il accepte :

  • L’UTF-8 est décodé avec MB_ERR_INVALID_CHARS, si bien qu’une séquence d’octets malformée fait échouer la page au lieu de planter des caractères de remplacement dans une couche cherchable
  • Les caractères de contrôle C0 et C1 sont rejetés ; les lignes ne contenant que des espaces sont sautées
  • La boîte doit tenir dans le bitmap, et la confiance doit être une valeur finie de 0 à 1
  • Le texte compte dans le MaxTextCodeUnits de la requête, avec un plafond dur de 1 048 576 unités UTF-16 par appel ; les caractères hors du plan multilingue de base coûtent deux unités
  • Une exception Pascal à l’intérieur du callback y est attrapée, stockée et transformée en retour 0, ce qui arrête la DLL ; le message stocké devient Info.Diagnostic

Deux de ces détails comptent quand vous réglez la sortie. L’unité est la ligne, pas le mot : chaque ligne prend un emplacement MaxWords, Info.AcceptedWordCount et Info.DroppedWordCount comptent des lignes, et un résultat de recherche met en surbrillance toute la boîte de la ligne. Et MinimumConfidence est comparé à la confiance moyenne des caractères de la ligne, si bien qu’un caractère taché parmi vingt propres fait rarement couler la ligne. Monter le seuil à 0,7 ou 0,8 abandonne des lignes entières, jamais des caractères isolés. Une page vide réussit avec zéro ligne, et tout échec jette les résultats partiels pour que le commit multipage reste tout-ou-rien

Un moteur, une copie des modèles, un appelant à la fois

Chaque moteur DLL RapidOCR possède exactement une instance de modèles pour toute sa durée de vie, et les appels Recognize sur ce moteur sont sérialisés par une section critique. C’est détenir la référence IHPDFOCREngine qui garde les modèles en mémoire, si bien que le travail par lots doit créer le moteur une fois et le réutiliser sur chaque document

procedure OcrBatch(const Files: TStrings; const OutputDir: string);
var
  Models: THPDFRapidOCRDLLOptions;
  Engine: IHPDFOCREngine;
  Doc: THotPDF;
  Options: THPDFOCRTextLayerOptions;
  Info: THPDFOCRTextLayerInfo;
  I: Integer;
begin
  Models := THPDFRapidOCRDLLOptions.ForLanguage('ru-RU');
  Models.UseAngleClassifier := False;    // scans droits : aucun modèle classificateur chargé
  Models.Threads := 4;                   // 1..64, borné aux processeurs actifs
  Models.TimeoutMilliseconds := 120000;  // par appel Recognize, coopératif
  Engine := HPDFCreateRapidOCRDLLOCREngine(
    'C:\OCR\Win64\HotPDFRapidOCR.dll', 'C:\OCR\models', Models);
  Options := THPDFOCRTextLayerOptions.Default;
  for I := 0 to Files.Count - 1 do
  begin
    Doc := THotPDF.Create(nil);
    try
      Doc.AutoLaunch := False;
      if (Doc.LoadFromFile(Files[I]) > 0) and
        Doc.ApplyLoadedOCRTextLayer([], Engine, Options, Info) then
        Doc.SaveLoadedDocument(IncludeTrailingPathDelimiter(OutputDir) +
          ExtractFileName(Files[I]))
      else
        Writeln(Files[I], ': ', string(Info.Diagnostic));
    finally
      Doc.Free;
    end;
  end;
end;  // dernière référence libérée : modèles détruits, puis DLL déchargée

Threads règle à la fois les comptes de threads intra-op et inter-op de chaque session ONNX du moteur, et la DLL le borne au nombre de processeurs actifs. Deux threads partageant un moteur n’exécutent jamais l’inférence en parallèle ; le second attend. Cette attente n’est pas un EnterCriticalSection aveugle. L’adaptateur tente le verrou avec TryEnterCriticalSection, dort 25 ms entre les tentatives, et vérifie à chaque fois le token d’annulation et l’échéance, si bien qu’une requête en file peut toujours être annulée

L’horloge de l’échéance démarre à l’entrée dans Recognize, avant la prise du verrou. Le temps passé en file derrière une autre page compte dans TimeoutMilliseconds. Avec quatre threads workers sur un moteur et une échéance de 60 secondes, la quatrième page peut expirer sans jamais atteindre le modèle. Donnez plutôt à chaque worker son propre moteur. Cela coûte une copie des modèles en mémoire par moteur, et cette mémoire achète des timeouts prévisibles et du parallélisme réel ; partager un seul moteur n’a de sens que quand les requêtes sont assez rares pour ne presque jamais faire la file

Pourquoi un appel OCR natif ne peut-il pas être tué en pleine inférence ?

Un appel RapidOCR natif ne peut pas être tué en pleine inférence parce qu’il tourne sur votre thread, dans votre processus, au milieu d’une session ONNX Runtime qui n’offre aucune API d’interruption pour un Run en cours. L’annulation dans l’adaptateur DLL est coopérative. La DLL appelle un callback d’abandon avant et après la détection, après la classification de chaque découpe, et après chaque ligne reconnue, et s’arrête au premier point de contrôle où le callback renvoie 0. Un Run déjà commencé finit d’abord

Les options forcées sont pires qu’attendre. TerminateThread laisserait le verrou de tas du CRT, le thread pool d’ONNX Runtime et tout état OpenCV dans la condition qui est la leur au moment du tir. Appeler FreeLibrary pendant qu’un appel s’exécute encore décharge du code qui est sur la pile. Ni l’un ni l’autre ne peut être rendu sûr, donc l’adaptateur ne tente jamais. Une échéance expirée revient en otlsEngineError avec un diagnostic de dépassement ; un token annulé revient en otlsCancelled :

// Le token est créé par l’appelant et partagé avec le thread UI,
// qui appelle Token.Cancel quand l’utilisateur appuie sur Stop
function OcrWithStop(Doc: THotPDF; const Engine: IHPDFOCREngine;
  Token: THPDFCancellationToken): Boolean;
var
  Options: THPDFOCRTextLayerOptions;
  Info: THPDFOCRTextLayerInfo;
begin
  Options := THPDFOCRTextLayerOptions.Default;
  Options.CancellationToken := Token;
  Result := Doc.ApplyLoadedOCRTextLayer([], Engine, Options, Info);
  if not Result then
    case Info.Status of
      otlsCancelled:
        // arrêté au prochain point de contrôle d’étape ou de ligne ; document inchangé
        Writeln('Cancelled');
      otlsEngineError:
        // inclut une échéance coopérative expirée et les diagnostics natifs
        Writeln('Engine: ', string(Info.Diagnostic));
      otlsBudgetExceeded:
        // une limite de page, pixel, mot ou contenu dans Options a été atteinte
        Writeln('Budget: ', string(Info.Diagnostic));
    else
      Writeln(string(Info.Diagnostic));
    end;
end;

C’est le vrai compromis entre les adaptateurs process et la DLL en process, et aucun des deux ne gagne toutes les lignes :

Compromis des adaptateurs OCR HotPDF : les adaptateurs process démarrent un worker et chargent les modèles à chaque page mais peuvent être tués et contiennent les crashes, tandis que la DLL RapidOCR en process charge les modèles une fois, ne s’arrête qu’aux points de contrôle coopératifs, partage l’espace d’adressage, et se déploie en DLL avec ses modèles et son dictionnaire
choisissez selon la charge : une appli bureau page par page profite de la DLL chaude, tandis qu’un serveur qui avale des scans non fiables doit payer pour le mur du processus
  • Coût de démarrage : les adaptateurs Tesseract et RapidOCR Python lancent un processus et chargent les modèles pour chaque page ; la DLL charge les modèles une fois par moteur
  • Arrêt : un processus enfant peut être terminé carrément, et le worker Python tourne dans un Job Object kill-on-close pour que tout son arbre de processus parte avec lui ; la DLL s’arrête aux points de contrôle d’étape et de ligne
  • Confinement des pannes : un crash de tesseract.exe fait échouer une page ; une violation d’accès à l’intérieur de la DLL emporte votre processus
  • Déploiement : les adaptateurs process ont besoin d’un programme installé ou d’un environnement Python ; la DLL a besoin d’elle-même, de ses modèles et de son dictionnaire, appariés à l’architecture de l’application
  • Mémoire : un adaptateur process libère tout quand l’enfant se termine ; un moteur DLL garde ses modèles résidents jusqu’à ce que la dernière référence d’interface disparaisse

Choisissez la DLL pour une application bureau interactive qui OCRise une page à la fois et a besoin d’un bouton Stop réactif qui revient en moins d’une étape d’inférence. Pour un serveur qui avale des scans non fiables jour et nuit, payez le coût de démarrage par page et gardez la frontière de processus ; une image forgée qui fait planter un reconnaisseur ne doit coûter qu’une page, et avec un processus enfant c’est le cas

Construire HotPDFRapidOCR.dll et choisir les modèles

HotPDFRapidOCR.dll se construit depuis les sources C++ de Native/RapidOCR avec MSVC, C++17, un Windows SDK et CMake 3.20 ou plus récent. Le helper tools/Build-HotPDFRapidOCR.ps1 prend le répertoire des sources natives, d’ONNX Runtime et d’OpenCV plus -Platform Win32 ou Win64, et écrit le résultat dans Lib/Native/RapidOCR/<Platform>/. Construisez les deux si vous livrez les deux. Une application Delphi 32 bits ne peut pas charger une DLL 64 bits, et les bibliothèques statiques que vous provisionnez doivent correspondre à l’architecture cible ainsi qu’au mode CRT

Les modèles ont leurs propres règles de compatibilité. Le détecteur est un détecteur de texte DB. Le reconnaisseur accepte les modèles CTC en agencement NCHW avec une hauteur d’entrée fixe de 32 ou 48, et utilise 48 quand le modèle déclare une hauteur dynamique. Le format de modèle doit être l’un de ceux que l’ONNX Runtime lié statiquement comprend ; des exports plus récents comme PP-OCRv5 peuvent exiger un runtime plus récent, et un modèle illisible échoue à l’initialisation avec un diagnostic. tools/Install-RapidOCRModels.ps1 installe des packs PP-OCRv3 et PP-OCRv4 vérifiés contre des hash SHA256 épinglés, avec un détecteur et un classificateur partagés sous les noms de fichiers qu’attend Default. Restez sur ces packs à moins de contrôler aussi le build du runtime

Le dictionnaire doit être en UTF-8 sans BOM, dans exactement l’ordre de caractères du modèle, et son compte d’entrées doit correspondre aux classes de sortie du modèle. Les fins de ligne CRLF conviennent. Quand un modèle embarque sa propre liste de caractères en métadonnées, l’initialisation du modèle compare chaque entrée et sa position au fichier dictionnaire, si bien qu’un dictionnaire qui a juste la bonne longueur échoue quand même. La DLL ne télécharge jamais un modèle manquant

HotPDF livre l’adaptateur RapidOCR natif avec les adaptateurs OCR process, le moteur de rendu de pages qui les alimente et l’écrivain de couche de texte Unicode invisible, le tout dans un composant VCL natif unique pour Delphi et C++Builder. Pour les logiciels de capture et d’archivage qui doivent produire du PDF cherchable sur des machines sans Python installé, le composant HotPDF Delphi PDF ne laisse à déployer que la DLL et ses fichiers de modèles