Article technique

Aplatir la rotation de pages PDF sans casser les boxes

Un numéro de page dessiné en x = 560, y = 30 en espace utilisateur PDF (origine en bas à gauche) appartient au coin inférieur droit d'une page Letter. Sur une page paysage scannée stockée en media portrait, avec /MediaBox [0 0 612 792] et /Rotate 90, le même appel de dessin place le numéro à 30 points du bord gauche et 52 points au-dessus du bas de ce que voit le lecteur, les chiffres courant droit vers le bas dans la marge. Le code d'estampillage a fait exactement ce qu'on lui a dit. Il a écrit dans un système de coordonnées que chaque viewer tourne d'un quart de tour horaire avant que quiconque ne le regarde

Les scanners et les applications de capture au téléphone produisent des pages comme ça tout le temps, car poser un drapeau de rotation coûte bien moins cher que réencoder un JPEG. Les viewers honorent /Rotate, donc le fichier paraît bon jusqu'à ce que quelque chose travaille en espace utilisateur brut : une routine d'estampillage, une étape d'imposition qui dimensionne ses cases d'après le seul /MediaBox, un RIP d'impression avec sa propre idée de l'orientation. La réparation durable est d'aplatir la rotation, en déplaçant le tour dans le flux de contenu et en posant /Rotate à 0 pour que la géométrie stockée et la géométrie affichée s'accordent enfin. Ça sonne comme une seule matrice. En pratique ça atteint cinq page boxes, trois sortes de géométrie d'annotations, chaque lien qui cible la page et l'arbre de structure, et ISO 32000-1 a une règle séparée pour chacun

Dans quel sens /Rotate tourne-t-il une page PDF ?

/Rotate tourne la page en horaire pour l'affichage et l'impression, par multiples de 90 degrés (ISO 32000-1 §7.7.3.3, Table 30). À 90 degrés, le bord gauche du media devient le haut et le bord haut devient le côté droit, donc dans un espace périphérique y-vers-le-bas le mapping est X = (y - Bottom) * Scale et Y = (x - Left) * Scale. À 270 degrés, le bord droit devient le haut à la place. La clé est aussi héritable : avec /Resources, /MediaBox et /CropBox, c'est l'un des quatre attributs de page qu'un ancêtre /Pages peut fournir (§7.7.3.4), donc un dictionnaire de page sans /Rotate propre peut quand même être tourné. THotPDF.GetLoadedPageRotation parcourt la chaîne /Parent, prend le premier /Rotate rencontré et le normalise en 0–359, donc un -90 stocké revient en 270

Le sens est la partie qui tourne mal sans que personne ne le remarque. Une matrice page-vers-périphérique avec les composantes y échangées pour 90 et 270 degrés ne tourne pas du tout la page — elle la reflète à travers la diagonale, et le déterminant change de signe. Les deux angles paraissent quand même tournés. La bitmap a la largeur et la hauteur échangées, et mapper un point vers la vue et retour renvoie où vous avez commencé, donc les contrôles de dimensions et les tests d'aller-retour passent sans broncher. Ce qui attrape l'erreur, c'est une page avec un marqueur asymétrique dans un coin, rendue et comparée pixel par pixel contre un moteur de rendu indépendant ; ne vérifier une implémentation de géométrie que contre elle-même ne prouve pas grand-chose ici. Dans HotPDF, FlattenLoadedPageRotation et RenderLoadedPageToBitmap partagent une seule convention horaire, donc un coin que le moteur dessine en haut à gauche d'une page tournée reste en haut à gauche après aplatissement

Comment HotPDF aplatit la rotation de pages en Delphi : une page portrait stockée avec /Rotate 90 s'affiche en horaire comme une vue paysage de 792 par 612, le mapping périphérique X = (y - Bottom) * Scale, Y = (x - Left) * Scale déplace chaque coin, et échanger les composantes y de la matrice produit une réflexion que seule une comparaison de marqueurs de coin attrape
Les lecteurs tournent la page en horaire pour l'affichage tandis que les octets restent portrait — GetLoadedPageRotation remonte d'abord la chaîne /Parent, car /Rotate est l'un des quatre attributs de page héritables

