技術文章

Delphi 裡攤平 PDF 頁面旋轉而不弄壞頁面框

在 PDF 使用者空間(原點在左下)畫在 x = 560、y = 30 的頁碼,本該落在 Letter 頁的右下角。在一份以直式媒體存放的掃描橫式頁上——/MediaBox [0 0 612 792] 配 /Rotate 90——同一個繪製呼叫把數字放在讀者所見畫面左緣 30 點、底部上方 52 點處,數字還沿著邊緣直直往下跑。蓋章程式碼一步都沒做錯:它寫進了一個所有檢視器都會在任何人看到之前順時針轉四分之一圈的座標系

掃描器與手機拍攝應用程式整天產出這種頁面,設一個旋轉旗標比重新編碼 JPEG 便宜太多。檢視器買 /Rotate 的帳,檔案於是一直看起來沒事,直到有東西開始在原始使用者空間裡工作:蓋章常式、只看 /MediaBox 決定槽位尺寸的拼版步驟、對方向另有主張的列印 RIP。治本的辦法是把旋轉攤平:把轉動搬進內容串流、把 /Rotate 設 0,存放的幾何與顯示的幾何終於說同一種話。聽起來像一個矩陣的事,實際上牽涉五個頁面框、三種註記幾何、每個指向該頁的連結與結構樹,而 ISO 32000-1 為它們每一個都準備了單獨的規則

/Rotate 把 PDF 頁面往哪邊轉?

/Rotate 為顯示與列印把頁面順時針轉,以 90 度的倍數為單位(ISO 32000-1 §7.7.3.3,Table 30)。90 度時媒體的左緣變成上緣、上緣變成右側,所以在 y 向下的設備空間裡映射是 X = (y - Bottom) * Scale、Y = (x - Left) * Scale。270 度則是右緣變上緣。這個鍵還可繼承:與 /Resources、/MediaBox、/CropBox 並列,它是 /Pages 祖先可以代供的四個頁面屬性之一(§7.7.3.4),自己沒帶 /Rotate 的頁面照樣可能被轉。THotPDF.GetLoadedPageRotation 走 /Parent 鏈、取遇到的第一個 /Rotate、正規化到 0–359,存放的 -90 因此回來是 270

方向是那個沒人察覺就出錯的部分。y 分量在 90 與 270 度時對調的頁到設備矩陣,根本沒有旋轉頁面——它沿對角線鏡射,行列式變號。兩個角度看起來都「轉了」:點陣圖有對調過的寬高,把點映射進視圖再映射回來還是原點,尺寸檢查與往返測試於是毫無怨言地通過。能逮到這個錯的,是一角帶不對稱標記的頁面,渲染後與獨立渲染器逐像素比對——只拿幾何實作跟自己比,在這裡證明不了什麼。HotPDF 裡 FlattenLoadedPageRotation 與 RenderLoadedPageToBitmap 共用同一個順時針約定,渲染器畫在轉過頁面左上角的標記,攤平之後還在左上角

HotPDF 在 Delphi 裡攤平頁面旋轉的方式:以 /Rotate 90 存放的直式頁面順時針顯示成 792×612 的橫式視圖,設備映射 X = (y - Bottom) * Scale、Y = (x - Left) * Scale 搬動每個角落;把矩陣的 y 分量對調則得到鏡射,只有角落標記比對抓得到
檢視器顯示時順時針轉頁,位元組仍躺成直式——GetLoadedPageRotation 先走 /Parent 鏈,因為 /Rotate 是四個可繼承頁面屬性之一

用 FlattenLoadedPageRotation 攤平頁面範圍

THotPDF.FlattenLoadedPageRotation(PageRange, Info) 處理 PageRange 裡每個有效旋轉為 90、180 或 270 的頁面,回傳攤平了幾頁。空的 PageRange 意味整份文件;字串則用一基起算的 '1-3,7' 語法,越過結尾的頁碼丟例外,不會悄悄滑出範圍。原始內容串流逐位元組保持原樣:方法把裝著 q 與一個 cm 旋轉的新串流放在 /Contents 最前面、把裝著 Q 的串流放在最後,然後把 /Rotate 0 寫進頁面字典本身

