Artículo técnico

RapidOCR in-process de HotPDF: OCR con DLL nativa en Delphi

TerminateThread parece la forma obvia de detener una llamada de OCR que lleva demasiado tiempo moliendo una página escaneada para la paciencia de su UI. La documentación de Windows explica por qué no lo es: si el thread objetivo sostiene el lock del heap del proceso, ese lock nunca se libera, y la siguiente asignación en cualquier otro thread se puede bloquear para siempre. Una vez que el OCR corre dentro de su propio proceso, la única parada segura es una cooperativa, en checkpoints entre etapas 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 prueba primero es un proceso hijo. Un worker Python por página se puede matar 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 archivo con 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 corre RapidOCR in-process a través de HPDFCreateRapidOCRDLLOCREngine, declarada en la unit HPDFRapidOCRRecognition. La factory carga HotPDFRapidOCR.dll, inicializa una sola vez los modelos de detección ONNX, la clasificación de ángulo opcional y el reconocimiento, y devuelve un IHPDFOCREngine. Ese engine se conecta a THotPDF.ApplyLoadedOCRTextLayer exactamente como los demás engines OCR: el documento renderiza cada página, el DLL corre inferencia de CPU sobre ella, y el resultado se confirma como una capa de texto Unicode invisible. Sin Python, sin proceso hijo. El adaptador se distribuye para builds Delphi, C++Builder y FPC/Lazarus en Windows

La validación ocurre en la factory, antes de tocar cualquier página. Cada archivo de modelo y diccionario debe resolver, HPDFRapidOCRAbiVersion debe devolver 1, y las exportaciones requeridas 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 propio del DLL, por ejemplo un diccionario que no corresponde al modelo de reconocimiento

Secuencia de validación de la factory de la DLL RapidOCR de HotPDF para HPDFCreateRapidOCRDLLOCREngine: las rutas y los archivos de modelos deben existir, HPDFRapidOCRAbiVersion debe devolver 1, los exports requeridos deben resolver, y HPDFRapidOCRCreate debe inicializar los modelos, con EArgumentException o EInvalidOperation levantadas con antelación antes de que corra cualquier reconocimiento, la última llevando el texto de diagnóstico nativo
la validación es anticipada a propósito: los problemas de configuración levantan antes de que se inicialice cualquier modelo, así que una ruta o una ABI malas jamás llegan 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 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
    // lista de páginas vacía = todas; SkipPagesWithText es True por default
    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 defaults 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 engine lee un idioma; elija el perfil por página o por documento. Por qué el modelo y el diccionario siempre viajan como pareja está cubierto en modelos multilingües RapidOCR y diccionarios CTC en HotPDF

El engine se reporta como RapidOCR (native DLL) en Info.EngineName. Registre esa cadena en el log. Cuando el mismo servicio también corre el adaptador del proceso Tesseract externo o el engine OCR de template matching incluido, 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 crudos y longitudes en bytes 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++ carga 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 hacia código Pascal termina en un stack corrupto o un bloque del heap liberado por el allocator equivocado

La versión 1 de la ABI es una lista corta de reglas. Cada exportación es cdecl y devuelve un estado int32_t: 1 para éxito, 0 para falla. Cada función que puede fallar toma un buffer de diagnóstico propiedad del llamador y su tamaño en bytes, y el DLL escribe un mensaje UTF-8 terminado en NUL truncado para caber. Dentro del DLL, el cuerpo de cada exportación vive en 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

ExportaciónRolCuándo la resuelve el adaptador
HPDFRapidOCRAbiVersionDevuelve 1; cualquier otro valor se rechazaInmediatamente después de cargar el DLL
HPDFRapidOCRCreateCarga los modelos de detección, clasificación opcional y reconocimiento, y el diccionarioEn la factory
HPDFRapidOCRRecognizeCorre un bitmap y emite un callback por línea de textoEn la factory
HPDFRapidOCRDestroyLibera la instancia de modelosEn la factory
HPDFRapidOCRSetReadingDirectionOrden de filas derecha a izquierda opcionalSolo cuando RightToLeft está asignado

La exportación de dirección de lectura se resuelve de forma perezosa a propósito, así que un DLL compilado sin ella sigue sirviendo toda solicitud de izquierda a derecha. El adaptador carga la librería con LoadLibraryEx y flags de búsqueda que cubren la carpeta propia del DLL más los directorios seguros por default; las dependencias de ONNX Runtime u OpenCV puestas junto a HotPDFRapidOCR.dll se encuentran sin editar PATH. Las rutas de modelo y diccionario cruzan la frontera como UTF-8, y el DLL las convierte con MultiByteToWideChar en modo estricto antes de abrir archivos vía APIs de caracteres anchos. Un directorio de modelos bajo C:\Users\Łukasz o un nombre de usuario cirílico abre normal

