Articolo tecnico

Incorporare immagini AVIF, HEIF e JPEG XL nel PDF da Delphi

Una foto HEIC da un telefono finisce in un report generato con Delphi, il PDF sembra giusto a schermo, e la pagina stampata torna con rossi spostati e un logo ritagliato seduto su un box pieno. La foto è stata decodificata attraverso una bitmap di piattaforma lungo la strada; caricatela con AddModernImageFromFile in PDF Library for Delphi invece, e le immagini AVIF, HEIF e JPEG XL conservano alfa, profilo ICC e canali a 16 bit per predefinito

Questi formati sono arrivati nei flussi documentali per lo più attraverso i telefoni. Gli iPhone salvano HEIC per predefinito da anni, i dispositivi Android producono AVIF, e JPEG XL sta comparendo in pipeline di archiviazione e fotografia. Un generatore di report progettato attorno a JPEG e PNG ha due opzioni quando ne arriva uno: rifiutare il file, o aprirlo attraverso qualunque decoder il sistema operativo offra e accettare una bitmap appiattita a 8 bit. Questo articolo copre una terza strada, dove la libreria riconosce il formato da sé, lo decodifica attraverso un codec che scegliete e incorpora il risultato con profondità e dati colore intatti

Cosa perde un round trip in bitmap?

Una conversione in bitmap di piattaforma perde tre cose in un passo: trasparenza, il profilo colore incorporato e qualsiasi profondità di canale sopra 8 bit. Ognuna ha un flusso di lavoro che dipende da essa. L'alfa conta per loghi e ritagli di prodotto posti sopra il contenuto della pagina. Il profilo ICC conta per tutto ciò che sarà stampato o abbinato cromaticamente a un riferimento, perché senza di esso il viewer assume sRGB e un'immagine fotografica a gamut ampio viene reinterpretata. E i canali a 16 bit contano per immagini mediche, scientifiche e di ispezione, dove quantizzare a 8 bit cancella esattamente le gradazioni per cui l'immagine è stata catturata

Niente di questo produce un errore. La pagina si renderizza, la foto è riconoscibile, e il problema aspetta finché qualcuno confronta una stampa con l'originale. Ecco perché trattiamo la conservazione come predefinito invece che come qualcosa in cui i chiamanti optano: AddModernImageFromFile, AddModernImageFromStream e AddModernImageFromString prendono tutti un parametro Options che vale 8 per predefinito, e l'opzione 8 è l'impostazione che porta alfa, ICC e campioni a 16 bit nell'oggetto immagine PDF insieme

Diagramma PDF Library for Delphi che contrappone una conversione in bitmap di piattaforma che butta via alfa, profilo ICC e canali a 16 bit con il percorso immagine moderna che porta tutte e tre nell'oggetto immagine PDF
Una decodifica bitmap generica appiattisce in silenzio la trasparenza e quantizza i canali prima che la pagina si renderizzi

Un'immagine a 16 bit cambia anche il file che producite. PDF Library for Delphi solleva il documento ad almeno PDF 1.5 quando un'immagine porta campioni a 16 bit, dato che quella è la versione in cui 16 bit per componente sono diventati validi per gli image XObject. Se un sistema a valle pretende PDF 1.4, quel requisito e fotografie a 16 bit non possono essere soddisfatti insieme, ed è meglio scoprirlo in fase di design

Aggiungere una foto da telefono a una pagina

Le chiamate immagine moderna restituiscono un ID immagine maggiore di zero al successo e 0 al fallimento, e l'ID poi va a DrawImageAndRelease o alla consueta coppia SelectImage / DrawImage. Lo schema sotto include l'unico fallback di cui i veri upload da telefono hanno bisogno, spiegato subito dopo:

uses
  PDFlibrary;

var
  Lib: TPDFlib;
  ImageID: Integer;
begin
  Lib := TPDFlib.Create;
  try
    Lib.NewDocument;
    Lib.SetPageSize('A4');      // il NewDocument ha già creato la pagina 1
    Lib.SetOrigin(1);           // misura Top dal bordo superiore

    // Options vale 8 per predefinito: alfa, profilo ICC e canali a 16 bit
    ImageID := Lib.AddModernImageFromFile('uploads\pump-housing.heic');

    // L'estensione dice HEIC, ma i byte possono essere un JPEG ordinario
    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;

Il fallback esiste perché i nomi dei file mentono. I share sheet, le app di messaggistica e i moduli di upload convertono HEIC in JPEG in uscita mantenendo il nome originale, o rinominano i file come il modulo ricevente si aspetta. AddModernImageFromFile non guarda mai l'estensione. Ispeziona i primi byte, e se non sono AVIF, HEIF o JPEG XL restituisce 0 senza toccare il decoder. Un JPEG con un suffisso .heic quindi fallisce la chiamata moderna e riesce attraverso la generale AddImageFromFile, che annusa il contenuto allo stesso modo e gestisce JPEG, PNG, TIFF e gli altri formati classici

