Artykuł techniczny

Spłaszczanie obrotu strony PDF bez psucia ramek w Delphi

Numer strony narysowany na x = 560, y = 30 w przestrzeni użytkownika PDF (początek w lewym dolnym rogu) należy do prawego dolnego rogu strony Letter. Na zeskanowanej poziomej stronie zapisanej jako pionowy nośnik, z /MediaBox [0 0 612 792] i /Rotate 90, to samo wywołanie rysujące kładzie numer 30 punktów od lewej krawędzi i 52 punkty nad spodem tego, co widzi czytelnik, z cyframi biegnącymi prosto w dół marginesu. Kod stemplujący zrobił dokładnie to, co mu kazano. Zapisał do układu współrzędnych, który każda przeglądarka obraca o ćwiartkę zgodnie z zegarem, zanim ktokolwiek na niego spojrzy

Skanery i aplikacje przechwytujące z telefonów produkują takie strony bez przerwy, bo ustawienie flagi obrotu jest dużo tańsze niż rekodowanie JPEG-a. Przeglądarki honorują /Rotate, więc plik wygląda dobrze aż do momentu, gdy coś zaczyna pracować w surowej przestrzeni użytkownika: rutyna stemplująca, krok impozycji wymiarujący sloty z samego /MediaBox, RIP druku z własnym zdaniem o orientacji. Trwała naprawa to spłaszczenie obrotu — przeniesienie obrotu do strumienia treści i ustawienie /Rotate na 0, żeby zapisana geometria i wyświetlana geometria wreszcie się zgodziły. Brzmi jak jedna macierz. W praktyce sięga pięciu ramek strony, trzech rodzajów geometrii adnotacji, każdego łącza celującego w stronę i drzewa struktury, a ISO 32000-1 ma osobną regułę dla każdego z nich

W którą stronę /Rotate obraca stronę PDF?

/Rotate obraca stronę zgodnie z ruchem wskazówek zegara przy wyświetlaniu i drukowaniu, w wielokrotnościach 90 stopni (ISO 32000-1 §7.7.3.3, tabela 30). Przy 90 stopniach lewa krawędź nośnika staje się górą, a górna krawędź prawą stroną, więc w y-down przestrzeni urządzenia mapowanie to X = (y - Bottom) * Scale i Y = (x - Left) * Scale. Przy 270 stopniach prawa krawędź staje się górą. Klucz jest też dziedziczalny: razem z /Resources, /MediaBox i /CropBox należy do czterech atrybutów strony, które przodek /Pages może podać (§7.7.3.4), więc słownik strony bez własnego /Rotate nadal może być obrócony. THotPDF.GetLoadedPageRotation przechodzi łańcuch /Parent, bierze pierwsze /Rotate, jakie spotka, i normalizuje je do 0–359, więc zapisane -90 wraca jako 270

Kierunek to ta część, która psuje się bez zauważenia przez kogokolwiek. Macierz strona-urządzenie z zamienionymi komponentami y dla 90 i 270 stopni nie obraca strony wcale — odbija ją po przekątnej, a wyznacznik zmienia znak. Oba kąty nadal wyglądają obrócone. Bitmapa ma zamienione szerokość i wysokość, a zmapowanie punktu do widoku i z powrotem wraca do punktu startowego, więc kontrole wymiarów i testy rundy przechodzą bez szemrania. Co łapie ten błąd, to strona z asymetrycznym znacznikiem w jednym rogu, wyrenderowana i porównana piksel po pikselu z niezależnym rendererem; sprawdzanie implementacji geometrii tylko samą sobą dowodzi tu bardzo mało. W HotPDF FlattenLoadedPageRotation i RenderLoadedPageToBitmap dzielą jedną konwencję zgodną z zegarem, więc róg, który renderer rysuje w lewym górnym rogu obróconej strony, pozostaje w lewym górnym rogu po spłaszczeniu

Jak HotPDF spłaszcza obrót strony w Delphi: pionowa strona zapisana z /Rotate 90 wyświetla się zgodnie z zegarem jako poziomy widok 792 na 612, mapowanie urządzenia X = (y - Bottom) * Scale, Y = (x - Left) * Scale przestawia każdy róg, a zamiana komponentów y macierzy daje odbicie, które wyłapie tylko porównanie znaczników rogów
Przeglądarki obracają stronę zgodnie z zegarem przy wyświetlaniu, podczas gdy bajty zostają pionowe — GetLoadedPageRotation najpierw przechodzi łańcuch /Parent, bo /Rotate to jeden z czterech dziedziczalnych atrybutów strony

