Articolo tecnico

Appiattire /Rotate nelle pagine PDF senza rompere i box

Un numero di pagina disegnato a x = 560, y = 30 nello spazio utente PDF (origine in basso a sinistra) appartiene all'angolo in basso a destra di una pagina Letter. Su una pagina scansionata in orizzontale conservata come media verticale, con /MediaBox [0 0 612 792] e /Rotate 90, la stessa chiamata di disegno mette il numero a 30 punti dal bordo sinistro e 52 punti sopra il fondo di ciò che il lettore vede, con le cifre che corrono dritte lungo il margine. Il codice di stamping ha fatto esattamente ciò che gli è stato detto. Ha scritto in un sistema di coordinate che ogni viewer ruota di un quarto in senso orario prima che qualcuno lo guardi

Scanner e app di cattura da telefono producono pagine così continuamente, perché impostare un flag di rotazione costa molto meno che ricodificare un JPEG. I viewer onorano /Rotate, quindi il file sembra a posto finché qualcosa non lavora nello spazio utente grezzo: una routine di stamping, un passo di imposition che dimensiona gli slot dal solo /MediaBox, un print RIP con le sue idee sull'orientamento. La correzione duratura è appiattire la rotazione, spostando la rotazione nello stream di contenuto e impostando /Rotate a 0 così che la geometria conservata e la geometria mostrata finalmente concordino. Sembra una sola matrice. In pratica tocca cinque page box, tre tipi di geometria delle annotazioni, ogni link che punta alla pagina e l'albero di struttura, e ISO 32000-1 ha una regola separata per ognuno

In che senso /Rotate ruota una pagina PDF?

/Rotate ruota la pagina in senso orario per visualizzazione e stampa, a multipli di 90 gradi (ISO 32000-1 §7.7.3.3, Tabella 30). A 90 gradi il bordo sinistro del media diventa il cima e il bordo superiore diventa il lato destro, quindi in uno spazio device con y verso il basso la mappatura è X = (y - Bottom) * Scale e Y = (x - Left) * Scale. A 270 gradi è il bordo destro a diventare la cima. La chiave è inoltre ereditabile: insieme a /Resources, /MediaBox e /CropBox è uno dei quattro attributi di pagina che un antenato /Pages può fornire (§7.7.3.4), quindi un dizionario di pagina senza /Rotate proprio può comunque essere ruotato. THotPDF.GetLoadedPageRotation percorre la catena /Parent, prende il primo /Rotate che incontra e lo normalizza in 0–359, così un -90 conservato torna come 270

La direzione è la parte che va storta senza che nessuno se ne accorga. Una matrice pagina→device con le componenti y scambiate per 90 e 270 gradi non ruota affatto la pagina — la riflette attraverso la diagonale, e il determinante cambia segno. Entrambi gli angoli sembrano comunque ruotati. La bitmap ha larghezza e altezza scambiate, e mappare un punto nella vista e indietro restituisce il punto di partenza, così i controlli di dimensione e i test di round trip passano senza proteste. Quello che becca l'errore è una pagina con un marcatore asimmetrico in un angolo, renderizzata e confrontata pixel per pixel contro un renderer indipendente; controllare un'implementazione di geometria solo contro se stessa prova ben poco qui. In HotPDF FlattenLoadedPageRotation e RenderLoadedPageToBitmap condividono una sola convenzione oraria, quindi un angolo che il renderer disegna in alto a sinistra di una pagina ruotata resta in alto a sinistra dopo l'appiattimento

Come HotPDF appiattisce la rotazione delle pagine in Delphi: una pagina verticale conservata con /Rotate 90 viene mostrata in orario come vista orizzontale di 792 per 612, la mappatura device X = (y - Bottom) * Scale, Y = (x - Left) * Scale sposta ogni angolo, e scambiare le componenti y della matrice produce una riflessione che solo un confronto con marcatore d'angolo becca
I viewer ruotano la pagina in orario per la visualizzazione mentre i byte restano verticali — GetLoadedPageRotation percorre prima la catena /Parent, perché /Rotate è uno dei quattro attributi di pagina ereditabili