有效 /Rotate前綴串流新 MediaBox
90q 0 -1 1 0 -Bottom Width+Left cm[0 0 Height Width]
180q -1 0 0 -1 Width+Left Height+Bottom cm[0 0 Width Height]
270q 0 1 -1 0 Height+Bottom -Left cm[0 0 Height Width]

那個顯式的零比看上去重要。刪掉 /Rotate 鍵似乎更乾淨,卻弄壞每個 90 來自 /Pages 節點的頁面:頁面再次繼承轉動,檢視器把已經正立的內容又轉一遍。頁面字典上的 /Rotate 0 擋住這個繼承,是唯一安全的寫入值

var
  Pdf: THotPDF;
  Info: THPDFRotationFlattenInfo;
  Flattened: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    if Pdf.LoadFromFile('scanned-batch.pdf') > 0 then
    begin
      // '' = 全部頁面;已在 0 度的頁面會計入但不動
      Flattened := Pdf.FlattenLoadedPageRotation('', Info);
      Writeln(Format('Scanned %d, flattened %d pages',
        [Info.ScannedPageCount, Info.FlattenedPageCount]));
      Writeln(Format('Turned %d annotations, %d destinations, %d tagged geometry entries',
        [Info.TransformedAnnotationCount, Info.TransformedDestinationCount,
         Info.TransformedStructureGeometryCount]));
      if Flattened > 0 then
        Pdf.SaveLoadedDocument('scanned-batch-upright.pdf');
    end;
  finally
    Pdf.Free;
  end;
end;

把 THPDFRotationFlattenInfo 記錄記下來,別丟掉。ScannedPageCount 是範圍內頁數,FlattenedPageCount 與回傳值一致,三個 Transformed... 計數顯示連結、書籤或標記幾何是否指向被轉的頁面。掃描批次裡 destinations 為零很正常,掃描器本來就少寫連結。標記了 PDF/UA、你明知帶有圖形邊界框、卻回報零結構幾何的檔案,才是該親手打開看的那種

寫入任何框之前,先讀完每個框

攤平只改寫頁面已有的框,而且寫第一個之前把所有框都讀完。順序之所以要緊,是因為 §14.11.2 的預設鏈:GetLoadedPageBox(PageIndex, pbCropBox, ...) 在頁面沒有 /CropBox 時回傳 MediaBox,/BleedBox、/TrimBox、/ArtBox 則回退到 CropBox。一次讀一個、轉一個、寫一個的迴圈會一頭撞進這條鏈:它轉了 MediaBox 並存起來,接著讀「CropBox」——拿回剛轉過的 MediaBox——再轉第二次,寫出一個頁面從未有過的 CropBox。Letter 頁上這第二轉得到 [0 -180 612 612],裁到新 MediaBox 之後,可見頁面縮成一個 612×612 的方形

繼承把五個框分成兩組。MediaBox 與 CropBox 沿 /Parent 鏈查找;BleedBox、TrimBox、ArtBox 只有坐在頁面字典本身時才算數。FlattenLoadedPageRotation 判斷哪些框存在時遵循同樣的分法:繼承來的 CropBox 會被轉動並寫上頁面;/Pages 節點上落單的 /TrimBox 視同不存在,絕不往下抄

procedure DumpPageGeometry(Pdf: THotPDF; PageIndex: Integer);
var
  L, B, R, T: Single;
