Artykuł techniczny

Redakcja PDF i układ N-up w Delphi z HotPDF

Na biurko trafia zadanie: weź paczkę już wyrenderowanych zestawień, zaczernij numery kont i wyślij po dwie strony na arkusz, żeby oszczędzić papier. Obie połowy tego zadania to chirurgia na strumieniach zawartości PDF, którego sam nie tworzyłeś, więc nie ma tu przyjaznego canvasu strony do rysowania ani menedżera fontów, na którym można się oprzeć. Edytujesz bezpośrednio graf obiektów załadowanego dokumentu, dopisując surowe operatory rysowania do strony rozłożonej przez inne narzędzie. HotPDF wystawia do tego dokładnie dwa punkty wejścia, a bardziej niebezpieczny z nich jest ten, który wygląda niewinnie

HotPDF to natywny komponent VCL do pracy z PDF dla Delphi i C++Builder, a jego API dla wczytanych dokumentów obejmuje metody, które tworzą zupełnie nową zawartość na stronie otwartej z dysku, zamiast na takiej zbudowanej od zera. Dwie z nich są tu tematem: RedactLoadedRect, malująca nieprzezroczysty prostokąt na wybranym obszarze, oraz StitchLoadedPage, skalująca jedną stronę i rysująca ją na drugiej. Obie działają, zapisując operatory strumienia zawartości z ISO 32000-1 §8.5 do strumienia /Contents strony. Zrozumienie, co te operatory robią, a równie ważne — czego nie robią, to różnica między działającym narzędziem a wyciekiem danych

Dopisywanie operatorów do wczytanej strony

Gdy budujesz stronę zwykłym API HotPDF, komponent sam jest właścicielem strumienia zawartości i serializuje za ciebie wywołania TextOut oraz wektorowe. Załadowana strona jest inna: jej /Contents to istniejący obiekt strumienia, być może współdzielony, być może będący częścią tablicy zawartości, i musisz się w niego wpiąć tak, by nie uszkodzić tego, co już tam jest. Trzy małe helpery robią to bezpiecznym. NewIndirectStream alokuje świeży pośredni THPDFStreamObject z pustym buforem i wpisem /Length 0; ResolveLoadedStream schodzi po referencji pośredniej aż do bazowego strumienia; a AppendLoadedStream dopisuje surowe bajty na końcu strumienia i przepisuje /Length, tak aby zapisany obiekt pozostał poprawnie uformowany

Schemat obu publicznych metod jest taki sam. Znajdź /Contents strony, rozwiąż je do strumienia, a jeśli nie ma użytecznego strumienia, utwórz go i podepnij. Następnie dopisz operatory. Ponieważ nowe bajty trafiają na koniec strumienia, model malarski gwarantuje, że zostaną wyrenderowane ponad wszystkim, co narysował pierwotny układ. Ta kolejność jest całym mechanizmem stojącym za prostokątem maskującym, i z tego samego powodu taki prostokąt nie jest tym, co większość ludzi zakłada

HotPDF: Dopisywanie operatorów do wczytanej strony przechodzi przez trzech pomocników, od zlokalizowania strumienia Contents strony przez rozwiązanie lub utworzenie go do dopisania surowych bajtów na końcu, a model malarza gwarantuje, że te bajty malują ponad wszystko, co narysował oryginalny układ
NewIndirectStream, ResolveLoadedStream i AppendLoadedStream wplatają świeże operatory na koniec istniejącego strumienia /Contents, więc cokolwiek narysują ląduje ponad oryginalnym układem strony bez przepisywania choćby bajtu

RedactLoadedRect: nieusuwająca osłona, nie kasowanie

RedactLoadedRect przyjmuje zerowy indeks strony, cztery współrzędne w przestrzeni użytkownika i trzy składowe koloru w zakresie 0-1:

var
  Pdf: THotPDF;
begin
  Pdf := THotPDF.Create(nil);
  try
    if Pdf.LoadFromFile('statement.pdf') > 0 then
    begin
      // Przykryj pasek numeru konta na stronie 1 jednolitym czarnym.
      // Współrzędne to przestrzeń użytkownika PDF: początek na dole z lewej, punkty.
      Pdf.RedactLoadedRect(0, 56, 690, 320, 706, 0, 0, 0);
      Pdf.SaveLoadedDocument('statement-covered.pdf');
    end;
  finally
    Pdf.Free;
  end;
end;

