Artículo técnico

RapidOCR en proceso con HotPDF: OCR de DLL nativa en Delphi

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

Secuencia de validación de la factoría RapidOCR DLL de HotPDF para HPDFCreateRapidOCRDLLOCREngine: las rutas y archivos de modelo deben existir, HPDFRapidOCRAbiVersion debe devolver 1, los exports requeridos deben resolverse, y HPDFRapidOCRCreate debe inicializar los modelos, con EArgumentException o EInvalidOperation lanzadas con ansias antes de que corra reconocimiento alguno, la segunda llevando el texto diagnóstico nativo
la validación es ansiosa a propósito: los problemas de configuración lanzan antes de que se inicialice cualquier modelo, así que una mala ruta o ABI jamás llega a un deadline 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

ExportPapelCuándo lo resuelve el adaptador
HPDFRapidOCRAbiVersionDevuelve 1; cualquier otro valor se rechazaJusto después de que la DLL carga
HPDFRapidOCRCreateCarga los modelos de detección, clasificación opcional y reconocimiento, y el diccionarioEn la factoría
HPDFRapidOCRRecognizeEjecuta un bitmap y emite un callback por línea de textoEn la factoría
HPDFRapidOCRDestroyLibera la instancia de modelosEn la factoría
HPDFRapidOCRSetReadingDirectionOrden de filas de derecha a izquierda opcionalSolo 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

Pipeline RapidOCR DLL de HotPDF desde el bitmap a la capa de texto: el adaptador toma la página como instantánea BGR pf24bit de arriba abajo, la DLL rellena, detecta, ordena y reconoce recortes, entrega un callback por línea con texto UTF-8 prestado, caja y confianza, y el adaptador valida cada línea antes del commit de la capa de texto
los píxeles cruzan la ABI una vez como instantánea, las líneas vuelven de un callback en uno, y nada llega a la capa buscable hasta que pasa cada check

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 MaxTextCodeUnits de 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:

Trade-offs de los adaptadores OCR de HotPDF: los adaptadores de proceso arrancan un worker y cargan modelos en cada página pero pueden matarse y contienen crashes, mientras que la DLL RapidOCR en proceso carga los modelos una vez, se detiene solo en checkpoints cooperativos, comparte el espacio de direcciones y se despliega como DLL con sus modelos y diccionario
escoja por carga de trabajo: una app de escritorio página a página se beneficia de la DLL caliente, mientras que un servidor que ingiere escaneos no fiables debería pagar el muro de proceso
  • 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.exe hace 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