技術記事

Delphiでページボックスを壊さずPDFページ回転をフラット化

PDFユーザー空間(原点は左下)のx = 560、y = 30に描かれたページ番号は、Letterページなら右下コーナーに収まるはずのものです。横向きのスキャンページが縦向きメディアとして保存され、/MediaBox [0 0 612 792]と/Rotate 90を抱えていると、同じ描画呼び出しは、読み手に見えるものの左端から30ポイント、下端から52ポイント上に番号を置き、数字は余白に沿ってまっすぐ下へ走ります。スタンプコードは言われたとおりのことを、正確にやったのです。誰かが見る前にすべてのビューアーが1/4時計回りに回す座標系に書き込んだだけで

スキャナーとスマホのキャプチャーアプリは、こういうページを四六時中作ります。回転フラグを立てる方が、JPEGを再エンコードするよりはるかに安いからです。ビューアーは/Rotateを尊重するため、ファイルは、生のユーザー空間で作業する何かに出会うまで問題なく見えます。スタンプルーチン、/MediaBoxだけでスロットを寸法取りする面付け工程、独自の向き観を持つ印刷RIPです。持ちこたえる修正は回転をフラット化すること、つまり回転をコンテンツストリームへ移し、/Rotateを0にして、保存されたジオメトリと表示されるジオメトリをようやく一致させることです。1つのマトリクスのように聞こえます。実際には5つのページボックス、3種類の注釈ジオメトリ、そのページを指すすべてのリンクと構造ツリーに届き、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の祖先が供給できる4つのページ属性の1つです(§7.7.3.4)。つまり自分の/Rotateを持たないページ辞書でも回され得ます。THotPDF.GetLoadedPageRotationは/Parentチェーンをたどり、最初に会った/Rotateを0〜359へ正規化するため、保存された-90は270として戻ります

誰にも気づかれないまま間違えるのは方向です。90度と270度でy成分を入れ替えたページからデバイスへのマトリクスは、ページをまったく回しません。対角線を軸に鏡映します。行列式の符号が変わるのです。どちらの角度でも回って見えます。ビットマップは入れ替わった幅と高さを持ち、点をビューへ写してまた戻すと出発点に返るため、寸法検査も往復テストも文句なしに通ります。この過ちを捕まえるのは、非対称なマーカーを1つのコーナーに抱えたページをレンダリングし、独立のレンダラーとピクセル単位で比較することです。ジオメトリ実装を自分自身とだけ照らしても、ここではほとんど何も証明できません。HotPDFでは、FlattenLoadedPageRotationとRenderLoadedPageToBitmapが1つの時計回りの規約を共有するため、レンダラーが回転ページの左上に描くコーナーは、フラット化後も左上に留まります

HotPDFがDelphiでページ回転をフラット化する方法。/Rotate 90付きで保存された縦向きページは時計回りに792 × 612の横向きビューとして表示されます。デバイスマッピングX = (y - Bottom) * Scale、Y = (x - Left) * Scaleが各コーナーを動かし、マトリクスのy成分の入れ替えは鏡映を生み、コーナーマーカーの比較だけがそれを捕まえます
ビューアーは表示のためにページを時計回りに回しますが、バイト列は縦向きのままです。GetLoadedPageRotationはまず/Parentチェーンをたどります。/Rotateは継承可能なページ属性4つのうちの1つだからです

FlattenLoadedPageRotationでページ範囲をフラット化する

THotPDF.FlattenLoadedPageRotation(PageRange, Info)は、実効回転が90、180、270であるPageRange内の全ページを処理し、フラット化したページ数を返します。空のPageRangeはドキュメント全体を意味します。そうでなければ文字列は1ベースの'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は戻り値と一致し、3つのTransformed...カウンターは、回したページを指すリンク、ブックマーク、タグ付きジオメトリがあったかどうかを教えます。スキャナーのバッチでデスティネーションがゼロなのは普通です。スキャナーはめったにリンクを書きません。図のバウンディングボックスを運んでいると分かっているタグ付きPDF/UAファイルが、構造ジオメトリゼロを報告するなら、それだけは手で開くべきファイルです

何かを書く前にすべてのページボックスを読む

フラット化が書き直すのは、ページがすでに持つボックスだけです。しかも最初の1つを書く前に、すべてを読みます。順序が効くのは§14.11.2のデフォルトチェーンのためです。GetLoadedPageBox(PageIndex, pbCropBox, ...)は、ページに/CropBoxがないときMediaBoxを返し、/BleedBox、/TrimBox、/ArtBoxはCropBoxへフォールバックします。1つのボックスを読んでは回して書く、というループは、このチェーンにまっすぐ突っ込みます。MediaBoxを回して保存し、「CropBox」を読むと、回したばかりのMediaBoxが返り、それをもう1度回して、ページが持ったことのないCropBoxを書きます。Letterページではこの2度目の回転が[0 -180 612 612]を生み、新しいMediaBoxへクリップされた可視ページは612 × 612の正方形へ縮みます