Perché non mandare tutto attraverso AddImageFromFile? Riconosce anch'essa i formati moderni, ma le chiamate moderne rendono l'intento esplicito e forniscono l'opzione 8 quando non passate nulla, quindi preferiamo vederle al sito di chiamata ogni volta che l'input dovrebbe essere una foto da telefono

Come la libreria distingue AVIF da HEIC?

PDF Library for Delphi decide il formato da una lettura limitata dell'header di al massimo 4096 byte e poi riporta la posizione dello stream del chiamante dov'era. JPEG XL è il caso facile: un codestream grezzo inizia con FF 0A, e la forma contenitore inizia con una signature box fissa di 12 byte. AVIF e HEIF sono più difficili, perché entrambi vivono nel formato file ISO base media, la stessa struttura di box di MP4, e differiscono solo nei brand elencati dentro il box ftyp

La trappola è che gli elenchi dei brand si sovrappongono. Un file AVIF di norma elenca mif1 tra i suoi compatible brand, perché AVIF è costruito sullo stesso profilo file immagine di HEIF. Un detector che restituisce HEIF nel momento in cui vede mif1 etichetterà male una gran quota di veri file AVIF. La libreria quindi prima scandisce l'intero elenco dei brand e lascia che avif o avis battano la famiglia HEIF (heic, heix, hevc, hevx, heim, heis, mif1, msf1)

Diagramma del cancello di rilevamento a magic number limitato che conferma AVIF, HEIF e JPEG XL prima che un backend di decodifica venga scelto da un percorso esplicito, variabili di ambiente, directory dell'eseguibile o callback Delphi registrata
Il rilevamento gira su una lettura limitata dell'header, quindi un eseguibile rinominato non raggiunge mai il codec

Eseguire il rilevamento prima della decodifica è anche una proprietà di sicurezza. Un input sconosciuto o travestito non raggiunge mai il codec esterno, quindi un eseguibile rinominato o un upload malformato viene mandato via da poche dozzine di confronti di byte invece che da un grande decoder di immagini che dovrebbe analizzarlo

Dove avviene la decodifica

PDF Library for Delphi non compila un codec AVIF, HEIF o JPEG XL in sé. Quei codec sono grandi, cambiano spesso, e un'applicazione che non vede mai una foto da telefono non dovrebbe pagare per loro. Il backend predefinito carica un modulo ImageMagick MagickWand in-process al primo uso e lo cerca in un ordine fisso: il file o la directory impostati tramite SetModernImageCodecLibrary, poi la variabile di ambiente PDFLIB_MODERN_IMAGE_CODEC, poi la directory dell'eseguibile, poi il normale percorso di ricerca di sistema. Su Windows prova CORE_RL_MagickWand_.dll, MagickWand-7.Q16HDRI-10.dll e MagickWand-7.Q16-10.dll in ogni posizione

Due conseguenze pratiche seguono. Spedite una build Q16 del codec, dato che una build con quantum a 8 bit non può consegnare campioni a 16 bit, qualunque opzione passiate. E se la directory del codec contiene una sottocartella modules\coders, la libreria riempie per voi MAGICK_HOME, MAGICK_CONFIGURE_PATH e MAGICK_CODER_MODULE_PATH, ma solo quelle variabili che il processo host non ha già impostato. Un'applicazione con il proprio layout di runtime lo conserva

La nostra raccomandazione è impostare il percorso esplicitamente e non contare sul percorso di ricerca di sistema. Una macchina che capita di avere un ImageMagick diverso su PATH altrimenti decide quale codec usa il vostro generatore di report, e quello è il tipo di differenza che affiora solo sul server di un cliente

Le applicazioni che spediscono già un decoder, o a cui non è permesso caricare un modulo esterno, registrano invece una callback. La callback è una funzione semplice che legge lo stream sorgente, scrive byte PNG nello stream di output e onora il flag di orientamento. La registrazione è a livello di processo e protetta da un lock, quindi fatela una volta all'avvio piuttosto che per documento:

uses
  Classes, PDFlibModernImage,
  AppCodec;  // la vostra unit che avvolge il codec che già spedite

function MyModernDecoder(InStream, OutPNG: TStream;
  ImageFormat: TPDFlibModernImageFormat;
  ApplyOrientation: Boolean): Boolean;
begin
  // InStream è posizionato a 0, OutPNG è vuoto
  Result := (ImageFormat <> mifUnknown) and
    AppDecodeToPNG(InStream, OutPNG, ApplyOrientation);
end;

initialization
  RegisterModernImageDecoderBackend(MyModernDecoder);

finalization
  ClearModernImageDecoderBackend;  // di nuovo al backend MagickWand

