Artigo Técnico

OCR com Tesseract DLL no HotPDF: a C API do Delphi

Um timeout de reconhecimento de 5.000 ms numa chamada Tesseract in-process não significa que a chamada volta depois de cinco segundos. Com um conjunto grande de models multi-idioma, a thread chamadora pode ficar dentro da library nativa bem além dessa marca, porque o progress monitor que força o deadline é consultado enquanto palavras estão sendo reconhecidas, e o carregamento de models e a análise de layout da página acontecem antes da primeira consulta. Esse vão, um cancel callback cujo tipo C de retorno é um único byte, e um iterator que entrega memória que você nunca deve liberar são o trabalho real de binding da C API do Tesseract para Delphi. O resto é encanamento

Ligando a DLL Tesseract numa camada de texto do HotPDF

O HotPDF expõe o caminho in-process como HPDFCreateTesseractDLLOCREngine na unit HPDFTesseractRecognition. A factory carrega uma DLL Tesseract que exporta a C API, dirige TessBaseAPIInit2, TessBaseAPIRecognize e o result iterator, e retorna uma IHPDFOCREngine. O THotPDF.ApplyLoadedOCRTextLayer recebe essa engine e adiciona uma camada de texto Unicode invisível e pesquisável às páginas escaneadas, a mesma chamada por que toda engine OCR do HotPDF passa

A factory valida cedo. O arquivo da DLL e o diretório tessdata têm de existir. O identificador de idioma pode conter só letras ASCII, dígitos, _ e +, e todo model numa combinação como chi_sim+eng precisa de um arquivo .traineddata correspondente. Todos os 21 exports requeridos têm de resolver antes de você receber uma engine de volta. Erros de configuração levantam EArgumentException, com export ou model faltante reportado pelo nome; uma DLL que não carrega levanta EOSError levando o código de erro do Windows e uma dica para checar arquitetura e dependências

uses
  SysUtils, HPDFDoc, HPDFTesseractRecognition;

procedure MakeSearchable(const SourceFile, TargetFile: string);
var
  Doc: THotPDF;
  Engine: IHPDFOCREngine;
  Options: THPDFOCRTextLayerOptions;
  Info: THPDFOCRTextLayerInfo;
begin
  // Uma aplicação Win64 precisa de uma DLL de 64 bits; o nome de arquivo depende do seu build,
  // e as DLLs de dependência dele vão na mesma pasta
  Engine := HPDFCreateTesseractDLLOCREngine('C:\OCR\Win64\libtesseract.dll',
    'C:\OCR\tessdata', 'chi_sim+eng');   // usa THPDFTesseractOptions.Default
  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 vazia significa todas as páginas; páginas que já têm texto são puladas
    if not Doc.ApplyLoadedOCRTextLayer([], Engine, Options, Info) then
      raise Exception.Create(string(Info.Diagnostic));
    Writeln(string(Info.EngineName), ': ', Info.AcceptedWordCount,
      ' words accepted, ', Info.DroppedWordCount, ' dropped');
    Doc.SaveLoadedDocument(TargetFile);
  finally
    Doc.Free;
  end;
end;

O THPDFTesseractOptions.Default define PageSegMode para tpsAuto, EngineMode para temDefault, TimeoutMilliseconds para 60.000 e MaxPixels para 16.777.216. Esse budget de pixels morde mais cedo do que se espera. Uma página US Letter no default de 300 DPI renderiza para 2.550 × 3.300 pixels, cerca de 8,4 milhões, e cabe. Suponha que você suba a mesma página para 600 DPI: ela vira 5.100 × 6.600, aproximadamente 33,7 milhões de pixels, e a engine rejeita com Invalid Tesseract DLL OCR request or pixel budget antes de o Tesseract ver a imagem. Ou você sobe o MaxPixels (o teto é 67.108.864) ou fica em 300 DPI, que é farto para corpo de texto; cada lado também é limitado a 32.767 pixels

