Technical Article

Embed AVIF, HEIF and JPEG XL Images in PDF from Delphi

A HEIC photo from a phone goes into a Delphi-generated report, the PDF looks right on screen, and the printed page comes back with shifted reds and a cutout logo sitting on a solid box. The photo was decoded through a platform bitmap on its way in; load it with AddModernImageFromFile in PDF Library for Delphi instead, and AVIF, HEIF and JPEG XL images keep alpha, the ICC profile and 16-bit channels by default

These formats reached document workflows mostly through phones. iPhones have saved HEIC by default for years, Android devices produce AVIF, and JPEG XL is turning up in archival and photography pipelines. A report generator designed around JPEG and PNG has two options when one arrives: refuse the file, or open it through whatever decoder the operating system offers and accept a flattened 8-bit bitmap. This article covers a third route, where the library recognises the format itself, decodes it through a codec you choose and embeds the result with its depth and colour data intact

What does a bitmap round trip lose?

A platform bitmap conversion loses three things in one step: transparency, the embedded colour profile and any channel depth above 8 bits. Each of them has a workflow that depends on it. Alpha matters for logos and product cutouts placed over page content. The ICC profile matters for anything that will be printed or colour-matched against a reference, because without it the viewer assumes sRGB and a wide-gamut camera image is reinterpreted. And 16-bit channels matter for medical, scientific and inspection imagery, where quantising to 8 bits erases exactly the gradations the image was captured for

None of this produces an error. The page renders, the photo is recognisable, and the problem waits until someone compares a print against the original. That is why we treat preservation as the default rather than as something callers opt into: AddModernImageFromFile, AddModernImageFromStream and AddModernImageFromString all take an Options parameter that defaults to 8, and option 8 is the setting that carries alpha, ICC and 16-bit samples into the PDF image object together

PDF Library for Delphi diagram comparing a platform bitmap conversion that drops alpha, the ICC profile and 16-bit channels against the modern image path that carries all three into the PDF image object
A generic bitmap decode quietly flattens transparency and quantises channels before the page ever renders

A 16-bit image also changes the file you produce. PDF Library for Delphi raises the document to at least PDF 1.5 when an image carries 16-bit samples, since that is the version where 16 bits per component became valid for image XObjects. If a downstream system insists on PDF 1.4, that requirement and 16-bit photographs cannot both be satisfied, and it is better to find that out at design time

Adding a phone photo to a page

The modern image calls return an image ID greater than zero on success and 0 on failure, and the ID then goes to DrawImageAndRelease or to the usual SelectImage / DrawImage pair. The sketch below includes the one fallback that real phone uploads need, explained straight afterwards:

uses
  PDFlibrary;

var
  Lib: TPDFlib;
  ImageID: Integer;
begin
  Lib := TPDFlib.Create;
  try
    Lib.NewDocument;
    Lib.SetPageSize('A4');      // NewDocument already made page 1
    Lib.SetOrigin(1);           // measure Top from the top edge

    // Options defaults to 8: alpha, ICC profile and 16-bit channels
    ImageID := Lib.AddModernImageFromFile('uploads\pump-housing.heic');

    // The extension says HEIC, but the bytes may be an ordinary JPEG
    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;

The fallback exists because file names lie. Share sheets, messaging apps and upload forms convert HEIC to JPEG on the way out while keeping the original name, or rename files to whatever the receiving form expects. AddModernImageFromFile never looks at the extension. It inspects the first bytes, and if they are not AVIF, HEIF or JPEG XL it returns 0 without touching the decoder. A JPEG wearing a .heic suffix therefore fails the modern call and succeeds through the general AddImageFromFile, which sniffs content in the same way and handles JPEG, PNG, TIFF and the other classic formats

Why not send everything through AddImageFromFile? It does recognise the modern formats too, but the modern calls make the intent explicit and supply option 8 when you pass nothing, so we would rather see them at the call site whenever the input is expected to be a phone photo

How does the library tell AVIF from HEIC?

PDF Library for Delphi decides the format from a bounded header read of at most 4096 bytes and then puts the caller's stream position back where it was. JPEG XL is the easy case: a raw codestream starts with FF 0A, and the container form starts with a fixed 12-byte signature box. AVIF and HEIF are harder, because both live in the ISO base media file format, the same box structure as MP4, and differ only in the brands listed inside the ftyp box

The trap is that the brand lists overlap. An AVIF file normally lists mif1 among its compatible brands, because AVIF is built on the same image file profile as HEIF. A detector that returns HEIF the moment it sees mif1 will mislabel a large share of real AVIF files. The library therefore scans the whole brand list first and lets avif or avis win over the HEIF family (heic, heix, hevc, hevx, heim, heis, mif1, msf1)

Diagram of the bounded magic-number detection gate that confirms AVIF, HEIF and JPEG XL before a decoding backend is chosen from an explicit path, environment variables, the executable directory or a registered Delphi callback
Detection runs on a bounded header read, so a renamed executable never reaches the codec

Running detection before decoding is also a safety property. An unknown or disguised input never reaches the external codec, so a renamed executable or a malformed upload is turned away by a few dozen byte comparisons instead of by a large image decoder that would have to parse it

Where the decoding happens

