技术文章

从 Delphi 在 PDF 中嵌入 AVIF、HEIF 和 JPEG XL 图像

一张手机拍的 HEIC 照片进了 Delphi 生成的报表,PDF 在屏幕上看着正常,打印出来的页面却红色偏移、抠好的 logo 趴在一块实色底上。照片在进入的路上被平台位图解码了一遍;改用 PDF Library for Delphi 的 AddModernImageFromFile 加载,AVIF、HEIF 和 JPEG XL 图像默认保留 alpha、ICC 配置文件和 16 位通道

这些格式大多是借手机之力进入文档工作流的。iPhone 多年来默认存 HEIC,Android 设备产出 AVIF,JPEG XL 正在档案和摄影管线里冒头。围绕 JPEG 和 PNG 设计的报表生成器遇到它们只有两个选择:拒绝文件,或者经由操作系统提供的解码器打开、接受一份压平的 8 位位图。本文讲第三条路:库自己识别格式,经你选定的编解码器解码,把结果带着完整的位深和颜色数据嵌入

位图一趟往返会丢掉什么?

平台位图转换一步丢三样东西:透明度、内嵌的颜色配置文件,以及 8 位以上的通道深度。每一样都有依赖它的工作流。Alpha 关系到叠在页面内容上的 logo 和产品抠图。ICC 配置文件关系到一切要打印或要跟基准比色的东西,因为没有它,查看器按 sRGB 理解,一部广色域相机的图像就被重新解读了。16 位通道关系到医疗、科学和检测影像——量化到 8 位抹掉的恰恰是当初捕获这些图像要保留的层次

这一切都不报错。页面照常渲染,照片认得出来,问题一直等着有人拿打印件跟原件对质。正因如此,我们把保留设为默认而不是让调用方主动选择:AddModernImageFromFile、AddModernImageFromStream 和 AddModernImageFromString 都带一个默认为 8 的 Options 参数,选项 8 就是把 alpha、ICC 和 16 位样本一起带进 PDF 图像对象的那个设置

PDF Library for Delphi 示意图:对比会丢弃 alpha、ICC 配置文件和 16 位通道的平台位图转换与将三者全部保留进 PDF 图像对象的现代图像路径
通用的位图解码会在页面渲染之前悄悄抹平透明度并对通道做量化

16 位图像还会改变你产出的文件。图像带 16 位样本时,PDF Library for Delphi 把文档至少提升到 PDF 1.5,因为正是在这个版本里每分量 16 位对图像 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:alpha、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,不碰解码器。于是披着 .heic 后缀的 JPEG 在现代调用上失败、经由通用 AddImageFromFile 成功——后者同样嗅探内容,处理 JPEG、PNG、TIFF 和其他经典格式

为什么不把一切都交给 AddImageFromFile?它确实也认识这些现代格式,但现代调用把意图写在明处,且什么都不传时替你带上选项 8,所以只要输入预期是手机照片,我们更愿意在调用点上看到它们

库怎么区分 AVIF 和 HEIC?

PDF Library for Delphi 通过一次最多 4096 字节的有界头部读取判定格式,然后把调用方的流位置放回原处。JPEG XL 是容易的案子:裸码流以 FF 0A 开头,容器形态以固定的 12 字节签名字盒开头。AVIF 和 HEIF 难一些,因为两者都住在 ISO 基础媒体文件格式里——与 MP4 同一种盒结构——只在 ftyp 盒里列出的品牌上不同

陷阱在于品牌列表互相重叠。AVIF 文件通常把 mif1 列进兼容品牌,因为 AVIF 建在与 HEIF 相同的图像文件 profile 之上。一看到 mif1 就报 HEIF 的检测器会把相当一部分真实 AVIF 文件贴错标签。所以库先扫完整张品牌列表,让 avif 或 avis 压过 HEIF 家族(heic、heix、hevc、hevx、heim、heis、mif1、msf1)

有界魔数检测门示意图:在选择解码后端(来自显式路径、环境变量、可执行文件目录或已注册的 Delphi 回调)之前,先确认 AVIF、HEIF 与 JPEG XL 格式
检测基于有界头部读取运行,改名的可执行文件永远到不了解码器

先检测后解码同时是一条安全性质。未知或伪装的输入永远到不了外部编解码器,改了名的可执行文件或畸形上传被几十次字节比较打发掉,而不是交给一个不得不解析它的大型图像解码器

解码发生在哪里

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,但只填宿主进程尚未设置的变量。已有自己运行时布局的应用保持原样

我们的建议是显式设路径,不要依赖系统搜索路径。一台恰好在 PATH 上装了另一个 ImageMagick 的机器,会替你的报表生成器决定用哪个编解码器——这类差异只在某一个客户的服务器上现形

已经随附解码器的应用,或不允许加载外部模块的应用,改为注册回调。回调就是一个普通函数:读源流、把 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 后端

图像加入文档时,库总是要求应用方向。手机相机惯常把传感器图像横着存、把想要的旋转记成元数据,所以忽略 ApplyOrientation 的回调会产出侧躺的竖拍照片。自制的后端很容易在这里出错,而测试图全是横拍时,这个错误极易漏网

为什么在内存里解码成 PNG?

后端把解码出的图像转成内存中的 PNG,再把这份 PNG 喂给既有的 PNG 嵌入路径。比起交出裸像素缓冲区,这看起来像绕路,实际上却是更便宜的正确选项。PNG 能表达一切必须幸存的东西(alpha、颜色类型、每样本 8 或 16 位、内嵌 ICC 配置文件),而 PDF Library for Delphi 已有一条成熟的从 PNG 到 PDF 图像对象的路,滤镜、软掩码和色彩空间都配得妥妥的。现代格式继承这份现成的工作,而不是另起一套带自己 bug 要找的实现。源每通道超过 8 位时,解码器输出归一到 16 位,否则归一到 8 位

不写任何临时文件,崩溃之后没有东西要清理。有一个皱褶需要显式处理。开发期间我们发现编解码器在把内存图像切换成 PNG 时可能丢掉 ICC 配置文件,这会重新引入这条路径本来要防止的那种色彩偏移。后端现在在格式切换前读取源配置文件,用 Flate 压缩,写进一个重算了 CRC 的合法 iCCP 块,并删掉与之矛盾的 sRGB 块。在真实 AVIF 上的一次 Win64 运行中,输出保留了带 16 位 alpha 的 16 位 RGBA,从 PDF 里取出的配置文件 60,960 字节,SHA-256 与源配置文件一致

PDF Library for Delphi 示意图:内存中的 PNG 桥接在格式切换前捕获源 ICC 配置文件,将其重建为压缩的 iCCP 块,丢弃冲突的 sRGB 块,并复用经过验证的 PNG 到 PDF 嵌入路径
在格式切换前先快照 ICC profile,使嵌入的副本与源文件逐字节一致

在启动时检查编解码器

应用启动时、第一张照片到来之前,先探一下编解码器。存在已注册回调或可加载的 MagickWand 模块时,ModernImageCodecAvailable 返回 1;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 产品页