Artigo Técnico

Incorporar imagens AVIF, HEIF e JPEG XL em PDF no Delphi

Uma foto HEIC de um celular entra em um relatório gerado em Delphi, o PDF parece certo na tela, e a página impressa volta com vermelhos deslocados e um logo recortado em cima de uma caixa sólida. A foto foi decodificada por um bitmap de plataforma a caminho de dentro; carregue-a com AddModernImageFromFile no PDF Library for Delphi em vez disso, e imagens AVIF, HEIF e JPEG XL mantêm alfa, o perfil ICC e canais de 16 bits por padrão

Esses formatos chegaram aos fluxos de documento majoritariamente pelos celulares. iPhones salvam HEIC por padrão há anos, aparelhos Android produzem AVIF, e o JPEG XL está aparecendo em pipelines de arquivamento e fotografia. Um gerador de relatórios desenhado em torno de JPEG e PNG tem duas opções quando um deles chega: recusar o arquivo, ou abri-lo pelo decodificador que o sistema operacional oferecer e aceitar um bitmap achatado de 8 bits. Este artigo cobre uma terceira rota, em que a biblioteca reconhece o formato ela mesma, decodifica por um codec que você escolhe e incorpora o resultado com os dados de profundidade e cor intactos

O que uma ida e volta por bitmap perde?

Uma conversão por bitmap de plataforma perde três coisas em um passo: transparência, o perfil de cores incorporado e qualquer profundidade de canal acima de 8 bits. Cada uma delas tem um fluxo de trabalho que depende dela. O alfa importa para logos e recortes de produto postos sobre conteúdo da página. O perfil ICC importa para qualquer coisa que será impressa ou comparada por cor contra uma referência, porque sem ele o visualizador assume sRGB e uma imagem de câmera wide-gamut é reinterpretada. E os canais de 16 bits importam para imagens médicas, científicas e de inspeção, onde quantizar para 8 bits apaga exatamente as gradações para as quais a imagem foi capturada

Nada disso produz um erro. A página renderiza, a foto é reconhecível, e o problema espera até alguém comparar a impressão com o original. É por isso que tratamos a preservação como padrão, e não como algo que quem chama precisa optar: AddModernImageFromFile, AddModernImageFromStream e AddModernImageFromString recebem todos um parâmetro Options que assume 8, e a opção 8 é a configuração que leva alfa, ICC e amostras de 16 bits juntos ao objeto de imagem do PDF

Diagrama do PDF Library for Delphi comparando uma conversão de bitmap de plataforma que descarta alfa, o perfil ICC e os canais de 16 bits com o caminho de imagem moderno que carrega os três no objeto de imagem do PDF
Uma decodificação genérica de bitmap achata silenciosamente a transparência e quantiza os canais antes mesmo de a página ser renderizada

Uma imagem de 16 bits também muda o arquivo que você produz. O PDF Library for Delphi eleva o documento para pelo menos PDF 1.5 quando uma imagem carrega amostras de 16 bits, já que essa é a versão em que 16 bits por componente se tornaram válidos para image XObjects. Se um sistema a jusante insiste em PDF 1.4, esse requisito e fotografias de 16 bits não podem ser satisfeitos ao mesmo tempo, e é melhor descobrir em tempo de design

Adicionando a foto de um celular a uma página

As chamadas de imagem moderna retornam um ID de imagem maior que zero em sucesso e 0 em falha, e o ID então vai para o DrawImageAndRelease ou para o par usual SelectImage / DrawImage. O esboço abaixo inclui o único fallback que uploads reais de celular precisam, explicado logo depois:

uses
  PDFlibrary;

var
  Lib: TPDFlib;
  ImageID: Integer;
begin
  Lib := TPDFlib.Create;
  try
    Lib.NewDocument;
    Lib.SetPageSize('A4');      // o NewDocument já criou a página 1
    Lib.SetOrigin(1);           // mede o Top a partir da borda superior

    // Options assume 8: alfa, perfil ICC e canais de 16 bits
    ImageID := Lib.AddModernImageFromFile('uploads\pump-housing.heic');

    // A extensão diz HEIC, mas os bytes podem ser um JPEG comum
    if ImageID = 0 then
      ImageID := Lib.AddImageFromFile('uploads\pump-housing.heic', 0);

    if ImageID > 0 then
      Lib.DrawImageAndRelease(ImageID, 40, 40, 515, 340)
    else
      Lib.DrawText(40, 40, 'Photo could not be decoded');

    Lib.SaveToFile('inspection-report.pdf');
  finally
    Lib.Free;
  end;
end;

O fallback existe porque nomes de arquivo mentem. Folhas de compartilhamento, apps de mensagens e formulários de upload convertem HEIC para JPEG na saída mantendo o nome original, ou renomeiam arquivos para o que o formulário receptor espera. O AddModernImageFromFile nunca olha a extensão. Ele inspeciona os primeiros bytes, e se não forem AVIF, HEIF ou JPEG XL retorna 0 sem tocar no decodificador. Um JPEG vestindo um sufixo .heic portanto falha na chamada moderna e tem sucesso pela AddImageFromFile geral, que fareja o conteúdo da mesma forma e trata JPEG, PNG, TIFF e os outros formatos clássicos

