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
| Aspecto | Adaptador tesseract.exe | Adaptador DLL Tesseract |
|---|---|---|
| Factoría | HPDFCreateTesseractOCREngine | HPDFCreateTesseractDLLOCREngine |
| Píxeles que entran | Archivo BMP en un directorio temporal privado | Buffer de escala de grises de 8 bits en memoria |
| Palabras que salen | TSV a nivel de palabra, topado a 64 MiB | Iterador de resultados, UTF-8 por palabra |
| Baselines | No vienen en el TSV; el pipeline las estima | Se trasladan desde TessPageIteratorBaseline |
| Segmentación de página y modo de motor | overload de THPDFTesseractOptions, enviada como --psm y --oem | THPDFTesseractOptions, enviada a TessBaseAPISetPageSegMode y TessBaseAPIInit2 |
| Presupuesto de píxeles | MaxPixels cuando se pasan opciones | MaxPixels siempre, más 32.767 píxeles por lado |
| Timeout | Duro: el proceso hijo se termina | Cooperativo: Tesseract debe darse por enterado |
| Aislamiento de crash y memoria | Proceso separado | Ninguno, 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
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
TessResultIteratorGetPageIteratordevuelve una vista dentro del iterador de resultados en lugar de un objeto nuevo. El adaptador lo usa paraTessPageIteratorBoundingBoxyTessPageIteratorBaseliney jamás lo libera; borrarlo además liberaría la misma memoria dos vecesTessResultIteratorGetUTF8Textdevuelve una cadena asignada por el runtime propio de la DLL. El adaptador la decodifica y la devuelve a través deTessDeleteTexten un bloquefinally, porque unFreeMemde 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
ApplyLoadedOCRTextLayerentrega 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
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