Artículo técnico

OCR in-process con la DLL de Tesseract desde Delphi

Un timeout de reconocimiento de 5,000 ms en una llamada in-process a Tesseract no significa que la llamada regrese a los cinco segundos. Con un set grande de modelos multilingües, el thread llamador puede quedarse dentro de la librería nativa mucho más allá de esa marca, porque el monitor de progreso que hace cumplir el deadline se consulta mientras se reconocen palabras, y la carga de modelos y el análisis de layout de página ocurren ambos antes de la primera consulta. Ese hueco, un callback de cancelación cuyo tipo de retorno C es un solo byte, y un iterador que entrega memoria que usted jamás debe liberar son el trabajo real de enlazar la API C de Tesseract con Delphi. El resto es plomería

Conectar la DLL de Tesseract a una capa de texto de HotPDF

HotPDF expone el camino in-process como HPDFCreateTesseractDLLOCREngine en la unit HPDFTesseractRecognition. La factory carga una DLL de Tesseract que exporta la API C, maneja TessBaseAPIInit2, TessBaseAPIRecognize y el iterador de resultados, y devuelve un IHPDFOCREngine. THotPDF.ApplyLoadedOCRTextLayer toma ese engine y agrega una capa de texto Unicode invisible y buscable a las páginas escaneadas, la misma llamada por la que pasa cada engine OCR de HotPDF

La factory valida con anticipación. El archivo DLL y el directorio tessdata deben existir. El identificador de idioma puede contener solo letras ASCII, dígitos, _ y +, y cada modelo en una combinación como chi_sim+eng necesita su archivo .traineddata correspondiente. Las 21 exportaciones requeridas tienen que resolver antes de recibir un engine. Los errores de configuración lanzan EArgumentException, con la exportación o el modelo faltante reportado por nombre; una DLL que no carga lanza EOSError con el código de error de Windows y la pista de revisar arquitectura y dependencias

uses
  SysUtils, HPDFDoc, HPDFTesseractRecognition;

procedure MakeSearchable(const SourceFile, TargetFile: string);
var
  Doc: THotPDF;
  Engine: IHPDFOCREngine;
  Options: THPDFOCRTextLayerOptions;
  Info: THPDFOCRTextLayerInfo;
begin
  // Una aplicación Win64 necesita una DLL de 64 bits; el nombre del archivo depende
  // de su build, y las DLLs de dependencia van en la misma carpeta
  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 de páginas vacía significa todas; las páginas que ya traen texto se saltan
    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 asigna PageSegMode a tpsAuto, EngineMode a temDefault, TimeoutMilliseconds a 60,000 y MaxPixels a 16,777,216. Ese presupuesto de píxeles muerde antes de lo que uno espera. Una página carta US al default de 300 DPI se renderiza a 2,550 × 3,300 píxeles, unos 8.4 millones, y cabe. Suponga que sube la misma página a 600 DPI: se vuelve 5,100 × 6,600, unos 33.7 millones de píxeles, y el engine la rechaza con Invalid Tesseract DLL OCR request or pixel budget antes de que Tesseract vea la imagen. O sube MaxPixels (el techo es 67,108,864) o se queda en 300 DPI, que es de sobra para texto corrido; cada lado también tiene tope de 32,767 píxeles

La DLL se carga con LoadLibraryEx y los flags de búsqueda para la carpeta propia de la DLL más los directorios seguros por default. Las librerías de imagen de las que depende Tesseract pueden quedar junto a ella, y usted nunca tiene que tocar PATH ni depender del directorio actual. HotPDF no incluye ni descarga un runtime de OCR ni ningún modelo de idioma; ambos los provisiona usted

Qué cambia con la vía DLL comparada con tesseract.exe

El mismo reconocedor también se alcanza vía el adaptador tesseract.exe externo que escribe un BMP y parsea TSV. Ambos adaptadores alimentan un mismo pipeline de capa de texto, así que el mapeo de coordenadas, el filtro de confianza y la confirmación todo-o-nada se comportan igual. Lo que difiere es cómo entran los píxeles, cómo salen las palabras y qué pasa cuando el reconocedor se porta mal