Una regla vive en los archivos de build y no en el header. El DLL enlaza ONNX Runtime y OpenCV estáticamente, y el proyecto CMake hace default al CRT release estático (/MT). Mezcle librerías estáticas compiladas contra /MD y obtiene errores de link si tiene suerte, y dos heaps independientes si no. Provisione librerías compiladas para el mismo modo de CRT que el DLL

¿Qué pasa entre un TBitmap y una línea de texto?

HotPDF le entrega al DLL una copia BGR top-down independiente de la página renderizada, y el DLL devuelve un callback por línea reconocida. El texto de ese callback es prestado: el puntero es válido solo hasta que el callback regresa, así que el adaptador lo copia en el momento

En Delphi el snapshot sale de un TBitmap privado forzado a pf24bit y leído con GetDIBits usando un biHeight negativo. Eso da filas top-down rellenadas a alineación de cuatro bytes, y el stride viaja al DLL como argumento explícito. En FPC el adaptador lee vía CreateIntfImage. El bitmap del llamador nunca se modifica. Los chequeos de tamaño corren antes de asignar la copia: a lo sumo 32,767 píxeles por lado, y no más de MaxPixels en total, que hace default a 16,777,216 y se puede subir a 67,108,864

Pipeline de la DLL RapidOCR de HotPDF de bitmap a capa de texto: el adapter toma un snapshot top-down pf24bit BGR de la página, la DLL acolcha, detecta, ordena y reconoce los recortes, entrega un callback por línea con texto UTF-8 prestado, caja y confianza, y el adapter valida cada línea antes de la confirmación de la capa de texto
los píxeles cruzan la ABI una vez como snapshot, las líneas vuelven de a un callback, y nada llega a la capa buscable hasta que todos los chequeos pasan

Dentro del DLL la imagen recibe un borde blanco de 50 píxeles, las regiones de texto se detectan con el lado largo escalado a 1,024 píxeles como máximo, y las cajas se ordenan en filas horizontales. Con el clasificador de ángulo habilitado, un recorte se gira 180 grados solo cuando el puntaje de boca abajo supera 0.9, lo que evita que una predicción débil voltee palabras cortas. Cada línea llega entonces como un const char*, un conteo 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, así que una secuencia de bytes malformada hace fallar la página en vez de plantar caracteres de reemplazo en una capa buscable
  • Los caracteres de control C0 y C1 se rechazan; las líneas de solo espacios se saltan
  • La caja debe quedar dentro del bitmap, y la confianza debe ser un valor finito de 0 a 1
  • El texto cuenta contra el MaxTextCodeUnits de la solicitud, 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 de Pascal dentro del callback se atrapa ahí, se almacena y se convierte en un retorno 0, lo que hace que el DLL se detenga; el mensaje almacenado 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 toma un slot de MaxWords, Info.AcceptedWordCount y Info.DroppedWordCount cuentan líneas, y un resultado de búsqueda resalta la caja de toda la línea. Y MinimumConfidence se compara con 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, nunca caracteres sueltos. Una página en blanco termina con éxito y cero líneas, y cualquier falla descarta los resultados parciales para que la confirmación multipágina quede todo-o-nada

Un engine, una copia de modelos, un llamador a la vez

Cada engine DLL RapidOCR posee exactamente una instancia de modelos durante toda su vida, y las llamadas Recognize sobre ese engine se serializan con una sección crítica. Sostener la referencia IHPDFOCREngine es lo que mantiene los modelos en memoria, así que el trabajo por lotes debe crear el engine 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 derechos: no se carga modelo clasificador
  Models.Threads := 4;                   // 1..64, acotado a los procesadores activos
  Models.TimeoutMilliseconds := 120000;  // por llamada 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 el DLL descargado

Threads asigna los conteos de threads intra-op e inter-op de cada sesión ONNX del engine, y el DLL lo acota al conteo de procesadores activos. Dos threads que comparten un engine nunca corren inferencia en paralelo; el segundo espera. Esa espera no es un EnterCriticalSection a ciegas. El adaptador prueba el lock con TryEnterCriticalSection, duerme 25 ms entre intentos, y revisa el token de cancelación y el deadline cada vez, así que una solicitud en cola todavía se puede cancelar

El reloj del deadline arranca cuando se entra a Recognize, antes de tomar el lock. El tiempo en cola detrás de otra página cuenta contra TimeoutMilliseconds. Con cuatro worker threads sobre un engine y un deadline de 60 segundos, la cuarta página puede expirar sin llegar jamás al modelo. Déle a cada worker su propio engine. Cuesta una copia de los modelos en memoria por engine, y esa memoria compra timeouts predecibles y paralelismo real; compartir un engine solo tiene sentido cuando las solicitudes son tan raras que casi nunca hacen cola