Pod spodem metoda emituje do strumienia zawartości trzy operatory: ustawienie koloru wypełnienia w DeviceRGB (r g b rg), ścieżkę prostokąta (x y w h re) oraz wypełnienie (f). Szerokość i wysokość są wyliczane jako X2 - X1 oraz Y2 - Y1, więc przekazujesz dwa przeciwległe narożniki, a metoda sama oblicza rozmiar. Podaj 0, 0, 0 jako kolor, a dostaniesz czarny pasek. Podaj 1, 1, 1 dla białego, dopasowanego do białej strony. Współrzędne należą do własnej przestrzeni użytkownika załadowanej strony, co oznacza lewy dolny róg jako początek i punkty jako jednostki. Oznacza to też, że do precyzyjnego umieszczenia czegokolwiek potrzebujesz /MediaBox strony; GetLoadedPageBox razem z pbMediaBox daje ci te informacje

Przeczytaj to dwa razy: wypełniony prostokąt zakrywa zawartość wizualnie, ale jej nie usuwa. Tekst, obraz albo grafika wektorowa pod prostokątem nadal istnieją w PDF, nadal są w grafie obiektów, nadal można je wydobyć przez skopiowanie strony, uruchomienie ekstraktora tekstu albo zwykłe usunięcie twojego prostokąta ze strumienia zawartości. To maskowanie wizualne, a nie redakcja w sensie prawnym czy bezpieczeństwa. Jeżeli ukrywasz naprawdę wrażliwe dane, takie jak numery kont, dane medyczne, tożsamości czy cokolwiek regulowanego, zakrycie ich czarnym prostokątem i wysłanie pliku jest wyciekiem danych czekającym na odkrycie. Prawdziwa redakcja wymaga usunięcia bazowych obiektów zawartości, a nie malowania po nich

HotPDF: Zakryty numer konta przeżywa redakcję przez malowanie: przeglądarka pokazuje pełny ciemny pas nad linią konta, podczas gdy strumień treści nadal wymienia ciąg ACCT, a każdy ekstraktor tekstu wypisuje go z powrotem niezmieniony
Operatory r g b rg, re i f dodają piksele tylko na wierzch — oryginalny obiekt tekstu pozostaje żywy w grafie obiektów, więc przebieg kopiowania i ekstrakcji odzyskuje każdy znak ukryty przez czarny pasek

Nazwa metody mówi „Redact”, i to użyteczne ostrzeżenie przed tym, jak wynik zostanie błędnie odczytany, a nie obietnica co do tego, co zostanie usunięte. RedactLoadedRect jest z założenia wizualnym prymitywem redakcyjnym; redakcja usuwająca zawartość to inna operacja, ta, która przechodzi po istniejących operatorach strumienia zawartości i przepisuje je. Bezpieczna zasada jest więc wąska: używaj RedactLoadedRect do niewrażliwego maskowania kosmetycznego — ukrycia znaku wodnego wersji roboczej, wyczyszczenia fragmentu przed zrzutem ekranu, zasłonięcia przestarzałego logo na wewnętrznym wydaniu próbnym. W chwili, gdy to, co jest pod prostokątem, miałoby znaczenie w razie wycieku, ta metoda to złe narzędzie, a właściwym rozwiązaniem jest ponowne wygenerowanie dokumentu bez tych danych albo użycie prawdziwego potoku usuwania zawartości

StitchLoadedPage: skaluj, przesuń, narysuj

Impozycja N-up jest przyjaźniejszym problemem, bo nic nie jest ukrywane, tylko przestawiane. StitchLoadedPage przyjmuje indeks strony docelowej, indeks strony źródłowej, przesunięcie X/Y i współczynnik skali, po czym rysuje stronę źródłową na docelowej w podanej pozycji i rozmiarze:

// Nałóż stronę 2 (indeks 1) na stronę 1 (indeks 0),
// skalowaną do 70% i przesuniętą w górę-prawo.
Pdf.StitchLoadedPage(0, 1, 40, 380, 0.7);

// Wygodne 2-up: strona źródłowa na prawej połowie celu.
Pdf.StitchLoadedPageSideBySide(0, 1);

Dopisany ciąg operatorów to standardowa sekwencja transformacji i rysowania: q do zapisania stanu grafiki, macierz cm niosąca skalę na przekątnej i przesunięcie w polach translacji, /StitchSrc Do do wywołania obiektu zewnętrznego oraz Q do przywrócenia stanu. Para q/Q ma znaczenie: izoluje transformację, tak aby wklejona strona nie przeciekła swoim układem współrzędnych do czegokolwiek dopisanego później. Metoda pilnuje też oczywistych błędów, takich jak indeksy poza zakresem, strona docelowa równa źródłowej czy niedodatnia skala, którą zaciska do 1.0, i wychodzi po cichu zamiast zgłaszać wyjątek, więc sprawdzaj wejście, bo cichy no-op wygląda dokładnie jak sukces

