Articolo tecnico

Tesseract DLL in-process da Delphi: binding della C API

Un timeout di riconoscimento di 5.000 ms su una chiamata Tesseract in-process non significa che la chiamata torni dopo cinque secondi. Con un grande set di modelli multilingua, il thread chiamante può restare dentro la libreria nativa ben oltre quella soglia, perché il monitor di avanzamento che impone la scadenza viene interrogato mentre le parole vengono riconosciute, e sia il caricamento dei modelli sia l'analisi del layout di pagina avvengono prima della prima interrogazione. Quello scarto, un callback di cancel il cui tipo di ritorno C è un singolo byte, e un iteratore che consegna memoria che non dovete mai liberare sono il lavoro vero di legare la C API di Tesseract a Delphi. Il resto è cablaggio

Collegare la DLL Tesseract a un livello di testo HotPDF

HotPDF espone il percorso in-process come HPDFCreateTesseractDLLOCREngine nell'unità HPDFTesseractRecognition. La factory carica una DLL Tesseract che esporta la C API, pilota TessBaseAPIInit2, TessBaseAPIRecognize e l'iteratore dei risultati, e restituisce un IHPDFOCREngine. THotPDF.ApplyLoadedOCRTextLayer prende quel motore e aggiunge un livello di testo Unicode invisibile e ricercabile alle pagine scansionate, la stessa chiamata che attraversa ogni motore OCR di HotPDF

La factory valida per tempo. Il file DLL e la directory tessdata devono esistere. L'identificatore di lingua può contenere solo lettere ASCII, cifre, _ e +, e ogni modello in una combinazione come chi_sim+eng richiede un file .traineddata corrispondente. Tutti i 21 export richiesti devono risolversi prima che vi venga restituito un motore. Gli errori di configurazione sollevano EArgumentException, con export o modello mancante riportato per nome; una DLL che non si carica solleva EOSError con il codice di errore Windows e un suggerimento di controllare architettura e dipendenze

uses
  SysUtils, HPDFDoc, HPDFTesseractRecognition;

procedure MakeSearchable(const SourceFile, TargetFile: string);
var
  Doc: THotPDF;
  Engine: IHPDFOCREngine;
  Options: THPDFOCRTextLayerOptions;
  Info: THPDFOCRTextLayerInfo;
begin
  // Un'applicazione Win64 richiede una DLL a 64 bit; il nome del file dipende dalla vostra build,
  // e le DLL di dipendenza stanno nella stessa cartella
  Engine := HPDFCreateTesseractDLLOCREngine('C:\OCR\Win64\libtesseract.dll',
    'C:\OCR\tessdata', 'chi_sim+eng');   // usa 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
    // Una lista pagine vuota significa tutte; le pagine che portano già testo vengono saltate
    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 imposta PageSegMode a tpsAuto, EngineMode a temDefault, TimeoutMilliseconds a 60.000 e MaxPixels a 16.777.216. Quel budget di pixel morde prima di quanto ci si aspetti. Una pagina US Letter alla default di 300 DPI si renderizza in 2.550 × 3.300 pixel, circa 8,4 milioni, e ci sta. Immaginate di alzare la stessa pagina a 600 DPI: diventa 5.100 × 6.600, circa 33,7 milioni di pixel, e il motore la rifiuta con Invalid Tesseract DLL OCR request or pixel budget prima che Tesseract veda mai l'immagine. O alzate MaxPixels (il tetto è 67.108.864) o restate a 300 DPI, che per il corpo del testo è abbondante; ogni lato è limitato anche a 32.767 pixel

La DLL viene caricata con LoadLibraryEx e i flag di ricerca per la cartella della DLL stessa più le directory sicure di default. Le librerie immagini da cui Tesseract dipende possono quindi stare accanto a lei, e non dovete mai toccare PATH né fidarvi della directory corrente. HotPDF non include né scarica alcun runtime OCR o modello linguistico; a fornirli pensate voi

Cosa cambia la via DLL rispetto a tesseract.exe

Lo stesso recognizer è raggiungibile anche attraverso l'adapter esterno tesseract.exe che scrive una BMP e analizza il TSV. Entrambi gli adapter alimentano una sola pipeline del livello di testo, quindi mappatura delle coordinate, filtro di confidenza e la scrittura tutto-o-nulla si comportano allo stesso modo. Ciò che differisce è come entrano i pixel, come escono le parole, e cosa succede quando il recognizer si comporta male

