Technischer Artikel

PDF-Seitenrotation in Delphi abflachen: Boxen unversehrt

Eine Seitenzahl, gezeichnet bei x = 560, y = 30 im PDF-User-Space (Ursprung unten links), gehört in die untere rechte Ecke einer Letter-Seite. Auf einer eingescannten Querformatseite, gespeichert als Hochformat-Medium, mit /MediaBox [0 0 612 792] und /Rotate 90, setzt derselbe Zeichenaufruf die Zahl 30 Punkte von der linken Kante und 52 Punkte über die Unterkante dessen, was der Leser sieht, mit den Ziffern geradewegs den Rand hinunterlaufend. Der Stempel-Code tat genau, was ihm aufgetragen war. Er schrieb in ein Koordinatensystem, das jeder Viewer um eine Vierteldrehung im Uhrzeigersinn dreht, bevor irgendwer hinschaut

Scanner und Handy-Capture-Apps produzieren solche Seiten ständig, denn ein Rotationsflag zu setzen ist weit billiger, als ein JPEG neu zu kodieren. Viewer ehren /Rotate, also sieht die Datei tadellos aus, bis etwas im rohen User-Space arbeitet: eine Stempel-Routine, ein Imposition-Schritt, der seine Slots allein aus /MediaBox bemisst, ein Druck-RIP mit eigener Vorstellung von Orientierung. Der dauerhafte Fix ist, die Rotation abzuflachen, die Drehung in den Content-Stream zu verlegen und /Rotate auf 0 zu setzen, sodass gespeicherte Geometrie und angezeigte Geometrie endlich übereinstimmen. Das klingt nach einer Matrix. In der Praxis erreicht es fünf Seitenboxen, drei Arten von Annotations-Geometrie, jeden Link, der auf die Seite zielt, und den Strukturbaum, und ISO 32000-1 hat für jede davon eine eigene Regel

In welche Richtung dreht /Rotate eine PDF-Seite?

/Rotate dreht die Seite für Anzeige und Druck im Uhrzeigersinn, in Vielfachen von 90 Grad (ISO 32000-1 §7.7.3.3, Tabelle 30). Bei 90 Grad wird die linke Kante des Mediums zur Oberkante und die Oberkante zur rechten Seite, also ist in einem y-nach-unten-Device-Space die Abbildung X = (y - Bottom) * Scale und Y = (x - Left) * Scale. Bei 270 Grad wird stattdessen die rechte Kante zur Oberkante. Das Schlüssel ist außerdem vererbbar: Zusammen mit /Resources, /MediaBox und /CropBox ist es eines der vier Seitenattribute, die ein /Pages-Vorfahre liefern kann (§7.7.3.4), also kann auch ein Seiten-Dictionary ohne eigenes /Rotate gedreht sein. THotPDF.GetLoadedPageRotation läuft die /Parent-Kette entlang, nimmt das erste /Rotate, dem es begegnet, und normalisiert es auf 0–359, also kommt ein gespeichertes -90 als 270 zurück

Die Richtung ist der Teil, der schiefgeht, ohne dass es jemand bemerkt. Eine Seite-zu-Device-Matrix mit vertauschten y-Komponenten für 90 und 270 Grad dreht die Seite überhaupt nicht — sie spiegelt sie über die Diagonale, und die Determinante wechselt das Vorzeichen. Beide Winkel sehen trotzdem gedreht aus. Die Bitmap hat die vertauschten Breite und Höhe, und einen Punkt in die Ansicht hinein und zurück abzubilden liefert den Ausgangspunkt, also bestehen Dimensionsprüfungen und Roundtrip-Tests ohne Murren. Was den Fehler erwischt, ist eine Seite mit einer asymmetrischen Marke in einer Ecke, gerendert und pixelweise gegen einen unabhängigen Renderer verglichen; eine Geometrie-Implementierung nur gegen sich selbst zu prüfen beweist hier sehr wenig. In HotPDF teilen FlattenLoadedPageRotation und RenderLoadedPageToBitmap eine einzige Uhrzeigersinn-Konvention, also sitzt eine Ecke, die der Renderer oben links auf einer gedrehten Seite zeichnet, nach dem Abflachen immer noch oben links

Wie HotPDF die Seitenrotation in Delphi abflacht: Eine als /Rotate 90 gespeicherte Hochformatseite erscheint im Uhrzeigersinn als 792-mal-612-Querformatansicht, die Device-Abbildung X = (y - Bottom) * Scale, Y = (x - Left) * Scale bewegt jede Ecke, und das Vertauschen der Matrix-y-Komponenten ergibt eine Spiegelung, die nur ein Eckmarken-Vergleich erwischt
Viewer drehen die Seite für die Anzeige im Uhrzeigersinn, während die Bytes Hochformat bleiben — GetLoadedPageRotation läuft zuerst die /Parent-Kette entlang, denn /Rotate ist eines der vier vererbbaren Seitenattribute

