Adapter RapidOCR de DLL nativa

O HPDFRapidOCRRecognition expõe uma IHPDFOCREngine em processo respaldada pela HotPDFRapidOCR.dll, com a mesma API pública em builds Win32 e Win64 de Delphi, C++Builder e FPC/Lazarus no Windows

A DLL executa inferência ONNX de CPU direto sobre snapshots de memória e mantém os modelos inicializados até que a interface da engine seja liberada; a implantação em runtime consiste na DLL nativa correspondente mais modelos e dicionário locais compatíveis

O adapter de processo Python existente continua disponível com as sobrecargas de factory originais

Factory e options

function HPDFCreateRapidOCRDLLOCREngine(const LibraryPath,
  ModelDirectory: string): IHPDFOCREngine; overload;
function HPDFCreateRapidOCRDLLOCREngine(const LibraryPath,
  ModelDirectory: string; const Options: THPDFRapidOCRDLLOptions): IHPDFOCREngine; overload;

THPDFRapidOCRDLLOptions = record
  DetectionModel: string;
  RecognitionModel: string;
  ClassificationModel: string;
  CharacterDictionary: string;
  UseAngleClassifier: Boolean;
  RightToLeft: Boolean;
  Threads: Integer;
  MaxPixels: Integer;
  TimeoutMilliseconds: Cardinal;
  class function Default: THPDFRapidOCRDLLOptions; static;
  class function ForLanguage(const Language: string): THPDFRapidOCRDLLOptions; static;
end;

Inicialize as options com THPDFRapidOCRDLLOptions.Default; os padrões usam os seguintes arquivos locais

Nomes de arquivo relativos são resolvidos contra o ModelDirectory; caminhos absolutos podem selecionar arquivos provisionados separadamente

A factory checa a disponibilidade dos arquivos, as options, os exports exigidos e a versão de ABI antes de inicializar os modelos; configuração inválida gera EArgumentException, e falhas de carregamento de modelo geram EInvalidOperation com um diagnóstico nativo

A inicialização dos modelos acontece na factory e fica fora do prazo de reconhecimento; as contagens de classes do dicionário precisam corresponder ao modelo de reconhecimento, e contagens de classes idênticas, sozinhas, não garantem que a ordem de caracteres ou o preprocessing sejam compatíveis

O pipeline fornecido usa detecção DB com lado máximo de detecção de 1.024 pixels e 50 pixels de padding branco; o recognizer aceita modelos NCHW compatíveis com altura de entrada fixa de 32 ou 48 e usa 48 para altura dinâmica

O reconhecimento preserva o aspect ratio para modelos de largura dinâmica e normaliza entradas com padding usando largura mínima de 320; um modelo de largura fixa limita a largura do crop redimensionado, o que pode comprimir uma linha de texto longa

A classificação de ângulo preserva o aspect ratio do crop dentro da largura de entrada do modelo e preenche os pixels não usados com zeros normalizados; um crop gira 180 graus apenas quando a pontuação de cabeça-para-baixo excede 0.9, evitando que previsões fracas de direção virem textos curtos

O dicionário precisa corresponder à ordem de caracteres do modelo e à contagem de classes de saída; line endings CRLF no dicionário são aceitos, mas um BOM UTF-8 é rejeitado

Quando o modelo embute metadados de caracteres, a factory também verifica cada entrada do dicionário e a ordem delas; só o tamanho do dicionário não basta

Chinês, russo e idiomas comuns

O THPDFRapidOCRDLLOptions.ForLanguage seleciona um modelo de reconhecimento e o dicionário correspondente abaixo do diretório local de modelos, mantendo os padrões compartilhados de detector, classificador, threads, pixels e timeout

O método aceita aliases de idioma sem diferenciar maiúsculas de minúsculas, troca underscores por hífens e remove espaços em volta; uma tag vazia ou não suportada gera EArgumentException antes de carregar os modelos

Todo perfil usa <profile>/recognition.onnx e <profile>/dictionary.txt; nomes de perfil são aceitos diretamente, e os aliases regionais reconhecidos são definidos explicitamente em vez de inferidos de um prefixo arbitrário

Instale os conjuntos de modelos selecionados antes da implantação com o helper de provisionamento com hashes SHA256 fixados

& tools/Install-RapidOCRModels.ps1 `
  -Destination C:/OCR/models `
  -Language ch,chinese_cht,en,latin,japan,korean,cyrillic,arabic,devanagari

O -Language All instala todos os nove perfis; o -SkipClassifier omite o classificador opcional, caso em que defina UseAngleClassifier := False ao criar uma engine

