Artículo técnico

Bindear la API C de Tesseract a Delphi: OCR en proceso

Un timeout de reconocimiento de 5.000 ms en una llamada Tesseract en proceso no significa que la llamada vuelva a los cinco segundos. Con un conjunto grande de modelos multilingües, el hilo llamador puede quedarse dentro de la librería nativa mucho más allá de esa marca, porque el monitor de progreso que aplica el deadline se sondea mientras se reconocen palabras, y tanto la carga de modelos como el análisis de layout de página ocurren antes del primer sondeo. Esa brecha, un callback de cancelación cuyo tipo de retorno C es un solo byte, y un iterador que reparte memoria que usted jamás debe liberar son el trabajo de verdad de bindear la API C de Tesseract a Delphi. El resto es fontanería

Conectar la DLL Tesseract a una capa de texto de HotPDF

HotPDF expone el camino en proceso como HPDFCreateTesseractDLLOCREngine en la unidad HPDFTesseractRecognition. La factoría 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 motor y añade una capa de texto Unicode invisible y buscable a las páginas escaneadas, la misma llamada por la que pasa todo motor OCR de HotPDF

La factoría valida con ansias. El archivo DLL y el directorio tessdata deben existir. El identificador de idioma solo puede contener letras ASCII, dígitos, _ y +, y cada modelo de una combinación como chi_sim+eng necesita su archivo .traineddata correspondiente. Los 21 exports requeridos deben resolverse antes de que usted reciba un motor. Los errores de configuración lanzan EArgumentException, con el export o modelo ausente reportado por su nombre; una DLL que no carga lanza EOSError llevando el código de error de Windows y una 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 de archivo depende de su build,
  // y sus DLL 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 que ya llevan 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 fija 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 la gente espera. Una página US Letter a los 300 DPI por defecto 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 convierte en 5.100 × 6.600, unos 33,7 millones de píxeles, y el motor 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 de cuerpo; cada lado además se topa en 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 defecto. Las librerías de imagen de las que depende Tesseract pueden por tanto vivir a su lado, y usted jamás tiene que tocar PATH ni fiarse del directorio en curso. HotPDF no incluye ni descarga ningún runtime OCR ni ningún modelo de idioma; usted provisiona ambos

Qué cambia el camino DLL respecto a tesseract.exe

El mismo reconocedor también es alcanzable a través del 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 filtrado por confianza y el commit todo-o-nada se comportan idéntico. 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 Tesseract
FactoríaHPDFCreateTesseractOCREngineHPDFCreateTesseractDLLOCREngine
Píxeles que entranArchivo BMP en un directorio temporal privadoBuffer de escala de grises de 8 bits en memoria
Palabras que salenTSV a nivel de palabra, topado a 64 MiBIterador de resultados, UTF-8 por palabra
BaselinesNo vienen en el TSV; el pipeline las estimaSe trasladan desde TessPageIteratorBaseline
Segmentación de página y modo de motoroverload de THPDFTesseractOptions, enviada como --psm y --oemTHPDFTesseractOptions, enviada 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 debe darse por enterado
Aislamiento de crash y memoriaProceso separadoNinguno, comparte su espacio de direcciones

Un coste se queda con la DLL. Cada llamada a Recognize crea su propia instancia de API y ejecuta TessBaseAPIInit2, así que los modelos de idioma se inicializan para cada página. La caché de archivos suaviza la recarga, pero con un conjunto grande de modelos multilingües sigue siendo el mayor coste fijo por página, y se carga contra el deadline de reconocimiento. El motor de DLL RapidOCR en proceso toma la decisión opuesta y mantiene sus modelos ONNX residentes durante la vida del motor, 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 entonces en producción? Para una herramienta de escritorio o un trabajo por lotes que procesa unos cientos de escaneos, la DLL encaja mejor: sin lanzamiento de proceso por página, sin bitmap temporal en disco, y baselines reales para líneas torcidas. Un servidor de larga vida que acepta PDFs de desconocidos debería quedarse en tesseract.exe, porque un crash nativo o una asignación desbocada allí tumba un proceso hijo en lugar de su servicio

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

Delphi no puede reflejar con seguridad el monitor de progreso de Tesseract, porque ETEXT_DESC lleva campos internos que varían entre builds de Tesseract. Un registro traducido a mano desde una cabecera coloca el callback de cancelación y el deadline en los offsets que esa cabecera usara. Ejecútelo contra un build distinto y Tesseract lee su puntero de callback de un campo que ahora significa otra cosa, o jamás encuentra el deadline, y el reconocimiento sencillamente corre hasta el final

El adaptador de HotPDF trata por eso el monitor como un puntero opaco y solo lo toca a través de funciones exportadas: TessMonitorCreate, TessMonitorSetCancelThis, TessMonitorSetCancelFunc, TessMonitorSetDeadlineMSecs y TessMonitorDelete. El esqueleto de abajo es su propio código de binding en lugar de una API de HotPDF; sus declaraciones casan con las que el adaptador resuelve con GetProcAddress

