技術文章

在 Delphi 中使用 HotPDF 將 PDF 頁面渲染為點陣圖

一批供應商發票的縮圖列乍看沒問題:表格線在、標誌清晰、欄位對齊。放大其中一張,客戶名稱是一排空心方框,合計欄裡的字母拼不出任何字。每張壞掉的發票用的都是同一個字型 ABCDEF+Arial,而每一張在同一台機器的桌面 PDF 檢視器裡都讀得好好的。縮圖程式拿了字型名稱、剝掉六字母的子集前綴、向 Windows 要 Arial,然後把頁面裡的原始字元碼交給它。那些字元碼從來就不是 Arial 的。要從 PDF 頁面拿到忠實的點陣圖,需要兩件事:把頁面的內容資料流當程式執行,以及從檔案裡存的字形外框畫文字,而不是從渲染機器碰巧裝了什麼字型就畫什麼

PDF 頁面是要拿來執行的東西

ISO 32000-1 §8 把頁面描述成一條內容資料流:用 cm 改變換矩陣、用 q 與 Q 存取圖形狀態、建路徑、用 Tf 選字型、用 Tj 擺字形、用 Do 畫圖片與 form 的運算子。檔案裡沒有任何東西記錄任一像素的長相。要得到點陣圖,得有東西對著當前變換矩陣、狀態堆疊、剪裁路徑與一對填色描邊色彩空間執行那條資料流,再把結果光柵化

HotPDF 的 RenderLoadedPageToBitmap 就是那個直譯器。它走訪已載入頁面的運算子,按規範定義維護矩陣與圖形狀態,解析色彩空間,把 PDF 路徑變成 GDI 路徑,字形前進量取自字型的 /Widths 陣列而非 GDI。圖片 XObject 走的是庫裡提取用的同一批解碼器,所以HotPDF 為提取能解碼的每一種圖片濾鏡——JPXDecode 壓縮的 JPEG 2000 圖片在內——也會出現在渲染出的頁面上

HotPDF 頁面渲染管線:PDF 內容串流直譯器追蹤變換矩陣、圖形狀態、色彩空間、路徑、字形寬度與內嵌字形外框,回傳由呼叫端持有的 24 位元 RGB TBitmap
每個運算子更新它觸及的矩陣、圖形狀態、顏色、路徑或文字狀態,結果就是一張由呼叫端持有的點陣圖

在 Delphi 把已載入頁面渲染成 TBitmap

THotPDF.RenderLoadedPageToBitmap(PageIndex, DPI) 接受一個零起算的頁面索引與一個以 DPI 計的解析度,72 DPI 把一個 PDF 單位映射成一個像素,回傳一張全新的 24 位元 RGB TBitmap。索引超出範圍或無法建構的頁面回傳 nil 而不是丟例外。這正合檢視器的口味:跳過一頁壞的,繼續處理其餘的。點陣圖歸呼叫端所有

var
  Pdf: THotPDF;
  Bmp: TBitmap;
begin
  Pdf := THotPDF.Create(nil);
  try
    if Pdf.LoadFromFile('report.pdf') > 0 then
    begin
      Bmp := Pdf.RenderLoadedPageToBitmap(0, 144);  // 第一頁,144 DPI
      if Bmp <> nil then
      try
        Image1.Picture.Assign(Bmp);
      finally
        Bmp.Free;  // 回傳的點陣圖歸呼叫端所有
      end;
    end;
  finally
    Pdf.Free;
  end;
end;

像素尺寸由頁面的可見區域決定。渲染器取被 /MediaBox 裁剪的 /CropBox——ISO 32000-1 §14.11.2 定義的可見區域,沒有可用裁剪框時用 /MediaBox——按 DPI/72 縮放並無條件進位。所以沒有獨立裁剪框的美規 Letter 頁面在 72 DPI 下正好回傳 612×792 像素。A4 頁面(595.28×841.89 點)在 96 DPI 下算出 794×1123,因為 793.7 與 1122.5 都向上進位。/Rotate 90 或 270 會交換寬高,從 PDF 左下原點到 GDI 左上原點的翻轉發生在頁面矩陣內部,圖片直挺挺送達,不需要後處理

DPI 是唯一的縮放旋鈕,常見工作都罩得住。36 或 48 DPI 的縮圖小而快。96 或 144 DPI 的螢幕預覽符合典型顯示密度。300 DPI 的匯出給列印級輸出,代價是每張 Letter 頁面一張 2550×3300 的點陣圖,每色一位元組下約 24 MiB 一張

被替換的字型為什麼畫出錯字形?

渲染出的 PDF 裡出現錯字形,幾乎都是光柵化器拿了一個已安裝字型去頂檔案裡內嵌的那個。發票範例裡那條捷徑很誘人,因為它常常行得通:剝掉 /BaseFont 的子集前綴,用剩下的名稱要一支 GDI 字型,畫出字串。標準編碼的普通 Arial 或 Times New Roman 文字,沒人會抱怨