O helper verifica hashes SHA256 fixados e instala um detector e um classificador multilíngues compartilhados sob os nomes de arquivo raiz usados pelo Default; o reconhecimento roda offline e nunca baixa modelos ausentes automaticamente

Escolha o idioma da engine para cada página ou região; uma engine não detecta o idioma automaticamente nem combina recognizers separados para scripts diferentes

Os pacotes fixados usam modelos compatíveis com PP-OCRv3 e PP-OCRv4; a precisão do reconhecimento depende do modelo, da fonte, da resolução e do crop, e o modelo latino pode confundir acentos como ñ mesmo com entrada limpa

Modelos PP-OCRv5 mais novos podem exigir um ONNX Runtime mais novo do que as bibliotecas estáticas usadas para construir a DLL; um formato de modelo não suportado falha a inicialização com um diagnóstico

Modelos de detecção precisam aceitar um único tensor de imagem float32 e produzir um mapa de probabilidade float32 com shape [1, 1, H, W] na resolução de entrada redimensionada; tipos, dimensões ou valores não finitos incompatíveis, ou probabilidades fora de [0, 1] por mais de quatro epsilons de máquina float32, falham com um diagnóstico antes que os resultados de detecção sejam usados

Pequenos erros de arredondamento sigmoid dentro dessa tolerância são limitados a [0, 1] antes da limiarização e da pontuação de contornos, para que modelos válidos mantenham o comportamento normal de detecção deles

Exemplo em chinês

uses SysUtils, HPDFDoc, HPDFRapidOCRRecognition;

procedure AddNativeRapidOCRText(PDF: THotPDF);
var
  Engine: IHPDFOCREngine;
  Models: THPDFRapidOCRDLLOptions;
  Layer: THPDFOCRTextLayerOptions;
  Info: THPDFOCRTextLayerInfo;
begin
  Models := THPDFRapidOCRDLLOptions.ForLanguage('zh-CN');
  Models.UseAngleClassifier := False;
  Engine := HPDFCreateRapidOCRDLLOCREngine(
    'C:\OCR\Win64\HotPDFRapidOCR.dll', 'C:\OCR\models', Models);
  Layer := THPDFOCRTextLayerOptions.Default;
  if not PDF.ApplyLoadedOCRTextLayer([0], Engine, Layer, Info) then
    raise Exception.Create('Native RapidOCR text layer was not added');
end;

Mantenha a interface da engine entre as requisições para reutilizar os modelos dela; use uma DLL que corresponda à arquitetura da aplicação chamadora e forneça as dependências dela ao lado da DLL ou nos diretórios padrão de loader do Windows

Exemplo em russo

procedure AddRussianRapidOCRText(PDF: THotPDF);
var
  Engine: IHPDFOCREngine;
  Models: THPDFRapidOCRDLLOptions;
  Layer: THPDFOCRTextLayerOptions;
  Info: THPDFOCRTextLayerInfo;
begin
  Models := THPDFRapidOCRDLLOptions.ForLanguage('ru-RU');
  Engine := HPDFCreateRapidOCRDLLOCREngine(
    'C:\OCR\Win64\HotPDFRapidOCR.dll', 'C:\OCR\models', Models);
  Layer := THPDFOCRTextLayerOptions.Default;
  if not PDF.ApplyLoadedOCRTextLayer([0], Engine, Layer, Info) then
    raise Exception.Create('Russian RapidOCR text layer was not added');
end;

ru, ru-RU e rus selecionam o mesmo modelo e dicionário de reconhecimento cyrillic

Resultados e tempo de vida

O adapter copia o bitmap atual para um snapshot BGR top-down independente; ele checa dimensões e o orçamento de pixels antes de alocar e não modifica o bitmap emprestado

O pipeline nativo emite um resultado por linha de texto reconhecida, com limites em pixels da imagem original e a confiança média dos caracteres; cada linha consome uma vaga de MaxWords, e nenhuma baseline nativa é fornecida

As caixas detectadas seguem a ordem de leitura das linhas horizontais, da esquerda para a direita por padrão e da direita para a esquerda quando o RightToLeft está habilitado; o preset árabe habilita essa opção

A classificação de ângulo corrige crops de texto individuais; ela não determina a orientação da página inteira nem reordena as caixas de detecção separadas de uma página de cabeça-para-baixo na ordem de leitura lógica

O texto reconhecido permanece na ordem lógica Unicode do modelo; o adapter não inverte strings árabes automaticamente nem aplica shaping bidirecional

O adapter valida UTF-8, caracteres de controle Unicode, limites, confiança e o limite de MaxTextCodeUnits da requisição, com um teto rígido de texto de 1.048.576 unidades UTF-16; caracteres suplementares consomem duas unidades

