技術文章

從 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 位元組簽章 box 開頭。AVIF 與 HEIF 較麻煩,兩者都住在 ISO 基礎媒體檔案格式裡——與 MP4 相同的 box 結構——只以 ftyp box 裡列出的品牌相區別

陷阱在於品牌清單互相重疊。AVIF 檔通常把 mif1 列在相容品牌裡,因為 AVIF 建在與 HEIF 相同的影像檔 profile 上。一看到 mif1 就回報 HEIF 的偵測器,會把一大部分真實的 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——但只填宿主行程還沒設的那些變數。有自己執行期佈局的應用程式保有自己的

我們的建議是明確設路徑,不要依賴系統搜尋路徑。機器上剛好在 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 後端

影像加進文件時,函式庫一律要求套用方向。手機相機照例把感光元件影像側著存、把想要的旋轉記成 metadata,所以忽略 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 位元 RGBA 含 16 位元 alpha,而從 PDF 抽出的描述檔共 60,960 位元組、SHA-256 與來源描述檔相同

PDF Library for Delphi 記憶體內 PNG 橋接圖解:在切換格式前擷取來源 ICC 描述檔,重建為壓縮的 iCCP chunk,移除衝突的 sRGB chunk,並重用經過驗證的 PNG 轉 PDF 內嵌路徑
在格式切換前先快照 ICC 設定檔,讓內嵌副本與來源逐位元組一致

啟動時檢查編解碼器

應用程式啟動時就探測編解碼器,別等第一張照片進門。ModernImageCodecAvailable 在已註冊回呼或可載入的 MagickWand 模組任一存在時回傳 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 產品頁