Aplatir une plage de pages avec FlattenLoadedPageRotation

THotPDF.FlattenLoadedPageRotation(PageRange, Info) traite chaque page de PageRange dont la rotation effective vaut 90, 180 ou 270 et renvoie le nombre de pages aplaties. Un PageRange vide signifie tout le document ; sinon la chaîne utilise la syntaxe à base un '1-3,7', et un numéro de page au-delà de la fin lève une exception au lieu de sortir discrètement de la plage. Les flux de contenu d'origine restent octet pour octet tels quels. La méthode place un nouveau flux en tête de /Contents portant q et un tour cm, place un flux portant Q à la fin, puis écrit /Rotate 0 dans le dictionnaire de page lui-même

/Rotate effectifFlux de préfixeNouveau 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]

Le zéro explicite compte plus qu'il n'y paraît. Supprimer la clé /Rotate semblerait plus propre, et ça casse chaque page dont le 90 venait d'un nœud /Pages : la page hérite du tour à nouveau et le viewer tourne un contenu déjà droit. Un /Rotate 0 sur le dictionnaire de page bloque cet héritage, ce qui en fait la seule valeur sûre à écrire

var
  Pdf: THotPDF;
  Info: THPDFRotationFlattenInfo;
  Flattened: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    if Pdf.LoadFromFile('scanned-batch.pdf') > 0 then
    begin
      // '' = chaque page ; les pages déjà à 0 degré sont comptées mais intactes
      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;

Journalisez l'enregistrement THPDFRotationFlattenInfo au lieu de le jeter. ScannedPageCount est le nombre de pages de la plage, FlattenedPageCount colle à la valeur de retour, et les trois compteurs Transformed... montrent si des liens, des marque-pages ou de la géométrie balisée pointaient vers les pages tournées. Zéro destination sur un lot de scanner est normal, puisque les scanners écrivent rarement des liens. Un fichier PDF/UA balisé qui rapporte zéro géométrie de structure alors que vous savez qu'il porte des boîtes englobantes de figures, c'est celui à ouvrir à la main

Lire chaque page box avant d'en écrire une seule

L'aplatissement ne réécrit que les boxes que la page possède déjà, et il les lit toutes avant d'écrire la première. L'ordre compte à cause de la chaîne par défaut du §14.11.2 : GetLoadedPageBox(PageIndex, pbCropBox, ...) renvoie le MediaBox quand la page n'a pas de /CropBox, et /BleedBox, /TrimBox et /ArtBox retombent sur le CropBox. Une boucle qui lit, tourne et écrit une box à la fois fonce droit dans cette chaîne. Elle tourne le MediaBox et le stocke, lit la « CropBox », récupère le MediaBox fraîchement tourné, le tourne une seconde fois et écrit une CropBox que la page n'a jamais eue. Sur une page Letter, ce second tour donne [0 -180 612 612], et rogné au nouveau MediaBox la page visible se réduit à un carré de 612 × 612

L'héritage partage les cinq boxes en deux groupes. MediaBox et CropBox se cherchent le long de la chaîne /Parent, tandis que BleedBox, TrimBox et ArtBox ne comptent que posés sur le dictionnaire de page lui-même. FlattenLoadedPageRotation suit le même partage quand il décide quelles boxes existent : une CropBox héritée est tournée et écrite sur la page, et un /TrimBox égaré sur un nœud /Pages est traité comme absent et jamais recopié vers le bas

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]));
  // Vrai même sans clé /TrimBox : la valeur retombe sur CropBox, puis MediaBox
  if Pdf.GetLoadedPageBox(PageIndex, pbTrimBox, L, B, R, T) then
    Writeln(Format('TrimBox  [%g %g %g %g]', [L, B, R, T]));
  // Letter préchargé ; GetLoadedPageVisibleBox laisse les sorties intactes en cas d'échec
  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;

