Adaptador nativo de DLL do RapidOCR

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

A DLL executa inferência ONNX de CPU diretamente sobre snapshots de memória e mantém os modelos inicializados até a interface do motor ser libertada; a implantação em runtime consiste na DLL nativa correspondente e em modelos locais e dicionário compatíveis

O adaptador de processo Python existente permanece disponível com as respetivas overloads originais de factory

Factory e opções

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 opções com THPDFRapidOCRDLLOptions.Default; as predefinições usam os seguintes ficheiros locais

Nomes de ficheiro relativos resolvem-se contra ModelDirectory; caminhos absolutos podem selecionar ficheiros aprovisionados separadamente

A factory verifica a disponibilidade dos ficheiros, as opções, os exports necessários e a versão da ABI antes de inicializar os modelos; configuração inválida gera EArgumentException, e falhas de carregamento de modelos geram EInvalidOperation com um diagnóstico nativo

A inicialização dos modelos ocorre na factory e está fora do prazo de reconhecimento; as contagens de classes do dicionário têm de corresponder ao modelo de reconhecimento, e contagens de classes idênticas, por si só, não estabelecem que a ordem de carateres ou o pré-processamento são compatíveis

O pipeline fornecido usa deteção DB com um lado máximo de deteção de 1,024 píxeis e 50 píxeis de preenchimento branco; o reconhecedor aceita modelos NCHW compatíveis com altura de entrada fixa de 32 ou 48 e usa 48 para altura dinâmica

O reconhecimento preserva a proporção para modelos de largura dinâmica e normaliza entradas preenchidas com uma largura mínima de 320; um modelo de largura fixa limita a largura do recorte redimensionado, o que pode comprimir uma linha de texto longa

O dicionário tem de corresponder à ordem de carateres e à contagem de classes de saída do modelo; fins de linha CRLF no dicionário são aceites, mas um BOM UTF-8 é rejeitado

Quando o modelo incorpora metadados de carateres, a factory também verifica cada entrada do dicionário e a respetiva ordem; o tamanho do dicionário, por si só, é insuficiente

A classificação de ângulo preserva a proporção do recorte dentro da largura de entrada do modelo e preenche os píxeis não usados com zeros normalizados; um recorte roda 180 graus apenas quando a pontuação de cabeça-para-baixo excede 0.9, impedindo previsões fracas de direção de virarem texto curto

Chinês, russo e idiomas comuns

THPDFRapidOCRDLLOptions.ForLanguage seleciona um modelo de reconhecimento e o dicionário correspondente abaixo do diretório local de modelos, mantendo as predefinições partilhadas de detetor, classificador, threads, píxeis e timeout

O método aceita aliases de idioma insensíveis a maiúsculas e minúsculas, troca sublinhados por hífenes e corta espaços em branco nas extremidades; uma etiqueta vazia ou não suportada gera EArgumentException antes de carregar modelos

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

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

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

-Language All instala todos os nove perfis; -SkipClassifier omite o classificador opcional, caso em que deve definir UseAngleClassifier := False ao criar um motor

O helper verifica os hashes SHA256 fixados e instala um detetor e um classificador multilingues partilhados sob os nomes de ficheiro de raiz usados por Default; o reconhecimento corre offline e nunca descarrega modelos em falta automaticamente

Escolha o idioma do motor para cada página ou região; um motor não deteta automaticamente o idioma nem combina reconhecedores separados para scripts diferentes

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

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

