Техническая статья

Встраивание изображений AVIF, HEIF и JPEG XL в PDF из Delphi

Фотография HEIC с телефона попадает в отчёт, сгенерированный на Delphi, PDF на экране выглядит правильно, а печатная страница возвращается со съехавшими красными и вырезанным логотипом, сидящим на сплошной плашке. Фотография по дороге внутрь была декодирована через битмап платформы; загрузите её через AddModernImageFromFile в PDF Library for Delphi — и изображения AVIF, HEIF и JPEG XL по умолчанию сохраняют альфа-канал, ICC-профиль и 16-битные каналы

Эти форматы добрались до документных рабочих процессов в основном через телефоны. iPhone годами сохраняет HEIC по умолчанию, устройства на Android выдают AVIF, а JPEG XL всплывает в архивных и фотографических конвейерах. У генератора отчётов, спроектированного вокруг JPEG и PNG, два варианта, когда такая фотография приходит: отказаться от файла или открыть его через какой-нибудь декодер операционной системы, приняв сплющенный 8-битный битмап. Эта статья — про третий маршрут: библиотека сама распознаёт формат, декодирует его через выбранный вами кодек и встраивает результат с нетронутыми глубиной и цветовыми данными

Что теряет путь через битмап платформы?

Преобразование в битмап платформы теряет три вещи за один шаг: прозрачность, встроенный цветовой профиль и всякую глубину каналов выше 8 бит. У каждой из них есть рабочий процесс, который на неё опирается. Альфа важна для логотипов и вырезок продуктов, компонуемых поверх содержимого страницы. ICC-профиль важен для всего, что будет напечатано или сведено по цвету с эталоном: без него вьювер считает, что это sRGB, и широкохватный снимок камеры переинтерпретируется. А 16-битные каналы важны для медицинской, научной и инспекционной съёмки, где квантование до 8 бит стирает ровно те градации, ради которых изображение снималось

Ничто из этого не даёт ошибки. Страница рендерится, фотография узнаваема, и проблема ждёт, пока кто-нибудь не сравнит распечатку с оригиналом. Поэтому мы считаем сохранение поведением по умолчанию, а не опцией, в которую вызывающий должен специально попасть: AddModernImageFromFile, AddModernImageFromStream и AddModernImageFromString все принимают параметр Options, по умолчанию равный 8, и именно опция 8 заносит альфа, ICC и 16-битные сэмплы в объект изображения PDF вместе

Диаграмма PDF Library for Delphi: сравнение платформенного преобразования битмапа, теряющего альфа-канал, ICC-профиль и 16-битные каналы, с современным путём изображений, сохраняющим все три в объекте PDF-изображения
Универсальное декодирование битмапа молча сводит прозрачность на нет и квантует каналы ещё до отрисовки страницы

16-битное изображение меняет и производимый файл. PDF Library for Delphi поднимает документ минимум до PDF 1.5, когда изображение несёт 16-битные сэмплы: именно с этой версии 16 бит на компонент стали допустимы для image XObject. Если нижележащая система настаивает на PDF 1.4, это требование и 16-битные фотографии несовместимы — и лучше узнать об этом на этапе проектирования

Добавление телефонной фотографии на страницу

Современные вызовы изображений возвращают ID изображения больше нуля при успехе и 0 при неудаче, а ID затем идёт в DrawImageAndRelease или в обычную пару SelectImage / DrawImage. Набросок ниже включает тот единственный запасной путь, который нужен реальным загрузкам с телефонов, — он объясняется сразу после:

uses
  PDFlibrary;

var
  Lib: TPDFlib;
  ImageID: Integer;
begin
  Lib := TPDFlib.Create;
  try
    Lib.NewDocument;
    Lib.SetPageSize('A4');      // NewDocument уже создал страницу 1
    Lib.SetOrigin(1);           // Top отсчитываем от верхнего края

    // Options по умолчанию 8: альфа-канал, ICC-профиль и 16-битные каналы
    ImageID := Lib.AddModernImageFromFile('uploads\pump-housing.heic');

    // Расширение говорит HEIC, но байты могут быть обычным 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;

Запасной путь существует, потому что имена файлов врут. Меню «Поделиться», мессенджеры и формы загрузки конвертируют HEIC в JPEG на выходе, сохраняя исходное имя, или переименовывают файлы как угодно принимающей форме. AddModernImageFromFile на расширение не смотрит вовсе. Она осматривает первые байты, и если это не AVIF, HEIF или JPEG XL, возвращает 0, не трогая декодер. Поэтому JPEG в маске .heic провалит современный вызов и пройдёт через общий AddImageFromFile, который принюхивается к содержимому так же и работает с JPEG, PNG, TIFF и прочими классическими форматами