A DLL é carregada com LoadLibraryEx e as flags de busca para a própria pasta da DLL mais os default safe directories. As image libraries das quais o Tesseract depende podem então ficar ao lado dele, e você nunca precisa tocar no PATH nem confiar no diretório corrente. O HotPDF não embute nem baixa uma runtime OCR ou qualquer language model; você provisiona os dois

O que o caminho da DLL muda comparado com o tesseract.exe

O mesmo recognizer também é alcançável através do adapter tesseract.exe externo que escreve um BMP e parseia TSV. Os dois adapters alimentam um mesmo pipeline de camada de texto, então mapeamento de coordenadas, filtragem de confidence e o commit all-or-nothing se comportam igual. O que difere é como os pixels entram, como as palavras saem, e o que acontece quando o recognizer se porta mal

AspectoAdapter tesseract.exeAdapter DLL Tesseract
FactoryHPDFCreateTesseractOCREngineHPDFCreateTesseractDLLOCREngine
Pixels entrandoArquivo BMP num diretório temporário privadoBuffer grayscale 8-bit na memória
Palavras saindoTSV por palavra, limitado a 64 MiBResult iterator, UTF-8 por palavra
BaselinesNão estão no TSV; o pipeline as estimaPassthrough de TessPageIteratorBaseline
Page segmentation e engine modeOverload de THPDFTesseractOptions, enviado como --psm e --oemTHPDFTesseractOptions, enviado ao TessBaseAPISetPageSegMode e ao TessBaseAPIInit2
Budget de pixelsMaxPixels quando options são passadasMaxPixels sempre, mais 32.767 pixels por lado
TimeoutDuro: o processo filho é terminadoCooperativo: o Tesseract tem de notar
Isolamento de crash e memóriaProcesso separadoNenhum, compartilha o seu address space

Um custo fica com a DLL. Cada chamada Recognize cria a própria instância de API e roda TessBaseAPIInit2, então os language models são inicializados a cada página. O file cache tira o peso do reload, mas com um conjunto grande de models multi-idioma isso continua sendo o maior custo fixo por página, e é cobrado do deadline de reconhecimento. A engine DLL RapidOCR in-process faz a escolha oposta e mantém os models ONNX residentes por toda a vida da engine, enquanto os problemas de fronteira (C ABI, buffers emprestados, trabalho nativo que você não pode interromper) pertencem à mesma família

Então qual entra em produção? Para uma ferramenta desktop ou um job em lote trabalhando por algumas centenas de scans, a DLL é o melhor encaixe: sem lançamento de processo por página, sem bitmap temporário em disco, e baselines reais para linhas inclinadas. Um server de longa duração que aceita PDFs de estranhos deve ficar no tesseract.exe, porque um crash nativo ou uma alocação fugida ali derruba um processo filho em vez do seu serviço

Por que o Delphi não pode copiar a struct de monitor do Tesseract?

O Delphi não pode espelhar com segurança o progress monitor do Tesseract, porque o ETEXT_DESC carrega campos internos que variam entre builds do Tesseract. Um record traduzido à mão de um header põe o cancel callback e o deadline nos offsets que aquele header usava. Rode contra um build diferente e o Tesseract lê o seu callback pointer de um campo que agora significa outra coisa, ou nunca encontra o deadline, e o reconhecimento simplesmente roda até o fim

O adapter do HotPDF por isso trata o monitor como um pointer opaco e o toca só através de funções exportadas: TessMonitorCreate, TessMonitorSetCancelThis, TessMonitorSetCancelFunc, TessMonitorSetDeadlineMSecs e TessMonitorDelete. O esboço abaixo é código de binding seu, não API do HotPDF; as declarações dele casam com as que o adapter resolve com GetProcAddress