Spłaszczanie zakresu stron przez FlattenLoadedPageRotation

THotPDF.FlattenLoadedPageRotation(PageRange, Info) przetwarza każdą stronę w PageRange, której efektywny obrót wynosi 90, 180 albo 270, i zwraca liczbę spłaszczonych stron. Pusty PageRange znaczy cały dokument; w przeciwnym razie łańcuch używa jedno-bazowej składni '1-3,7', a numer strony za końcem podnosi wyjątek, zamiast po cichu wypaść z zakresu. Oryginalne strumienie treści zostają bajt w bajt takie, jakie były. Metoda dokleja z przodu /Contents nowy strumień z q i obrotem cm, dokleja z tyłu strumień z Q, a potem zapisuje /Rotate 0 do samego słownika strony

Efektywny /RotateStrumień prefiksuNowy 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]

Jawne zero znaczy więcej, niż wygląda. Usunięcie klucza /Rotate zdawałoby się schludniejsze i psuje każdą stronę, której 90 przyszło z węzła /Pages: strona odziedzicza obrót ponownie, a przeglądarka obraca treść, która jest już pionowa. /Rotate 0 na słowniku strony blokuje to dziedziczenie, co czyni go jedyną bezpieczną wartością do zapisania

var
  Pdf: THotPDF;
  Info: THPDFRotationFlattenInfo;
  Flattened: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    if Pdf.LoadFromFile('scanned-batch.pdf') > 0 then
    begin
      // '' = wszystkie strony; strony już przy 0 stopni są liczone, ale nietknięte
      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;

Rekord THPDFRotationFlattenInfo loguj, zamiast go wyrzucać. ScannedPageCount to liczba stron w zakresie, FlattenedPageCount zgadza się z wartością zwracaną, a trzy liczniki Transformed... pokazują, czy łącza, zakładki albo otagowana geometria celowały w obrócone strony. Zero celów w całej partii ze skanera to norma, bo skanery rzadko w ogóle zapisują łącza. Otagowany plik PDF/UA, który raportuje zero geometrii struktury, choć wiesz, że wozi ramki figur, to ten, który otwierasz ręcznie

Przeczytaj każdą ramkę strony, zanim napiszesz jakąkolwiek

Spłaszczanie przepisuje tylko ramki, które strona już ma, i czyta wszystkie, zanim napisze pierwszą. Kolejność ma znaczenie przez łańcuch domyśleń z §14.11.2: GetLoadedPageBox(PageIndex, pbCropBox, ...) zwraca MediaBox, gdy strona nie ma /CropBox, a /BleedBox, /TrimBox i /ArtBox spadają do CropBoxa. Pętla czytająca, obracająca i pisząca po jednej ramce naraz wchodzi w ten łańcuch na prostej. Obraca MediaBox i zapisuje go, czyta „CropBox", dostaje z powrotem świeżo obrócony MediaBox, obraca go drugi raz i zapisuje CropBoxa, którego strona nigdy nie miała. Na stronie Letter ten drugi obrót daje [0 -180 612 612], a przycięty do nowego MediaBoxa widoczna strona kurczy się do kwadratu 612 × 612

Dziedziczenie dzieli pięć ramek na dwie grupy. MediaBox i CropBox są wyszukiwane wzdłuż łańcucha /Parent, podczas gdy BleedBox, TrimBox i ArtBox liczą się tylko, gdy siedzą na samym słowniku strony. FlattenLoadedPageRotation podąża za tym samym podziałem, gdy rozstrzyga, które ramki istnieją: odziedziczony CropBox jest obracany i zapisywany na stronę, a zabłąkany /TrimBox na węźle /Pages jest traktowany jako nieobecny i nigdy nie jest kopiowany w dół

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 nawet bez klucza /TrimBox: wartość spada do CropBoxa, potem MediaBoxa
  if Pdf.GetLoadedPageBox(PageIndex, pbTrimBox, L, B, R, T) then
    Writeln(Format('TrimBox  [%g %g %g %g]', [L, B, R, T]));
  // Ustawiony wstępnie Letter; GetLoadedPageVisibleBox zostawia wyjścia nietknięte przy porażce
  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;