AspectoAdaptador tesseract.exeAdaptador DLL de Tesseract
FactoryHPDFCreateTesseractOCREngineHPDFCreateTesseractDLLOCREngine
Píxeles que entranArchivo BMP en un directorio temporal privadoBuffer de escala de grises de 8 bits en memoria
Palabras que salenTSV por palabra, con tope de 64 MiBIterador de resultados, UTF-8 por palabra
BaselinesNo están en el TSV; el pipeline las estimaPassthrough desde TessPageIteratorBaseline
Segmentación de página y modo de engineOverload de THPDFTesseractOptions, enviado como --psm y --oemTHPDFTesseractOptions, enviado a TessBaseAPISetPageSegMode y TessBaseAPIInit2
Presupuesto de píxelesMaxPixels cuando se pasan opcionesMaxPixels siempre, más 32,767 píxeles por lado
TimeoutDuro: el proceso hijo se terminaCooperativo: Tesseract tiene que enterarse
Aislamiento de crashes y memoriaProceso separadoNinguno, comparte su address space

Un costo se queda con la DLL. Cada llamada Recognize crea su propia instancia de API y corre TessBaseAPIInit2, así que los modelos de idioma se inicializan por cada página. El caché de archivos le quita filo a la recarga, pero con un set grande de modelos multilingües sigue siendo el costo fijo más grande por página, y se cobra contra el deadline de reconocimiento. El engine DLL RapidOCR in-process toma la decisión contraria y mantiene sus modelos ONNX residentes durante la vida del engine, mientras que los problemas de frontera (ABI C, buffers prestados, trabajo nativo que no se puede interrumpir) son de la misma familia

¿Y cuál va en producción? Para una herramienta de escritorio o un trabajo por lotes que procesa unos cientos de escaneos, la DLL es la mejor opción: sin lanzamiento de proceso por página, sin bitmap temporal en disco, y baselines reales para líneas inclinadas. Un servidor de larga vida que acepta PDFs de extraños debe quedarse en tesseract.exe, porque un crash nativo o una asignación desbocada ahí tumba un proceso hijo y no su servicio

¿Por qué Delphi no puede copiar la struct monitor de Tesseract?

Delphi no puede reflejar con seguridad el monitor de progreso de Tesseract, porque ETEXT_DESC carga campos internos que varían entre builds de Tesseract. Un record traducido a mano desde un header pone el callback de cancelación y el deadline en los offsets que ese header usaba. Corra contra otro build y Tesseract lee su puntero de callback de un campo que ahora significa otra cosa, o nunca encuentra el deadline, y el reconocimiento simplemente corre hasta el final

El adaptador de HotPDF por eso trata el monitor como un puntero opaco y solo lo toca mediante funciones exportadas: TessMonitorCreate, TessMonitorSetCancelThis, TessMonitorSetCancelFunc, TessMonitorSetDeadlineMSecs y TessMonitorDelete. El bosquejo de abajo es su propio código de binding, no una API de HotPDF; sus declaraciones coinciden con las que el adaptador resuelve con GetProcAddress

Manejo del monitor en la DLL de Tesseract de HotPDF: copiar el record ETEXT_DESC dependiente de versión pone el callback de cancelación y el deadline en offsets equivocados y falla en silencio, mientras que HotPDF trata el monitor como opaco, maneja TessMonitorCreate, TessMonitorSetCancelThis, TessMonitorSetCancelFunc y TessMonitorSetDeadlineMSecs, y mantiene el callback cdecl libre de excepciones
Un puntero opaco más cinco exportaciones es todo el contrato; el callback sigue siendo un Boolean de un byte que solo lee un flag y un reloj
type
  // C: typedef bool (*TessCancelFunc)(void *cancel_this, int words);
  TTessCancelFunc = function(CancelThis: Pointer; Words: Integer): Boolean; cdecl;
  TTessMonitorCreate = function: Pointer; cdecl;   // ETEXT_DESC*, nunca desreferenciado
  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;

  // Estado de su propio job, no un tipo de HotPDF
  TOCRJob = record
    CancelRequested: Boolean;
    DeadlineTick: UInt64;
  end;
  POCRJob = ^TOCRJob;

function ShouldCancel(CancelThis: Pointer; Words: Integer): Boolean; cdecl;
begin
  // Corre en el stack de Tesseract: lea un flag y el reloj, nunca lance excepciones
  Result := (CancelThis = nil) or POCRJob(CancelThis)^.CancelRequested or
    (GetTickCount64 >= POCRJob(CancelThis)^.DeadlineTick);
end;

// Uso, con los punteros de función resueltos por GetProcAddress:
//   Monitor := MonitorCreate();
//   try
//     MonitorSetCancelThis(Monitor, @Job);
//     MonitorSetCancelFunc(Monitor, ShouldCancel);
//     MonitorSetDeadlineMSecs(Monitor, RemainingMs);
//     RC := BaseAPIRecognize(API, Monitor);
//   finally
//     MonitorDelete(Monitor);
//   end;