Appiattire un intervallo di pagine con FlattenLoadedPageRotation

THotPDF.FlattenLoadedPageRotation(PageRange, Info) elabora ogni pagina in PageRange la cui rotazione effettiva è 90, 180 o 270 e restituisce quante ne ha appiattite. Un PageRange vuoto significa l'intero documento; altrimenti la stringa usa la sintassi a base uno '1-3,7', e un numero di pagina oltre la fine solleva un'eccezione anziché uscire di nascosto dall'intervallo. Gli stream di contenuto originali vengono lasciati byte per byte come erano. Il metodo mette in cima a /Contents un nuovo stream che contiene q e una rotazione cm, mette in fondo uno stream con Q, e poi scrive /Rotate 0 nel dizionario della pagina stessa

Rotazione effettiva /RotateStream di prefissoNuovo 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]

Lo zero esplicito conta più di quanto sembri. Eliminare la chiave /Rotate sembrerebbe più ordinato, e rompe ogni pagina il cui 90 veniva da un nodo /Pages: la pagina eredita di nuovo la rotazione e il viewer ruota un contenuto già dritto. Un /Rotate 0 sul dizionario di pagina blocca quell'eredità, il che lo rende l'unico valore sicuro da scrivere

var
  Pdf: THotPDF;
  Info: THPDFRotationFlattenInfo;
  Flattened: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    if Pdf.LoadFromFile('scanned-batch.pdf') > 0 then
    begin
      // '' = tutte le pagine; le pagine già a 0 gradi sono contate ma non toccate
      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;

Loggate il record THPDFRotationFlattenInfo anziché buttarlo via. ScannedPageCount è il numero di pagine nell'intervallo, FlattenedPageCount combacia con il valore di ritorno, e i tre contatori Transformed... mostrano se link, bookmark o geometria taggata puntavano alle pagine ruotate. Zero destinazioni su un batch da scanner è normale, visto che gli scanner raramente scrivono link. Un file PDF/UA taggato che riporta zero geometria di struttura mentre sapete che porta bounding box di figure è quello da aprire a mano

Leggere ogni page box prima di scriverne uno

L'appiattimento riscrive solo i box che la pagina ha già, e li legge tutti prima di scrivere il primo. L'ordine conta a causa della catena di default della §14.11.2: GetLoadedPageBox(PageIndex, pbCropBox, ...) restituisce il MediaBox quando la pagina non ha /CropBox, e /BleedBox, /TrimBox e /ArtBox ripiegano sul CropBox. Un ciclo che legge, ruota e scrive un box alla volta ci finisce dritto dentro. Ruota il MediaBox e lo conserva, legge il «CropBox», riceve indietro il MediaBox appena ruotato, lo ruota una seconda volta e scrive un CropBox che la pagina non ha mai avuto. Su una pagina Letter quella seconda rotazione dà [0 -180 612 612], e ritagliata al nuovo MediaBox la pagina visibile si riduce a un quadrato di 612 × 612

L'eredità divide i cinque box in due gruppi. MediaBox e CropBox vengono cercati lungo la catena /Parent, mentre BleedBox, TrimBox e ArtBox contano solo quando stanno sul dizionario della pagina stessa. FlattenLoadedPageRotation segue la stessa divisione quando decide quali box esistono: un CropBox ereditato viene ruotato e scritto sulla pagina, e un /TrimBox disperso su un nodo /Pages è trattato come assente e non viene mai copiato giù

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 anche senza una chiave /TrimBox: il valore ripiega su CropBox, poi MediaBox
  if Pdf.GetLoadedPageBox(PageIndex, pbTrimBox, L, B, R, T) then
    Writeln(Format('TrimBox  [%g %g %g %g]', [L, B, R, T]));
  // Preset Letter; GetLoadedPageVisibleBox lascia intatti gli output in caso di fallimento
  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;

