Article technique

Images AVIF, HEIF et JPEG XL dans un PDF depuis Delphi

Une photo HEIC d'un téléphone entre dans un rapport généré en Delphi, le PDF a l'air juste à l'écran, et la page imprimée revient avec des rouges décalés et un logo détouré posé sur une boîte pleine. La photo a été décodée via un bitmap de plateforme en chemin ; chargez-la avec AddModernImageFromFile dans PDF Library for Delphi à la place, et les images AVIF, HEIF et JPEG XL gardent l'alpha, le profil ICC et les canaux 16 bits par défaut

Ces formats ont atteint les flux documentaires surtout par les téléphones. Les iPhones sauvent du HEIC par défaut depuis des années, les appareils Android produisent du AVIF, et le JPEG XL pointe dans les pipelines d'archivage et de photographie. Un générateur de rapports conçu autour du JPEG et du PNG a deux options quand un tel fichier arrive : refuser le fichier, ou l'ouvrir via le décodeur que le système offre et accepter un bitmap aplati en 8 bits. Cet article couvre une troisième voie, où la bibliothèque reconnaît elle-même le format, le décode via un codec que vous choisissez et incorpore le résultat avec ses données de profondeur et de couleur intactes

Que perd un aller-retour bitmap ?

Une conversion bitmap de plateforme perd trois choses en une étape : la transparence, le profil de couleur incorporé et toute profondeur de canal au-delà de 8 bits. Chacune a un flux de travail qui en dépend. L'alpha compte pour les logos et les détourés de produits posés sur du contenu de page. Le profil ICC compte pour tout ce qui sera imprimé ou raccordé en couleur à une référence, car sans lui le lecteur suppose du sRGB et une image caméra à large gamut est réinterprétée. Et les canaux 16 bits comptent pour l'imagerie médicale, scientifique et de contrôle, où quantifier en 8 bits efface exactement les gradations pour lesquelles l'image a été capturée

Rien de tout cela ne produit une erreur. La page se rend, la photo est reconnaissable, et le problème attend que quelqu'un compare une impression à l'original. Voilà pourquoi nous traitons la préservation comme le défaut plutôt que comme quelque chose que les appelants activent : AddModernImageFromFile, AddModernImageFromStream et AddModernImageFromString prennent tous un paramètre Options qui vaut 8 par défaut, et l'option 8 est le réglage qui porte alpha, ICC et échantillons 16 bits ensemble dans l'objet image PDF

Diagramme PDF Library for Delphi comparant une conversion bitmap de plateforme qui perd l'alpha, le profil ICC et les canaux 16 bits avec le chemin d'image moderne qui transporte les trois dans l'objet image PDF
Un décodage bitmap générique aplatit silencieusement la transparence et quantifie les canaux avant même le rendu de la page

Une image 16 bits change aussi le fichier que vous produisez. PDF Library for Delphi élève le document à au moins PDF 1.5 quand une image porte des échantillons 16 bits, puisque c'est la version où 16 bits par composant est devenu valide pour les XObjects image. Si un système aval exige du PDF 1.4, cette exigence et des photos 16 bits ne peuvent pas être satisfaites ensemble, et il vaut mieux le découvrir à la conception

Ajouter une photo de téléphone à une page

Les appels d'images modernes renvoient un identifiant d'image supérieur à zéro en cas de succès et 0 en cas d'échec, et l'identifiant va ensuite à DrawImageAndRelease ou à la paire habituelle SelectImage / DrawImage. L'esquisse ci-dessous inclut le seul repli dont les vrais téléversements de téléphone ont besoin, expliqué juste après :

uses
  PDFlibrary;

var
  Lib: TPDFlib;
  ImageID: Integer;
begin
  Lib := TPDFlib.Create;
  try
    Lib.NewDocument;
    Lib.SetPageSize('A4');      // NewDocument a déjà créé la page 1
    Lib.SetOrigin(1);           // mesurer Top depuis le bord supérieur

    // Options vaut 8 par défaut : alpha, profil ICC et canaux 16 bits
    ImageID := Lib.AddModernImageFromFile('uploads\pump-housing.heic');

    // L'extension dit HEIC, mais les octets peuvent être un JPEG ordinaire
    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;

Le repli existe parce que les noms de fichiers mentent. Les feuilles de partage, les applis de messagerie et les formulaires de téléversement convertissent le HEIC en JPEG en sortant tout en gardant le nom d'origine, ou renomment les fichiers selon ce que le formulaire récepteur attend. AddModernImageFromFile ne regarde jamais l'extension. Il inspecte les premiers octets, et s'ils ne sont ni AVIF, ni HEIF, ni JPEG XL, il renvoie 0 sans toucher au décodeur. Un JPEG portant un suffixe .heic échoue donc à l'appel moderne et réussit via le AddImageFromFile général, qui renifle le contenu de la même manière et gère JPEG, PNG, TIFF et les autres formats classiques