El bosquejo declara el callback como Boolean, un byte tanto en Delphi como en Free Pascal, lo que coincide con el bool de C en TessCancelFunc. El BOOL de Windows de cuatro bytes y el LongBool de Delphi se ven intercambiables y son otro tipo: cuando un lado escribe un solo byte y el otro lee cuatro, los tres bytes altos son lo que el register tenía antes, y un false puede llegar como true. TessPageIteratorBoundingBox devuelve un int, declarado como Integer del lado Pascal, así que lea el tipo C de cada valor de retorno en vez de asumir una sola regla para toda la API

El callback además nunca lanza. Una excepción de Delphi haciendo unwinding a través de los frames de C++ de Tesseract es comportamiento indefinido. El callback de HotPDF lee solo el token de cancelación y un valor monótono de GetTickCount64, y el adaptador convierte el resultado en un diagnóstico de cancelación o timeout después de que TessBaseAPIRecognize regresa. Corre esa revisión haya sido o no 0 el código de retorno nativo

¿Qué punteros nativos posee el lado Delphi?

El adaptador Tesseract DLL de HotPDF posee tres objetos nativos por solicitud (la instancia de API, el monitor y el iterador de resultados) y todo lo demás es prestado. Cada llamada Recognize crea su propio set y lo libera en un bloque finally en orden fijo: TessResultIteratorDelete, luego TessMonitorDelete, luego TessBaseAPIDelete. Liberar la interfaz del engine llama FreeLibrary sobre la DLL

Propiedad de objetos nativos de la DLL de Tesseract de HotPDF por llamada Recognize: el iterador de resultados, el monitor y la instancia de API son propiedad y se liberan en ese orden dentro de finally, el page iterator de TessResultIteratorGetPageIterator es una vista prestada que jamás debe liberarse, y las cadenas de GetUTF8Text se copian y se devuelven vía TessDeleteText
Tres objetos propios, todo lo demás prestado: libere en el orden fijo, nunca haga double free del page iterator, y nunca mezcle allocators
  • TessResultIteratorGetPageIterator devuelve una vista dentro del iterador de resultados, no un objeto nuevo. El adaptador la usa para TessPageIteratorBoundingBox y TessPageIteratorBaseline y nunca la libera; borrarla también liberaría la misma memoria dos veces
  • TessResultIteratorGetUTF8Text devuelve una cadena asignada por el runtime propio del DLL. El adaptador la decodifica y la devuelve vía TessDeleteText en un bloque finally, porque un FreeMem de Pascal la liberaría en el heap equivocado
  • El texto de cada palabra pasa por decodificación UTF-8 estricta con chequeo de longitud primero. Una palabra con caracteres de control, UTF-8 malformado, una caja fuera de la imagen, un rectángulo invertido o una confianza fuera de 0-100 hace fallar la solicitud; el adaptador no la remienda
  • El texto por solicitud tiene tope de 1,048,576 unidades de código UTF-16, y el conteo de palabras tiene que caber en el presupuesto que ApplyLoadedOCRTextLayer entrega con cada página

La confianza llega como 0-100 y se escala a 0-1, así que THPDFOCRTextLayerOptions.MinimumConfidence significa lo mismo para todos los engines. Cuando Tesseract reporta una baseline, ambos extremos se pasan a través, y para una palabra predominantemente vertical el ancho de la caja se usa como altura del texto. Sin baseline, el pipeline de la capa de texto recurre a su estimación geométrica, exactamente como hace con entrada TSV

Validar por rango las opciones de enum antes de que lleguen al DLL

La factory copia los bytes crudos de PageSegMode y EngineMode a un Integer antes de validarlos por rango. Un compilador tiene derecho a asumir que una variable de enum siempre guarda un valor declarado, así que una prueba como Ord(X) > Ord(High(T)) escrita directamente contra el enum se puede plegar a una constante false. Esos ordinales llegan al DLL como enteros planos: THPDFTesseractPageSegMode sigue la numeración de segmentación de página de Tesseract de 0 a 13, y THPDFTesseractEngineMode su numeración de modos de engine de 0 a 3. Un record de opciones limpiado con FillChar, leído de un stream o llenado desde C++Builder vía un cast a entero puede cargar un byte como 200, y validar la copia convierte eso en una EArgumentException en la factory. La factory también rechaza tpsOSDOnly y tpsAutoOnly, que no devuelven palabras, y exige osd.traineddata para tpsAutoOSD y tpsSparseTextOSD

¿Qué garantiza en realidad el timeout de reconocimiento?

