TerminateThread parece la forma obvia de parar una llamada OCR que lleva demasiado tiempo atascada en una página escaneada para lo que su UI está dispuesta a esperar. La documentación de Windows explica por qué no lo es: si el hilo objetivo sostiene el lock del heap del proceso, ese lock jamás se libera, y la siguiente asignación en cualquier otro hilo puede bloquearse para siempre. Una vez que el OCR corre dentro de su propio proceso, la única parada segura es una cooperativa, en checkpoints entre fases de inferencia, y ese es el precio de cargar los modelos ONNX una vez y mantenerlos calientes
La alternativa que la mayoría de los equipos Delphi prueban primero es un proceso hijo. Un worker de Python por página puede matarse en cualquier momento, lo que resulta atractivo, pero cada llamada arranca un intérprete, importa su runtime y carga los modelos de detección y reconocimiento antes de leer un píxel. Suponga un trabajo de archivado de 500 páginas: ese trabajo de arranque corre 500 veces, y el despliegue ahora incluye un entorno Python sentado junto a un ejecutable nativo
PDF buscable desde escaneos con HPDFCreateRapidOCRDLLOCREngine
HotPDF ejecuta RapidOCR en proceso a través de HPDFCreateRapidOCRDLLOCREngine, declarada en la unidad HPDFRapidOCRRecognition. La factoría carga HotPDFRapidOCR.dll, inicializa una vez los modelos ONNX de detección, de clasificación de ángulo opcional y de reconocimiento, y devuelve un IHPDFOCREngine. Ese motor se enchufa a THotPDF.ApplyLoadedOCRTextLayer exactamente igual que los demás motores OCR de HotPDF: el documento renderiza cada página, la DLL ejecuta la inferencia en CPU sobre ella, y el resultado se compromete como una capa de texto Unicode invisible. Sin Python, sin proceso hijo. El adaptador se distribuye para builds Delphi, C++Builder y FPC/Lazarus para Windows
La validación ocurre en la factoría, antes de tocar página alguna. Cada archivo de modelo y de diccionario debe resolverse, HPDFRapidOCRAbiVersion debe devolver 1, y los exports requeridos deben existir antes de que HPDFRapidOCRCreate construya los modelos. Los errores de configuración lanzan EArgumentException; un modelo que se niega a cargar lanza EInvalidOperation con el diagnóstico de la propia DLL, como un diccionario que no casa con el modelo de reconocimiento
uses
SysUtils, HPDFTypes, HPDFDoc, HPDFRapidOCRRecognition;
procedure MakeSearchable(const SourceFile, TargetFile: string);
var
Doc: THotPDF;
Engine: IHPDFOCREngine;
Options: THPDFOCRTextLayerOptions;
Info: THPDFOCRTextLayerInfo;
begin
// Los modelos se cargan aquí, fuera de cualquier deadline de reconocimiento.
// Los nombres de modelo relativos en THPDFRapidOCRDLLOptions.Default
// se resuelven contra el directorio de modelos.
Engine := HPDFCreateRapidOCRDLLOCREngine(
'C:\OCR\Win64\HotPDFRapidOCR.dll', 'C:\OCR\models');
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 tienen texto se saltan
if not Doc.ApplyLoadedOCRTextLayer([], Engine, Options, Info) then
raise Exception.Create(string(Info.Diagnostic));
Writeln(string(Info.EngineName), ': ', Info.AcceptedWordCount,
' lines accepted, ', Info.DroppedWordCount, ' dropped');
Doc.SaveLoadedDocument(TargetFile);
finally
Doc.Free;
end;
end;
THPDFRapidOCRDLLOptions.Default nombra ch_PP-OCRv3_det_infer.onnx, ch_PP-OCRv3_rec_infer.onnx, ch_ppocr_mobile_v2.0_cls_infer.onnx y ppocr_keys_v1.txt, con un hilo de CPU, un límite de entrada de 16.777.216 píxeles y un deadline de 60.000 ms por llamada de reconocimiento. Para otras escrituras, THPDFRapidOCRDLLOptions.ForLanguage conserva esos valores por defecto y cambia <profile>/recognition.onnx más <profile>/dictionary.txt por uno de nueve perfiles, del chino tradicional y el cirílico al árabe y el devanagari. Cada motor lee un idioma; escoja el perfil por página o por documento. Por qué el modelo y el diccionario viajan siempre como pareja está cubierto en modelos multilingües RapidOCR y diccionarios CTC en HotPDF
El motor se reporta como RapidOCR (native DLL) en Info.EngineName. Registre esa cadena en los logs. Cuando el mismo servicio también ejecuta el adaptador de proceso OCR Tesseract externo o el motor OCR de plantillas incorporado, es la manera más rápida de saber qué reconocedor produjo una página mala
¿Por qué la ABI C solo habla int32_t y bytes UTF-8?
La frontera de HotPDFRapidOCR.dll usa enteros de ancho fijo, punteros en crudo y longitudes de byte explícitas porque Delphi, C++Builder y Free Pascal no comparten nada con MSVC más allá de la convención de llamada C. Un std::string, un std::vector o una excepción de C++ llevan consigo una disposición de memoria y un modelo de unwinding que pertenecen a un compilador y a una librería de runtime, y dejar que cualquiera de ellos cruce a código Pascal acaba en una pila corrompida o en un bloque de heap liberado por el asignador equivocado
La versión de ABI 1 es una lista corta de reglas. Cada export es cdecl y devuelve un estado int32_t: 1 para éxito, 0 para fracaso. Toda función que puede fallar recibe un buffer de diagnóstico propiedad del llamador y su tamaño en bytes, y la DLL escribe un mensaje UTF-8 terminado en NUL truncado para caber. Dentro de la DLL, el cuerpo de cada export va dentro de un try con catch (const std::exception &) y catch (...). Un error de ONNX Runtime, un assert de OpenCV o un diccionario malformado se convierte en estado 0 más texto
| Export | Papel | Cuándo lo resuelve el adaptador |
|---|---|---|
HPDFRapidOCRAbiVersion | Devuelve 1; cualquier otro valor se rechaza | Justo después de que la DLL carga |
HPDFRapidOCRCreate | Carga los modelos de detección, clasificación opcional y reconocimiento, y el diccionario | En la factoría |
HPDFRapidOCRRecognize | Ejecuta un bitmap y emite un callback por línea de texto | En la factoría |
HPDFRapidOCRDestroy | Libera la instancia de modelos | En la factoría |
HPDFRapidOCRSetReadingDirection | Orden de filas de derecha a izquierda opcional | Solo cuando RightToLeft está activo |
El export de dirección de lectura se resuelve perezosamente a propósito, así que una DLL compilada sin él sigue sirviendo toda petición de izquierda a derecha. El adaptador carga la librería con LoadLibraryEx y flags de búsqueda que cubren la carpeta propia de la DLL más los directorios seguros por defecto; las dependencias de ONNX Runtime u OpenCV colocadas junto a HotPDFRapidOCR.dll se encuentran sin editar PATH. Las rutas de modelos y diccionarios cruzan la frontera como UTF-8, y la DLL las convierte con MultiByteToWideChar en modo estricto antes de abrir archivos por APIs de caracteres anchos. Un directorio de modelos bajo C:\Users\Łukasz o un nombre de usuario cirílico abre con normalidad
Una regla vive en los archivos de build más que en la cabecera. La DLL enlaza estáticamente ONNX Runtime y OpenCV, y el proyecto CMake usa por defecto el CRT release estático (/MT). Mezcle librerías estáticas compiladas contra /MD y obtendrá errores de enlace si tiene suerte y dos heaps independientes si no. Provisione librerías compiladas para el mismo modo CRT que la DLL
¿Qué pasa entre un TBitmap y una línea de texto?
HotPDF entrega a la DLL una copia BGR independiente de arriba abajo de la página renderizada, y la DLL devuelve un callback por línea reconocida. El texto de ese callback es prestado: el puntero solo es válido hasta que el callback retorna, así que el adaptador lo copia en el momento
En Delphi la instantánea viene de un TBitmap privado forzado a pf24bit y leído con GetDIBits usando un biHeight negativo. Eso da filas de arriba abajo rellenadas a alineación de cuatro bytes, y el stride viaja a la DLL como argumento explícito. En FPC el adaptador lee a través de CreateIntfImage. El bitmap del llamador jamás se modifica. Los checks de tamaño corren antes de asignar la copia: como máximo 32.767 píxeles por lado, y no más de MaxPixels en total, que por defecto es 16.777.216 y puede subir hasta 67.108.864
Dentro de la DLL la imagen recibe un borde blanco de 50 píxeles, las regiones de texto se detectan con el lado más largo escalado a 1.024 píxeles como máximo, y las cajas se ordenan en filas horizontales. Con el clasificador de ángulo activado, un recorte solo se gira 180 grados cuando la puntuación de boca abajo supera 0.9, lo que evita que una predicción débil invierta palabras cortas. Cada línea llega entonces como un const char*, un recuento de bytes, una caja entera en píxeles de la imagen original y la confianza media de caracteres. El adaptador es estricto con lo que acepta:
- El UTF-8 se decodifica con
MB_ERR_INVALID_CHARS; una secuencia malformada hace fallar la página en lugar de plantar caracteres de sustitución en una capa buscable - Los caracteres de control C0 y C1 se rechazan; las líneas de solo espacios en blanco se saltan
- La caja debe caber dentro del bitmap y la confianza debe ser un valor finito de 0 a 1
- El texto se cuenta contra el
MaxTextCodeUnitsde la petición, con un techo duro de 1.048.576 unidades UTF-16 por llamada; los caracteres fuera del Basic Multilingual Plane cuestan dos unidades - Una excepción Pascal dentro del callback se captura ahí, se guarda y se convierte en un retorno 0, lo que hace que la DLL se detenga; el mensaje guardado se convierte en
Info.Diagnostic
Dos de estos detalles importan cuando ajusta la salida. La unidad es una línea, no una palabra: cada línea consume una ranura MaxWords, Info.AcceptedWordCount y Info.DroppedWordCount cuentan líneas, y un hit de búsqueda resalta la caja de la línea entera. Y MinimumConfidence se compara contra la confianza media de caracteres de la línea, así que un carácter borroso entre veinte limpios rara vez hunde la línea. Subir el umbral a 0.7 o 0.8 descarta líneas enteras, jamás caracteres sueltos. Una página en blanco tiene éxito con cero líneas, y cualquier fallo descarta los resultados parciales para que el commit multipágina siga siendo todo-o-nada
Un motor, una copia de modelos, un llamador a la vez
Cada motor de DLL RapidOCR posee exactamente una instancia de modelos durante toda su vida, y las llamadas a Recognize sobre ese motor se serializan con una critical section. Sostener la referencia IHPDFOCREngine es lo que mantiene los modelos en memoria, así que el trabajo por lotes debería crear el motor una vez y reutilizarlo en todos los documentos
procedure OcrBatch(const Files: TStrings; const OutputDir: string);
var
Models: THPDFRapidOCRDLLOptions;
Engine: IHPDFOCREngine;
Doc: THotPDF;
Options: THPDFOCRTextLayerOptions;
Info: THPDFOCRTextLayerInfo;
I: Integer;
begin
Models := THPDFRapidOCRDLLOptions.ForLanguage('ru-RU');
Models.UseAngleClassifier := False; // escaneos rectos: no se carga modelo clasificador
Models.Threads := 4; // 1..64, topado al número de procesadores activos
Models.TimeoutMilliseconds := 120000; // por llamada a Recognize, cooperativo
Engine := HPDFCreateRapidOCRDLLOCREngine(
'C:\OCR\Win64\HotPDFRapidOCR.dll', 'C:\OCR\models', Models);
Options := THPDFOCRTextLayerOptions.Default;
for I := 0 to Files.Count - 1 do
begin
Doc := THotPDF.Create(nil);
try
Doc.AutoLaunch := False;
if (Doc.LoadFromFile(Files[I]) > 0) and
Doc.ApplyLoadedOCRTextLayer([], Engine, Options, Info) then
Doc.SaveLoadedDocument(IncludeTrailingPathDelimiter(OutputDir) +
ExtractFileName(Files[I]))
else
Writeln(Files[I], ': ', string(Info.Diagnostic));
finally
Doc.Free;
end;
end;
end; // última referencia liberada: modelos destruidos, luego se descarga la DLL
El valor de Threads fija los recuentos de hilos intra-op e inter-op de cada sesión ONNX del motor, y la DLL lo topa al número de procesadores activos. Dos hilos compartiendo un motor jamás corren inferencia en paralelo; el segundo espera. Esa espera no es un EnterCriticalSection a ciegas. El adaptador intenta el lock con TryEnterCriticalSection, duerme 25 ms entre intentos, y comprueba el token de cancelación y el deadline cada vez, así que una petición en cola aún puede cancelarse
El reloj del deadline arranca al entrar en Recognize, antes de tomar el lock. El tiempo en cola detrás de otra página cuenta contra TimeoutMilliseconds. Con cuatro hilos worker sobre un motor y un deadline de 60 segundos, la cuarta página puede agotar su tiempo sin llegar jamás al modelo. Déle a cada worker su propio motor. Cuesta una copia de los modelos en memoria por motor, y esa memoria compra timeouts previsibles y paralelismo de verdad; compartir un motor solo tiene sentido cuando las peticiones son tan raras que casi jamás se encolan
¿Por qué no se puede matar una llamada OCR nativa a mitad de inferencia?
Una llamada RapidOCR nativa no puede matarse a mitad de inferencia porque corre en su hilo, dentro de su proceso, en mitad de una sesión de ONNX Runtime que no tiene API de interrupción para un Run en curso. La cancelación en el adaptador de DLL es cooperativa. La DLL llama a un callback de aborto antes y después de la detección, tras la clasificación de cada recorte y tras cada línea reconocida, y se detiene en el primer checkpoint donde el callback devuelve 0. Un Run que ya ha arrancado termina primero
Las opciones contundentes son peores que esperar. TerminateThread dejaría el lock del heap del CRT, el thread pool de ONNX Runtime y cualquier estado de OpenCV en la condición en que estuvieran. Un FreeLibrary mientras una llamada sigue ejecutándose descarga código que está en la pila. Ninguno de los dos puede hacerse seguro, así que el adaptador jamás lo intenta. Un deadline vencido vuelve como otlsEngineError con un diagnóstico de timeout; un token cancelado vuelve como otlsCancelled:
// El token lo crea el llamador y lo comparte con el hilo de UI,
// que llama a Token.Cancel cuando el usuario pulsa Stop
function OcrWithStop(Doc: THotPDF; const Engine: IHPDFOCREngine;
Token: THPDFCancellationToken): Boolean;
var
Options: THPDFOCRTextLayerOptions;
Info: THPDFOCRTextLayerInfo;
begin
Options := THPDFOCRTextLayerOptions.Default;
Options.CancellationToken := Token;
Result := Doc.ApplyLoadedOCRTextLayer([], Engine, Options, Info);
if not Result then
case Info.Status of
otlsCancelled:
// parada en el siguiente checkpoint de fase o de línea; documento sin cambiar
Writeln('Cancelled');
otlsEngineError:
// incluye un deadline cooperativo vencido y diagnósticos nativos
Writeln('Engine: ', string(Info.Diagnostic));
otlsBudgetExceeded:
// se alcanzó un límite de página, píxel, palabra o contenido en Options
Writeln('Budget: ', string(Info.Diagnostic));
else
Writeln(string(Info.Diagnostic));
end;
end;
Este es el trade-off real entre los adaptadores de proceso y la DLL en proceso, y ninguno de los dos lados gana en todas las filas:
- Coste de arranque: los adaptadores Tesseract y RapidOCR de Python lanzan un proceso y cargan modelos por cada página; la DLL carga los modelos una vez por motor
- Parada: un proceso hijo puede terminarse sin más, y el worker de Python corre dentro de un Job Object de kill-on-close así que su árbol de procesos entero cae con él; la DLL se detiene en checkpoints de fase y de línea
- Contención de fallos: un crash en
tesseract.exehace fallar una página; un access violation dentro de la DLL se lleva su proceso por delante - Despliegue: los adaptadores de proceso necesitan un programa instalado o un entorno Python; la DLL se necesita a sí misma, sus modelos y su diccionario, casando con el bitness de la aplicación
- Memoria: los adaptadores de proceso liberan todo cuando el hijo sale; un motor de DLL mantiene sus modelos residentes hasta que se libera la última referencia de interfaz
Escoja la DLL para una aplicación de escritorio interactiva que hace OCR a una página por vez y necesita un botón Stop responsivo que retorne dentro de una fase de inferencia. Para un servidor que ingiere escaneos no fiables a todas horas, pague el coste de arranque por página y conserve la frontera de proceso; una imagen maliciosa que tumbe un reconocedor debería costar una página, y con un proceso hijo lo hace
Compilar HotPDFRapidOCR.dll y elegir modelos
HotPDFRapidOCR.dll se compila de los fuentes C++ en Native/RapidOCR con MSVC, C++17, un Windows SDK y CMake 3.20 o posterior. El ayudante tools/Build-HotPDFRapidOCR.ps1 toma los directorios de fuentes nativas, ONNX Runtime y OpenCV más -Platform Win32 o Win64, y escribe el resultado en Lib/Native/RapidOCR/<Platform>/. Compile ambas si despacha ambas. Una aplicación Delphi de 32 bits no puede cargar una DLL de 64 bits, y las librerías estáticas que provisione deben casar con la arquitectura objetivo además de con el modo CRT
Los modelos tienen sus propias reglas de compatibilidad. El detector es un DB text detector. El reconocedor acepta modelos CTC en disposición NCHW con altura de entrada fija de 32 o 48, y usa 48 cuando el modelo declara altura dinámica. El formato del modelo tiene que ser uno que el ONNX Runtime enlazado estáticamente entienda; exports más nuevos como PP-OCRv5 pueden exigir un runtime más nuevo, y un modelo ilegible falla en la inicialización con un diagnóstico. tools/Install-RapidOCRModels.ps1 instala packs PP-OCRv3 y PP-OCRv4 verificados contra hashes SHA256 fijados, con un detector y un clasificador compartidos bajo los nombres de archivo que Default espera. Quédese en esos packs a menos que usted también controle la build del runtime
El diccionario debe ser UTF-8 sin BOM, en el orden de caracteres exacto del modelo, y su recuento de entradas debe casar con las clases de salida del modelo. Los finales de línea CRLF están bien. Cuando un modelo incrusta su propia lista de caracteres en metadatos, la inicialización del modelo compara cada entrada y su posición contra el archivo de diccionario, así que un diccionario que solo tenga la longitud correcta también falla. La DLL jamás descarga un modelo que falte
HotPDF empaqueta el adaptador RapidOCR nativo junto a los adaptadores OCR basados en proceso, el renderer de páginas que los alimenta y el escritor de capas de texto Unicode invisibles, todo dentro de un componente VCL nativo para Delphi y C++Builder. Para software de captura y archivado que tiene que producir PDF buscable en máquinas sin Python instalado, el componente Delphi PDF de HotPDF deja solo la DLL y sus archivos de modelos por desplegar