Een paginanummer getekend op x = 560, y = 30 in PDF user space (oorsprong linksonder) hoort in de rechteronderhoek van een Letter-pagina. Op een gescande liggende pagina die als staand medium is bewaard, met /MediaBox [0 0 612 792] en /Rotate 90, zet dezelfde tekenaanroep het getal 30 points van de linkerrand en 52 points boven de onderkant van wat de lezer ziet, met de cijfers rechtdoor de marge in lopend. De stempelcode deed precies wat hem was opgedragen. Hij schreef in een coördinatenstelsel dat elke viewer een kwartslag tegen de klok in draait voordat iemand ernaar kijkt
Scanners en phone-capture-apps produceren voortdurend zulke pagina's, want een rotatievlag zetten is veel goedkoper dan een JPEG opnieuw encoderen. Viewers volgen /Rotate, dus het bestand ziet er prima uit totdat iets in rauwe user space werkt: een stempelroutine, een opmaakstap die zijn slots alleen op /MediaBox baseert, een print-RIP met eigen opvattingen over oriëntatie. De duurzame oplossing is de rotatie afvlakken: de draai in de content stream terugstoppen en /Rotate op 0 zetten, zodat de bewaarde geometrie en de getoonde geometrie het eindelijk met elkaar eens zijn. Dat klinkt als één matrix. In de praktijk raakt het vijf paginaboxen, drie soorten annotatiegeometrie, elke link die de pagina benoemt en de structuurboom, en ISO 32000-1 heeft voor elk ervan een aparte regel
Welke kant draait /Rotate een PDF-pagina op?
/Rotate draait de pagina voor weergave en afdruk met de klok mee, in veelvouden van 90 graden (ISO 32000-1 §7.7.3.3, Tabel 30). Op 90 graden wordt de linkerrand van het medium de bovenkant en de bovenrand wordt de rechterkant, dus in een y-naar-beneden apparaatruimte luidt de afbeelding X = (y - Bottom) * Scale en Y = (x - Left) * Scale. Op 270 graden wordt de rechterrand de bovenkant. De sleutel is ook erfelijk: samen met /Resources, /MediaBox en /CropBox is het één van de vier pagina-attributen die een /Pages-voorouder kan aanleveren (§7.7.3.4), dus ook een pagedictionary zonder eigen /Rotate kan gedraaid zijn. THotPDF.GetLoadedPageRotation loopt de /Parent-keten af, neemt de eerste /Rotate die hij tegenkomt en normaliseert die naar 0-359, dus een bewaarde -90 komt terug als 270
De richting is het deel dat verkeerd gaat zonder dat iemand het ziet. Een pagina-naar-apparaatmatrix met de y-componenten gewisseld voor 90 en 270 graden draait de pagina helemaal niet — hij spiegelt hem over de diagonaal, en de determinant wisselt van teken. Beide hoeken zien er nog steeds gedraaid uit. De bitmap heeft de gewisselde breedte en hoogte, en een punt heen en weer in de view mappen brengt je terug waar je begon, dus formaatcontroles en roundtriptests slagen zonder mopperen. Wat de fout vangt, is een pagina met een asymmetrisch merkteken in één hoek, gerenderd en pixel voor pixel vergeleken met een onafhankelijke renderer; een geometrie-implementatie alleen tegen zichzelf controleren bewijst hier weinig. In HotPDF delen FlattenLoadedPageRotation en RenderLoadedPageToBitmap één conventie met de klok mee, dus een hoek die de renderer linksboven op een gedraaide pagina tekent, zit na het afvlakken nog steeds linksboven
Een paginabereik afvlakken met FlattenLoadedPageRotation
THotPDF.FlattenLoadedPageRotation(PageRange, Info) behandelt elke pagina in PageRange waarvan de effectieve rotatie 90, 180 of 270 is en geeft terug hoeveel pagina's hij afvlakte. Een lege PageRange betekent het hele document; anders gebruikt de string de ééngebaseerde '1-3,7'-syntaxis, en een paginanummer voorbij het eind gooit een exception in plaats van stilletjes buiten het bereik te vallen. De originele content streams blijven byte voor byte zoals ze waren. De methode zet een nieuwe stream met q en een cm-draai vooraan in /Contents, zet een stream met Q achteraan, en schrijft daarna /Rotate 0 in de pagedictionary zelf
| Effectieve /Rotate | Prefix-stream | Nieuwe MediaBox |
|---|---|---|
| 90 | q 0 -1 1 0 -Bottom Width+Left cm | [0 0 Height Width] |
| 180 | q -1 0 0 -1 Width+Left Height+Bottom cm | [0 0 Width Height] |
| 270 | q 0 1 -1 0 Height+Bottom -Left cm | [0 0 Height Width] |
Het expliciete nulpunt telt zwaarder dan het lijkt. De /Rotate-sleutel verwijderen lijkt netter, en het breekt elke pagina waarvan de 90 uit een /Pages-knoop komt: de pagina erft de draai opnieuw en de viewer draait inhoud die al recht staat. Een /Rotate 0 op de pagedictionary blokkeert die overerving, en daarom is het de enige veilige waarde om weg te schrijven
var
Pdf: THotPDF;
Info: THPDFRotationFlattenInfo;
Flattened: Integer;
begin
Pdf := THotPDF.Create(nil);
try
if Pdf.LoadFromFile('scanned-batch.pdf') > 0 then
begin
// '' = elke pagina; pagina's die al op 0 graden staan worden geteld maar niet aangepast
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;
Log het record THPDFRotationFlattenInfo in plaats van het weg te gooien. ScannedPageCount is het aantal pagina's in het bereik, FlattenedPageCount hoort bij de retourwaarde, en de drie Transformed...-tellers laten zien of links, bookmarks of getagde geometrie naar de gedraaide pagina's wezen. Nul destinations in een scannerbatch is normaal, want scanners schrijven zelden links. Een getagd PDF/UA-bestand dat nul structure-geometrie meldt terwijl je weet dat het figuren met bounding boxes bevat, is het ene bestand dat je met de hand opent
Lees elke paginabox voordat je er een schrijft
Afvlakken herschrijft alleen de boxen die de pagina al heeft, en hij leest ze allemaal voordat hij de eerste schrijft. De volgorde telt vanwege de defaultketen in §14.11.2: GetLoadedPageBox(PageIndex, pbCropBox, ...) geeft de MediaBox terug als de pagina geen /CropBox heeft, en /BleedBox, /TrimBox en /ArtBox vallen terug op de CropBox. Een lus die box voor box leest, draait en schrijft, loopt recht die keten in. Hij draait de MediaBox en bewaart hem, leest de 'CropBox', krijgt de net gedraaide MediaBox terug, draait hem een tweede keer en schrijft een CropBox die de pagina nooit had. Op een Letter-pagina levert die tweede draai [0 -180 612 612] op, en geknipt op de nieuwe MediaBox krimpt de zichtbare pagina tot een vierkant van 612 × 612
Overerving verdeelt de vijf boxen in twee groepen. MediaBox en CropBox worden langs de /Parent-keten opgezocht, terwijl BleedBox, TrimBox en ArtBox alleen meetellen als ze op de pagedictionary zelf staan. FlattenLoadedPageRotation volgt dezelfde scheiding bij het bepalen welke boxen bestaan: een geërfde CropBox wordt gedraaid en op de pagina geschreven, en een verdwaalde /TrimBox op een /Pages-knoop geldt als afwezig en wordt nooit naar beneden gekopieerd
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 ook zonder een /TrimBox-key: de waarde valt terug op CropBox, daarna 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 laat de uitvoerwaarden onaanroerd bij mislukking
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;
Draai die helper voor en na het afvlakken. Voor een pagina van 90 graden met MediaBox [0 0 612 792] luidt de afgevlakte MediaBox [0 0 792 612]. Elke herschreven box doorloopt dezelfde draai met de klok mee rond de oorsprong van de originele MediaBox, dus de nieuwe MediaBox begint altijd op 0,0, en een TrimBox van [18 18 594 774] wordt [18 18 774 594] — nog steeds 18 points vanaf elke rand van de liggende pagina
GetLoadedPageVisibleBox geeft het gebied terug dat een viewer toont en een printer print: de CropBox geknipt op de MediaBox, genormaliseerd zodat Left kleiner is dan Right en Bottom kleiner dan Top. De paginarenderder en de SVG-export nemen hun uitvoerformaat uit diezelfde box. Code die het formaat wil dat een mens echt ziet, hoort GetLoadedPageVisibleBox aan te roepen, want /MediaBox daarvoor lezen geeft op elke pagina met een CropBox het verkeerde antwoord
Waarom breken annotaties als u alleen /Rect draait?
Annotaties breken omdat een appearance stream nooit rechtstreeks in /Rect wordt getekend. Onder §12.5.5 transformeert de viewer eerst de /BBox van het formulier met zijn /Matrix, schaalt en verschuift daarna de bounding box van het resultaat naar /Rect. Draai alleen /Rect en een stempel van 200 × 40 wordt geperst in een gleuf van 40 × 200, waar niemand hem kan lezen. FlattenLoadedPageRotation vermenigvuldigt daarom rechts de draai met de klok mee van de pagina door elke appearance-/Matrix ([0 -1 1 0 0 0] op 90 graden, in de rijvectorconventie), over de appearances /N, /R en /D en elke toestand daarin. Eén appearance stream kan meerdere annotaties of toestanden dienen, dus elke stream wordt per aanroep exact één keer gedraaid; een stream gedeeld door pagina's met verschillende rotaties krijgt de draai van de eerste pagina die hem bereikt
Twee kleinere regels houden formuliervelden en notitieblokjes op hun plek. De /MK /R-entry van een widget (§12.5.6.19) is een hoek tegen de klok in, dus de hoek met de klok mee van de pagina wordt eraan onttrokken, modulo 360. Hem met rust laten betekent dat de eerstvolgende appearance-regeneratie de veldtekst verkeerd om tekent. Annotaties met de NoRotate-vlag (bitpositie 5, waarde 16, §12.5.3) blijven op een gedraaide pagina rechtop en draaien rond de linkerbovenhoek van hun /Rect; voor die gevallen houdt de methode breedte, hoogte en de rechtopstaande appearance vast en verplaatst alleen die hoek naar waar de draai hem brengt
Voorbij de annotatiedictionaries draait dezelfde aanroep /QuadPoints, /Vertices, /L en /InkList. Hij herschrijft expliciete destinations die de pagina noemen: /XYZ-punten en /FitR-rechthoeken worden door de draai gemapt, en op 90 of 270 graden worden /FitH en /FitBH /FitV en /FitBV, en andersom (§12.3.2.2). Ook transformeert hij getagde geometrie zoals attribuut-/BBox-entries op structuurelementen waarvan de /Pg de pagina is
De structuurboom is waar een naïeve wandeling op een onaangename manier misgaat. De /Pg van een structuurelement wijst terug naar het paginaobject, dus een scanner die 'dit hoort bij de pagina' bij elke sleutel naar beneden neemt, volgt /Pg de pagina in, dan /Annots in — waarbij annotatierechthoeken een tweede keer draaien — en Form XObjects in waarvan de /BBox in formulierleefruimte zit en al door de buitenste cm wordt gedekt. /P volgen klimt naar de boomwortel en haalt elementen van andere pagina's binnen. Of dit alles afgaat, hangt af van de volgorde waarin objecten toevallig worden bezocht; staat /Pages vóór /StructTreeRoot in de catalogus, dan wordt de pagina meestal het eerst bereikt en blijft de schade verborgen, dus gewone testbestanden kunnen slagen. FlattenLoadedPageRotation neemt paginacontext alleen mee via /K (kinderen) en /A (attributen), en een kind met een eigen /Pg op een andere pagina laat hij aan die pagina over
Het resultaat controleren voordat de batch de deur uit gaat
Een afgevlakte pagina hoort er in een viewer identiek uit te zien, en de nuttige controles zijn degene die het opmerken als dat niet zo is. Een paar gedragingen bepalen hoe je dat verifieert
- Pagina's waarvan de effectieve rotatie al 0 is, of waarvan de MediaBox ontbreekt of nul breed of hoog is, worden zonder exception overgeslagen, dus vergelijk de retourwaarde met het aantal dat je verwachtte te veranderen
- Form XObjects waarnaar de paginaresources verwijzen houden hun eigen
/BBoxen/Matrix, want de buitenstecmdraait al alles wat zij tekenen - Destinations worden gevonden door elke indirecte object één keer per afgevlakte pagina af te lopen; op een groot bestand met honderden gedraaide pagina's kun je die wandeling per pagina beter inplannen
RenderLoadedPageToBitmaptekent de content streams van de pagina en laat annotaties weg, dus een visuele controle van gedraaide stempels vraagt eerstFlattenLoadedAnnotations, op een werkkopie van het document
Het testbestand dat zichzelf terugverdient heeft iets asymmetrisch in één hoek, bijvoorbeeld een gevuld vierkant linksboven op de getoonde pagina. Render het voor en na het afvlakken en vergelijk daarna de pixels rond dat merkteken. Alleen breedte en hoogte zijn net zo blij eens te zijn op een gespiegelde pagina
// Alleen op een werkkopie: FlattenLoadedAnnotations bakt de annotaties
// in de pagina-inhoud en haalt ze van de pagina
Pdf.FlattenLoadedAnnotations('1'); // ééngebaseerd paginabereik
Before := Pdf.RenderLoadedPageToBitmap(0, 96); // nulgebaseerde pagina-index
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
// Eigen controles, geen bibliotheekaanroepen: de formaten moeten kloppen...
Assert((Before.Width = After.Width) and (Before.Height = After.Height));
// ...en de merktekenpixels in de linkerbovenhoek ook
Assert(Before.Canvas.Pixels[8, 8] = After.Canvas.Pixels[8, 8]);
finally
After.Free;
end;
finally
Before.Free;
end;
Hebben de stempels op je gedraaide pagina's nog geen appearance streams, dan behandelt annotatie-appearances synthetiseren vóór het afvlakken die stap. De renderer achter de hoekvergelijking staat beschreven in een geladen PDF-pagina naar een bitmap renderen, en redaction en N-up stitching op geladen PDF's leunt op hetzelfde idee van streams aan /Contents toevoegen zonder de originele te herencoderen. FlattenLoadedPageRotation, GetLoadedPageBox en GetLoadedPageVisibleBox worden geleverd met HotPDF voor Delphi en C++Builder — de HotPDF Delphi PDF-componentpagina heeft de details