Artigo Técnico

Renderizar páginas PDF em bitmap no Delphi com HotPDF

Uma faixa de miniaturas para um lote de notas fiscais de fornecedores parece certa de relance: réguas de tabela no lugar, logo nítido, colunas alinhadas. Dê zoom em uma e o nome do cliente é uma fileira de caixas vazias, enquanto a coluna de totais guarda letras que não soletram nada. Toda nota fiscal quebrada usa a mesma fonte, ABCDEF+Arial, e todas são lidas sem problema em um visualizador de PDF de desktop na mesma máquina. O código de miniatura pegou o nome da fonte, descartou a tag de subset de seis letras, pediu Arial ao Windows e entregou a ele os códigos de caractere brutos da página. Esses códigos nunca foram da Arial. Tirar um bitmap fiel de uma página de PDF exige duas coisas: rodar o content stream da página como um programa, e desenhar texto dos contornos de glifo guardados no arquivo em vez de das fontes que a máquina de renderização por acaso tem instaladas

Uma página PDF é algo que você executa

A ISO 32000-1 §8 descreve uma página como um content stream: operadores que mudam a matriz de transformação com cm, salvam e restauram o estado gráfico com q e Q, constroem caminhos, selecionam fontes com Tf, posicionam glifos com Tj, e pintam imagens e forms com Do. Nada no arquivo registra como qualquer pixel parece. Para obter um bitmap, algo precisa rodar esse stream contra uma matriz de transformação atual, uma pilha de estados, um caminho de recorte e um par de espaços de cor de preenchimento e traço, e então rasterizar o que sair

O RenderLoadedPageToBitmap do HotPDF é esse interpretador. Ele percorre os operadores de uma página carregada, mantém a matriz e o estado gráfico do jeito que a especificação os define, resolve espaços de cor, transforma caminhos de PDF em caminhos GDI, e pega os avanços de glifo do array /Widths da fonte em vez de do GDI. Image XObjects passam pelos mesmos decodificadores que a biblioteca usa para extração, então todo filtro de imagem que o HotPDF decodifica para extração, imagens JPEG 2000 comprimidas com JPXDecode incluídas, também aparece na página renderizada

Pipeline de renderização de página do HotPDF: um interpretador de content stream de PDF acompanha a matriz de transformação, estado gráfico, espaços de cor, caminhos, larguras de glifo e contornos de glifo incorporados, e retorna um TBitmap RGB de 24 bits pertencente a quem chamou
Cada operador atualiza a matriz, o estado gráfico, a cor, o caminho ou o estado de texto que toca, e o resultado é um bitmap pertencente a quem chamou

Renderizando uma página carregada em um TBitmap no Delphi

O THotPDF.RenderLoadedPageToBitmap(PageIndex, DPI) recebe um índice de página zero-based e uma resolução em pontos por polegada, em que 72 DPI mapeia uma unidade PDF para um pixel, e retorna um novo TBitmap RGB de 24 bits. Um índice fora da faixa ou uma página que não pode ser construída retorna nil em vez de levantar exceção. Isso serve a um viewer, que deve pular uma página danificada e seguir com o resto. O bitmap pertence a quem chamou

var
  Pdf: THotPDF;
  Bmp: TBitmap;
begin
  Pdf := THotPDF.Create(nil);
  try
    if Pdf.LoadFromFile('report.pdf') > 0 then
    begin
      Bmp := Pdf.RenderLoadedPageToBitmap(0, 144);  // primeira página a 144 DPI
      if Bmp <> nil then
      try
        Image1.Picture.Assign(Bmp);
      finally
        Bmp.Free;  // quem chamou é dono do bitmap retornado
      end;
    end;
  finally
    Pdf.Free;
  end;
end;

As dimensões em pixels seguem da área visível da página. O renderizador recebe a /CropBox recortada pela /MediaBox, como a ISO 32000-1 §14.11.2 define a região visível, usa a /MediaBox quando não há crop box utilizável, escala por DPI/72 e arredonda para cima. Uma página US Letter sem crop box separado portanto volta com exatamente 612×792 pixels a 72 DPI. Uma página A4 (595.28×841.89 pontos) a 96 DPI dá 794×1123, porque 793.7 e 1122.5 ambos arredondam para cima. Um /Rotate de 90 ou 270 troca largura e altura, e o flip da origem inferior esquerda do PDF para a superior esquerda do GDI acontece dentro da matriz da página, então a imagem chega em pé sem pós-processamento