Einen Seitenbereich mit FlattenLoadedPageRotation abflachen

THotPDF.FlattenLoadedPageRotation(PageRange, Info) verarbeitet jede Seite in PageRange, deren effektive Rotation 90, 180 oder 270 ist, und liefert die Anzahl der abgeflachten Seiten zurück. Ein leerer PageRange bedeutet das ganze Dokument; sonst verwendet der String die 1-basierte '1-3,7'-Syntax, und eine Seitenzahl hinter dem Ende wirft eine Exception, statt still aus dem Bereich herauszufallen. Die ursprünglichen Content-Streams bleiben Byte für Byte, wie sie waren. Die Methode stellt einen neuen Stream mit q und einer cm-Drehung vorne an /Contents, setzt einen Stream mit Q hinten daran und schreibt dann /Rotate 0 ins Seiten-Dictionary selbst

Effektives /RotatePräfix-StreamNeue 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]

Die explizite Null zählt mehr, als sie aussieht. Das /Rotate-Schlüssel zu löschen wäre aufgeräumter, und es bricht jede Seite, deren 90 von einem /Pages-Knoten kam: Die Seite erbt die Drehung erneut, und der Viewer dreht Inhalt, der bereits aufrecht ist. Ein /Rotate 0 auf dem Seiten-Dictionary blockiert diese Vererbung, was es zum einzigen sicheren Wert macht, den man schreiben kann

var
  Pdf: THotPDF;
  Info: THPDFRotationFlattenInfo;
  Flattened: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    if Pdf.LoadFromFile('scanned-batch.pdf') > 0 then
    begin
      // '' = alle Seiten; Seiten, die bereits bei 0 Grad stehen, werden gezählt, aber unberührt gelassen
      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;

Loggen Sie den THPDFRotationFlattenInfo-Record, statt ihn wegzuwerfen. ScannedPageCount ist die Anzahl der Seiten im Bereich, FlattenedPageCount entspricht dem Rückgabewert, und die drei Transformed...-Zähler zeigen, ob Links, Bookmarks oder getaggte Geometrie auf die gedrehten Seiten zeigten. Null Destinationen über einen Scanner-Batch ist normal, denn Scanner schreiben selten überhaupt Links. Eine getaggte PDF/UA-Datei, die null Struktur-Geometrie meldet, während Sie wissen, dass sie Figuren-Begrenzungsboxen trägt, ist die eine, die man von Hand öffnet

Jede Seitenbox lesen, bevor man irgendeine schreibt

Abflachen schreibt nur die Boxen um, die die Seite bereits hat, und es liest alle, bevor es die erste schreibt. Die Reihenfolge zählt wegen der Default-Kette in §14.11.2: GetLoadedPageBox(PageIndex, pbCropBox, ...) liefert die MediaBox, wenn die Seite keine /CropBox hat, und /BleedBox, /TrimBox und /ArtBox fallen auf die CropBox zurück. Eine Schleife, die eine Box nach der anderen liest, dreht und schreibt, läuft direkt in diese Kette hinein. Sie dreht die MediaBox und speichert sie, liest die „CropBox“, bekommt die frisch gedrehte MediaBox zurück, dreht sie ein zweites Mal und schreibt eine CropBox, die die Seite nie hatte. Auf einer Letter-Seite ergibt dieser zweite Dreh [0 -180 612 612], und auf die neue MediaBox zugeschnitten schrumpft die sichtbare Seite auf ein 612-mal-612-Quadrat

Die Vererbung spaltet die fünf Boxen in zwei Gruppen. MediaBox und CropBox werden entlang der /Parent-Kette gesucht, während BleedBox, TrimBox und ArtBox nur zählen, wenn sie auf dem Seiten-Dictionary selbst sitzen. FlattenLoadedPageRotation folgt derselben Spaltung, wenn es entscheidet, welche Boxen existieren: Eine geerbte CropBox wird gedreht und auf die Seite geschrieben, und ein verirrtes /TrimBox auf einem /Pages-Knoten gilt als nicht vorhanden und wird nie hinunterkopiert

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]));
  // True sogar ohne /TrimBox-Schlüssel: der Wert fällt auf CropBox zurück, dann MediaBox
  if Pdf.GetLoadedPageBox(PageIndex, pbTrimBox, L, B, R, T) then
    Writeln(Format('TrimBox  [%g %g %g %g]', [L, B, R, T]));
  // Brief voreingestellt; GetLoadedPageVisibleBox lässt die Ausgaben bei Scheitern unangetastet
  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;