AspettoAdapter tesseract.exeAdapter DLL Tesseract
FactoryHPDFCreateTesseractOCREngineHPDFCreateTesseractDLLOCREngine
Pixel in ingressoFile BMP in una directory temporanea privataBuffer grayscale a 8 bit in memoria
Parole in uscitaTSV a livello parola, limitato a 64 MiBIteratore dei risultati, UTF-8 per parola
BaselineNon nel TSV; le stima la pipelineTrasmesse da TessPageIteratorBaseline
Segmentazione di pagina e modalità motoreOverload di THPDFTesseractOptions, inviati come --psm e --oemTHPDFTesseractOptions, inviati a TessBaseAPISetPageSegMode e TessBaseAPIInit2
Budget di pixelMaxPixels quando le opzioni vengono passateMaxPixels sempre, più 32.767 pixel per lato
TimeoutDuro: il processo figlio viene terminatoCooperativo: Tesseract deve accorgersene
Isolamento di crash e memoriaProcesso separatoNessuno, condivide il vostro spazio di indirizzi

Un costo resta in mano alla DLL. Ogni chiamata Recognize crea la propria istanza API ed esegue TessBaseAPIInit2, quindi i modelli linguistici vengono inizializzati per ogni pagina. La cache dei file attutisce il ricaricamento, eppure con un grande set di modelli multilingua resta il costo fisso più grande per pagina, e va a carico della scadenza di riconoscimento. Il motore della DLL RapidOCR in-process prende la scelta opposta e tiene i propri modelli ONNX residenti per tutta la vita del motore, mentre i problemi di confine (C ABI, buffer in prestito, lavoro nativo che non potete interrompere) appartengono alla stessa famiglia

E allora quale va in produzione? Per uno strumento desktop o un job a lotti che lavora qualche centinaio di scansioni, la DLL è la scelta migliore: niente avvio di processo per pagina, niente bitmap temporanea su disco, e baseline vere per le righe storte. Un server a lunga permanenza che accetta PDF da sconosciuti dovrebbe restare su tesseract.exe, perché un crash nativo o un'allocazione fuori controllo lì abbatte un processo figlio invece del vostro servizio

Perché Delphi non può copiare la struct monitor di Tesseract?

Delphi non può replicare in sicurezza il monitor di avanzamento di Tesseract, perché ETEXT_DESC porta campi interni che variano tra build di Tesseract. Un record tradotto a mano da un header mette il callback di cancel e la scadenza agli offset che quel header usava. Eseguetelo contro una build diversa e Tesseract legge il vostro puntatore al callback da un campo che ora significa altro, o non trova mai la scadenza, e il riconoscimento semplicemente gira fino in fondo

L'adapter di HotPDF quindi tratta il monitor come un puntatore opaco e lo tocca solo attraverso funzioni esportate: TessMonitorCreate, TessMonitorSetCancelThis, TessMonitorSetCancelFunc, TessMonitorSetDeadlineMSecs e TessMonitorDelete. Lo schizzo qui sotto è codice di binding vostro anziché API HotPDF; le sue dichiarazioni rispecchiano quelle che l'adapter risolve con GetProcAddress

Gestione del monitor della DLL Tesseract in HotPDF: copiare il record ETEXT_DESC dipendente dalla versione mette il callback di cancel e la scadenza a offset sbagliati e fallisce in silenzio, mentre HotPDF tratta il monitor come opaco, pilota TessMonitorCreate, TessMonitorSetCancelThis, TessMonitorSetCancelFunc e TessMonitorSetDeadlineMSecs, e tiene il callback cdecl senza eccezioni
Un puntatore opaco più cinque export sono l'intero contratto; il callback resta un Boolean da un byte che legge solo un flag e un orologio
type
  // C: typedef bool (*TessCancelFunc)(void *cancel_this, int words);
  TTessCancelFunc = function(CancelThis: Pointer; Words: Integer): Boolean; cdecl;
  TTessMonitorCreate = function: Pointer; cdecl;   // ETEXT_DESC*, mai dereferenziato
  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;

  // Stato del job vostro, non un tipo HotPDF
  TOCRJob = record
    CancelRequested: Boolean;
    DeadlineTick: UInt64;
  end;
  POCRJob = ^TOCRJob;

function ShouldCancel(CancelThis: Pointer; Words: Integer): Boolean; cdecl;
begin
  // Gira sullo stack di Tesseract: leggete un flag e l'orologio, non sollevate mai
  Result := (CancelThis = nil) or POCRJob(CancelThis)^.CancelRequested or
    (GetTickCount64 >= POCRJob(CancelThis)^.DeadlineTick);
end;

// Uso, con i puntatori a funzione risolti da GetProcAddress:
//   Monitor := MonitorCreate();
//   try
//     MonitorSetCancelThis(Monitor, @Job);
//     MonitorSetCancelFunc(Monitor, ShouldCancel);
//     MonitorSetDeadlineMSecs(Monitor, RemainingMs);
//     RC := BaseAPIRecognize(API, Monitor);
//   finally
//     MonitorDelete(Monitor);
//   end;