Quando un'immagine viene aggiunta a un documento, la libreria chiede sempre che l'orientamento venga applicato. Le fotocamere dei telefoni memorizzano di routine l'immagine del sensore di lato e registrano la rotazione intesa come metadato, quindi una callback che ignora ApplyOrientation produce foto in formato ritratto sdraiate di lato. Un backend fatto in casa sbaglia questo facilmente, e l'errore è facile da perdere quando le immagini di test erano state tutte scattate in orizzontale

Perché decodificare in PNG in memoria?

Il backend converte l'immagine decodificata in un PNG in memoria e passa quel PNG al percorso di incorporamento PNG esistente. Sembra una deviazione rispetto a consegnare un buffer di pixel grezzo, eppure è l'opzione corretta più economica. PNG può esprimere tutto ciò che deve sopravvivere (alfa, tipo colore, 8 o 16 bit per campione e un profilo ICC incorporato) e PDF Library for Delphi ha già una via matura dal PNG a un oggetto immagine PDF con i filtri giusti, soft mask e spazio colore. I formati moderni ereditano quel lavoro invece di prendersi un'implementazione parallela con i propri bug da trovare. L'output del decoder viene normalizzato a 16 bit quando la sorgente ha più di 8 bit per canale e a 8 bit altrimenti

Nessun file temporaneo viene scritto, quindi non c'è nulla da ripulire dopo un crash. Una magagna ha richiesto gestione esplicita. Durante lo sviluppo abbiamo trovato che il codec poteva perdere il profilo ICC mentre commutava l'immagine in memoria a PNG, il che avrebbe reintrodotto esattamente lo spostamento di colore che questo percorso esiste per prevenire. Il backend ora legge il profilo sorgente prima del cambio di formato, lo comprime con Flate, lo scrive in un chunk iCCP valido con CRC ricalcolato e rimuove ogni chunk sRGB che lo contraddirebbe. In un run Win64 su un vero AVIF, l'output ha conservato RGBA a 16 bit con alfa a 16 bit, e il profilo estratto dal PDF era di 60.960 byte con SHA-256 identico al profilo sorgente

Diagramma PDF Library for Delphi del ponte PNG in memoria che cattura il profilo ICC sorgente prima del cambio di formato, lo ricostruisce come chunk iCCP compresso, butta il chunk sRGB in conflitto e riusa il percorso collaudato di incorporamento PNG in PDF
Fotografare il profilo ICC prima del cambio di formato tiene la copia incorporata byte-identica alla sorgente

Controllare il codec all'avvio

Sondate il codec quando l'applicazione parte, prima che arrivi la prima fotografia. ModernImageCodecAvailable restituisce 1 quando c'è o una callback registrata o un modulo MagickWand caricabile, e SetModernImageCodecLibrary punta il loader su un file o una directory specifici:

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

  // Restituisce 0 una volta che un modulo codec è già caricato in questo 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;

Due comportamenti valgono la pena conoscere prima di collegare questo a un installer o a un servizio. Un caricamento fallito viene ricordato, quindi la libreria non scandisce di nuovo il disco per ogni immagine. Se il vostro servizio sonda prima che l'installer abbia finito di copiare la cartella del codec, continua a riportare il codec come non disponibile finché SetModernImageCodecLibrary viene chiamata di nuovo, il che cancella quel fallimento ricordato. Vale anche il contrario: una volta che un modulo si è caricato, SetModernImageCodecLibrary restituisce 0 e il percorso sta com'è per la vita del processo, perché scaricare un codec nativo sotto conversioni in corso non è qualcosa che vogliamo fare implicitamente

Occhio anche alla dimensione dell'output. Una foto RGBA a 16 bit con il suo profilo è un oggetto immagine grande, e un report con quaranta così diventa pesante in fretta. Per documenti che saranno letti solo a schermo, il downsampling prima dell'incorporamento è il cambio giusto, e le leve generali sulla dimensione sono trattate in ottimizzazione della dimensione dei file PDF. Anche la policy del colore merita una decisione deliberata. Conservare ogni profilo sorgente è corretto per lavoro di archiviazione e stampa, mentre convertire tutto in uno spazio unico a livello di documento sta bene a un set di fotografie da telefoni diversi che devono sembrare coerenti fianco a fianco; quella strada è descritta in ricolorare un documento in un altro spazio colore. Per confermare cosa è davvero atterrato nel file, il percorso di ispezione in estrazione di testo, immagini e font riporta gli oggetti immagine che un documento porta

L'input AVIF, HEIF e JPEG XL sta accanto a input PNG, JPEG, TIFF e WebP, conversione di spazio colore e ottimizzazione immagini nella stessa libreria per Delphi, C++Builder e Free Pascal. Licenze, supporto di piattaforma e il riferimento API completo sono sulla pagina del prodotto PDF Library for Delphi