¿Por qué una llamada de OCR nativa no se puede matar a mitad de inferencia?

Una llamada nativa RapidOCR no se puede matar a mitad de inferencia porque corre en su thread, dentro de su proceso, en medio de una sesión de ONNX Runtime que no tiene API de interrupción para un Run en marcha. La cancelación en el adaptador del DLL es cooperativa. El DLL llama a un callback de aborto antes y después de la detección, después de la clasificación de cada recorte, y después de cada línea reconocida, y se detiene en el primer checkpoint donde el callback devuelve 0. Un Run único que ya arrancó termina primero

Las opciones violentas 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 al momento. Llamar FreeLibrary mientras una llamada sigue ejecutándose desmapea código que está en el stack. Ninguna de las dos se puede volver segura, así que el adaptador nunca lo intenta. Un deadline expirado regresa como otlsEngineError con un diagnóstico de timeout; un token cancelado regresa como otlsCancelled:

// El token lo crea el llamador y lo comparte con el thread de UI,
// que llama 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:
        // detenido en el siguiente checkpoint de etapa o línea; documento sin cambios
        Writeln('Cancelled');
      otlsEngineError:
        // incluye un deadline cooperativo expirado 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 verdadero trade-off entre los adaptadores de proceso y el DLL in-process, y ningún lado gana en todas las filas:

Trade-offs de los adapters OCR de HotPDF: los adapters de proceso arrancan un worker y cargan modelos en cada página pero se pueden matar y contienen crashes, mientras que la DLL RapidOCR in-process carga los modelos una vez, se detiene solo en checkpoints cooperativos, comparte el address space, y se despliega como una DLL con sus modelos y diccionario
elija por workload: una app de escritorio de a una página por vez se beneficia de la DLL caliente, mientras que un server que ingiere escaneos no confiables debería pagar por el muro de proceso
  • Costo de arranque: los adaptadores Tesseract y RapidOCR Python lanzan un proceso y cargan modelos por cada página; el DLL carga modelos una vez por engine
  • Detención: un proceso hijo se puede terminar sin más, y el worker Python corre dentro de un Job Object kill-on-close así que todo su árbol de proceso se va con él; el DLL se detiene en checkpoints de etapa y de línea
  • Contención de fallas: un crash en tesseract.exe hace fallar una página; una access violation dentro del DLL se lleva su proceso abajo
  • Despliegue: los adaptadores de proceso necesitan un programa instalado o un entorno Python; el DLL se necesita a sí mismo, sus modelos y su diccionario, acordes al bitness de la aplicación
  • Memoria: un adaptador de proceso libera todo cuando el hijo sale; un engine DLL mantiene sus modelos residentes hasta que la última referencia de interfaz desaparece

Elija el DLL para una aplicación de escritorio interactiva que aplica OCR a una página por vez y necesita un botón de Stop responsivo que regrese dentro de una etapa de inferencia. Para un server que ingiere escaneos no confiables las 24 horas, pague el costo de arranque por página y conserve la frontera de proceso; una imagen maliciosamente construida que tumba 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 desde las fuentes C++ en Native/RapidOCR con MSVC, C++17, un Windows SDK y CMake 3.20 o posterior. El helper tools/Build-HotPDFRapidOCR.ps1 toma los directorios de la fuente nativa, ONNX Runtime y OpenCV más -Platform Win32 o Win64, y escribe el resultado en Lib/Native/RapidOCR/<Platform>/. Compile ambos si distribuye ambos. Una aplicación Delphi de 32 bits no puede cargar un DLL de 64 bits, y las librerías estáticas que provisione deben coincidir con la arquitectura objetivo y también con el modo de CRT

Los modelos tienen sus propias reglas de compatibilidad. El detector es un DB text detector. El reconocedor acepta modelos CTC en layout 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; exportaciones más nuevas como PP-OCRv5 pueden requerir 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 detector y clasificador compartidos bajo los nombres de archivo que Default espera. Quédese con esos packs salvo que usted también controle el build del runtime

El diccionario debe ser UTF-8 sin BOM, en exactamente el orden de caracteres del modelo, y su conteo de entradas debe coincidir con las clases de salida del modelo. Los fines de línea CRLF están bien. Cuando un modelo incrusta su propia lista de caracteres en metadatos, la inicialización compara cada entrada y su posición contra el archivo de diccionario, así que un diccionario que solo tenga la longitud correcta igual falla. El DLL nunca descarga un modelo faltante

HotPDF incluye el adaptador RapidOCR nativo junto con los adaptadores OCR basados en proceso, el page renderer que los alimenta y el escritor de la capa de texto Unicode invisible, 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 PDF de HotPDF para Delphi deja solo el DLL y sus archivos de modelo por desplegar