Lo schizzo dichiara il callback come Boolean, un byte sia in Delphi sia in Free Pascal, che corrisponde al bool C in TessCancelFunc. Il BOOL Windows a quattro byte e il LongBool Delphi sembrano intercambiabili e sono un tipo diverso: quando un lato scrive un singolo byte e l'altro ne legge quattro, i tre byte alti sono ciò che il registro conteneva prima, e un false può arrivare come true. TessPageIteratorBoundingBox restituisce un int, dichiarato come Integer sul lato Pascal, quindi leggete il tipo C di ogni valore di ritorno invece di presumere una regola sola per tutta l'API

Il callback inoltre non solleva mai. Un'eccezione Delphi che fa unwinding attraverso i frame C++ di Tesseract è comportamento indefinito. Il callback di HotPDF legge solo il token di cancellazione e un valore monotono GetTickCount64, e l'adapter trasforma l'esito in una diagnostica di cancellazione o timeout dopo che TessBaseAPIRecognize torna. Esegue quel controllo sia che il codice di ritorno nativo sia stato 0 sia che non lo sia stato

Quali puntatori nativi possiede il lato Delphi?

L'adapter DLL Tesseract di HotPDF possiede tre oggetti nativi per richiesta (l'istanza API, il monitor e l'iteratore dei risultati) e prende in prestito tutto il resto. Ogni chiamata Recognize crea il proprio insieme e lo rilascia in un blocco finally in un ordine fisso: TessResultIteratorDelete, poi TessMonitorDelete, poi TessBaseAPIDelete. Rilasciare l'interfaccia del motore chiama FreeLibrary sulla DLL

Proprietà degli oggetti della DLL Tesseract in HotPDF per chiamata Recognize: l'iteratore dei risultati, il monitor e l'istanza API sono posseduti e liberati in quell'ordine dentro finally, l'iteratore di pagina da TessResultIteratorGetPageIterator è una vista in prestito che non deve mai venire liberata, e le stringhe GetUTF8Text vengono copiate e restituite via TessDeleteText
Tre oggetti posseduti, tutto il resto in prestito: libera nell'ordine fisso, non fare mai doppia liberazione dell'iteratore di pagina, e non mescolare mai allocatori
  • TessResultIteratorGetPageIterator restituisce una vista dentro l'iteratore dei risultati anziché un nuovo oggetto. L'adapter la usa per TessPageIteratorBoundingBox e TessPageIteratorBaseline e non la libera mai; cancellarla anche lei rilascerebbe la stessa memoria due volte
  • TessResultIteratorGetUTF8Text restituisce una stringa allocata dal runtime della DLL stessa. L'adapter la decodifica e la restituisce attraverso TessDeleteText in un blocco finally, perché una FreeMem Pascal la rilascerebbe sull'heap sbagliato
  • Il testo delle parole passa per una decodifica UTF-8 strict con prima un controllo di lunghezza. Una parola con caratteri di controllo, UTF-8 malformato, una box fuori dall'immagine, un rettangolo invertito o una confidenza fuori da 0–100 fa fallire la richiesta; l'adapter non la sistema
  • Il testo per richiesta è limitato a 1.048.576 code unit UTF-16, e il conteggio di parole deve stare nel budget che ApplyLoadedOCRTextLayer consegna con ogni pagina

La confidenza arriva come 0–100 e viene scalata a 0–1, quindi THPDFOCRTextLayerOptions.MinimumConfidence significa la stessa cosa per ogni motore. Quando Tesseract riporta una baseline, entrambi gli estremi vengono trasmessi, e per una parola prevalentemente verticale la larghezza della box viene usata come altezza del testo. Senza baseline la pipeline del livello di testo ripiega sulla propria stima geometrica, esattamente come fa per l'input TSV

Controllare l'intervallo delle opzioni enum prima che raggiungano la DLL

La factory copia i byte grezzi di PageSegMode e EngineMode in una Integer prima di controllarne l'intervallo. Un compilatore è autorizzato a presumere che una variabile enum tenga sempre un valore dichiarato, quindi un test come Ord(X) > Ord(High(T)) scritto direttamente sull'enum può venire piegato a una costante false. Quegli ordinali raggiungono la DLL come interi semplici: THPDFTesseractPageSegMode segue la numerazione di segmentazione pagina di Tesseract da 0 a 13 e THPDFTesseractEngineMode la numerazione delle modalità motore da 0 a 3. Un record di opzioni azzerato con FillChar, letto da uno stream, o riempito da C++Builder attraverso un cast a intero può portare un byte come 200, e validare la copia trasforma quello in una EArgumentException al tempo della factory. La factory rifiuta anche tpsOSDOnly e tpsAutoOnly, che non restituiscono parole, e richiede osd.traineddata per tpsAutoOSD e tpsSparseTextOSD

Che cosa garantisce davvero il timeout di riconoscimento?