O DPI é o único botão de escala, e cobre os trabalhos comuns. Miniaturas a 36 ou 48 DPI são pequenas e rápidas. Uma prévia de tela a 96 ou 144 DPI casa com a densidade típica de exibição. Exportação a 300 DPI dá saída de qualidade de impressão, ao preço de um bitmap de 2550×3300 para cada página Letter, cerca de 24 MiB cada a três bytes por pixel

Por que fontes substituídas desenham os glifos errados?

Glifos errados em um PDF renderizado quase sempre significam que o rasterizador trocou uma fonte instalada pela embutida no arquivo. O atalho do exemplo da nota fiscal é tentador porque frequentemente funciona: retire o prefixo de subset do /BaseFont, peça uma fonte GDI pelo nome restante, desenhe a string. Para texto Arial ou Times New Roman comum com codificação padrão, ninguém reclama

Fontes subset quebram isso primeiro. Um subset pode carregar apenas os quarenta glifos que um documento usa, numerados em uma ordem privada daquele arquivo, então o código 1 pode ser "T" e o código 2 "h". Uma fonte instalada não pode saber disso. Codificações personalizadas, fontes de símbolos e barcode, e qualquer typeface ausente da máquina de renderização falham pela mesma razão. E mesmo quando a substituta tem todo caractere, os avanços dela diferem da face incorporada, então linhas crescem ou encolhem e colunas alinhadas à direita param de se alinhar

HotPDF: A substituição por fonte do sistema remove o prefixo de subset de ABCDEF+Arial e desenha glifos errados, enquanto a renderização de glifos incorporados reproduz os contornos do FontFile para formas exatas
A substituição sobrevive apenas em faces de sistema comuns e falha exatamente nas fontes subset que tornaram a incorporação necessária

Desenhando texto a partir do programa de fonte incorporado

O HotPDF desenha texto dos programas de fonte guardados no PDF. Quando uma fonte carrega um programa TrueType incorporado (/FontFile2) ou um programa CFF (/FontFile3), cada glifo é delineado desses dados e preenchido como um caminho GDI, com tamanho de fonte, matriz de texto e matriz de transformação atual compostos em uma única transformação. Fontes subset, codificações privadas e faces que a máquina nunca viu saem com as formas reais delas. Como um código de caractere chega a um glifo depende do tipo de fonte, e cada tipo tem a própria armadilha:

  • Contornos TrueType: contornos vêm das tabelas glyf e loca. Segmentos quadráticos são elevados às Béziers cúbicas que o GDI desenha, o que é uma conversão exata, o ponto implícito na curva entre dois pontos fora da curva consecutivos é reconstruído, e glifos compostos recursam nos componentes deles com a transformação de cada componente aplicada
  • TrueType com chave CID: fontes Type0 sobre CIDFontType2 chegam aos IDs de glifo por /CIDToGIDMap, seja Identity (também o padrão quando a entrada falta) ou um stream de mapa explícito, e recebem avanços de /W e /DW, então texto Identity-H de dois bytes avança a quantidade certa. CMaps CJK predefinidos e streams de CMap incorporados decodificam códigos de comprimento variável antes da consulta
  • Programas CFF: Type1C, CIDFontType0C e CFF embrulhado em um container OpenType passam por um interpretador de charstrings Type 2 que trata linhas, curvas, a família flex, máscaras de hint, e chamadas de sub-rotinas locais e globais com o viés de sub-rotina aplicado. Programas com chave CID mapeiam cada código pelo charset da fonte, o que importa para subsets cuja ordem de glifos difere da ordem de CIDs, e selecionam o dicionário privado por glifo via FDArray e FDSelect
  • Fontes TrueType simples: códigos de um byte passam pelo cmap incorporado, tentando as subtables Unicode (3,1) e (3,10) primeiro, depois a subtable de símbolos (3,0) tanto direto quanto no espelho U+F000 que fontes de símbolos usam, depois a tabela Macintosh antiga (1,0)