Laufen Sie diesen Helfer vor und nach dem Abflachen. Für eine 90-Grad-Seite mit MediaBox [0 0 612 792] liest sich die abgeflachte MediaBox als [0 0 792 612]. Jede umgeschriebene Box durchläuft dieselbe Drehung im Uhrzeigersinn relativ zum ursprünglichen MediaBox-Ursprung, also beginnt die neue MediaBox immer bei 0,0, und eine TrimBox von [18 18 594 774] wird [18 18 774 594] — weiterhin 18 Punkte von jeder Kante der Querformatseite entfernt

GetLoadedPageVisibleBox liefert die Region, die ein Viewer anzeigt und ein Drucker druckt: die CropBox, zugeschnitten auf die MediaBox, normalisiert, sodass Left kleiner als Right und Bottom kleiner als Top ist. Der Seitenrenderer und der SVG-Export bemessen ihre Ausgabe an derselben Box. Code, der die Größe wissen will, die eine Person tatsächlich sieht, sollte GetLoadedPageVisibleBox aufrufen, denn /MediaBox dafür zu lesen gibt auf jeder Seite mit CropBox die falsche Antwort

Warum HotPDF bei FlattenLoadedPageRotation jede Seitenbox liest, bevor es irgendeine schreibt: BleedBox, TrimBox und ArtBox fallen auf die CropBox zurück, die selbst auf die MediaBox zurückfällt — Boxen einzeln zu drehen ließ die CropBox also die bereits umgeschriebene MediaBox lesen, ein zweiter Dreh schrieb eine Box, die die Seite nie hatte, und schnitt eine Querformatseite auf ein Quadrat zu
Die Default-Kette bedeutet, dass die Ausgabe einer Box die Eingabe einer anderen ist — erst alles lesen, gegen den ursprünglichen MediaBox-Ursprung transformieren, dann schreiben

Warum brechen Annotationen, wenn man nur /Rect dreht?

Annotationen brechen, weil ein Appearance-Stream nie direkt in /Rect gezeichnet wird. Unter §12.5.5 transformiert der Viewer zuerst die /BBox des Formulars mit seiner /Matrix, dann skaliert und verschiebt er die Begrenzungsbox des Ergebnisses in /Rect. Dreht man nur /Rect, wird ein 200-mal-40-Stempel in einen 40-mal-200-Slot gequetscht, wo ihn niemand lesen kann. FlattenLoadedPageRotation multipliziert deshalb die Drehung der Seite im Uhrzeigersinn von rechts auf jede Appearance-/Matrix ([0 -1 1 0 0 0] bei 90 Grad, in der Row-Vektor-Konvention), über die /N-, /R- und /D-Appearances und jeden Zustand darin. Ein Appearance-Stream kann mehrere Annotationen oder Zustände bedienen, also wird jeder Stream pro Aufruf genau einmal gedreht; ein Stream, den Seiten mit unterschiedlichen Rotationen teilen, nimmt die Drehung der ersten Seite an, die ihn erreicht

Zwei kleinere Regeln halten Formfelder und Haftnotizen dort, wo sie hingehören. Der /MK /R-Eintrag eines Widgets (§12.5.6.19) ist ein Winkel gegen den Uhrzeigersinn, also wird der Uhrzeigersinn-Winkel der Seite modulo 360 von ihm subtrahiert. In Ruhe gelassen zeichnet die nächste Appearance-Regeneration den Feldtext in die falsche Richtung. Annotationen mit dem NoRotate-Flag (Bitposition 5, Wert 16, §12.5.3) bleiben auf einer gedrehten Seite aufrecht und pivieren um die obere linke Ecke ihrer /Rect; für diese hält die Methode Breite, Höhe und die aufrechte Appearance fest und verlegt nur diese Ecke dorthin, wo die Drehung sie hinlegt

Hinter den Annotation-Dictionaries dreht derselbe Aufruf /QuadPoints, /Vertices, /L und /InkList. Er schreibt explizite Destinationen um, die die Seite nennen: /XYZ-Punkte und /FitR-Rechtecke werden durch die Drehung gemappt, und bei 90 oder 270 Grad werden /FitH und /FitBH zu /FitV und /FitBV und umgekehrt (§12.3.2.2). Er transformiert auch getaggte Geometrie, etwa Attribut-/BBox-Einträge auf Strukturelementen, deren /Pg die Seite ist