Почему бы не гнать всё через AddImageFromFile? Она и правда распознаёт современные форматы тоже, но современные вызовы делают намерение явным и подставляют опцию 8, когда вы ничего не передаёте, поэтому нам милее видеть их в месте вызова всякий раз, когда на входе ожидается фотография с телефона

Как библиотека отличает AVIF от HEIC?

PDF Library for Delphi решает формат по ограниченному чтению заголовка не более чем на 4096 байт и затем возвращает позицию потока вызывающего туда, где она была. JPEG XL — простой случай: сырой кодовый поток начинается с FF 0A, а контейнерная форма — с фиксированной 12-байтной сигнатурной коробки. AVIF и HEIF труднее, потому что оба живут в ISO base media file format — той же коробочной структуре, что MP4, — и различаются лишь брендами, перечисленными внутри коробки ftyp

Ловушка в том, что списки брендов пересекаются. Файл AVIF обычно перечисляет mif1 среди совместимых брендов, потому что AVIF построен на том же профиле файла изображения, что и HEIF. Детектор, кричащий «HEIF» при первом же mif1, неправильно разметит изрядную долю настоящих AVIF-файлов. Поэтому библиотека сперва сканирует весь список брендов и отдаёт победу avif или avis над семейством HEIF (heic, heix, hevc, hevx, heim, heis, mif1, msf1)

Диаграмма ограниченного шлюза распознавания по магическим числам, подтверждающего AVIF, HEIF и JPEG XL до выбора декодирующего бэкенда из явного пути, переменных окружения, каталога исполняемого файла или зарегистрированного Delphi-колбэка
Распознавание выполняется на ограниченном чтении заголовка, поэтому переименованный исполняемый файл никогда не достигает кодека

Распознавание до декодирования — ещё и свойство безопасности. Неизвестный или замаскированный вход никогда не добирается до внешнего кодека: переименованный исполняемый файл или искажённая загрузка отворачивается парой десятков сравнений байтов, а не большим декодером изображений, которому пришлось бы её парсить

Где происходит декодирование

PDF Library for Delphi не компилирует кодек AVIF, HEIF или JPEG XL внутрь себя. Эти кодеки велики, часто меняются, и приложение, никогда не видящее телефонных фотографий, не должно за них платить. Бэкенд по умолчанию подгружает модуль ImageMagick MagickWand в свой процесс при первом использовании и ищет его в фиксированном порядке: файл или каталог, заданный через SetModernImageCodecLibrary, затем переменная окружения PDFLIB_MODERN_IMAGE_CODEC, затем каталог исполняемого файла, затем обычный системный путь поиска. На Windows в каждом месте он пробует CORE_RL_MagickWand_.dll, MagickWand-7.Q16HDRI-10.dll и MagickWand-7.Q16-10.dll

Отсюда два практических следствия. Поставляйте сборку кодека Q16: сборка с 8-битным квантом не сможет отдать 16-битные сэмплы, какую опцию ни передавай. И если каталог кодека содержит подкаталог modules\coders, библиотека заполнит за вас MAGICK_HOME, MAGICK_CONFIGURE_PATH и MAGICK_CODER_MODULE_PATH — но лишь те переменные, которые хост-процесс ещё не выставил сам. Приложение с собственной раскладкой времени выполнения её сохранит

Наша рекомендация — задавать путь явно и не полагаться на системный путь поиска. Иначе машина, на которой случайно стоит другой ImageMagick в PATH, сама решит, каким кодеком пользуется ваш генератор отчётов, а это из тех различий, что всплывают только на сервере одного конкретного заказчика

Приложения, которые уже поставляют декодер или которым нельзя загружать внешний модуль, регистрируют вместо этого callback. Это простая функция, читающая исходный поток, пишущая байты PNG в выходной поток и соблюдающая флаг ориентации. Регистрация действует на весь процесс и защищена блокировкой, поэтому делайте её один раз при старте, а не на каждый документ:

uses
  Classes, PDFlibModernImage,
  AppCodec;  // ваш собственный юнит, оборачивающий кодек, который вы уже поставляете

function MyModernDecoder(InStream, OutPNG: TStream;
  ImageFormat: TPDFlibModernImageFormat;
  ApplyOrientation: Boolean): Boolean;
begin
  // InStream стоит на 0, OutPNG пуст
  Result := (ImageFormat <> mifUnknown) and
    AppDecodeToPNG(InStream, OutPNG, ApplyOrientation);
end;

initialization
  RegisterModernImageDecoderBackend(MyModernDecoder);