Pourquoi ne pas tout envoyer par AddImageFromFile ? Il reconnaît aussi les formats modernes, mais les appels modernes rendent l'intention explicite et fournissent l'option 8 quand vous ne passez rien, donc nous préférons les voir au site d'appel dès que l'entrée est censée être une photo de téléphone

Comment la bibliothèque distingue-t-elle AVIF de HEIC ?

PDF Library for Delphi décide du format depuis une lecture d'en-tête bornée à 4096 octets au plus, puis remet la position du flux de l'appelant où elle était. Le JPEG XL est le cas facile : un codestream brut démarre par FF 0A, et la forme conteneur démarre par une signature box fixe de 12 octets. AVIF et HEIF sont plus coriaces, car tous deux vivent dans le format de fichier de base ISO, la même structure de boxes que MP4, et ne diffèrent que par les marques listées dans la box ftyp

Le piège est que les listes de marques se chevauchent. Un fichier AVIF liste normalement mif1 parmi ses marques compatibles, car AVIF est bâti sur le même profil de fichier image que HEIF. Un détecteur qui renvoie HEIF dès qu'il voit mif1 étiquettera à tort une grande part des vrais fichiers AVIF. La bibliothèque balaye donc toute la liste de marques d'abord et laisse avif ou avis l'emporter sur la famille HEIF (heic, heix, hevc, hevx, heim, heis, mif1, msf1)

Diagramme de la porte de détection par nombre magique bornée qui confirme AVIF, HEIF et JPEG XL avant de choisir un backend de décodage via un chemin explicite, des variables d'environnement, le répertoire de l'exécutable ou un callback Delphi enregistré
La détection s'effectue sur une lecture bornée de l'en-tête, si bien qu'un exécutable renommé n'atteint jamais le codec

Faire la détection avant le décodage est aussi une propriété de sûreté. Une entrée inconnue ou déguisée n'atteint jamais le codec externe, donc un exécutable renommé ou un téléversement mal formé est tourné par quelques dizaines de comparaisons d'octets au lieu de l'être par un grand décodeur d'images qui devrait l'analyser

Où se passe le décodage

PDF Library for Delphi ne compile pas de codec AVIF, HEIF ou JPEG XL en lui-même. Ces codecs sont volumineux, ils changent souvent, et une application qui ne voit jamais de photo de téléphone ne devrait pas les payer. Le backend par défaut charge un module ImageMagick MagickWand en cours de processus à la première utilisation et le cherche dans un ordre fixe : le fichier ou répertoire posé via SetModernImageCodecLibrary, puis la variable d'environnement PDFLIB_MODERN_IMAGE_CODEC, puis le répertoire de l'exécutable, puis le chemin de recherche système normal. Sous Windows, il essaie CORE_RL_MagickWand_.dll, MagickWand-7.Q16HDRI-10.dll et MagickWand-7.Q16-10.dll à chaque emplacement

Deux conséquences pratiques suivent. Livrez un build Q16 du codec, car un build à quantum 8 bits ne peut pas remettre des échantillons 16 bits quelle que soit l'option passée. Et si le répertoire du codec contient un sous-dossier modules\coders, la bibliothèque remplit MAGICK_HOME, MAGICK_CONFIGURE_PATH et MAGICK_CODER_MODULE_PATH pour vous, mais seulement celles de ces variables que le processus hôte n'a pas déjà posées. Une application avec son propre agencement d'exécution le garde

Notre recommandation est de poser le chemin explicitement et de ne pas compter sur le chemin de recherche système. Une machine qui a par hasard un autre ImageMagick sur son PATH déciderait sinon du codec que votre générateur de rapports utilise, et c'est le genre de différence qui ne surgit que sur le serveur d'un client

Les applications qui livrent déjà un décodeur, ou qui n'ont pas le droit de charger un module externe, enregistrent un callback à la place. Le callback est une fonction simple qui lit le flux source, écrit des octets PNG dans le flux de sortie et honore le drapeau d'orientation. L'enregistrement est à l'échelle du processus et protégé par un verrou, donc faites-le une fois au démarrage plutôt que par document :

uses
  Classes, PDFlibModernImage,
  AppCodec;  // votre propre unité enveloppant le codec que vous livrez déjà

function MyModernDecoder(InStream, OutPNG: TStream;
  ImageFormat: TPDFlibModernImageFormat;
  ApplyOrientation: Boolean): Boolean;
begin
  // InStream est positionné à 0, OutPNG est vide
  Result := (ImageFormat <> mifUnknown) and
    AppDecodeToPNG(InStream, OutPNG, ApplyOrientation);
end;

initialization
  RegisterModernImageDecoderBackend(MyModernDecoder);