PDF Library for Delphi does not compile an AVIF, HEIF or JPEG XL codec into itself. Those codecs are large, they change often, and an application that never sees a phone photo should not pay for them. The default backend loads an ImageMagick MagickWand module in-process on first use and searches for it in a fixed order: the file or directory set through SetModernImageCodecLibrary, then the PDFLIB_MODERN_IMAGE_CODEC environment variable, then the executable's directory, then the normal system search path. On Windows it tries CORE_RL_MagickWand_.dll, MagickWand-7.Q16HDRI-10.dll and MagickWand-7.Q16-10.dll in each location

Two practical consequences follow. Ship a Q16 build of the codec, since an 8-bit-quantum build cannot hand over 16-bit samples no matter what option you pass. And if the codec directory contains a modules\coders subfolder, the library fills in MAGICK_HOME, MAGICK_CONFIGURE_PATH and MAGICK_CODER_MODULE_PATH for you, but only those variables the host process has not already set. An application with its own runtime layout keeps it

Our recommendation is to set the path explicitly and not rely on the system search path. A machine that happens to have a different ImageMagick on PATH will otherwise decide which codec your report generator uses, and that is the kind of difference that only shows up on one customer's server

Applications that already ship a decoder, or that are not allowed to load an external module, register a callback instead. The callback is a plain function that reads the source stream, writes PNG bytes to the output stream and honours the orientation flag. The registration is process-wide and protected by a lock, so do it once at startup rather than per document:

uses
  Classes, PDFlibModernImage,
  AppCodec;  // your own unit wrapping the codec you already ship

function MyModernDecoder(InStream, OutPNG: TStream;
  ImageFormat: TPDFlibModernImageFormat;
  ApplyOrientation: Boolean): Boolean;
begin
  // InStream is positioned at 0, OutPNG is empty
  Result := (ImageFormat <> mifUnknown) and
    AppDecodeToPNG(InStream, OutPNG, ApplyOrientation);
end;

initialization
  RegisterModernImageDecoderBackend(MyModernDecoder);

finalization
  ClearModernImageDecoderBackend;  // back to the MagickWand backend

When an image is added to a document, the library always asks for orientation to be applied. Phone cameras routinely store the sensor image sideways and record the intended rotation as metadata, so a callback that ignores ApplyOrientation produces portrait photos lying on their side. A home-grown backend gets this wrong easily, and the mistake is easy to miss when the test images were all shot in landscape

Why decode to PNG in memory?

The backend converts the decoded image into an in-memory PNG and feeds that PNG into the existing PNG embedding path. That looks like a detour compared to handing over a raw pixel buffer, yet it is the cheaper correct option. PNG can express everything that has to survive (alpha, colour type, 8 or 16 bits per sample and an embedded ICC profile) and PDF Library for Delphi already has a mature route from PNG to a PDF image object with the right filters, soft mask and colour space. Modern formats inherit that work instead of getting a parallel implementation with its own bugs to find. The decoder output is normalised to 16 bits when the source has more than 8 bits per channel and to 8 bits otherwise

No temporary files are written, so there is nothing to clean up after a crash. One wrinkle needed explicit handling. During development we found that the codec could drop the ICC profile while switching the in-memory image to PNG, which would have reintroduced exactly the colour shift this path exists to prevent. The backend now reads the source profile before the format switch, compresses it with Flate, writes it into a valid iCCP chunk with a recomputed CRC and removes any sRGB chunk that would contradict it. In a Win64 run on a real AVIF, the output kept 16-bit RGBA with 16-bit alpha, and the profile extracted from the PDF was 60,960 bytes with a SHA-256 identical to the source profile

PDF Library for Delphi diagram of the in-memory PNG bridge that captures the source ICC profile before the format switch, rebuilds it as a compressed iCCP chunk, drops the conflicting sRGB chunk and reuses the proven PNG to PDF embedding path
Snapshotting the ICC profile ahead of the format change keeps the embedded copy byte-identical to the source

Checking the codec at startup

Probe the codec when the application starts, before the first photograph arrives. ModernImageCodecAvailable returns 1 when either a registered callback or a loadable MagickWand module is present, and SetModernImageCodecLibrary points the loader at a specific file or directory:

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

  // Returns 0 once a codec module is already loaded in this process
  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;

Two behaviours are worth knowing before you wire this into an installer or a service. A failed load is remembered, so the library does not search the disk again for every image. If your service probes before the installer has finished copying the codec folder, it keeps reporting the codec as unavailable until SetModernImageCodecLibrary is called again, which clears that remembered failure. The opposite also holds: once a module has loaded, SetModernImageCodecLibrary returns 0 and the path stays as it is for the life of the process, because unloading a native codec under running conversions is not something we want to do implicitly

Watch the size of the output as well. A 16-bit RGBA photo with its profile is a large image object, and a report with forty of them gets heavy fast. For documents that will only be read on screen, downsampling before embedding is the right trade, and the general size levers are covered in PDF file size optimization. Colour policy deserves a deliberate decision too. Keeping each source profile is correct for archival and print work, while converting everything to one document-wide space suits a set of photographs from different phones that must look consistent side by side; that route is described in recoloring a document to another color space. To confirm what actually landed in the file, the inspection path in text, image and font extraction reports the image objects a document carries

AVIF, HEIF and JPEG XL input sits alongside PNG, JPEG, TIFF and WebP input, colour space conversion and image optimisation in the same library for Delphi, C++Builder and Free Pascal. Licensing, platform support and the full API reference are on the PDF Library for Delphi product page