Por que não mandar tudo pelo AddImageFromFile? Ele também reconhece os formatos modernos, mas as chamadas modernas deixam a intenção explícita e fornecem a opção 8 quando você não passa nada, então preferimos vê-las no ponto de chamada sempre que a entrada deve ser uma foto de celular

Como a biblioteca distingue AVIF de HEIC?

O PDF Library for Delphi decide o formato a partir de uma leitura limitada de cabeçalho de no máximo 4096 bytes e depois devolve a posição do stream de quem chama para onde estava. O JPEG XL é o caso fácil: um codestream bruto começa com FF 0A, e a forma contêiner começa com uma signature box fixa de 12 bytes. AVIF e HEIF são mais difíceis, porque ambos vivem no ISO base media file format, a mesma estrutura de boxes do MP4, e diferem apenas nas brands listadas dentro do box ftyp

A armadilha é que as listas de brands se sobrepõem. Um arquivo AVIF normalmente lista mif1 entre as suas compatible brands, porque o AVIF é construído sobre o mesmo image file profile que o HEIF. Um detector que retorna HEIF no momento em que vê mif1 vai rotular errado uma grande parte dos arquivos AVIF reais. A biblioteca portanto varre a lista de brands inteira primeiro e deixa avif ou avis vencer a família HEIF (heic, heix, hevc, hevx, heim, heis, mif1, msf1)

Diagrama do portão de detecção limitada por magic number que confirma AVIF, HEIF e JPEG XL antes de escolher um backend de decodificação a partir de um caminho explícito, variáveis de ambiente, diretório do executável ou um callback Delphi registrado
A detecção roda sobre uma leitura limitada do cabeçalho, de modo que um executável renomeado nunca chega ao codec

Rodar a detecção antes da decodificação também é uma propriedade de segurança. Uma entrada desconhecida ou disfarçada nunca chega ao codec externo, então um executável renomeado ou um upload malformado é barrado por algumas dezenas de comparações de bytes em vez de por um decodificador de imagens grande que teria de analisá-lo

Onde a decodificação acontece

O PDF Library for Delphi não compila um codec AVIF, HEIF ou JPEG XL dentro de si. Esses codecs são grandes, mudam com frequência, e uma aplicação que nunca vê uma foto de celular não deveria pagar por eles. O backend padrão carrega um módulo ImageMagick MagickWand no processo na primeira utilização e o procura em uma ordem fixa: o arquivo ou diretório definido via SetModernImageCodecLibrary, depois a variável de ambiente PDFLIB_MODERN_IMAGE_CODEC, depois o diretório do executável, depois o caminho de busca normal do sistema. No Windows, ele tenta CORE_RL_MagickWand_.dll, MagickWand-7.Q16HDRI-10.dll e MagickWand-7.Q16-10.dll em cada local

Duas consequências práticas se seguem. Distribua um build Q16 do codec, pois um build de quantum de 8 bits não consegue entregar amostras de 16 bits, não importa a opção que você passe. E se o diretório do codec contém uma subpasta modules\coders, a biblioteca preenche MAGICK_HOME, MAGICK_CONFIGURE_PATH e MAGICK_CODER_MODULE_PATH para você, mas apenas as variáveis que o processo hospedeiro ainda não definiu. Uma aplicação com layout de runtime próprio mantém o dele

Nossa recomendação é definir o caminho explicitamente e não depender do caminho de busca do sistema. Uma máquina que por acaso tem um ImageMagick diferente no PATH decidirá qual codec o seu gerador de relatórios usa, e esse é o tipo de diferença que só aparece no servidor de um cliente

Aplicações que já distribuem um decodificador, ou que não podem carregar um módulo externo, registram um callback em vez disso. O callback é uma função simples que lê o stream de origem, escreve bytes PNG no stream de saída e honra a flag de orientação. O registro é no nível do processo e protegido por um lock, então faça-o uma vez na inicialização em vez de por documento:

uses
  Classes, PDFlibModernImage,
  AppCodec;  // unit sua que embrulha o codec que você já distribui

function MyModernDecoder(InStream, OutPNG: TStream;
  ImageFormat: TPDFlibModernImageFormat;
  ApplyOrientation: Boolean): Boolean;
begin
  // InStream está posicionado em 0, OutPNG está vazio
  Result := (ImageFormat <> mifUnknown) and
    AppDecodeToPNG(InStream, OutPNG, ApplyOrientation);
end;

initialization
  RegisterModernImageDecoderBackend(MyModernDecoder);

finalization
  ClearModernImageDecoderBackend;  // volta ao backend MagickWand

