手機來的 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 位元組簽章 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)
在解碼之前先跑偵測,也是一種安全屬性。未知或偽裝的輸入永遠到不了外部編解碼器,改名的執行檔或畸形的上傳,由幾十個位元組比較擋下,而不是交給一個本來得硬啃它的大型影像解碼器
解碼在哪裡發生
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 與來源描述檔相同
啟動時檢查編解碼器
應用程式啟動時就探測編解碼器,別等第一張照片進門。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 產品頁