Tratamento do monitor pela DLL Tesseract do HotPDF: copiar o record ETEXT_DESC dependente de versão põe o cancel callback e o deadline em offsets errados e falha silenciosamente, enquanto o HotPDF trata o monitor como opaco, dirige TessMonitorCreate, TessMonitorSetCancelThis, TessMonitorSetCancelFunc e TessMonitorSetDeadlineMSecs, e mantém o callback cdecl livre de exceções
Um pointer opaco mais cinco exports é todo o contrato; o callback continua um Boolean de um byte que só lê uma flag e um relógio
type
  // C: typedef bool (*TessCancelFunc)(void *cancel_this, int words);
  TTessCancelFunc = function(CancelThis: Pointer; Words: Integer): Boolean; cdecl;
  TTessMonitorCreate = function: Pointer; cdecl;   // ETEXT_DESC*, nunca desreferenciado
  TTessMonitorDelete = procedure(Monitor: Pointer); cdecl;
  TTessMonitorSetCancelFunc = procedure(Monitor: Pointer; Func: TTessCancelFunc); cdecl;
  TTessMonitorSetCancelThis = procedure(Monitor, CancelThis: Pointer); cdecl;
  TTessMonitorSetDeadlineMSecs = procedure(Monitor: Pointer; MSecs: Integer); cdecl;
  TTessBaseAPIRecognize = function(Handle, Monitor: Pointer): Integer; cdecl;

  // Estado do seu job, não é um tipo do HotPDF
  TOCRJob = record
    CancelRequested: Boolean;
    DeadlineTick: UInt64;
  end;
  POCRJob = ^TOCRJob;

function ShouldCancel(CancelThis: Pointer; Words: Integer): Boolean; cdecl;
begin
  // Roda na stack do Tesseract: leia uma flag e o relógio, nunca levante exceção
  Result := (CancelThis = nil) or POCRJob(CancelThis)^.CancelRequested or
    (GetTickCount64 >= POCRJob(CancelThis)^.DeadlineTick);
end;

// Uso, com os function pointers resolvidos por GetProcAddress:
//   Monitor := MonitorCreate();
//   try
//     MonitorSetCancelThis(Monitor, @Job);
//     MonitorSetCancelFunc(Monitor, ShouldCancel);
//     MonitorSetDeadlineMSecs(Monitor, RemainingMs);
//     RC := BaseAPIRecognize(API, Monitor);
//   finally
//     MonitorDelete(Monitor);
//   end;

O esboço tipa o callback como Boolean, um byte tanto no Delphi quanto no Free Pascal, o que casa com o bool C do TessCancelFunc. O BOOL Windows de quatro bytes e o LongBool do Delphi parecem intercambiáveis e são um tipo diferente: quando um lado escreve um único byte e o outro lê quatro, os três bytes superiores são o que quer que o register segurasse antes, e um false pode chegar como true. O TessPageIteratorBoundingBox retorna um int, declarado como Integer do lado Pascal, então leia o tipo C de cada valor de retorno em vez de assumir uma regra para a API inteira

O callback também nunca levanta exceção. Uma exceção Delphi fazendo unwinding pelos frames C++ do Tesseract é undefined behavior. O callback do HotPDF lê só o cancellation token e um valor monotônico de GetTickCount64, e o adapter transforma o resultado num diagnóstico de cancelamento ou timeout depois de o TessBaseAPIRecognize retornar. Ele roda essa checagem quer o código de retorno nativo fosse 0 ou não

Quais pointers nativos o lado Delphi possui?

O adapter DLL Tesseract do HotPDF possui três objetos nativos por request (a instância de API, o monitor e o result iterator) e toma emprestado todo o resto. Cada chamada Recognize cria o próprio conjunto e o libera num bloco finally numa ordem fixa: TessResultIteratorDelete, depois TessMonitorDelete, depois TessBaseAPIDelete. Liberar a interface da engine chama FreeLibrary na DLL