begin
  Writeln('Effective /Rotate: ', Pdf.GetLoadedPageRotation(PageIndex));
  if Pdf.GetLoadedPageBox(PageIndex, pbMediaBox, L, B, R, T) then
    Writeln(Format('MediaBox [%g %g %g %g]', [L, B, R, T]));
  // 沒有 /TrimBox 鍵也回 True:值回退到 CropBox,再退到 MediaBox
  if Pdf.GetLoadedPageBox(PageIndex, pbTrimBox, L, B, R, T) then
    Writeln(Format('TrimBox  [%g %g %g %g]', [L, B, R, T]));
  // 先預設 Letter;失敗時 GetLoadedPageVisibleBox 不動輸出參數
  L := 0; B := 0; R := 612; T := 792;
  Pdf.GetLoadedPageVisibleBox(PageIndex, L, B, R, T);
  Writeln(Format('Visible  [%g %g %g %g]', [L, B, R, T]));
end;

攤平前後各跑一次那個輔助函式。MediaBox [0 0 612 792] 的 90 度頁面,攤平後 MediaBox 讀作 [0 0 792 612]。每個被改寫的框都對著原始 MediaBox 原點做同樣的順時針旋轉,新 MediaBox 因此總是從 0,0 起步;[18 18 594 774] 的 TrimBox 變成 [18 18 774 594]——離橫式頁每個邊緣依然是 18 點

GetLoadedPageVisibleBox 回傳檢視器顯示、印表機列印的區域:裁到 MediaBox 的 CropBox,並正規化成 Left 小於 Right、Bottom 小於 Top。頁面渲染器與 SVG 匯出都用同一個框決定輸出尺寸。想要「人實際看到的大小」的程式碼應該呼叫 GetLoadedPageVisibleBox——為這個目的去讀 /MediaBox,在帶 CropBox 的頁面上必得錯的答案

FlattenLoadedPageRotation 為何先讀完所有頁面框再動手:BleedBox、TrimBox、ArtBox 預設取 CropBox,CropBox 又回退到 MediaBox;一次轉一個框,CropBox 會讀到剛改寫完的 MediaBox,第二度旋轉寫出頁面從未有過的框,把橫式頁裁成一個方形
預設鏈讓一個框的輸出成為另一個框的輸入——先全部讀完、對著原始 MediaBox 原點變換,然後才寫

只轉 /Rect 時,註記為什麼會壞?

註記會壞,是因為外觀串流從不直接畫進 /Rect。按 §12.5.5,檢視器先用 form 的 /Matrix 變換 /BBox,再把結果的邊界框縮放平移塞進 /Rect。只轉 /Rect,200×40 的印章被擠進 40×200 的槽位,沒人讀得了。FlattenLoadedPageRotation 因此把頁面的順時針旋轉右乘到每個外觀 /Matrix 上(90 度時是行向量約定下的 [0 -1 1 0 0 0]),遍及 /N、/R、/D 外觀與其中每個狀態。一份外觀串流可以服務多個註記或多個狀態,所以每次呼叫每份串流只轉一次;被不同旋轉的頁面共用的串流,取第一個碰到它的頁面的轉角

兩條小規則把表單欄位與便條釘在原位。widget 的 /MK /R 條目(§12.5.6.19)是逆時針角度,頁面的順時針角度要從它身上減掉、模 360。放著不管,下一次外觀再生成就會把欄位文字畫反。帶 NoRotate 旗標(位元位置 5、值 16,§12.5.3)的註記在轉過的頁面上保持正立、繞自己 /Rect 的左上角轉動;對這些註記,方法保留寬、高與正立的外觀,只把那個角落搬到旋轉放它的地方

過了註記字典,同一個呼叫還轉 /QuadPoints、/Vertices、/L 與 /InkList;改寫指名該頁的顯式目的地:/XYZ 點與 /FitR 矩形穿過旋轉映射,90 與 270 度時 /FitH 與 /FitBH 對調成 /FitV 與 /FitBV(§12.3.2.2);也變換標記幾何,例如 /Pg 指向該頁的結構元素上的屬性 /BBox 條目