Der Strukturbaum ist der Ort, an dem ein geradliniger Durchlauf auf unangenehme Weise schiefgeht. Das /Pg eines Strukturelements zeigt zurück auf das Seitenobjekt, also folgt ein Scanner, der „das gehört zur Seite“ jeden Schlüssel hinunterträgt, dem /Pg in die Seite hinein, dann in /Annots — und dreht Annotations-Rechtecke ein zweites Mal — und in Form XObjects, deren /BBox im Form-Space lebt und bereits von dem äußeren cm abgedeckt ist. Dem /P zu folgen klettert zur Baumwurzel und zieht Elemente anderer Seiten hinein. Ob etwas davon zündet, hängt davon ab, in welcher Reihenfolge die Objekte gerade besucht werden; wenn /Pages im Katalog vor /StructTreeRoot steht, wird die Seite tendenziell zuerst erreicht und der Schaden bleibt verborgen, also können gewöhnliche Testdateien bestehen. FlattenLoadedPageRotation trägt Seitenkontext nur durch /K (Kinder) und /A (Attribute), und ein Kind mit eigenem /Pg auf einer anderen Seite bleibt dieser Seite überlassen

Warum Annotationen brechen, wenn eine HotPDF-Seite allein durch Drehen von /Rect abgeflacht wird: Ein 200 mal 40 großer Stempel wird in einen 40 mal 200 großen Slot skaliert und wird unlesbar, also multipliziert FlattenLoadedPageRotation die Uhrzeigersinn-Drehung von rechts auf jede Appearance-/Matrix über /N, /R und /D, passt das gegenläufige /MK /R an und piviert NoRotate-Annotationen um ihre obere linke Ecke
Der Viewer passt die transformierte BBox der Appearance in /Rect ein, also muss der Stream selbst gedreht werden — ein Durchlauf pro geteilter Appearance, genau einmal pro Aufruf

Das Ergebnis prüfen, bevor Sie den Batch ausliefern

Eine abgeflachte Seite sollte in einem Viewer identisch aussehen, und die nützlichen Prüfungen sind die, die bemerken würden, wenn sie es nicht täte. Ein paar Verhaltensweisen prägen, wie Sie das verifizieren

  • Seiten, deren effektive Rotation bereits 0 ist, oder deren MediaBox fehlt oder Breite oder Höhe null hat, werden ohne Exception übersprungen, also vergleichen Sie den Rückgabewert mit der Anzahl, die Sie sich als geändert erwartet hätten
  • Form XObjects, die aus den Seitenressourcen referenziert werden, behalten ihr eigenes /BBox und ihre eigene /Matrix, denn das äußere cm dreht bereits alles, was sie zeichnen
  • Destinationen werden gefunden, indem jeder indirekte Objekt einmal pro abgeflachter Seite durchlaufen wird; bei einer großen Datei mit hunderten gedrehter Seiten planen Sie diesen Durchlauf für jede ein
  • RenderLoadedPageToBitmap zeichnet die Content-Streams der Seite und lässt Annotationen außen vor, also braucht eine visuelle Prüfung gedrehter Stempel zuerst FlattenLoadedAnnotations, auf einer Scratch-Kopie des Dokuments

Die Testseite, die sich bezahlt macht, hat etwas Asymmetrisches in einer Ecke, etwa ein gefülltes Quadrat oben links der angezeigten Seite. Rendern Sie sie vor dem Abflachen und danach, und vergleichen Sie die Pixel um diese Marke. Breite und Höhe allein stimmen auf einer gespiegelten Seite genauso fröhlich überein

// Nur auf einer Scratch-Kopie: FlattenLoadedAnnotations bäckt die Annotationen
// in den Seiteninhalt ein und entfernt sie von der Seite
Pdf.FlattenLoadedAnnotations('1');              // 1-basierter Seitenbereich
Before := Pdf.RenderLoadedPageToBitmap(0, 96);  // nullbasierter Seitenindex
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
    // Ihre eigenen Prüfungen, keine Bibliotheksaufrufe: die Größen müssen übereinstimmen...
    Assert((Before.Width = After.Width) and (Before.Height = After.Height));
    // ...und ebenso die Marken-Pixel in der oberen linken Ecke
    Assert(Before.Canvas.Pixels[8, 8] = After.Canvas.Pixels[8, 8]);
  finally
    After.Free;
  end;
finally
  Before.Free;
end;

Wenn die Stempel auf Ihren gedrehten Seiten noch keine Appearance-Streams haben, behandelt Annotation-Appearances vor dem Abflachen synthetisieren diesen Schritt. Der Renderer hinter dem Ecken-Vergleich ist in eine geladene PDF-Seite in eine Bitmap rendern beschrieben, und Schwärzung und N-up-Zusammenführung auf geladenen PDFs verlässt sich auf dieselbe Idee, Streams an /Contents anzuhängen, ohne die ursprünglichen neu zu kodieren. FlattenLoadedPageRotation, GetLoadedPageBox und GetLoadedPageVisibleBox kommen mit HotPDF für Delphi und C++Builder — die HotPDF-Delphi-PDF-Komponentenseite hat die Details