子集字型最先打破它。子集可能只帶文件用到的四十個字形,按該檔案私有的順序編號,所以碼 1 可能是「T」、碼 2 是「h」。已安裝字型無從知道這件事。自訂編碼、符號與條碼字型,以及渲染機器上缺的任何字體,都基於同一個理由失敗。就算替身字型每個字元都有,它的前進寬度也與內嵌字體不同,線條於是變長變短,右對齊的欄位不再對齊

HotPDF:系統字型替代會剝掉 ABCDEF+Arial 的子集前綴而畫出錯誤字形;內嵌字形渲染則重放 FontFile 輪廓,得到精確形狀
替換只在常見系統字型上存活,偏偏在那些非內嵌不可的子集字型上失效

從內嵌字型程式畫文字

HotPDF 從 PDF 裡存的字型程式畫文字。字型帶有內嵌 TrueType 程式(/FontFile2)或 CFF 程式(/FontFile3)時,每個字形都從那份資料取外框、以 GDI 路徑填色,字型大小、文字矩陣與當前變換矩陣組合成一個變換。子集字型、私有編碼與機器上從未見過的字體,都帶著真實形狀出場。字元碼怎麼到達字形取決於字型類型,而每種類型都有自己的陷阱:

  • TrueType 外框:輪廓來自 glyf 與 loca 表。二次曲線段被升階成 GDI 畫的三次貝茲——這是精確轉換;連續兩個離曲線點之間隱含的上曲線點會被重建;複合字形遞迴進自己的元件並套用每個元件的變換
  • CID 為鍵的 TrueType:疊在 CIDFontType2 上的 Type0 字型經 /CIDToGIDMap 到達圖形 ID——Identity(條目缺席時的預設)或明確的映射資料流——前進量取自 /W 與 /DW,雙位元組的 Identity-H 文字因此按正確步幅前進。預定義的 CJK CMap 與內嵌 CMap 資料流在查找之前先解出變長碼
  • CFF 程式:Type1C、CIDFontType0C 與包在 OpenType 容器裡的 CFF,跑的是一個 Type 2 charstring 直譯器,處理直線、曲線、flex 家族、hint 遮罩,以及套用了子常式偏置的區域與全域子常式呼叫。CID 為鍵的程式讓每個碼經過字型的 charset——字形順序與 CID 順序不同的子集正是關鍵——並經 FDArray 與 FDSelect 挑出每字形私用字典
  • 簡單 TrueType 字型:單位元組碼過內嵌 cmap,先試 Unicode 子表 (3,1) 與 (3,10),再試 (3,0) 符號子表——直接試一次、在符號字型用的 U+F000 鏡像再試一次——最後是老 Macintosh (1,0) 表

這之上還有兩條規則。簡單字型的 /Encoding 字典按 ISO 32000-1 §9.6.6 規定的順序解析:/Differences 覆蓋基礎編碼,基礎編碼覆蓋程式內建映射。TeX 與其他源自 PostScript 的工具鏈深深依賴這一條,順序弄錯,亂掉的恰恰是數學與符號文字——錯字形最難被察覺的地方。Type3 字型的字形是小段內容資料流,經同一個直譯器重播,字型矩陣、字型大小與文字矩陣組合在內;字形空間的 /Widths 按 §9.6.5 的要求過 /FontMatrix,宣告 d1 邊界框的字形程序被裁剪到框內,畸形的條碼字形畫不出自己的儲存格

單一個碼映射不出去時——程式損壞或子集缺那個字形——就那一個字元改用同名已安裝字型繪製,字串其餘部分照用內嵌外框。丟掉整個字串只會把問題藏起來;一個怪字母更容易被注意到。沒有可用內嵌程式的字型,走以系統字體渲染非內嵌字型描述的已安裝字型路線

怎麼讓重複渲染保持快?

任何互動場景,請呼叫 RenderLoadedPageToBitmapCached 而不是普通版。它把最近渲染的頁面留在以頁面索引、DPI 與當前渲染設定(色彩意圖、疊印預覽、後備政策,以及哪些選擇性內容圖層可見)為鍵的 MRU 快取裡,命中時交回一張全新的、歸呼叫端所有的副本,不再解讀內容資料流。在兩頁之間翻動,或以同 DPI 重新請求同一頁的視窗縮放,每次都命中快取。只拜訪每頁一次的一次性匯出,用普通 RenderLoadedPageToBitmap 更好,因為快取版會複製它回傳的每一張點陣圖,把沒人會再問的頁面留在記憶體裡

HotPDF:MRU 已渲染頁快取流程——命中時回傳全新的 TBitmap 複本,不必重新解讀頁面;未命中時渲染並儲存,上限 RenderCacheCapacity 頁
快取命中直接跳過內容串流,失效與記憶體預算則讓重複渲染既正確又安全
// 縮圖列:第一趟渲染,回捲時命中快取
Pdf.RenderCacheCapacity := 32;   // 條目上限;預設 8
for I := 0 to Pdf.LoadedPageCount - 1 do
begin
  Bmp := Pdf.RenderLoadedPageToBitmapCached(I, 48);
  if Bmp <> nil then
  try
    ThumbList.AddThumbnail(I, Bmp);  // 你自己的 UI 程式碼
  finally
    Bmp.Free;
  end;
end;