finalization
  ClearModernImageDecoderBackend;  // retour au backend MagickWand

Quand une image est ajoutée à un document, la bibliothèque demande toujours que l'orientation soit appliquée. Les caméras de téléphone stockent routinièrement l'image du capteur de travers et enregistrent la rotation voulue en métadonnées, donc un callback qui ignore ApplyOrientation produit des photos portrait couchées sur le flanc. Un backend maison se trompe là-dessus facilement, et l'erreur est facile à rater quand les images de test ont toutes été prises en paysage

Pourquoi décoder en PNG en mémoire ?

Le backend convertit l'image décodée en PNG en mémoire et donne ce PNG au chemin d'incorporation PNG existant. Cela ressemble à un détour comparé à remettre un tampon de pixels brut, pourtant c'est l'option correcte la moins chère. Le PNG peut exprimer tout ce qui doit survivre (alpha, type de couleur, 8 ou 16 bits par échantillon et un profil ICC incorporé) et PDF Library for Delphi a déjà une route mature du PNG à un objet image PDF avec les bons filtres, soft mask et espace de couleur. Les formats modernes héritent de ce travail au lieu de recevoir une implémentation parallèle avec ses propres bogues à trouver. La sortie du décodeur est normalisée en 16 bits quand la source dépasse 8 bits par canal et en 8 bits sinon

Aucun fichier temporaire n'est écrit, donc il n'y a rien à nettoyer après un crash. Un grain de sable a exigé une gestion explicite. Pendant le développement, nous avons constaté que le codec pouvait laisser tomber le profil ICC en basculant l'image en mémoire vers le PNG, ce qui aurait réintroduit exactement le décalage de couleur que ce chemin existe pour prévenir. Le backend lit maintenant le profil source avant le changement de format, le compresse en Flate, l'écrit dans un chunk iCCP valide avec un CRC recalculé et retire tout chunk sRGB qui le contredirait. Dans une exécution Win64 sur un vrai AVIF, la sortie a gardé du RGBA 16 bits avec alpha 16 bits, et le profil extrait du PDF faisait 60 960 octets avec un SHA-256 identique au profil source

Diagramme PDF Library for Delphi du pont PNG en mémoire qui capture le profil ICC source avant le changement de format, le reconstruit en chunk iCCP compressé, supprime le chunk sRGB en conflit et réutilise le chemin éprouvé d'intégration PNG vers PDF
Capturer le profil ICC avant le changement de format garantit que la copie incorporée reste identique à l'octet près à la source

Tester le codec au démarrage

Sondez le codec au démarrage de l'application, avant que la première photo n'arrive. ModernImageCodecAvailable renvoie 1 quand un callback enregistré ou un module MagickWand chargeable est présent, et SetModernImageCodecLibrary pointe le chargeur vers un fichier ou répertoire précis :

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

  // Renvoie 0 dès qu'un module de codec est déjà chargé dans ce processus
  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;

Deux comportements valent la peine d'être connus avant de câbler cela dans un installateur ou un service. Un chargement raté est mémorisé, donc la bibliothèque ne reparcourt pas le disque pour chaque image. Si votre service sonde avant que l'installateur ait fini de copier le dossier du codec, il continue de rapporter le codec comme indisponible jusqu'à ce que SetModernImageCodecLibrary soit rappelé, ce qui efface cet échec mémorisé. L'inverse vaut aussi : dès qu'un module a chargé, SetModernImageCodecLibrary renvoie 0 et le chemin reste en l'état pour la vie du processus, car décharger un codec natif sous des conversions en cours n'est pas quelque chose que nous voulons faire implicitement

Surveillez aussi la taille de la sortie. Une photo RGBA 16 bits avec son profil est un grand objet image, et un rapport qui en compte quarante devient lourd vite. Pour des documents qui ne seront lus qu'à l'écran, le sous-échantillonnage avant incorporation est le bon troc, et les leviers de taille généraux sont couverts dans l'optimisation de la taille de fichier PDF. La politique de couleur mérite aussi une décision délibérée. Garder chaque profil source est correct pour l'archivage et l'impression, tandis que tout convertir vers un espace unique à l'échelle du document convient à un ensemble de photos venues de téléphones différents qui doivent sembler cohérentes côte à côte ; cette voie est décrite dans la recoloration d'un document vers un autre espace de couleur. Pour confirmer ce qui a réellement atterri dans le fichier, le chemin d'inspection dans l'extraction de texte, d'images et de polices rapporte les objets image qu'un document porte

L'entrée AVIF, HEIF et JPEG XL côtoie l'entrée PNG, JPEG, TIFF et WebP, la conversion d'espaces de couleur et l'optimisation d'images dans la même bibliothèque pour Delphi, C++Builder et Free Pascal. Licence, support des plateformes et référence complète de l'API sont sur la page produit de PDF Library for Delphi