A PDF Library for Delphi aceita imagens AVIF, HEIF e JPEG XL como entrada através de AddModernImageFromFile e das suas variantes de fluxo e de string, preservando o alfa, o perfil ICC incorporado e os canais de 16 bits no caminho para dentro do objeto de imagem PDF. A deteção de formato acontece sobre uma leitura limitada de número mágico, e a descodificação corre através de um backend substituível, pelo que nada externo é invocado para um ficheiro que não seja realmente um desses formatos
Estes formatos chegaram aos fluxos de trabalho de documentos através dos telemóveis. O iOS produz HEIC por defeito há anos, os dispositivos Android produzem AVIF, e um técnico de campo que fotografa uma peça danificada envia uma imagem que um gerador de relatórios PDF construído em 2015 simplesmente não consegue abrir. O caminho de recurso genérico, descodificar através de um bitmap da plataforma, produz de forma consistente cor de 8 bits e perde o alfa e o perfil de cor pelo caminho
O que é que o caminho de imagem moderna preserva que uma conversão para bitmap perde?
Três coisas, e cada uma tem um fluxo de trabalho que depende dela. O alfa sobrevive, o que importa para logótipos e recortes de produto compostos sobre o conteúdo da página. O perfil ICC sobrevive, o que importa para tudo o que vá ser impresso ou correspondido em cor. E os canais de 16 bits sobrevivem, o que importa para imagens médicas e científicas onde a quantização a 8 bits destrói exatamente as gradações para as quais a imagem foi captada
Passar uma imagem por um bitmap da plataforma perde as três coisas num único passo, e fá-lo silenciosamente: o PDF resultante parece aproximadamente correto, e ninguém repara até uma gráfica perguntar por que razão o vermelho corporativo está errado. O valor de opção 8 nas chamadas de imagem moderna é o sinalizador que mantém o alfa, o ICC e os canais de 16 bits em conjunto, e é a predefinição para essas chamadas
Acrescentar uma imagem a uma página
A chamada devolve um identificador de imagem, que é depois selecionado e desenhado, ou desenhado e libertado num único passo:
uses
PDFlibrary, PDFlibModernImage;
var
Lib: TPDFlib;
ImageID: Integer;
begin
Lib := TPDFlib.Create;
try
Lib.NewDocument;
Lib.SetPageSize('A4');
Lib.NewPage;
// Options = 8 mantém o alfa, o ICC e os canais de 16 bits
ImageID := Lib.AddModernImageFromFile('site-photo.heic', 8);
if ImageID > 0 then
Lib.DrawImageAndRelease(ImageID, 40, 40, 515, 340)
else
Lib.DrawText(40, 40, 'image could not be decoded');
Lib.SaveToFile('inspection-report.pdf');
finally
Lib.Free;
end;
end;A deteção antecede a descodificação e é deliberadamente restrita. A biblioteca lê um cabeçalho limitado, reconhece as marcas de formato de ficheiro multimédia base ISO que identificam o AVIF e o HEIF, e reconhece tanto as assinaturas em bruto como as de contentor do JPEG XL, e depois restaura a posição de fluxo do chamador. Uma entrada desconhecida ou disfarçada nunca chega ao codec externo, o que impede que um executável renomeado seja entregue a um descodificador como se fosse uma fotografia
Onde é que a descodificação realmente acontece?
Os formatos de imagem modernos são codecs grandes e complexos, e colocar um deles dentro de uma biblioteca PDF seria uma escolha de design estranha. O backend predefinido carrega dinamicamente um módulo MagickWand implantável no mesmo processo e procura-o por uma ordem documentada: um ficheiro ou diretório explícito definido pelo utilizador, variáveis de ambiente, o diretório do executável, e o caminho de pesquisa do sistema
As aplicações que já incluem um descodificador, ou que não podem de todo carregar um módulo externo, registam em alternativa o seu próprio callback. O contrato é pequeno: ler o fluxo de entrada, escrever um PNG no fluxo de saída, respeitar a orientação pedida:
function MyDecoder(InStream, OutPNG: TStream;
ImageFormat: TPDFlibModernImageFormat;
ApplyOrientation: Boolean): Boolean;
begin
// Descodifique InStream com o seu próprio codec e escreva bytes PNG em OutPNG
Result := DecodeWithBundledCodec(InStream, OutPNG,
ImageFormat, ApplyOrientation);
end;
begin
RegisterModernImageDecoderBackend(MyDecoder);
// ... acrescentar imagens ...
ClearModernImageDecoderBackend; // voltar ao backend predefinido
end;A implantação recebe uma conveniência e uma contenção deliberada. Se o diretório do codec contiver um subdiretório modules\coders, a biblioteca preenche as variáveis de ambiente de codec que esse esquema exige, mas apenas quando a aplicação anfitriã ainda não as definiu. Uma aplicação com a sua própria estratégia de implantação de runtime mantém-na
Por que razão PNG no meio?
Fazer a ponte através de um PNG em memória em vez de um buffer de pixels em bruto parece um passo extra e é, na verdade, o passo correto mais económico. O PNG exprime tudo o que tem de sobreviver, alfa, tipo de cor, profundidade de bits e um perfil ICC incorporado, e a biblioteca já tem um caminho maduro e bem testado de PNG para um objeto de imagem PDF com os filtros e o espaço de cor corretos. Reutilizá-lo significa que os formatos modernos herdam anos de trabalho de correção em vez de receberem uma implementação paralela
A ponte fica inteiramente em memória, pelo que não são criados ficheiros temporários e não é preciso nenhuma limpeza numa falha. Uma particularidade exigiu tratamento explícito: algumas conversões descartam o perfil ICC ao mudar de formato. O backend captura, por isso, o perfil de origem antes da mudança de formato, comprime-o com Flate, constrói um bloco iCCP válido com um CRC recalculado, e remove qualquer bloco sRGB que entrasse em conflito com ele. Em testes, um AVIF descodificado manteve RGBA de 16 bits com alfa de 16 bits, e o perfil extraído do PDF resultante correspondeu ao perfil de origem byte a byte, com 60 960 bytes
Notas práticas antes de ativar isto em produção
Verifique a disponibilidade no arranque, não na primeira fotografia. ModernImageCodecAvailable reporta se um backend pode ser usado, e SetModernImageCodecLibrary aponta para um ficheiro ou diretório explícito quando a implantação coloca o codec algures fora do padrão:
Lib.SetModernImageCodecLibrary('C:\MyApp\codecs');
if Lib.ModernImageCodecAvailable = 0 then
Log('modern image input unavailable - HEIC and AVIF will be refused');Fique atento ao tamanho do ficheiro do resultado. Uma imagem RGBA de 16 bits com um perfil incorporado é um objeto de imagem PDF grande, e um relatório com quarenta destas será grande. Quando o documento se destina a visualização em ecrã e não a impressão, reduzir a resolução antes de incorporar é a opção certa, e as alavancas gerais de tamanho estão descritas em otimização do tamanho de ficheiro PDF
Por fim, decida a política de cor deliberadamente. Manter o perfil de origem é correto para trabalho de arquivo e de impressão; converter para um espaço à escala do documento é correto quando um conjunto misto de fotografias tem de parecer consistente, e o percurso de conversão está descrito em recolorir um documento para outro espaço de cor. Se precisar de confirmar o que realmente ficou no ficheiro, o percurso de inspeção em extração de texto, imagem e fonte reporta os objetos de imagem que um documento transporta
A entrada de imagem moderna, a gestão de cor e a otimização de imagem fazem parte da mesma biblioteca para Delphi, C++Builder e Free Pascal; a lista completa de funcionalidades está na página da PDF Library for Delphi