Adapter RapidOCR con DLL nativa

HPDFRapidOCRRecognition espone un IHPDFOCREngine in-process supportato da HotPDFRapidOCR.dll, con la stessa API pubblica nelle build Delphi, C++Builder e FPC/Lazarus Win32 e Win64 per Windows

La DLL esegue l'inferenza ONNX su CPU direttamente sugli snapshot di memoria e mantiene i modelli inizializzati finché l'interfaccia dell'engine non viene rilasciata; il deployment a runtime consiste nella DLL nativa corrispondente e in modelli e dizionario locali compatibili

L'adapter a processo Python esistente resta disponibile con i suoi overload di factory originali

Factory e opzioni

function HPDFCreateRapidOCRDLLOCREngine(const LibraryPath,
  ModelDirectory: string): IHPDFOCREngine; overload;
function HPDFCreateRapidOCRDLLOCREngine(const LibraryPath,
  ModelDirectory: string; const Options: THPDFRapidOCRDLLOptions): IHPDFOCREngine; overload;

THPDFRapidOCRDLLOptions = record
  DetectionModel: string;
  RecognitionModel: string;
  ClassificationModel: string;
  CharacterDictionary: string;
  UseAngleClassifier: Boolean;
  RightToLeft: Boolean;
  Threads: Integer;
  MaxPixels: Integer;
  TimeoutMilliseconds: Cardinal;
  class function Default: THPDFRapidOCRDLLOptions; static;
  class function ForLanguage(const Language: string): THPDFRapidOCRDLLOptions; static;
end;

Inizializza le opzioni con THPDFRapidOCRDLLOptions.Default; i default usano i seguenti file locali

I nomi di file relativi si risolvono rispetto a ModelDirectory; i percorsi assoluti possono selezionare file provisionati separatamente

La factory controlla disponibilità dei file, opzioni, export richiesti e versione ABI prima di inizializzare i modelli; una configurazione non valida solleva EArgumentException, i fallimenti di caricamento dei modelli sollevano EInvalidOperation con una diagnostica nativa

L'inizializzazione dei modelli avviene nella factory ed è fuori dalla deadline di riconoscimento; i conteggi di classe del dizionario devono corrispondere al modello di riconoscimento, e conteggi identici da soli non garantiscono che ordine dei caratteri o preprocessing siano compatibili

La pipeline fornita usa rilevamento DB con un lato massimo di rilevamento di 1.024 pixel e 50 pixel di padding bianco; il recognizer accetta modelli NCHW compatibili con altezza di input fissa di 32 o 48 e usa 48 per un'altezza dinamica

Il riconoscimento preserva l'aspect ratio per i modelli a larghezza dinamica e normalizza gli input con padding a una larghezza minima di 320; un modello a larghezza fissa limita la larghezza del crop ridimensionato, il che può comprimere una lunga riga di testo

La classificazione dell'angolo preserva l'aspect ratio del crop entro la larghezza di input del modello e riempie i pixel inutilizzati con zeri normalizzati; un crop ruota di 180 gradi solo quando il punteggio upside-down supera 0,9, così le previsioni deboli di direzione non capovolgono testo corto

Il dizionario deve corrispondere all'ordine dei caratteri del modello e al numero di classi di output; le terminazioni di riga CRLF del dizionario sono accettate, ma un BOM UTF-8 viene rifiutato

Quando il modello incorpora i metadati dei caratteri, la factory verifica anche ogni voce del dizionario e il suo ordine; la sola dimensione del dizionario non basta

Cinese, russo e lingue comuni

THPDFRapidOCRDLLOptions.ForLanguage seleziona un modello di riconoscimento e il dizionario corrispondente sotto la directory locale dei modelli mantenendo i default condivisi di detector, classifier, thread, pixel e timeout

Il metodo accetta alias di lingua case-insensitive, converte gli underscore in trattini e rimuove gli spazi ai bordi; un tag vuoto o non supportato solleva EArgumentException prima di caricare i modelli

Ogni profilo usa <profile>/recognition.onnx e <profile>/dictionary.txt; i nomi dei profili sono accettati direttamente, e gli alias regionali riconosciuti sono definiti esplicitamente anziché dedotti da un prefisso arbitrario

Installa prima del deployment i set di modelli selezionati con l'helper di provisioning con hash SHA256 pinnati

& tools/Install-RapidOCRModels.ps1 `
  -Destination C:/OCR/models `
  -Language ch,chinese_cht,en,latin,japan,korean,cyrillic,arabic,devanagari

-Language All installa tutti e nove i profili; -SkipClassifier omette il classifier opzionale, nel qual caso imposta UseAngleClassifier := False quando crei un engine