Quando uma imagem é adicionada a um documento, a biblioteca sempre pede que a orientação seja aplicada. Câmeras de celular rotineiramente guardam a imagem do sensor de lado e registram a rotação pretendida como metadado, então um callback que ignora o ApplyOrientation produz fotos em retrato deitadas de lado. Um backend caseiro erra isso facilmente, e o erro é fácil de perder quando as imagens de teste foram todas tiradas em paisagem

Por que decodificar para PNG em memória?

O backend converte a imagem decodificada em um PNG em memória e alimenta esse PNG pelo caminho de incorporação de PNG existente. Isso parece um desvio comparado a entregar um buffer de pixels bruto, mas é a opção correta mais barata. O PNG consegue expressar tudo o que precisa sobreviver (alfa, color type, 8 ou 16 bits por amostra e um perfil ICC incorporado) e o PDF Library for Delphi já tem uma rota madura de PNG para objeto de imagem PDF com os filtros certos, soft mask e espaço de cores. Os formatos modernos herdam esse trabalho em vez de ganhar uma implementação paralela com os seus próprios bugs para achar. A saída do decodificador é normalizada para 16 bits quando a origem tem mais de 8 bits por canal e para 8 bits caso contrário

Nenhum arquivo temporário é escrito, então não há nada a limpar depois de uma queda. Uma rugosidade precisou de tratamento explícito. Durante o desenvolvimento, descobrimos que o codec podia descartar o perfil ICC ao trocar a imagem em memória para PNG, o que teria reintroduzido exatamente o deslocamento de cor que esse caminho existe para evitar. O backend agora lê o perfil de origem antes da troca de formato, comprime com Flate, escreve em um chunk iCCP válido com CRC recalculado e remove qualquer chunk sRGB que o contradissesse. Em uma execução Win64 sobre um AVIF real, a saída manteve RGBA de 16 bits com alfa de 16 bits, e o perfil extraído do PDF tinha 60.960 bytes com SHA-256 idêntico ao do perfil de origem

Diagrama do PDF Library for Delphi da ponte PNG em memória que captura o perfil ICC de origem antes da troca de formato, o reconstrói como um chunk iCCP comprimido, descarta o chunk sRGB conflitante e reutiliza o caminho comprovado de incorporação de PNG em PDF
Capturar o perfil ICC antes da mudança de formato mantém a cópia incorporada byte a byte idêntica à origem

Conferindo o codec na inicialização

Sondar o codec quando a aplicação inicia, antes da primeira fotografia chegar. O ModernImageCodecAvailable retorna 1 quando um callback registrado ou um módulo MagickWand carregável está presente, e o SetModernImageCodecLibrary aponta o carregador para um arquivo ou diretório específico:

procedure CheckModernImageSupport(Lib: TPDFlib);
var
  CodecDir: string;
begin
  CodecDir := ExtractFilePath(ParamStr(0)) + 'codecs';

  // Retorna 0 depois que um módulo de codec já foi carregado neste processo
  if Lib.SetModernImageCodecLibrary(CodecDir) = 0 then
    Log('Codec already loaded, path change ignored');

  if Lib.ModernImageCodecAvailable = 0 then
    Log('No AVIF/HEIF/JPEG XL decoder in ' + CodecDir +
      ' - phone photos will be rejected');
end;

Dois comportamentos valem a pena conhecer antes de ligar isso a um instalador ou a um serviço. Uma carga falha é lembrada, então a biblioteca não varre o disco de novo para cada imagem. Se o seu serviço sonda antes de o instalador terminar de copiar a pasta do codec, ele continua reportando o codec como indisponível até que o SetModernImageCodecLibrary seja chamado de novo, o que limpa essa falha lembrada. O oposto também vale: depois que um módulo carregou, o SetModernImageCodecLibrary retorna 0 e o caminho fica como está pela vida do processo, porque descarregar um codec nativo sob conversões em andamento não é algo que queiramos fazer implicitamente

Fique de olho no tamanho da saída também. Uma foto RGBA de 16 bits com o perfil dela é um objeto de imagem grande, e um relatório com quarenta delas fica pesado rápido. Para documentos que só serão lidos na tela, downsampling antes de incorporar é a troca certa, e as alavancas gerais de tamanho estão cobertas em otimização de tamanho de arquivo PDF. A política de cores também merece uma decisão deliberada. Manter cada perfil de origem é o correto para trabalho de arquivamento e impressão, enquanto converter tudo para um espaço único de documento serve para um conjunto de fotografias de celulares diferentes que precisam parecer consistentes lado a lado; essa rota está descrita em recolorir um documento para outro espaço de cores. Para confirmar o que realmente chegou ao arquivo, o caminho de inspeção em extração de texto, imagem e fonte reporta os objetos de imagem que um documento carrega

Entrada AVIF, HEIF e JPEG XL fica ao lado de entrada PNG, JPEG, TIFF e WebP, conversão de espaço de cores e otimização de imagens na mesma biblioteca para Delphi, C++Builder e Free Pascal. Licenciamento, suporte a plataformas e a referência completa da API estão na página do produto PDF Library for Delphi