Faites tourner ce helper avant et après l'aplatissement. Pour une page à 90 degrés avec MediaBox [0 0 612 792], le MediaBox aplati se lit [0 0 792 612]. Chaque box réécrite passe par le même tour horaire relatif à l'origine du MediaBox d'origine, donc le nouveau MediaBox démarre toujours à 0,0, et un TrimBox de [18 18 594 774] devient [18 18 774 594] — toujours 18 points du bord de la page paysage

GetLoadedPageVisibleBox renvoie la région qu'un viewer affiche et qu'une imprimante imprime : le CropBox rogné au MediaBox, normalisé pour que Left soit inférieur à Right et Bottom inférieur à Top. Le moteur de rendu de pages et l'export SVG dimensionnent leur sortie depuis cette même box. Le code qui veut la taille qu'une personne voit réellement devrait appeler GetLoadedPageVisibleBox, car lire /MediaBox pour ça donne la mauvaise réponse sur toute page avec un CropBox

Pourquoi HotPDF lit chaque page box avant d'en écrire une seule pendant FlattenLoadedPageRotation : BleedBox, TrimBox et ArtBox valent par défaut le CropBox, qui lui-même retombe sur la MediaBox, si bien que tourner les boxes une à la fois faisait lire à la CropBox la MediaBox déjà réécrite, et une seconde rotation écrivait une box que la page n'a jamais eue, recadrant une page paysage en carré
La chaîne de défauts fait que la sortie d'une box est l'entrée d'une autre — tout lire d'abord, transformer par rapport à l'origine de la MediaBox d'origine, puis écrire

Pourquoi les annotations cassent-elles quand on ne tourne que /Rect ?

Les annotations cassent parce qu'un flux d'apparence n'est jamais dessiné directement dans /Rect. Sous §12.5.5, le viewer transforme d'abord le /BBox du form par son /Matrix, puis met à l'échelle et translate la boîte englobante du résultat vers /Rect. Ne tournez que /Rect et un tampon de 200 × 40 se retrouve pressé dans une case de 40 × 200, où personne ne peut le lire. FlattenLoadedPageRotation multiplie donc à droite le tour horaire de la page sur chaque /Matrix d'apparence ([0 -1 1 0 0 0] à 90 degrés, en convention vecteur-ligne) à travers les apparences /N, /R et /D et chaque état à l'intérieur. Un seul flux d'apparence peut servir plusieurs annotations ou états, donc chaque flux est tourné exactement une fois par appel ; un flux partagé par des pages aux rotations différentes prend le tour de la première page qui l'atteint

Deux règles plus petites gardent champs de formulaire et post-its à leur place. L'entrée /MK /R d'un widget (§12.5.6.19) est un angle antihoraire, donc on lui soustrait l'angle horaire de la page, modulo 360. Le laisser tranquille et la prochaine régénération d'apparence dessine le texte du champ dans le mauvais sens. Les annotations avec le drapeau NoRotate (position de bit 5, valeur 16, §12.5.3) restent droites sur une page tournée et pivotent autour du coin supérieur gauche de leur /Rect ; pour celles-là la méthode garde la largeur, la hauteur et l'apparence droite, et ne déplace que ce coin là où le tour le met

Au-delà des dictionnaires d'annotation, le même appel tourne /QuadPoints, /Vertices, /L et /InkList. Il réécrit les destinations explicites qui nomment la page : les points /XYZ et les rectangles /FitR sont mappés à travers le tour, et à 90 ou 270 degrés /FitH et /FitBH deviennent /FitV et /FitBV, et l'inverse (§12.3.2.2). Il transforme aussi la géométrie balisée comme les entrées /BBox d'attributs sur les éléments de structure dont le /Pg est la page