継承は5つのボックスを2つのグループに分けます。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へクリップされ、LeftがRightより、BottomがTopより小さくなるよう正規化されたCropBoxです。ページレンダラーとSVG書き出しは、出力の寸法をこの同じボックスから取ります。人が実際に見るサイズが要るコードはGetLoadedPageVisibleBoxを呼ぶべきです。その目的で/MediaBoxを読むと、CropBoxを持つどんなページでも間違った答えが返ります

FlattenLoadedPageRotationでHotPDFが書く前にすべてのページボックスを読む理由。BleedBox、TrimBox、ArtBoxはCropBoxへデフォルトし、CropBox自身はMediaBoxへフォールバックします。だからボックスを1つずつ回すと、CropBoxがすでに書き直されたMediaBoxを読み、2度目の回転がページの持ったことのないボックスを書き、横向きページを正方形に刈り込みました
デフォルトチェーンでは、あるボックスの出力が別のボックスの入力です。まず全部読み、元のMediaBoxの原点に対して変換し、それから書く

/Rectだけ回すとなぜ注釈が壊れるのか

注釈が壊れるのは、アピアランスストリームが/Rectへまっすぐ描かれないからです。§12.5.5のもとで、ビューアーはまずフォームの/BBoxをその/Matrixで変換し、それから結果のバウンディングボックスを/Rectへスケールし平行移動します。/Rectだけ回すと、200 × 40のスタンプは40 × 200のスロットへ絞め込まれ、誰にも読めません。そこでFlattenLoadedPageRotationは、ページの時計回りの回転を各アピアランスの/Matrixへ右から乗算します(90度なら行ベクトル規約で[0 -1 1 0 0 0])。/N、/R、/Dのアピアランスと、その内側のすべての状態にわたってです。1つのアピアランスストリームは複数の注釈や状態に仕えるため、各ストリームは呼び出しごとに正確に1回だけ回されます。異なる回転を持つページたちに共有されるストリームは、最初にそれへ到達したページの回転を受け取ります

さらに2つの小さな規則が、フォームフィールドと付箋を所定の位置に保ちます。ウィジェットの/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へ入って注釈矩形を2度回し、フォーム空間に/BBoxを持ち外側のcmですでに覆われているForm XObjectへも入ります。/Pを追うとツリーの根へ登り、他のページの要素を引き込みます。これらが発火するかどうかは、オブジェクトを訪れる順番の偶然に依存します。カタログで/Pagesが/StructTreeRootより先行していると、ページが先に到達されがちで被害は隠れたままになるため、普通のテストファイルは通ってしまいます。FlattenLoadedPageRotationはページ文脈を/K(子)と/A(属性)だけに通し、別のページへ自分の/Pgを持つ子はそのページへ委ねます

HotPDFページを/Rectの回転だけでフラット化すると注釈が壊れる理由。200 × 40のスタンプは40 × 200のスロットへスケールされ、読めなくなります。だからFlattenLoadedPageRotationは時計回りの回転を各アピアランス/Matrixへ右から乗算し、/N、/R、/Dにわたり、反時計回りの/MK /Rを調整し、NoRotate注釈を左上コーナーでピボットさせます
ビューアーはアピアランスの変換済みBBoxを/Rectへはめ込みます。だからストリーム自身を回さなければなりません。共有アピアランスごとに1パス、呼び出しごとに正確に1度

バッチを出荷する前に結果を検査する

フラット化されたページはビューアーの中で同一に見えるはずで、役に立つ検査は、見えなかったときに気づく種類のものです。いくつかの振る舞いが検証の形を決めます

  • 実効回転がすでに0であるページや、MediaBoxが欠けているか幅か高さがゼロのページは、例外なしでスキップされます。戻り値を、変化を期待したカウントと比較してください
  • ページリソースから参照されるForm XObjectは、自分の/BBoxと/Matrixを保ちます。外側のcmがすでに描くものすべてを回しているからです
  • デスティネーションは、フラット化したページごとにすべての間接オブジェクトを1回たどって見つけます。数百の回転ページを持つ大きなファイルでは、ページごとにそのたどりの予算を取ってください
  • RenderLoadedPageToBitmapはページのコンテンツストリームを描き、注釈を外に置くため、回したスタンプの目視検査には、まずFlattenLoadedAnnotationsが要ります。ドキュメントのスクラッチコピーの上で

対価を払う価値のあるテストページは、表示されるページのどこかのコーナーに非対称なものを持ちます。たとえば左上の塗りつぶし四角です。フラット化の前と後でレンダリングし、そのマーカーの周りのピクセルを比較します。幅と高さだけなら、鏡映されたページでも同じように笑顔で一致します

// スクラッチコピー専用:FlattenLoadedAnnotationsは注釈をページコンテンツへ
// 焼き込み、ページから取り除く
Pdf.FlattenLoadedAnnotations('1');              // 1ベースのページ範囲
Before := Pdf.RenderLoadedPageToBitmap(0, 96);  // 0ベースのページインデックス
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はDelphiとC++Builder向けHotPDFに同梱されます。詳細はHotPDF Delphi PDFコンポーネントページにあります