Duas regras ficam por cima disso. O dicionário /Encoding de uma fonte simples é resolvido na ordem que a ISO 32000-1 §9.6.6 prescreve: /Differences sobrepõe a codificação base, que sobrepõe o mapeamento embutido do programa. TeX e outras toolchains derivadas de PostScript dependem muito disso, então errar a ordem embaralha exatamente o texto de matemática e símbolos em que um glifo errado é mais difícil de notar. Fontes Type3, cujos glifos são pequenos content streams próprios, são reproduzidas pelo mesmo interpretador com matriz de fonte, tamanho de fonte e matriz de texto compostos; /Widths em espaço de glifo passam pela /FontMatrix como a §9.6.5 exige, e um procedimento de glifo que declara uma bounding box d1 é recortado a ela, então um glifo de barcode malformado não consegue pintar fora da célula dele

Quando um único código não pode ser mapeado, porque o programa está danificado ou o subset não tem aquele glifo, aquele único caractere é desenhado com a fonte instalada de mesmo nome e o resto da sequência ainda usa os contornos incorporados. Descartar a sequência inteira esconderia o problema; uma letra estranha é mais fácil de notar. Fontes sem programa incorporado utilizável seguem a rota de fonte instalada descrita em renderizar fontes não incorporadas com faces do sistema

Como manter renders repetidos rápidos?

Para qualquer coisa interativa, chame o RenderLoadedPageToBitmapCached em vez do método simples. Ele mantém páginas renderizadas recentemente em um cache most-recently-used com chave por índice de página, DPI e configurações de render atuais (intent de cor, prévia de overprint, política de fallback e quais camadas de optional content estão visíveis), e um hit devolve uma cópia nova pertencente a quem chamou sem interpretar o content stream de novo. Alternar entre duas páginas, ou um resize que pede a mesma página de novo no mesmo DPI, acerta o cache toda vez. Para uma exportação de uso único que visita cada página uma vez, o RenderLoadedPageToBitmap simples é a chamada melhor, já que a variante em cache copia todo bitmap que retorna e manteria por perto páginas que ninguém vai pedir de novo

HotPDF: Fluxo do cache MRU de páginas renderizadas: um hit retorna uma cópia nova de TBitmap sem reinterpretar a página, um miss renderiza e guarda até RenderCacheCapacity páginas
Um hit de cache pula o content stream por completo, enquanto invalidação e orçamento de memória mantêm renders repetidos corretos e seguros
// Faixa de miniaturas: a primeira passada renderiza, voltar a rolar acerta o cache
Pdf.RenderCacheCapacity := 32;   // limite de entradas; o padrão é 8
for I := 0 to Pdf.LoadedPageCount - 1 do
begin
  Bmp := Pdf.RenderLoadedPageToBitmapCached(I, 48);
  if Bmp <> nil then
  try
    ThumbList.AddThumbnail(I, Bmp);  // código de UI seu
  finally
    Bmp.Free;
  end;
end;

// Cacheando páginas de 300 DPI também? Dê ao cache raster um orçamento de bytes maior
// (Policy: THPDFCacheAdmissionPolicy)
if Pdf.GetCacheAdmissionPolicy(clkRaster, Policy) then
begin
  Policy.MaxTotalBytes := Int64(512) * 1024 * 1024;
  Pdf.SetCacheAdmissionPolicy(clkRaster, Policy);
end;

// Depois de mudar o conteúdo da página direto:
Pdf.InvalidateRenderedPageCache;  // o próximo render reflete a edição

O RenderCacheCapacity é apenas um de dois limites. O cache raster também tem um orçamento de bytes, 128 MiB por padrão, com teto de 64 MiB por entrada, e conta quatro bytes por pixel ao orçar. Suponha um viewer cacheando páginas Letter a 300 DPI: cada entrada é contada como cerca de 32 MiB, então apenas três cabem, diga o que disser o RenderCacheCapacity. A 48 DPI a mesma página é contada como cerca de 0.82 MiB, e até 32 miniaturas do loop acima ficam residentes em menos de 27 MiB. Quando o cache está cheio, uma página pedida uma vez pode não deslocar uma página pedida com frequência; ela ainda é renderizada e devolvida, só não é mantida. Se um viewer vira páginas em uma ordem previsível, o PrefetchLoadedPages enche o mesmo cache em uma worker thread antes do usuário