StitchLoadedPageSideBySide jest cienką wygodną nakładką na metodę ogólną. Odczytuje szerokość media box strony docelowej, dzieli ją na pół i wywołuje StitchLoadedPage z tą połową szerokości jako przesunięciem X i ze stałą skalą 0.5, umieszczając źródło na prawej połowie. To zakodowane na sztywno 0.5 zakłada, że źródło i cel mają tę samą szerokość. Jeśli tak nie jest, źródło nie wypełni czysto swojej połowy i będziesz chciał użyć ogólnej StitchLoadedPage ze skalą obliczoną samodzielnie z obu media boxów

Jak stitch odwołuje się do strony źródłowej

To szczegół, który warto znać, zanim zaufasz wynikowi w różnych przeglądarkach. Klasyczna impozycja N-up owija zawartość strony źródłowej w Form XObject — samowystarczalny obiekt rysowalny, który według ISO 32000-1 §8.10.1 musi nieść /Type /XObject, /Subtype /Form oraz własny obszar przycinania /BBox. StitchLoadedPage idzie prostszą drogą: rejestruje bezpośrednio sam słownik strony źródłowej pod /Resources /XObject celu pod nazwą StitchSrc, po czym rysuje go przez Do. Słownik strony i Form XObject mają na tyle wspólny model zawartości — oba wskazują strumień zawartości i słownik zasobów — że wiele czytników wyrenderuje taki wynik

Ponieważ zarejestrowany obiekt nie niesie znacznika /Subtype /Form ani własnego /BBox, rygorystyczny odbiorca ma pełne prawo zignorować Do albo przyciąć go inaczej, niż oczekujesz. Sprawdzaj więc zszyty wynik w konkretnych przeglądarkach używanych przez klientów, nie tylko w tej na własnej maszynie, a jeśli zależy ci na PDF-ach archiwalnych albo czystych dla rygorystycznych walidatorów, składaj strony upstream przez pełną otoczkę Form XObject. Ta sama dyscyplina dotyczy wszystkiego, co budujesz na grafie wczytanych obiektów — dlatego przebieg preflight PDF w Delphi zasłużenie zajmuje miejsce w pipeline’ie wydaniowym, kiedykolwiek programowo modyfikujesz dokumenty

HotPDF: Zszywanie dopisuje q, macierz cm niosącą skalę i przesunięcie, wywołanie Do StitchSrc oraz Q do strony docelowej, podczas gdy słownik zasobów dostaje sam słownik strony źródłowej bez podtypu Form i bez BBox
Para q/Q zamyka w nawias jedno przekształcenie cm, po którym następuje /StitchSrc Do, ale ponieważ zarejestrowany obiekt nie ma /Subtype /Form ani /BBox, zszyte wyjście potrzebuje wizualnej weryfikacji w każdej przeglądarce, jaką uruchamiają twoi klienci

Gdzie to pasuje, a gdzie nie

Obie metody są narzędziami strumienia zawartości, więc model mentalny jest ten sam, którego używasz przy rysowaniu bezpośrednim. Jeśli budowałeś strony od zera komponentem, operatory wektorowe i koloru stojące za tymi wywołaniami będą ci znane z artykułu o rysowaniu na kanwie HotPDF w Delphi; różnica polega tylko na tym, że tutaj dopisujesz do strumienia autorstwa kogoś innego, zamiast do strumienia, nad którym sam panujesz. Pamiętaj o trzech granicach:

  • Redaction jest kosmetyczne. RedactLoadedRect maluje po zawartości i nigdy jej nie usuwa. Dla wszystkiego wrażliwego wygeneruj źródło ponownie albo użyj prawdziwego usuwania zawartości. Czarny prostokąt nie jest zabezpieczeniem
  • Sprawdź zszyte strony w docelowych przeglądarkach. Strona źródłowa jest referencjonowana bezpośrednio, a nie przez Form XObject z §8.10.1 z /Subtype /Form i /BBox, więc potwierdź renderowanie w docelowych przeglądarkach i składaj strony upstream tam, gdzie wymagana jest ścisła walidacja
  • Współrzędne należą do przestrzeni użytkownika strony. Lewy dolny róg jako początek, punkty jako jednostki, wszystko sterowane przez własny media box strony. Odczytaj go przez GetLoadedPageBox, zanim cokolwiek umieścisz, bo załadowana strona może nie mieć rozmiaru, który zakładałeś

Stosowana z tymi granicami para pokrywa realny workflow: przestawienie stron do druku, zamaskowanie niepoufnych obszarów i zapis wyniku przez SaveLoadedDocument — wszystko bez pełnego ponownego renderowania. API dla wczytanych dokumentów, obejmujące te prymitywy stitch i maskowania, jest dostarczane z HotPDF Delphi Component dla Delphi i C++Builder, razem z jego metodami pól formularzy, adnotacji i FDF