El timeout del DLL de Tesseract es cooperativo: HotPDF puede detener su propio trabajo y pedirle a Tesseract que se detenga, pero no puede forzar a código nativo a regresar. El reloj arranca cuando Recognize comienza, así que la conversión a escala de grises y la inicialización de modelos consumen del mismo presupuesto que el reconocimiento. El adaptador revisa el tiempo transcurrido y el token de cancelación cada 64 filas durante la conversión a escala de grises, después de la inicialización, y antes de cada palabra mientras recorre los resultados. Justo antes de TessBaseAPIRecognize pasa los milisegundos restantes a TessMonitorSetDeadlineMSecs

El hueco vive dentro de las llamadas nativas. Tesseract consulta su monitor solo durante el reconocimiento de palabras, así que dentro de TessBaseAPIInit2 o del análisis de layout una carga de modelo lenta o un layout patológico puede pasarse del deadline antes de que el timeout se reporte. Los presupuestos de píxeles y de salida tampoco acotan el uso de memoria de la propia librería nativa. Cuando necesita un worker que pueda matar sin más, el adaptador de proceso es la herramienta

Anatomía del timeout cooperativo del DLL de Tesseract de HotPDF: el reloj arranca cuando Recognize comienza y cubre la conversión a escala de grises, TessBaseAPIInit2 y el análisis de layout, pero el monitor solo se consulta durante el reconocimiento de palabras, así que cargas de modelo y layout pueden pasarse del límite antes de que HotPDF reporte otlsEngineError u otlsCancelled
Un deadline aquí es una solicitud, no una garantía: init y el análisis de layout pueden alargarse, y un worker que de verdad pueda matarse necesita el adaptador de proceso

La segmentación de página es donde el adaptador DLL rinde con entrada difícil. Formularios, etiquetas y tablas escaneadas con campos dispersos suelen reconocer mejor con tpsSparseText que con segmentación automática, que intenta armar columnas y párrafos que no existen. El timeout de abajo es corto para una página de formulario y aun así tiene que cubrir la inicialización de modelos

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;  // campos dispersos, sin armado de columnas
  TessOptions.EngineMode := temLSTMOnly;     // necesita modelos LSTM en tessdata
  TessOptions.TimeoutMilliseconds := 20000;  // incluye la inicialización de modelos
  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 aparece como otlsEngineError con Tesseract DLL OCR timed out en el diagnóstico. Un token asignado vía THPDFOCRTextLayerOptions.CancellationToken aparece como otlsCancelled. En ambos casos ApplyLoadedOCRTextLayer reconoce todas las páginas seleccionadas antes de empezar la confirmación, así que una falla en la página 40 de 50 deja el documento cargado exactamente como estaba. tpsSingleLine, tpsSingleBlock y tpsSparseText cambian solo la segmentación; ninguno endereza un escaneo torcido

Free Pascal y Lazarus: píxeles viejos y chino perdido

Ambas factory de Tesseract funcionan en builds Win32 y Win64 de Free Pascal y Lazarus para Windows una vez que el package de Lazarus se recompila para la arquitectura objetivo; el port general está cubierto en HotPDF en Free Pascal y Lazarus Win64. El manejo de la entrada es donde FPC se comporta distinto

Un TBitmap de la LCL escrito vía scanlines puede actualizar su imagen cruda sin refrescar el handle del bitmap de Windows, así que GetDIBits sobre ese handle devuelve los píxeles viejos. El síntoma desconcierta: texto dibujado directo sobre un bitmap se reconoce, una página renderizada vía scanlines no produce palabras. Bajo FPC el adaptador DLL lee un snapshot consciente del formato vía CreateIntfImage, que respeta el formato de píxel y el orden de filas de la imagen cruda. El build Delphi conserva el camino de GetDIBits sobre una copia privada de 24 bits, y ninguno de los builds modifica el bitmap del llamador

El adaptador tesseract.exe se topa con un problema distinto. El TStringList de FPC almacena cadenas ANSI, así que asignar el texto TSV decodificado UTF-8 a Lines.Text suelta cada carácter chino o de plano complementario que la página de códigos ANSI del sistema no pueda representar. El camino FPC conserva el TSV como bytes UTF-8, quita el BOM a nivel de bytes y decodifica cada palabra a UnicodeString por su cuenta. El adaptador DLL jamás se topa con el problema, porque decodifica cada palabra directo del iterador

El adaptador Tesseract DLL se distribuye junto con los adaptadores de proceso y el engine OCR incluido en HotPDF para Delphi, C++Builder y Free Pascal. Las ediciones y descargas están listadas en la página del componente PDF de HotPDF para Delphi