Uma página vazia termina com sucesso e um array de resultados vazio; uma falha limpa os resultados parciais, e a publicação de PDF pesquisável mantém o comportamento atual de transação atômica de páginas

Chamadas na mesma engine são serializadas; a espera pelo lock da engine checa cancelamento e o prazo de reconhecimento a cada 25 milissegundos

Os callbacks nativos checam cancelamento e prazos antes e depois da detecção, da classificação e de cada linha reconhecida; uma chamada individual de inferência ONNX não pode ser interrompida à força, então o cancelamento pode retornar depois que o estágio atual terminar

Os limites de entrada e de texto restringem as alocações do adapter e a saída aceita, mas não impõem um teto rígido à memória de modelo, detecção, crop ou inferência

Build e ABI

O Native/RapidOCR contém a bridge C++, o recognizer de modelos compatível, o header C versionado, a definição de exports e o projeto CMake; provisione fontes de rede de CPU compatíveis expondo DbNet, AngleNet e OcrUtils, mais bibliotecas ONNX Runtime e OpenCV correspondentes

Use MSVC no Windows com C++17, um Windows SDK e CMake 3.20 ou mais novo; o build padrão usa a CRT release estática, que precisa corresponder às bibliotecas provisionadas

& tools/Build-HotPDFRapidOCR.ps1 `
  -NativeSourceDirectory C:/OCR/native-sources `
  -OnnxRuntimeDirectory C:/OCR/onnxruntime/windows-x64 `
  -OpenCVDirectory C:/OCR/opencv/x64/vc16/staticlib `
  -Platform Win64

O OnnxRuntimeDirectory precisa conter o OnnxRuntimeConfig.cmake, e o OpenCVDirectory precisa apontar para a configuração de bibliotecas específica da arquitetura; selecione Win32 e bibliotecas x86 correspondentes para uma DLL de 32 bits

O helper de build grava Lib/Native/RapidOCR/<Platform>/HotPDFRapidOCR.dll; -BuildDirectory, -OutputDirectory e -Generator podem mudar o local do build e o gerador do Visual Studio

A bridge contém as exceções C++ e expõe a ABI versão 1 por meio de HPDFRapidOCRAbiVersion, HPDFRapidOCRCreate, HPDFRapidOCRRecognize e HPDFRapidOCRDestroy; todos usam cdecl, valores de status de 32 bits e comprimentos explícitos de bytes UTF-8

A ABI versão 1 também define o export opcional HPDFRapidOCRSetReadingDirection; o adapter o exige apenas quando o RightToLeft está habilitado, então DLLs existentes ainda podem atender requisições da esquerda para a direita

Os callbacks emprestam o texto deles apenas pela duração da chamada; o adapter copia o texto validado antes de retornar, e o destrutor da engine destrói os modelos antes de descarregar a DLL

Validação

Com o pacote Python onnx e um build nativo com BUILD_TESTING, execute python tools/test_rapidocr_detector.py <build>/Release/NativeDetectorTests.exe para verificar saída em branco válida, ranks de tensor inválidos, canais e tipos, dimensões espaciais incompatíveis e probabilidades inválidas por meio da ABI da DLL; múltiplos caminhos de runner podem validar as duas arquiteturas em uma única invocação

Adicione -RapidOCRLanguageModelDirectory e um ou ambos os parâmetros de biblioteca da DLL nativa ao runner de adapter de Delphi ou FPC para validar todos os presets instalados com amostras em chinês, russo, japonês, coreano, idiomas latinos comuns, árabe e hindi; russo e chinês tradicional também passam por salvamento de PDF pesquisável, reload, extração de texto e comparação de pixels

Os runners de adapter de Delphi e FPC testam o tempo de vida persistente dos modelos, o layout de linhas BGR, caracteres Unicode e suplementares, checagens de ABI, resultados inválidos, orçamentos, cancelamento cooperativo, espera serializada de lock e limpeza

Forneça -RapidOCRNativeWin32Library, -RapidOCRNativeWin64Library e -RapidOCRNativeModelDirectory ao Tests/Delphi/Run-TesseractRecognitionTests.ps1 ou ao Tests/Delphi/Run-TesseractFPCRecognitionTests.ps1 para validação real de modelos, páginas vazias, tratamento de modelos danificados, reconhecimento de inglês e chinês e round trips de PDF pesquisável com pixels renderizados inalterados

Veja Camadas de texto OCR pesquisáveis para renderização de páginas, mapeamento de texto Unicode do PDF, agrupamento de optional content e restrições de conformidade