Il timeout della DLL Tesseract è cooperativo: HotPDF può fermare il proprio lavoro e chiedere a Tesseract di fermarsi, ma non può forzare il codice nativo a tornare. L'orologio parte quando Recognize comincia, quindi la conversione in grayscale e l'inizializzazione dei modelli attingono allo stesso budget del riconoscimento. L'adapter controlla il tempo trascorso e il token di cancellazione ogni 64 righe durante la conversione in grayscale, dopo l'inizializzazione, e prima di ogni parola mentre percorre i risultati. Subito prima di TessBaseAPIRecognize passa i millisecondi rimanenti a TessMonitorSetDeadlineMSecs

Lo scarto siede dentro le chiamate native. Tesseract consulta il proprio monitor solo durante il riconoscimento delle parole, quindi dentro TessBaseAPIInit2 o l'analisi del layout un caricamento lento di modello o un layout patologico può superare la scadenza prima che il timeout venga riportato. I budget di pixel e output non limitano nemmeno l'uso di memoria della libreria nativa stessa. Quando vi serve un worker che potete uccidere sul posto, l'adapter di processo è lo strumento giusto

Anatomia del timeout cooperativo della DLL Tesseract in HotPDF: l'orologio parte quando Recognize comincia e copre la conversione grayscale, TessBaseAPIInit2 e l'analisi del layout, ma il monitor viene consultato solo durante il riconoscimento delle parole, quindi caricamenti di modelli e layout possono sforare prima che HotPDF riporti otlsEngineError o otlsCancelled
Una scadenza qui è una richiesta, non una garanzia: init e analisi del layout possono allungarsi, e un worker che potete davvero uccidere richiede l'adapter di processo

La segmentazione di pagina è dove l'adapter DLL dà i suoi frutti sull'input ostico. Moduli, etichette e tabelle scansionate con campi sparsi spesso riconoscono meglio con tpsSparseText che con la segmentazione automatica, che prova ad assemblare colonne e paragrafi che non ci sono. Il timeout qui sotto è corto per una pagina di modulo e deve comunque coprire l'inizializzazione dei modelli

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;  // campi sparsi, nessun assemblaggio colonne
  TessOptions.EngineMode := temLSTMOnly;     // richiede modelli LSTM in tessdata
  TessOptions.TimeoutMilliseconds := 20000;  // include l'inizializzazione dei modelli
  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 emerge come otlsEngineError con Tesseract DLL OCR timed out nella diagnostica. Un token impostato attraverso THPDFOCRTextLayerOptions.CancellationToken emerge come otlsCancelled. In entrambi i casi ApplyLoadedOCRTextLayer riconosce ogni pagina selezionata prima di iniziare la scrittura, così un fallimento alla pagina 40 di 50 lascia il documento caricato esattamente com'era. tpsSingleLine, tpsSingleBlock e tpsSparseText cambiano solo la segmentazione; nessuna di esse raddrizza una scansione storta

Free Pascal e Lazarus: pixel obsoleti e cinese perduto

Entrambe le factory Tesseract funzionano nelle build Windows Free Pascal e Lazarus Win32 e Win64 una volta che il pacchetto Lazarus viene ricompilato per l'architettura bersaglio; il porting generale è coperto in HotPDF su Free Pascal e Lazarus Win64. La gestione dell'input è dove FPC si comporta diversamente

Una TBitmap LCL scritta attraverso scanline può aggiornare la propria immagine grezza senza rinfrescare l'handle bitmap Windows, così GetDIBits su quell'handle restituisce i vecchi pixel. Il sintomo sconcerta: il testo disegnato direttamente su una bitmap viene riconosciuto, una pagina renderizzata attraverso scanline non produce parole. Sotto FPC l'adapter DLL legge uno snapshot consapevole del formato attraverso CreateIntfImage, che rispetta il formato pixel e l'ordine delle righe dell'immagine grezza. La build Delphi conserva la via GetDIBits su una copia privata a 24 bit, e nessuna delle due build modifica la bitmap del chiamante

L'adapter tesseract.exe incontra un problema diverso. La TStringList di FPC conserva stringhe ANSI, quindi assegnare il testo TSV decodificato UTF-8 a Lines.Text scarta ogni carattere cinese o del piano supplementare che la code page ANSI di sistema non può rappresentare. La via FPC tiene il TSV come byte UTF-8, toglie il BOM a livello di byte e decodifica ogni parola a UnicodeString per conto suo. L'adapter DLL non incontra mai il problema, dato che decodifica ogni parola direttamente dall'iteratore

L'adapter DLL Tesseract viene spedito accanto agli adapter di processo e al motore OCR integrato in HotPDF per Delphi, C++Builder e Free Pascal. Edizioni e download sono elencati nella pagina HotPDF Delphi PDF Component