結構樹是直接走訪會摔得很難看的地方。結構元素的 /Pg 回指頁面物件,把「這屬於這一頁」帶進每個鍵的掃描器會沿 /Pg 進頁面、再進 /Annots——把註記矩形又轉一遍——再進 /BBox 住在 form 空間、早已被外層 cm 蓋住的 Form XObject。沿 /P 爬則爬到樹根,把其他頁的元素捲進來。這些觸不觸發取決於物件被走訪的順序:目錄裡 /Pages 排在 /StructTreeRoot 前面時,頁面往往先被走到、傷害保持隱形,普通測試檔因此能過。FlattenLoadedPageRotation 只沿 /K(子節點)與 /A(屬性)攜帶頁面脈絡,自己帶著別頁 /Pg 的子節點留給那一頁

只轉 /Rect 來攤平 HotPDF 頁面時註記為何壞掉:200×40 的印章被塞進 40×200 的槽位而無法閱讀;FlattenLoadedPageRotation 因此把順時針旋轉右乘到 /N、/R、/D 每個外觀 /Matrix 上,調整逆時針的 /MK /R,並讓 NoRotate 註記繞自己左上角轉動
檢視器把外觀變換後的 BBox 塞進 /Rect,所以串流本身必須轉——共用外觀每次呼叫恰好一圈

出貨整批之前先驗結果

攤平後的頁面在檢視器裡應該一模一樣,有用的檢查是那種「不一樣就會發現」的檢查。幾個行為決定了你該怎麼驗

  • 有效旋轉已是 0、或 MediaBox 缺失或寬高為零的頁面,無例外地跳過,所以要把回傳值跟你預期會變的數量對一對
  • 從頁面資源引用的 Form XObjects 保有自己的 /BBox 與 /Matrix,因為外層的 cm 已經轉動了它們畫的一切
  • 目的地靠每攤平一頁就把所有間接物件走訪一遍找到;幾百頁旋轉頁的大檔,每一頁都要為這趟走訪編預算
  • RenderLoadedPageToBitmap 畫頁面內容串流、不含註記,所以轉過印章的視覺檢查得先在文件草稿副本上跑 FlattenLoadedAnnotations

值得花的那張測試頁,某個角落裡有點不對稱的東西,比如顯示頁面左上角一個實心方塊。攤平前渲染一次、攤平後再渲染一次,比對標記周圍的像素。只看寬高,鏡射過的頁面同樣高高興興地吻合

// 只在草稿副本上做:FlattenLoadedAnnotations 會把註記
// 烘進頁面內容並從頁面移除
Pdf.FlattenLoadedAnnotations('1');              // 一基起算的頁範圍
Before := Pdf.RenderLoadedPageToBitmap(0, 96);  // 零基起算的頁索引
if Before = nil then
  raise Exception.Create('Page 1 did not render');
try
  Pdf.FlattenLoadedPageRotation('1', Info);
  After := Pdf.RenderLoadedPageToBitmap(0, 96);
  if After = nil then
    raise Exception.Create('Flattened page 1 did not render');
  try
    // 你自己的檢查,不是函式庫呼叫:尺寸必須一致…
    Assert((Before.Width = After.Width) and (Before.Height = After.Height));
    // …左上角的標記像素也必須一致
    Assert(Before.Canvas.Pixels[8, 8] = After.Canvas.Pixels[8, 8]);
  finally
    After.Free;
  end;
finally
  Before.Free;
end;

轉過的頁面上印章還沒有外觀串流的話,攤平前合成註記外觀講的就是那一步。角落比對背後的渲染器見把已載入 PDF 頁面渲染成點陣圖;已載入 PDF 的遮蓋與 N-up 拼頁依賴的正是「往 /Contents 加串流而不重新編碼原始串流」的同一個思路。FlattenLoadedPageRotation、GetLoadedPageBox 與 GetLoadedPageVisibleBox 隨 HotPDF 出貨,支援 Delphi 與 C++Builder——細節見HotPDF Delphi PDF 元件頁