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