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
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)
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
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