finalization
  ClearModernImageDecoderBackend;  // возврат к бэкенду MagickWand

Когда изображение добавляется в документ, библиотека всегда просит применить ориентацию. Телефонные камеры сплошь и рядом хранят снимок сенсора боком и записывают задуманный поворот как метаданные, поэтому callback, игнорирующий ApplyOrientation, выдаёт портретные фотографии, лежащие на боку. Самодельный бэкенд ошибается тут легко, а ошибку легко пропустить, если все тестовые изображения сняты в альбомной ориентации

Почему декодировать в PNG в памяти?

Бэкенд преобразует декодированное изображение в PNG в памяти и скармливает этот PNG существующему пути встраивания PNG. Рядом с передачей сырого пиксельного буфера это выглядит крюком, но это более дешёвый правильный вариант. PNG умеет выразить всё, что обязано выжить (альфа, тип цвета, 8 или 16 бит на сэмпл и встроенный ICC-профиль), а у PDF Library for Delphi уже есть зрелая дорога от PNG к объекту изображения PDF с правильными фильтрами, мягкой маской и цветовым пространством. Современные форматы наследуют эту работу вместо того, чтобы получить параллельную реализацию с собственными багами, которые ещё искать. Выход декодера нормализуется до 16 бит, когда в источнике больше 8 бит на канал, и до 8 бит в противном случае

Временные файлы не пишутся, поэтому после падения нечего убирать. Одна загвоздка потребовала явной обработки. В ходе разработки мы обнаружили, что кодек мог потерять ICC-профиль при переключении образа в памяти на PNG — это вернуло бы ровно тот сдвиг цвета, ради предотвращения которого путь и существует. Теперь бэкенд читает исходный профиль до переключения формата, сжимает его Flate, пишет в корректный чанк iCCP с пересчитанной CRC и удаляет любой чанк sRGB, который стал бы ему противоречить. В прогоне Win64 на настоящем AVIF вывод сохранил 16-битный RGBA с 16-битной альфой, а профиль, извлечённый из PDF, составил 60 960 байт с SHA-256, идентичным исходному профилю

Диаграмма PDF Library for Delphi: PNG-мост в памяти захватывает исходный ICC-профиль до смены формата, пересобирает его в сжатый чанк iCCP, отбрасывает конфликтующий чанк sRGB и повторяет проверенный путь встраивания PNG в PDF
Снятие копии ICC-профиля до смены формата сохраняет встроенную копию побайтово идентичной исходной

Проверка кодека при запуске

Прощупывайте кодек при старте приложения, до первой фотографии. ModernImageCodecAvailable возвращает 1, когда есть либо зарегистрированный callback, либо загружаемый модуль MagickWand, а SetModernImageCodecLibrary указывает загрузчику конкретный файл или каталог:

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

  // Возвращает 0, когда модуль кодека уже загружен в этом процессе
  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;

Два поведения стоит знать, прежде чем вплетать это в инсталлятор или службу. Неудавшаяся загрузка запоминается, поэтому библиотека не прочёсывает диск заново на каждом изображении. Если ваша служба прощупывает кодек до того, как инсталлятор закончил копировать папку кодека, она продолжит рапортовать о недоступности, пока SetModernImageCodecLibrary не будет вызвана снова — это сбрасывает запомненную неудачу. Верно и обратное: раз модуль загрузился, SetModernImageCodecLibrary возвращает 0, а путь остаётся прежним на всю жизнь процесса, потому что выгружать нативный кодек посреди идущих конвертаций мы не хотим делать неявно

Следите и за размером вывода. 16-битная фотография RGBA с профилем — крупный объект изображения, и отчёт с сорока такими тяжелеет на глазах. Для документов, которые будут только читаться с экрана, правильная сделка — даунсэмпл перед встраиванием, а общие рычаги размера описаны в статье о оптимизации размера файла PDF. Цветовая политика тоже заслуживает осознанного решения. Хранить каждый исходный профиль правильно для архивной и печатной работы, а конвертация всего в одно общедокументное пространство подходит набору фотографий с разных телефонов, которым положено выглядеть согласованно бок о бок; этот маршрут описан в статье о перекраске документа в другое цветовое пространство. Чтобы подтвердить, что реально легло в файл, путь инспекции из статьи о извлечении текста, изображений и шрифтов сообщает об объектах изображений, которые несёт документ

Ввод AVIF, HEIF и JPEG XL живёт рядом с вводом PNG, JPEG, TIFF и WebP, преобразованием цветовых пространств и оптимизацией изображений — в той же библиотеке для Delphi, C++Builder и Free Pascal. Лицензирование, поддержка платформ и полный справочник API — на странице продукта PDF Library for Delphi