Propriedade de objetos nativos da DLL Tesseract do HotPDF por chamada Recognize: o result iterator, o monitor e a instância de API são possuídos e liberados nessa ordem dentro de finally, o page iterator do TessResultIteratorGetPageIterator é uma vista emprestada que nunca deve ser liberada, e strings do GetUTF8Text são copiadas e devolvidas via TessDeleteText
Três objetos possuídos, todo o resto emprestado: libere na ordem fixa, nunca faça double-free do page iterator, e nunca misture allocators
  • O TessResultIteratorGetPageIterator retorna uma vista para dentro do result iterator em vez de um objeto novo. O adapter o usa para TessPageIteratorBoundingBox e TessPageIteratorBaseline e nunca o libera; apagá-lo também liberaria a mesma memória duas vezes
  • O TessResultIteratorGetUTF8Text retorna uma string alocada pela própria runtime da DLL. O adapter a decodifica e devolve via TessDeleteText num bloco finally, porque FreeMem Pascal a liberaria no heap errado
  • O texto de palavra passa por decodificação UTF-8 estrita com checagem de comprimento antes. Uma palavra com caracteres de controle, UTF-8 malformado, uma box fora da imagem, um retângulo invertido ou uma confidence fora de 0–100 falha o request; o adapter não remenda
  • O texto por request é limitado a 1.048.576 code units UTF-16, e a contagem de palavras tem de caber no budget que o ApplyLoadedOCRTextLayer repassa com cada página

A confidence chega como 0–100 e é escalada para 0–1, então o THPDFOCRTextLayerOptions.MinimumConfidence significa a mesma coisa para toda engine. Quando o Tesseract reporta uma baseline, os dois endpoints passam direto, e para uma palavra predominantemente vertical a largura da box é usada como altura do texto. Sem baseline o pipeline da camada de texto cai na estimativa geométrica dele, exatamente como faz para input TSV

Checando faixas de enum options antes de elas chegarem à DLL

A factory copia os bytes crus de PageSegMode e EngineMode para um Integer antes de checar as faixas. Um compilador está no direito de assumir que uma variável enum sempre segura um valor declarado, então um teste como Ord(X) > Ord(High(T)) escrito direto contra o enum pode ser dobrado para uma constante false. Esses ordinais chegam à DLL como inteiros crus: o THPDFTesseractPageSegMode segue a numeração de page segmentation do Tesseract de 0 a 13 e o THPDFTesseractEngineMode a numeração de engine mode de 0 a 3. Um record de options limpo com FillChar, lido de um stream, ou preenchido do C++Builder através de um cast para inteiro pode carregar um byte como 200, e validar a cópia transforma isso num EArgumentException na hora da factory. A factory também rejeita tpsOSDOnly e tpsAutoOnly, que não retornam palavras, e exige osd.traineddata para tpsAutoOSD e tpsSparseTextOSD

O que o timeout de reconhecimento realmente garante?

O timeout da DLL Tesseract é cooperativo: o HotPDF pode parar o próprio trabalho e pedir ao Tesseract que pare, mas não pode forçar código nativo a retornar. O relógio começa quando o Recognize começa, então a conversão grayscale e a inicialização de models bebem do mesmo budget que o reconhecimento. O adapter confere tempo decorrido e o cancellation token a cada 64 linhas durante a conversão grayscale, depois da inicialização, e antes de cada palavra enquanto caminha pelos resultados. Logo antes do TessBaseAPIRecognize ele passa os milissegundos restantes ao TessMonitorSetDeadlineMSecs

O vão mora dentro das chamadas nativas. O Tesseract consulta o monitor dele só durante o reconhecimento de palavras, então dentro do TessBaseAPIInit2 ou da análise de layout um carregamento lento de model ou um layout patológico pode passar do deadline antes de o timeout ser reportado. Os budgets de pixel e output também não limitam o uso de memória da própria library nativa. Quando você precisa de um worker que pode ser morto de uma vez, o adapter de processo é a ferramenta

Anatomia do timeout cooperativo da DLL Tesseract do HotPDF: o relógio começa quando o Recognize começa e cobre conversão grayscale, TessBaseAPIInit2 e análise de layout, mas o monitor só é consultado durante o reconhecimento de palavras, então cargas de model e layout podem extrapolar antes de o HotPDF reportar otlsEngineError ou otlsCancelled
Um deadline aqui é um pedido, não uma garantia: init e análise de layout podem demorar, e um worker que você possa matar de verdade precisa do adapter de processo