L'arbre de structure, c'est là qu'une traversée naïve tourne mal de façon désagréable. Le /Pg d'un élément de structure pointe en retour vers l'objet page, donc un scanner qui transporte « ceci appartient à la page » dans chaque clé suit /Pg vers la page, puis vers /Annots — tournant les rectangles d'annotation une seconde fois — et vers les Form XObjects dont le /BBox vit dans l'espace du form et est déjà couvert par le cm externe. Suivre /P grimpe vers la racine de l'arbre et tire des éléments d'autres pages. Que l'un de ces feux se déclenche dépend de l'ordre où les objets se font visiter ; quand /Pages précède /StructTreeRoot dans le catalogue, la page tend à être atteinte d'abord et le dégât reste caché, ainsi des fichiers de test ordinaires peuvent passer. FlattenLoadedPageRotation ne transporte le contexte de page que par /K (enfants) et /A (attributs), et un enfant avec son propre /Pg vers une autre page est laissé à cette page

Pourquoi les annotations cassent quand une page HotPDF est aplatie en ne tournant que /Rect : un tampon de 200 par 40 est mis à l'échelle dans un emplacement de 40 par 200 et devient illisible, donc FlattenLoadedPageRotation multiplie à droite la rotation horaire dans chaque /Matrix d'apparence à travers /N, /R et /D, ajuste le /MK /R antihoraire et fait pivoter les annotations NoRotate sur leur coin supérieur gauche
Le lecteur fait tenir le BBox transformé de l'apparence dans /Rect, donc le flux lui-même doit tourner — une passe par apparence partagée, exactement une fois par appel

Vérifier le résultat avant d'expédier le lot

Une page aplatie doit paraître identique dans un viewer, et les vérifications utiles sont celles qui remarqueraient si ce n'était pas le cas. Quelques comportements façonnent la façon de la vérifier

  • Les pages dont la rotation effective vaut déjà 0, ou dont le MediaBox est absent ou de largeur ou hauteur nulle, sont sautées sans exception, donc comparez la valeur de retour au compte que vous attendiez changer
  • Les Form XObjects référencés depuis les ressources de la page gardent leur /BBox et leur /Matrix propres, car le cm externe tourne déjà tout ce qu'ils dessinent
  • Les destinations se trouvent en parcourant chaque objet indirect une fois par page aplatie ; sur un gros fichier avec des centaines de pages tournées, budgétez cette traversée à chacune
  • RenderLoadedPageToBitmap dessine les flux de contenu de la page et laisse les annotations de côté, donc un contrôle visuel de tampons tournés exige d'abord FlattenLoadedAnnotations, sur une copie de travail du document

La page de test qui se paie toute seule porte quelque chose d'asymétrique dans un coin, par exemple un carré plein en haut à gauche de la page affichée. Rendez-la avant l'aplatissement et après, puis comparez les pixels autour du marqueur. Largeur et hauteur seules s'accordent tout aussi volontiers sur une page reflétée

// Copie de travail seulement : FlattenLoadedAnnotations cuit les annotations
// dans le contenu de la page et les retire de la page
Pdf.FlattenLoadedAnnotations('1');              // plage de pages à base un
Before := Pdf.RenderLoadedPageToBitmap(0, 96);  // index de page à base zéro
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
    // Vos propres contrôles, pas des appels de la bibliothèque : les tailles doivent coller...
    Assert((Before.Width = After.Width) and (Before.Height = After.Height));
    // ...et les pixels du marqueur dans le coin supérieur gauche aussi
    Assert(Before.Canvas.Pixels[8, 8] = After.Canvas.Pixels[8, 8]);
  finally
    After.Free;
  end;
finally
  Before.Free;
end;

Si les tampons de vos pages tournées n'ont pas encore de flux d'apparence, la synthèse d'apparences d'annotations avant de les aplatir couvre cette étape. Le moteur derrière la comparaison de coins est décrit dans le rendu d'une page PDF chargée vers une bitmap, et la rédaction et l'assemblage N-up sur PDF chargés s'appuient sur la même idée d'ajouter des flux à /Contents sans réencoder les originaux. FlattenLoadedPageRotation, GetLoadedPageBox et GetLoadedPageVisibleBox sont livrés avec HotPDF pour Delphi et C++Builder — la page du composant PDF HotPDF pour Delphi a les détails