Carregar um documento novo limpa o cache. Várias das chamadas de edição de página da própria biblioteca, como FlattenLoadedFormFields, descartam as páginas afetadas por si; depois de qualquer mudança que você fizer em objetos de página ou content streams direto, chame InvalidateRenderedPageCache, porque o cache não consegue saber que os bytes atrás de uma página mudaram. Por baixo fica um segundo repositório para image XObjects decodificados, limitado por ImageCacheMaxBytes (32 MiB por padrão), então um logo ou timbre repetido em toda página decodifica uma vez por carga de documento em vez de uma vez por operador Do. O InvalidateRenderedPageCache limpa esse também. Se as miniaturas devem sobreviver a uma reinicialização da aplicação, o tier de disco do cache de render cobre esse caso

Descobrindo quando uma página foi aproximada

A maioria das páginas nunca aciona um fallback, porque o renderizador cobre muito mais que texto e imagens. Espaços de cor CalGray, CalRGB, Lab e baseados em ICC são convertidos com o rendering intent em vigor, que o RenderColourIntent pode sobrepor, e o ConfigureRenderICCWorkflow recebe perfis ICC de proof e saída para soft-proofing. Paletas indexadas, tintas Separation e DeviceN e consultas de cor de função Type 0 amostrada estão cobertas. Shadings baseados em função, axiais, radiais e mesh renderizam tanto pelo operador sh quanto por padrões de shading, e grupos de transparência, grupos knockout e soft masks de alpha ou luminosidade são compostos com os blend modes deles, como descrito em grupos de blend mode e máscaras de luminosidade

Arquivos reais ainda contêm coisas que não podem ser desenhadas exatamente: um recurso que a página nomeia mas nunca define, uma imagem cujos dados falham ao decodificar, um Form XObject que se pinta. O RenderFallbackPolicy decide o que acontece então. O padrão, rfpIgnore, desenha a aproximação mais próxima e segue. O rfpReport faz o mesmo mas registra um diagnóstico para cada fallback, até RenderFallbackDiagnosticLimit entradas (256 por padrão). O rfpStrict levanta uma exceção em vez de retornar um bitmap aproximado. Aninhamento de forms para em 32 níveis e um form que se refere a si é pulado, então um arquivo quebrado ou hostil não consegue recursar sem fim

// rfpReport e THPDFRenderFallbackDiagnostics são declarados em HPDFPageRenderer
var
  Diags: THPDFRenderFallbackDiagnostics;
  J: Integer;
begin
  Pdf.RenderFallbackPolicy := rfpReport;
  Bmp := Pdf.RenderLoadedPageToBitmap(PageIndex, 150);
  try
    Diags := Pdf.GetLastRenderFallbackDiagnostics;
    for J := 0 to High(Diags) do
      Log.Add(Format('page %d: %s %s - %s', [PageIndex + 1,
        string(Diags[J].OperatorName), string(Diags[J].ObjectName),
        string(Diags[J].Reason)]));
    if Pdf.LastRenderFallbackDroppedCount > 0 then
      Log.Add(Format('%d more fallbacks not recorded',
        [Pdf.LastRenderFallbackDroppedCount]));
  finally
    Bmp.Free;  // Free é seguro com nil
  end;
end;

Rode builds de QA e de ingestão com rfpReport. O bitmap é idêntico ao que o rfpIgnore produz, e o log mostra quais páginas foram aproximadas e por quê, antes de um cliente reportar que a página 14 parece estranha. Deixe o rfpStrict para conversão para arquivamento, em que uma página silenciosamente aproximada é pior que uma que falhou. Um hit de cache restaura os diagnósticos gravados quando aquela página foi renderizada pela primeira vez, então o GetLastRenderFallbackDiagnostics dá a mesma resposta tenham ou não a variante em cache feito algum trabalho

O RenderLoadedPageToBitmap, a variante em cache e o caminho de texto com glifos incorporados fazem parte do HotPDF Delphi Component, uma biblioteca VCL nativa para Delphi e C++Builder sem DLLs externas, que também cria, edita e extrai texto dos mesmos documentos carregados que você renderiza