Uruchom ten helper przed spłaszczeniem i po nim. Dla strony 90-stopniowej z MediaBox [0 0 612 792] spłaszczony MediaBox czyta się [0 0 792 612]. Każda przepisywana ramka przechodzi ten sam obrót zgodny z zegarem względem początku oryginalnego MediaBoxa, więc nowy MediaBox zawsze zaczyna się w 0,0, a TrimBox [18 18 594 774] staje się [18 18 774 594] — nadal 18 punktów od każdej krawędzi poziomej strony

GetLoadedPageVisibleBox zwraca region, który przeglądarka pokazuje, a drukarka drukuje: CropBox przycięty do MediaBoxa i znormalizowany tak, że Left jest mniejsze od Right, a Bottom od Top. Renderer stron i eksport SVG wymiarują wyjście z tego samego pudełka. Kod, który chce rozmiaru faktycznie widzianego przez człowieka, powinien wołać GetLoadedPageVisibleBox, bo czytanie /MediaBox w tym celu daje złą odpowiedź na każdej stronie z CropBoxem

Dlaczego HotPDF czyta każdą ramkę strony przed pisaniem czegokolwiek podczas FlattenLoadedPageRotation: BleedBox, TrimBox i ArtBox domyślają się CropBoxa, który sam spada do MediaBoxa, więc obracanie ramek po jednej sprawiło, że CropBox przeczytał już przepisany MediaBox, a drugi obrót napisał ramkę, której strona nigdy nie miała, przycinając poziomą stronę do kwadratu
Łańcuch domyśleń znaczy, że wyjście jednej ramki jest wejściem drugiej — przeczytaj najpierw wszystko, transformuj względem początku oryginalnego MediaBoxa, potem pisz

Dlaczego adnotacje się psują, gdy obrócisz tylko /Rect?

Adnotacje się psują, bo strumień wyglądu nie jest nigdy rysowany prosto do /Rect. Zgodnie z §12.5.5 przeglądarka najpierw transformuje /BBox formularza jego /Matrix, po czym skaluje i przesuwa ramkę ograniczającą wyniku do /Rect. Obróć tylko /Rect, a stempel 200 × 40 zostanie wciśnięty w slot 40 × 200, gdzie nie przeczyta go nikt. FlattenLoadedPageRotation mnoży dlatego z prawej obrót strony zgodny z zegarem na każdą /Matrix wyglądu ([0 -1 1 0 0 0] przy 90 stopniach, w konwencji wektorów-wierszy) w obrębie wyglądów /N, /R i /D oraz każdego stanu w ich środku. Jeden strumień wyglądu może obsługiwać kilka adnotacji albo stanów, więc każdy strumień jest obracany dokładnie raz na wywołanie; strumień współdzielony przez strony o różnych obrotach bierze obrót pierwszej strony, która go dosięgnie

Dwie mniejsze reguły trzymają pola formularza i karteczki tam, gdzie ich miejsce. Wpis /MK /R widżetu (§12.5.6.19) to kąt przeciwny do wskazówek zegara, więc kąt strony zgodny z zegarem jest od niego odejmowany modulo 360. Zostaw go w spokoju, a następna regeneracja wyglądu narysuje tekst pola w złym kierunku. Adnotacje z flagą NoRotate (pozycja bitu 5, wartość 16, §12.5.3) zostają pionowe na obróconej stronie i obracają się wokół lewego górnego rogu swojego /Rect; dla nich metoda zachowuje szerokość, wysokość i pionowy wygląd, a przesuwa tylko ten róg tam, gdzie kładzie go obrót

Za słownikami adnotacji to samo wywołanie obraca /QuadPoints, /Vertices, /L i /InkList. Przepisuje jawne cele wymieniające stronę: punkty /XYZ i prostokąty /FitR są mapowane przez obrót, a przy 90 albo 270 stopniach /FitH i /FitBH stają się /FitV i /FitBV, i odwrotnie (§12.3.2.2). Transformuje też otagowaną geometrię, jak wpisy /BBox atrybutów na elementach struktury, których /Pg to ta strona