Os modelos de deteção têm de aceitar um único tensor de imagem float32 e produzir um mapa de probabilidades float32 com a forma [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 de os resultados de deteção serem usados

Pequenos erros de arredondamento sigmoidal 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 possam manter o seu comportamento normal de deteção

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;

Retenha a interface do motor entre pedidos para reutilizar os respetivos modelos; use uma DLL que corresponda à arquitetura da aplicação chamadora e forneça as dependências dela ao lado ou nos diretórios padrão do 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 de reconhecimento e dicionário cyrillic

Resultados e tempo de vida

O adaptador copia o bitmap atual para um snapshot BGR independente, de cima para baixo; verifica as dimensões e o orçamento de píxeis antes da alocação e não modifica o bitmap emprestado

O pipeline nativo emite um resultado por linha de texto reconhecida, com limites em píxeis da imagem original e a confiança média dos carateres; cada linha consome um lugar de MaxWords, e nenhuma linha de base nativa é fornecida

As caixas detetadas seguem a ordem de leitura das linhas horizontais, da esquerda para a direita por predefinição e da direita para a esquerda quando RightToLeft está ativado; a predefinição de árabe ativa esta opção

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

O texto reconhecido mantém-se na ordem Unicode lógica do modelo; o adaptador não inverte automaticamente cadeias em árabe nem aplica modelação bidirecional

O adaptador valida UTF-8, carateres de controlo Unicode, limites, confiança e o limite MaxTextCodeUnits do pedido, com um teto rígido de texto de 1,048,576 unidades UTF-16; carateres suplementares consomem duas unidades

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

As chamadas ao mesmo motor são serializadas; a espera pelo lock do motor verifica o cancelamento e o prazo de reconhecimento a cada 25 milissegundos

Os callbacks nativos verificam cancelamento e prazos antes e depois da deteção, da classificação e de cada linha reconhecida; uma chamada individual de inferência ONNX não pode ser interrompida à força, pelo que o cancelamento pode chegar depois de a fase atual terminar

Os limites de entrada e de texto limitam as alocações do adaptador e a saída aceite, mas não impõem um teto rígido à memória de modelos, deteção, recortes ou inferência

Compilação e ABI

Native/RapidOCR contém a ponte C++, o reconhecedor de modelos compatível, o cabeçalho C com versões, a definição de exports e o projeto CMake; aprovisione fontes de redes CPU compatíveis que exponham DbNet, AngleNet e OcrUtils, mais bibliotecas ONNX Runtime e OpenCV correspondentes

Use MSVC para Windows com C++17, um Windows SDK e CMake 3.20 ou posterior; a compilação predefinida usa a CRT estática de release, que tem de corresponder às bibliotecas aprovisionadas

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

OnnxRuntimeDirectory tem de conter OnnxRuntimeConfig.cmake, e OpenCVDirectory tem de 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 compilação escreve Lib/Native/RapidOCR/<Platform>/HotPDFRapidOCR.dll; -BuildDirectory, -OutputDirectory e -Generator podem sobrepor a localização da compilação e o gerador do Visual Studio

A ponte contém as exceções C++ e expõe a ABI versão 1 através de HPDFRapidOCRAbiVersion, HPDFRapidOCRCreate, HPDFRapidOCRRecognize e HPDFRapidOCRDestroy; todas usam cdecl, valores de estado de 32 bits e comprimentos de bytes UTF-8 explícitos

A ABI versão 1 também define o export opcional HPDFRapidOCRSetReadingDirection; o adaptador só o exige quando RightToLeft está ativado, pelo que DLLs existentes podem continuar a servir pedidos da esquerda para a direita

Os callbacks emprestam o texto apenas durante a chamada; o adaptador copia o texto validado antes de devolver, e o destruidor do motor destrói os modelos antes de descarregar a DLL

Validação

Com o pacote Python onnx e uma compilação nativa com BUILD_TESTING, execute python tools/test_rapidocr_detector.py <build>/Release/NativeDetectorTests.exe para verificar saída em branco válida, ranks de tensores, canais e tipos inválidos, dimensões espaciais não correspondentes e probabilidades inválidas através da ABI da DLL; vários caminhos de runner podem validar ambas as arquiteturas numa única invocação

Acrescente -RapidOCRLanguageModelDirectory e um ou ambos os parâmetros de biblioteca da DLL nativa ao runner de adaptadores Delphi ou FPC para validar todas as predefinições instaladas com amostras em chinês, russo, japonês, coreano, línguas latinas comuns, árabe e hindi; o russo e o chinês tradicional passam também por gravação, recarregamento, extração de texto e comparação de píxeis de PDF pesquisável

Os runners de adaptadores Delphi e FPC testam o tempo de vida persistente de modelos, o layout BGR de linhas, carateres Unicode e suplementares, verificações de ABI, resultados inválidos, orçamentos, cancelamento cooperativo, espera serializada pelo lock e limpeza

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

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