Manejo del monitor de la DLL Tesseract en HotPDF: copiar el registro ETEXT_DESC dependiente de la versión coloca 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 exports es el contrato entero; 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*, jamás 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;

  // Su propio estado de trabajo, 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 la pila de Tesseract: lea un flag y el reloj, jamás lance
  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 esqueleto tipa el callback como Boolean, un byte tanto en Delphi como en Free Pascal, lo que casa con el bool de C en TessCancelFunc. El BOOL de Windows de cuatro bytes y el LongBool de Delphi parecen intercambiables y son un tipo distinto: cuando un lado escribe un solo byte y el otro lee cuatro, los tres bytes altos son lo que el registro tuviera antes, y un false puede llegar como true. TessPageIteratorBoundingBox devuelve un int, declarado como Integer en el lado Pascal, así que lea el tipo C de cada valor de retorno en lugar de asumir una regla para toda la API

El callback también jamás lanza. Una excepción Delphi deshaciéndose por los frames de C++ de Tesseract es comportamiento indefinido. El callback de HotPDF solo lee 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 retorna. Hace ese check tanto si el código de retorno nativo fue 0 como si no

¿Qué punteros nativos posee el lado Delphi?

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

Propiedad de objetos nativos de la DLL Tesseract en HotPDF por llamada a Recognize: el iterador de resultados, el monitor y la instancia de API son de su propiedad y se liberan en ese orden dentro de finally, el iterador de página 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 en propiedad, todo lo demás prestado: libere en el orden fijo, jamás libere dos veces el iterador de página, y jamás mezcle asignadores
  • TessResultIteratorGetPageIterator devuelve una vista dentro del iterador de resultados en lugar de un objeto nuevo. El adaptador lo usa para TessPageIteratorBoundingBox y TessPageIteratorBaseline y jamás lo libera; borrarlo además liberaría la misma memoria dos veces
  • TessResultIteratorGetUTF8Text devuelve una cadena asignada por el runtime propio de la DLL. El adaptador la decodifica y la devuelve a través de TessDeleteText en un bloque finally, porque un FreeMem de Pascal la liberaría en el heap equivocado
  • El texto de palabra pasa por una decodificación UTF-8 estricta con un check 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 petición; el adaptador no la parchea
  • El texto por petición se topa en 1.048.576 unidades de código UTF-16, y el recuento 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 todo motor. Cuando Tesseract reporta una baseline, ambos extremos se trasladan, 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 recae en su estimación geométrica, exactamente igual que con entrada TSV

Validación de rango de las opciones enum antes de llegar a la DLL

La factoría copia los bytes en crudo de PageSegMode y EngineMode a un Integer antes del check de rango. Un compilador tiene derecho a asumir que una variable enum siempre contiene un valor declarado, así que un test como Ord(X) > Ord(High(T)) escrito directamente contra el enum puede plegarse a una constante false. Esos ordinales llegan a la 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 modo de motor de 0 a 3. Un registro de opciones limpiado con FillChar, leído desde un stream, o rellenado desde C++Builder mediante un cast a entero puede llevar un byte como 200, y validar la copia convierte eso en una EArgumentException en tiempo de factoría. La factoría además rechaza tpsOSDOnly y tpsAutoOnly, que no devuelven palabras, y exige osd.traineddata para tpsAutoOSD y tpsSparseTextOSD

¿Qué garantiza realmente el timeout de reconocimiento?

El timeout de la DLL Tesseract es cooperativo: HotPDF puede parar su propio trabajo y pedirle a Tesseract que pare, pero no puede forzar a código nativo a retornar. El reloj arranca cuando Recognize comienza, así que la conversión a escala de grises y la inicialización de modelos consumen el mismo presupuesto que el reconocimiento. El adaptador comprueba 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

La brecha está 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 de página una carga de modelos lenta o un layout patológico puede pasarse del deadline antes de que se reporte el timeout. Los presupuestos de píxeles y de salida tampoco acotan el uso de memoria propio de la librería nativa. Cuando necesite un worker que pueda matar sin más, el adaptador de proceso es la herramienta para ello

Anatomía del timeout cooperativo de la DLL Tesseract en 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 las cargas de modelos y el layout pueden pasarse antes de que HotPDF reporte otlsEngineError u otlsCancelled
un deadline aquí es una petición, no una garantía: la inicialización y el análisis de layout pueden alargarse, y un worker que usted pueda matar de verdad necesita el adaptador de proceso

La segmentación de página es donde el adaptador de DLL se gana su sueldo con entrada difícil. Formularios, etiquetas y tablas escaneadas con campos dispersos suelen reconocer mejor con tpsSparseText que con la segmentación automática, que intenta ensamblar columnas y párrafos que no están. 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 ensamblado 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 emerge como otlsEngineError con Tesseract DLL OCR timed out en el diagnóstico. Un token fijado a través de THPDFOCRTextLayerOptions.CancellationToken emerge como otlsCancelled. En ambos casos ApplyLoadedOCRTextLayer reconoce cada página seleccionada antes de arrancar el commit, así que un fallo 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 caducados y chino perdido

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

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

El adaptador tesseract.exe se encuentra con un problema distinto. El TStringList de FPC guarda cadenas ANSI, así que asignar texto TSV UTF-8 decodificado a Lines.Text descarta cada carácter chino o de plano suplementario que la code page ANSI del sistema no pueda representar. El camino FPC conserva el TSV como bytes UTF-8, retira el BOM a nivel de byte y decodifica cada palabra a UnicodeString por su cuenta. El adaptador de DLL jamás se encuentra con el problema, porque decodifica cada palabra directamente del iterador

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