Drzewo struktury to miejsce, gdzie proste przejście psuje się w nieprzyjemny sposób. /Pg elementu struktury wskazuje z powrotem na obiekt strony, więc skaner niosący „to należy do strony" przez każdy klucz podąża za /Pg do strony, potem do /Annots — obracając prostokąty adnotacji drugi raz — i do Form XObjects, których /BBox żyje w przestrzeni formularza i jest już pokryty zewnętrznym cm. Podążanie za /P wspina się do korzenia drzewa i ciągnie elementy z innych stron. Czy ktokolwiek z tych przypadków odpali, zależy od kolejności, w jakiej obiekty akurat są odwiedzane; gdy /Pages poprzedza /StructTreeRoot w katalogu, strona bywa osiągana pierwsza i szkoda pozostaje ukryta, więc zwykłe pliki testowe mogą przechodzić. FlattenLoadedPageRotation niesie kontekst strony tylko przez /K (dzieci) i /A (atrybuty), a dziecko z własnym /Pg na innej stronie zostawiane jest tej stronie

Dlaczego adnotacje się psują, gdy strona HotPDF jest spłaszczana samym obrotem /Rect: stempel 200 na 40 jest skalowany do slotu 40 na 200 i staje się nieczytelny, więc FlattenLoadedPageRotation mnoży z prawej obrót zgodny z zegarem na każdą /Matrix wyglądu w obrębie /N, /R i /D, koryguje przeciwny do zegara /MK /R i obraca adnotacje NoRotate wokół ich lewego górnego rogu
Przeglądarka wciska przetransformowany BBox wyglądu w /Rect, więc sam strumień musi się obrócić — jeden przebieg na współdzielony wygląd, dokładnie raz na wywołanie

Sprawdzanie wyniku, zanim wyślesz partię

Spłaszczona strona powinna wyglądać identycznie w przeglądarce, a użyteczne kontrole to te, które zauważyłyby, gdyby nie wyglądała. Kilka zachowań kształtuje to, jak ją weryfikujesz

  • Strony o efektywnym obrocie już równym 0 albo z brakującym MediaBoxem albo zerową szerokością czy wysokością są pomijane bez wyjątku, więc porównaj wartość zwracaną z liczbą stron, których zmiany się spodziewałeś
  • Form XObjects wskazywane z zasobów strony zachowują własny /BBox i /Matrix, bo zewnętrzny cm obraca już wszystko, co rysują
  • Cele są znajdowane przejściem każdego obiektu pośredniego raz na spłaszczaną stronę; przy dużym pliku z setkami obróconych stron zaplanuj ten spacer dla każdej z nich
  • RenderLoadedPageToBitmap rysuje strumienie treści strony i zostawia adnotacje na uboczu, więc wzrokowa kontrola obróconych stempli wymaga najpierw FlattenLoadedAnnotations, na kopii roboczej dokumentu

Strona testowa, która opłaca się sama, ma coś asymetrycznego w jednym rogu — na przykład wypełniony kwadrat w lewym górnym rogu wyświetlanej strony. Wyrenderuj ją przed spłaszczeniem i po, po czym porównaj piksele wokół tego znacznika. Sama szerokość i wysokość zgadzają się równie chętnie na stronie odbitej

// Tylko kopia robocza: FlattenLoadedAnnotations wypala adnotacje
// w treść strony i usuwa je ze strony
Pdf.FlattenLoadedAnnotations('1');              // zakres stron liczony od jedynki
Before := Pdf.RenderLoadedPageToBitmap(0, 96);  // indeks strony liczony od zera
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
    // Twoje własne kontrole, nie wywołania biblioteki: rozmiary muszą się zgadzać...
    Assert((Before.Width = After.Width) and (Before.Height = After.Height));
    // ...i piksele znacznika w lewym górnym rogu też
    Assert(Before.Canvas.Pixels[8, 8] = After.Canvas.Pixels[8, 8]);
  finally
    After.Free;
  end;
finally
  Before.Free;
end;

Jeśli stemple na twoich obróconych stronach nie mają jeszcze strumieni wyglądu, syntezowanie wyglądów adnotacji przed ich spłaszczeniem pokrywa ten krok. Renderer stojący za porównaniem rogów jest opisany w artykule o renderowaniu wczytanej strony PDF do bitmapy, a redakcja i składanie N-up na wczytanych PDF-ach opiera się na tej samej idei doklejania strumieni do /Contents bez rekodowania oryginalnych. FlattenLoadedPageRotation, GetLoadedPageBox i GetLoadedPageVisibleBox przychodzą z HotPDF dla Delphi i C++Buildera — szczegóły są na stronie HotPDF Delphi PDF component