Page segmentation é onde o adapter da DLL compensa em input esquisito. Formulários, etiquetas e tabelas escaneadas com campos espalhados costumam reconhecer melhor com tpsSparseText do que com segmentação automática, que tenta montar colunas e parágrafos que não estão lá. O timeout abaixo é curto para uma página de formulário e ainda assim tem de cobrir a inicialização de models

procedure OCRFormPages(Doc: THotPDF; const Pages: array of Integer);
var
  Engine: IHPDFOCREngine;
  TessOptions: THPDFTesseractOptions;
  LayerOptions: THPDFOCRTextLayerOptions;
  Info: THPDFOCRTextLayerInfo;
begin
  TessOptions := THPDFTesseractOptions.Default;
  TessOptions.PageSegMode := tpsSparseText;  // campos espalhados, sem montagem de colunas
  TessOptions.EngineMode := temLSTMOnly;     // precisa de models LSTM no tessdata
  TessOptions.TimeoutMilliseconds := 20000;  // inclui inicialização de models
  Engine := HPDFCreateTesseractDLLOCREngine('C:\OCR\Win64\libtesseract.dll',
    'C:\OCR\tessdata', 'eng+deu', TessOptions);

  LayerOptions := THPDFOCRTextLayerOptions.Default;
  LayerOptions.MinimumConfidence := 0.6;
  if not Doc.ApplyLoadedOCRTextLayer(Pages, Engine, LayerOptions, Info) then
    case Info.Status of
      otlsCancelled:
        Writeln('OCR cancelled, document unchanged');
      otlsEngineError:
        if Pos('timed out', string(Info.Diagnostic)) > 0 then
          Writeln('Tesseract timed out, document unchanged')
        else
          Writeln('Tesseract failed: ', string(Info.Diagnostic));
    else
      Writeln(string(Info.Diagnostic));
    end;
end;

Um timeout aparece como otlsEngineError com Tesseract DLL OCR timed out no diagnóstico. Um token definido via THPDFOCRTextLayerOptions.CancellationToken aparece como otlsCancelled. Nos dois casos o ApplyLoadedOCRTextLayer reconhece todas as páginas selecionadas antes de começar o commit, então uma falha na página 40 de 50 deixa o documento carregado exatamente como estava. tpsSingleLine, tpsSingleBlock e tpsSparseText mudam só a segmentação; nenhum deles endireita um scan inclinado

Free Pascal e Lazarus: pixels velhos e chinês perdido

Ambas as factories Tesseract funcionam em builds Win32 e Win64 de Free Pascal e Lazarus no Windows depois de o pacote Lazarus ser rebuildado para a arquitetura alvo; o port geral é coberto em HotPDF em Free Pascal e Lazarus Win64. O tratamento de input é onde o FPC se comporta diferente

Um TBitmap LCL escrito via scanlines pode atualizar a raw image dele sem atualizar o handle do bitmap Windows, então GetDIBits nesse handle devolve os pixels velhos. O sintoma desconcerta: texto desenhado direto num bitmap é reconhecido, uma página renderizada via scanlines não produz palavras. No FPC o adapter da DLL lê um snapshot consciente de formato via CreateIntfImage, que respeita o pixel format e a ordem de linhas da raw image. O build Delphi mantém o caminho GetDIBits numa cópia privada de 24 bits, e nenhum dos builds modifica o bitmap do caller

O adapter tesseract.exe encontra um problema diferente. O TStringList do FPC armazena strings ANSI, então atribuir texto TSV UTF-8 decodificado a Lines.Text descarta todo caractere chinês ou de plano suplementar que a página de código ANSI do sistema não represente. O caminho FPC mantém o TSV como bytes UTF-8, remove o BOM a nível de byte e decodifica cada palavra para UnicodeString por conta própria. O adapter da DLL nunca encontra o problema, já que decodifica cada palavra direto do iterator

O adapter DLL Tesseract vem junto dos adapters de processo e da engine OCR integrada no HotPDF para Delphi, C++Builder e Free Pascal. Edições e downloads estão listados na página do HotPDF Delphi PDF component