L'helper verifica gli hash SHA256 pinnati e installa un detector e un classifier multilingua condivisi sotto i nomi radice usati da Default; il riconoscimento gira offline e non scarica mai automaticamente i modelli mancanti

Scegli la lingua dell'engine per ogni pagina o regione; un solo engine non rileva automaticamente la lingua né combina recognizer separati per script diversi

I pacchetti pinnati usano modelli PP-OCRv3 e PP-OCRv4 compatibili; l'accuratezza del riconoscimento dipende da modello, font, risoluzione e crop, e il modello latino può confondere accenti come ñ anche con input pulito

I modelli PP-OCRv5 più recenti possono richiedere un ONNX Runtime più nuovo delle librerie statiche usate per compilare la DLL; un formato di modello non supportato fallisce l'inizializzazione con una diagnostica

I modelli di rilevamento devono accettare un singolo tensore immagine float32 e produrre una mappa di probabilità float32 con shape [1, 1, H, W] alla risoluzione di input ridimensionata; tipi, dimensioni o valori non finiti incompatibili, o probabilità fuori da [0, 1] per più di quattro epsilon macchina float32 falliscono con una diagnostica prima che i risultati del rilevamento vengano usati

I piccoli errori di arrotondamento della sigmoid entro quella tolleranza vengono limitati a [0, 1] prima della soglia e del punteggio dei contorni, così i modelli validi conservano il loro comportamento di rilevamento normale

Esempio cinese

uses SysUtils, HPDFDoc, HPDFRapidOCRRecognition;

procedure AddNativeRapidOCRText(PDF: THotPDF);
var
  Engine: IHPDFOCREngine;
  Models: THPDFRapidOCRDLLOptions;
  Layer: THPDFOCRTextLayerOptions;
  Info: THPDFOCRTextLayerInfo;
begin
  Models := THPDFRapidOCRDLLOptions.ForLanguage('zh-CN');
  Models.UseAngleClassifier := False;
  Engine := HPDFCreateRapidOCRDLLOCREngine(
    'C:\OCR\Win64\HotPDFRapidOCR.dll', 'C:\OCR\models', Models);
  Layer := THPDFOCRTextLayerOptions.Default;
  if not PDF.ApplyLoadedOCRTextLayer([0], Engine, Layer, Info) then
    raise Exception.Create('Native RapidOCR text layer was not added');
end;

Conserva l'interfaccia dell'engine tra le richieste per riusare i suoi modelli; usa una DLL corrispondente all'architettura dell'applicazione chiamante e fornisci le sue dipendenze accanto ad essa o nelle directory standard del loader di Windows

Esempio russo

procedure AddRussianRapidOCRText(PDF: THotPDF);
var
  Engine: IHPDFOCREngine;
  Models: THPDFRapidOCRDLLOptions;
  Layer: THPDFOCRTextLayerOptions;
  Info: THPDFOCRTextLayerInfo;
begin
  Models := THPDFRapidOCRDLLOptions.ForLanguage('ru-RU');
  Engine := HPDFCreateRapidOCRDLLOCREngine(
    'C:\OCR\Win64\HotPDFRapidOCR.dll', 'C:\OCR\models', Models);
  Layer := THPDFOCRTextLayerOptions.Default;
  if not PDF.ApplyLoadedOCRTextLayer([0], Engine, Layer, Info) then
    raise Exception.Create('Russian RapidOCR text layer was not added');
end;

ru, ru-RU e rus selezionano lo stesso modello di riconoscimento e dizionario cyrillic

Risultati e ciclo di vita

L'adapter copia la bitmap corrente in uno snapshot BGR top-down indipendente; controlla dimensioni e budget di pixel prima dell'allocazione e non modifica la bitmap presa in prestito

La pipeline nativa emette un risultato per ogni riga di testo riconosciuta, con bounds in pixel dell'immagine originale e confidenza media dei caratteri; ogni riga consuma uno slot di MaxWords e non viene fornita nessuna baseline nativa

I box rilevati seguono l'ordine di lettura delle righe orizzontali, da sinistra a destra per default e da destra a sinistra quando RightToLeft è abilitato; il preset arabo abilita questa opzione

La classificazione dell'angolo corregge i singoli crop di testo; non determina l'orientamento dell'intera pagina né riordina in ordine di lettura logico i box di rilevamento separati di una pagina capovolta

Il testo riconosciuto resta nell'ordine Unicode logico del modello; l'adapter non inverte automaticamente le stringhe arabe né applica lo shaping bidirezionale

L'adapter valida UTF-8, caratteri di controllo Unicode, bounds, confidenza e il limite MaxTextCodeUnits della richiesta, con un tetto rigido del testo di 1.048.576 unità UTF-16; i caratteri supplementari consumano due unità