// 連 300 DPI 的頁面也要快取?給點陣快取更大的位元組預算
// (Policy: THPDFCacheAdmissionPolicy)
if Pdf.GetCacheAdmissionPolicy(clkRaster, Policy) then
begin
  Policy.MaxTotalBytes := Int64(512) * 1024 * 1024;
  Pdf.SetCacheAdmissionPolicy(clkRaster, Policy);
end;

// 直接改過頁面內容之後:
Pdf.InvalidateRenderedPageCache;  // 下一次渲染會反映這筆編輯

RenderCacheCapacity 只是兩個上限之一。點陣快取還有位元組預算,預設 128 MiB,每條目上限 64 MiB,記帳時每像素算四個位元組。假設檢視器快取 300 DPI 的 Letter 頁面:每條目按約 32 MiB 計,所以只裝得下三張,RenderCacheCapacity 說什麼都沒用。48 DPI 下同一頁按約 0.82 MiB 計,上面那個迴圈的縮圖最多 32 張全部常駐也花不到 27 MiB。快取滿了之後,只被要求過一次的頁面可能擠不掉經常被要求的頁面;它照樣被渲染、被回傳,只是不被保留。如果檢視器以可預測的順序翻頁,PrefetchLoadedPages 會在工作執行緒上搶在使用者之前把同一個快取填好

載入新文件會清空快取。庫自己的若干頁面編輯呼叫——例如 FlattenLoadedFormFields——會自行丟棄受影響的頁面;你自己直接改了頁面物件或內容資料流之後,請呼叫 InvalidateRenderedPageCache,因為快取無從得知頁面背後的位元組變了。底下還有第二個存放區,放解碼後的圖片 XObject,受 ImageCacheMaxBytes(預設 32 MiB)約束,所以每頁都重複的標誌或信頭,每次文件載入只解碼一次,而不是每個 Do 運算子解碼一次。InvalidateRenderedPageCache 連它一起清。要是縮圖得活過應用程式重啟,渲染快取的磁碟層處理那種情況

怎麼發現某一頁被近似處理過

大多數頁面根本碰不到後備,因為渲染器涵蓋的遠不止文字與圖片。CalGray、CalRGB、Lab 與基於 ICC 的色彩空間按當下生效的渲染意圖轉換——RenderColourIntent 可以覆寫——ConfigureRenderICCWorkflow 接受校樣與輸出 ICC 設定檔做軟校樣。Indexed 調色盤、Separation 與 DeviceN 色調,以及取樣 Type 0 函式色彩查找都有涵蓋。函式型、軸向、放射與網格著色,既透過 sh 運算子渲染也透過著色圖樣渲染;透明群組、knockout 群組與 alpha 或 luminosity 軟遮罩按各自混合模式合成,混合模式群組與 luminosity 遮罩一文有描述

真實世界的檔案仍然裝得下畫不準的東西:頁面指名卻從未定義的資源、資料解不開的圖片、自己畫自己的 Form XObject。這時由 RenderFallbackPolicy 決定怎麼辦。預設的 rfpIgnore 畫出最接近的近似然後繼續。rfpReport 做同樣的事,但為每次後備記下一筆診斷,上限 RenderFallbackDiagnosticLimit 條(預設 256)。rfpStrict 改為丟例外,不回傳近似點陣圖。Form 巢狀在 32 層處截止,引用自己的 form 會被跳過,損壞或惡意的檔案無法無限遞迴

// rfpReport 與 THPDFRenderFallbackDiagnostics 宣告在 HPDFPageRenderer
var
  Diags: THPDFRenderFallbackDiagnostics;
  J: Integer;
begin
  Pdf.RenderFallbackPolicy := rfpReport;
  Bmp := Pdf.RenderLoadedPageToBitmap(PageIndex, 150);
  try
    Diags := Pdf.GetLastRenderFallbackDiagnostics;
    for J := 0 to High(Diags) do
      Log.Add(Format('page %d: %s %s - %s', [PageIndex + 1,
        string(Diags[J].OperatorName), string(Diags[J].ObjectName),
        string(Diags[J].Reason)]));
    if Pdf.LastRenderFallbackDroppedCount > 0 then
      Log.Add(Format('%d more fallbacks not recorded',
        [Pdf.LastRenderFallbackDroppedCount]));
  finally
    Bmp.Free;  // 對 nil 呼叫 Free 是安全的
  end;
end;

QA 與進件建置請用 rfpReport。點陣圖與 rfpIgnore 產出的完全相同,日誌卻會指出哪些頁面被近似過、為什麼——趕在客戶回報第 14 頁看起來怪怪的之前。封存轉檔留給 rfpStrict,那種場景裡,悄悄近似過的頁面比失敗更糟。快取命中會還原該頁首次渲染時記下的診斷,所以 GetLastRenderFallbackDiagnostics 給出相同答案,無論快取版有沒有真的幹活

RenderLoadedPageToBitmap、快取變體與內嵌字形文字路徑,都是 HotPDF Delphi Component 的一部分——一個給 Delphi 與 C++Builder 的原生 VCL 程式庫,沒有外部 DLL,還能對你渲染的同一批已載入文件建立、編輯與提取文字