Fate girare quell'helper prima e dopo l'appiattimento. Per una pagina a 90 gradi con MediaBox [0 0 612 792], il MediaBox appiattito legge [0 0 792 612]. Ogni box riscritto passa per la stessa rotazione oraria relativa all'origine del MediaBox originale, quindi il nuovo MediaBox parte sempre da 0,0, e un TrimBox di [18 18 594 774] diventa [18 18 774 594] — sempre 18 punti dentro da ogni bordo della pagina orizzontale

GetLoadedPageVisibleBox restituisce la regione che un viewer mostra e una stampante stampa: il CropBox ritagliato al MediaBox, normalizzato così che Left sia minore di Right e Bottom minore di Top. Il renderer di pagine e l'export SVG dimensionano il loro output dallo stesso box. Il codice che vuole la dimensione che una persona vede davvero dovrebbe chiamare GetLoadedPageVisibleBox, perché leggere /MediaBox per quello scopo dà la risposta sbagliata su qualsiasi pagina con un CropBox

Perché HotPDF legge ogni page box prima di scriverne uno durante FlattenLoadedPageRotation: BleedBox, TrimBox e ArtBox fanno default al CropBox, che a sua volta ripiega sul MediaBox, quindi ruotare i box uno alla volta fa leggere al CropBox il MediaBox già riscritto e una seconda rotazione scrive un box che la pagina non ha mai avuto, ritagliando una pagina orizzontale a un quadrato
La catena di default significa che l'output di un box è l'input di un altro — leggete tutto prima, trasformate contro l'origine del MediaBox originale, poi scrivete

Perché le annotazioni si rompono se ruoti solo /Rect?

Le annotazioni si rompono perché uno stream di appearance non viene mai disegnato dritto dentro /Rect. Secondo la §12.5.5 il viewer trasforma prima la /BBox della form tramite la sua /Matrix, poi ridimensiona e trasla la bounding box del risultato dentro /Rect. Ruotate solo /Rect e uno stamp di 200 × 40 viene spremuto in uno slot di 40 × 200, dove nessuno può leggerlo. FlattenLoadedPageRotation quindi moltiplica a destra la rotazione oraria della pagina su ogni /Matrix di appearance ([0 -1 1 0 0 0] a 90 gradi, nella convenzione row-vector) attraverso le appearance /N, /R e /D e ogni stato dentro di loro. Uno stream di appearance può servire più annotazioni o stati, quindi ogni stream viene ruotato esattamente una volta per chiamata; uno stream condiviso da pagine con rotazioni diverse prende la rotazione della prima pagina che lo raggiunge

Due regole minori tengono campi modulo e post-it dove stanno. La voce /MK /R di un widget (§12.5.6.19) è un angolo antiorario, quindi l'angolo orario della pagina gli viene sottratto, modulo 360. Lasciatelo stare e la prossima rigenerazione di appearance disegna il testo del campo nella direzione sbagliata. Le annotazioni con flag NoRotate (posizione bit 5, valore 16, §12.5.3) restano dritte su una pagina ruotata e ruotano attorno all'angolo in alto a sinistra della propria /Rect; per quelle il metodo conserva larghezza, altezza e appearance dritta, e sposta soltanto quell'angolo dove la rotazione lo mette

Oltre i dizionari delle annotazioni, la stessa chiamata ruota /QuadPoints, /Vertices, /L e /InkList. Riscrive le destinazioni esplicite che nominano la pagina: i punti /XYZ e i rettangoli /FitR sono mappati attraverso la rotazione, e a 90 o 270 gradi /FitH e /FitBH diventano /FitV e /FitBV, e viceversa (§12.3.2.2). Trasforma inoltre la geometria taggata come le voci /BBox degli attributi sugli elementi di struttura il cui /Pg è la pagina