Una pagina vuota va a buon fine con un array di risultati vuoto; un fallimento cancella i risultati parziali, e la pubblicazione del PDF cercabile conserva il comportamento esistente di transazione atomica delle pagine

Le chiamate sullo stesso engine sono serializzate; l'attesa del lock dell'engine controlla cancellazione e deadline di riconoscimento ogni 25 millisecondi

I callback nativi controllano cancellazione e deadline prima e dopo rilevamento, classificazione e ogni riga riconosciuta; una singola chiamata di inferenza ONNX non può essere interrotta forzatamente, quindi la cancellazione può tornare dopo che la fase corrente è finita

I limiti di input e testo vincolano le allocazioni dell'adapter e l'output accettato, ma non impongono un tetto rigido alla memoria di modelli, rilevamento, crop o inferenza

Compilazione e ABI

Native/RapidOCR contiene il bridge C++, il recognizer di modelli compatibile, l'header C versionato, la definizione degli export e il progetto CMake; provisiona sorgenti di rete CPU compatibili che espongono DbNet, AngleNet e OcrUtils, più le librerie ONNX Runtime e OpenCV corrispondenti

Usa MSVC per Windows con C++17, un Windows SDK e CMake 3.20 o successivo; la build predefinita usa la CRT release statica, che deve corrispondere alle librerie provisionate

& tools/Build-HotPDFRapidOCR.ps1 `
  -NativeSourceDirectory C:/OCR/native-sources `
  -OnnxRuntimeDirectory C:/OCR/onnxruntime/windows-x64 `
  -OpenCVDirectory C:/OCR/opencv/x64/vc16/staticlib `
  -Platform Win64

OnnxRuntimeDirectory deve contenere OnnxRuntimeConfig.cmake, e OpenCVDirectory deve puntare alla configurazione di libreria specifica per architettura; seleziona Win32 e librerie x86 corrispondenti per una DLL a 32 bit

L'helper di build scrive Lib/Native/RapidOCR/<Platform>/HotPDFRapidOCR.dll; -BuildDirectory, -OutputDirectory e -Generator possono cambiare la collocazione della build e il generatore di Visual Studio

Il bridge contiene le eccezioni C++ ed espone la versione ABI 1 attraverso HPDFRapidOCRAbiVersion, HPDFRapidOCRCreate, HPDFRapidOCRRecognize e HPDFRapidOCRDestroy; tutte usano cdecl, valori di stato a 32 bit e lunghezze esplicite in byte UTF-8

La versione ABI 1 definisce anche l'export opzionale HPDFRapidOCRSetReadingDirection; l'adapter lo richiede solo quando RightToLeft è abilitato, quindi le DLL esistenti possono ancora servire richieste da sinistra a destra

I callback prendono in prestito il loro testo solo per la durata della chiamata; l'adapter copia il testo validato prima di restituire, e il distruttore dell'engine distrugge i modelli prima di scaricare la DLL

Validazione

Con il pacchetto Python onnx e una build nativa con BUILD_TESTING, esegui python tools/test_rapidocr_detector.py <build>/Release/NativeDetectorTests.exe per controllare output bianco valido, ranghi di tensore non validi, canali e tipi, dimensioni spaziali non corrispondenti e probabilità non valide attraverso l'ABI della DLL; più percorsi di runner possono validare entrambe le architetture in una sola invocazione

Aggiungi -RapidOCRLanguageModelDirectory e uno o entrambi i parametri della libreria DLL nativa al runner degli adapter Delphi o FPC per validare tutti i preset installati con campioni cinese, russo, giapponese, coreano, lingue latine comuni, arabo e hindi; russo e cinese tradizionale subiscono anche salvataggio del PDF cercabile, ricaricamento, estrazione del testo e confronto dei pixel

I runner degli adapter Delphi e FPC testano il ciclo di vita persistente dei modelli, il layout delle righe BGR, i caratteri Unicode e supplementari, i controlli ABI, i risultati non validi, i budget, la cancellazione cooperativa, l'attesa serializzata del lock e la pulizia

Fornisci -RapidOCRNativeWin32Library, -RapidOCRNativeWin64Library e -RapidOCRNativeModelDirectory a Tests/Delphi/Run-TesseractRecognitionTests.ps1 oppure Tests/Delphi/Run-TesseractFPCRecognitionTests.ps1 per la validazione con modelli reali, pagine vuote, gestione di modelli danneggiati, riconoscimento inglese e cinese e round-trip del PDF cercabile con pixel renderizzati invariati

Vedi Layer di testo OCR cercabili per il rendering delle pagine, la mappatura del testo PDF Unicode, il raggruppamento optional-content e i vincoli di conformità