一张手机拍的 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 图像对象的那个设置
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)
先检测后解码同时是一条安全性质。未知或伪装的输入永远到不了外部编解码器,改了名的可执行文件或畸形上传被几十次字节比较打发掉,而不是交给一个不得不解析它的大型图像解码器
解码发生在哪里
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 与源配置文件一致
在启动时检查编解码器
应用启动时、第一张照片到来之前,先探一下编解码器。存在已注册回调或可加载的 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 产品页