L'albero di struttura è dove un percorso lineare va storto in modo sgradevole. La /Pg di un elemento di struttura punta indietro all'oggetto pagina, quindi uno scanner che porta «questo appartiene alla pagina» lungo ogni chiave segue /Pg dentro la pagina, poi dentro /Annots — ruotando i rettangoli delle annotazioni una seconda volta — e dentro Form XObjects la cui /BBox vive nello spazio della form ed è già coperta dal cm esterno. Seguire /P sale fino alla radice dell'albero e tira dentro elementi di altre pagine. Se qualcuna di queste cose scatta dipende dall'ordine in cui gli oggetti capitano di essere visitati; quando /Pages precede /StructTreeRoot nel catalogo, la pagina tende a essere raggiunta per prima e il danno resta nascosto, così file di test ordinari possono passare. FlattenLoadedPageRotation porta contesto di pagina solo attraverso /K (figli) e /A (attributi), e un figlio con una /Pg propria su un'altra pagina viene lasciato a quella pagina

Perché le annotazioni si rompono quando una pagina HotPDF viene appiattita ruotando solo /Rect: uno stamp di 200 per 40 viene scalato in uno slot di 40 per 200 e diventa illeggibile, quindi FlattenLoadedPageRotation moltiplica a destra la rotazione oraria su ogni /Matrix di appearance attraverso /N, /R e /D, aggiusta l'antiorario /MK /R e fa ruotare le annotazioni NoRotate attorno al proprio angolo in alto a sinistra
Il viewer adatta la BBox trasformata dell'appearance dentro /Rect, quindi lo stream stesso deve ruotare — un passaggio per appearance condivisa, esattamente una volta per chiamata

Controllare il risultato prima di spedire il batch

Una pagina appiattita dovrebbe apparire identica in un viewer, e i controlli utili sono quelli che si accorgerebbero se non fosse così. Poche comportamenti plasmano come verificarla

  • Le pagine la cui rotazione effettiva è già 0, o il cui MediaBox manca o ha larghezza o altezza nulla, vengono saltate senza eccezione, quindi confrontate il valore di ritorno con il conteggio che vi aspettavate cambiare
  • I Form XObjects referenziati dalle risorse della pagina conservano la propria /BBox e /Matrix, perché il cm esterno ruota già tutto ciò che disegnano
  • Le destinazioni vengono trovate percorrendo ogni oggetto indiretto una volta per pagina appiattita; su un file grande con centinaia di pagine ruotate, mettete in budget quel percorso per ognuna
  • RenderLoadedPageToBitmap disegna gli stream di contenuto della pagina e lascia fuori le annotazioni, quindi un controllo visivo degli stamp ruotati richiede prima FlattenLoadedAnnotations, su una copia di lavoro del documento

La pagina di test che si ripaga da sola ha qualcosa di asimmetrico in un angolo, per esempio un quadrato pieno in alto a sinistra della pagina mostrata. Renderizzatela prima e dopo l'appiattimento, poi confrontate i pixel attorno a quel marcatore. Larghezza e altezza da sole concordano altrettanto volentieri su una pagina specchiata

// Solo copia di lavoro: FlattenLoadedAnnotations cuoce le annotazioni
// nel contenuto della pagina e le rimuove dalla pagina
Pdf.FlattenLoadedAnnotations('1');              // intervallo di pagine a base uno
Before := Pdf.RenderLoadedPageToBitmap(0, 96);  // indice di pagina a base zero
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
    // Controlli vostri, non chiamate di libreria: le dimensioni devono combaciare...
    Assert((Before.Width = After.Width) and (Before.Height = After.Height));
    // ...e così anche i pixel del marcatore nell'angolo in alto a sinistra
    Assert(Before.Canvas.Pixels[8, 8] = After.Canvas.Pixels[8, 8]);
  finally
    After.Free;
  end;
finally
  Before.Free;
end;

Se gli stamp sulle vostre pagine ruotate non hanno ancora stream di appearance, sintetizzare le appearance delle annotazioni prima di appiattirle copre quel passaggio. Il renderer dietro il confronto d'angolo è descritto in renderizzare una pagina PDF caricata in una bitmap, e redaction e stitching N-up su PDF caricati si affida alla stessa idea di aggiungere stream a /Contents senza ricodificare quelli originali. FlattenLoadedPageRotation, GetLoadedPageBox e GetLoadedPageVisibleBox viaggiano con HotPDF per Delphi e C++Builder — la pagina del componente HotPDF Delphi PDF ha i dettagli