Technischer Artikel

PDF-Schwärzung und N-up-Stitch in Delphi mit HotPDF

Eine Anfrage landet auf Ihrem Schreibtisch: Nehmen Sie einen Stapel bereits gerenderter Kontoauszüge, schwärzen Sie die Kontonummern und geben Sie zwei Seiten pro Blatt aus, um Papier zu sparen. Beide Teile dieser Aufgabe sind Eingriffe in den Content-Stream einer PDF-Datei, die Sie nicht selbst erstellt haben. Es gibt also weder eine komfortable Seite zum Zeichnen noch einen Schriftarten-Manager, auf den Sie sich stützen könnten. Sie bearbeiten den Objektgraphen eines geladenen Dokuments direkt und hängen rohe Zeichenoperatoren an eine Seite an, die von einem anderen Werkzeug gestaltet wurde. HotPDF bietet genau zwei Einstiegspunkte dafür, und der gefährlichere von beiden ist derjenige, der harmlos aussieht

HotPDF ist eine native VCL-PDF-Komponente für Delphi und C++Builder, und ihre API für geladene Dokumente umfasst Methoden, die brandneue Inhalte auf einer von der Festplatte geöffneten Seite erzeugen statt auf einer, die Sie von Grund auf selbst aufbauen. Zwei davon sind hier das Thema: RedactLoadedRect, das ein undurchsichtiges Rechteck über einen Bereich malt, und StitchLoadedPage, das eine Seite skaliert und auf eine andere zeichnet. Beide arbeiten, indem sie ISO 32000-1 §8.5 Content-Stream-Operatoren in den /Contents-Stream der Seite schreiben. Zu verstehen, was diese Operatoren tun und – ebenso wichtig – was sie nicht tun, macht den Unterschied zwischen einem funktionierenden Werkzeug und einer Datenpanne aus

Anhängen von Operatoren an eine geladene Seite

Wenn Sie eine Seite mit der normalen HotPDF-API erstellen, besitzt die Komponente den Content-Stream und serialisiert Ihre TextOut- und Vektoraufrufe für Sie. Eine geladene Seite ist anders: Ihre /Contents ist ein bereits vorhandenes Stream-Objekt, möglicherweise geteilt, möglicherweise Teil eines Content-Arrays, und Sie müssen sich hineinhängen, ohne das Vorhandene zu beschädigen. Drei kleine Hilfsfunktionen machen das sicher. NewIndirectStream allokiert ein neues indirektes THPDFStreamObject mit leerem Puffer und einem Eintrag /Length 0; ResolveLoadedStream folgt einer indirekten Referenz bis zum zugrunde liegenden Stream; und AppendLoadedStream schreibt rohe Bytes an das Ende des Streams und schreibt /Length neu, damit das gespeicherte Objekt wohlgeformt bleibt

Das Muster, dem beide öffentlichen Methoden folgen, ist dasselbe. Suchen Sie die /Contents der Seite, lösen Sie sie in einen Stream auf, und wenn kein brauchbarer Stream vorhanden ist, erstellen Sie einen und hängen Sie ihn an. Hängen Sie dann die Operatoren an. Da die neuen Bytes am Ende des Streams eingefügt werden, garantiert das Malermodell, dass sie über allem gerendert werden, was das ursprüngliche Layout gezeichnet hat. Diese Reihenfolge ist der gesamte Mechanismus hinter dem Schwärzungsrechteck, und es ist auch der Grund, warum dieses Rechteck nicht das ist, was die meisten Leute vermuten

HotPDF: Operatoren an eine geladene Seite anhängen durchläuft drei Helfer: vom Auffinden des Contents-Streams der Seite über sein Auflösen oder Erzeugen bis zum letzten Anhängen roher Bytes, und das Painter-Modell garantiert, dass diese Bytes über alles malen, was das ursprüngliche Layout zeichnet
NewIndirectStream, ResolveLoadedStream und AppendLoadedStream fügen frische Operatoren an das Ende eines bestehenden /Contents-Streams an, sodass alles, was sie zeichnen, über dem ursprünglichen Seitenlayout landet, ohne ein Byte davon umzuschreiben

RedactLoadedRect: Eine undurchsichtige Abdeckung, kein Löschen

RedactLoadedRect übernimmt einen nullbasierten Seitenindex, vier Benutzerraum-Koordinaten und drei Farbkomponenten im Bereich von 0 bis 1:

var
  Pdf: THotPDF;
begin
  Pdf := THotPDF.Create(nil);
  try
    if Pdf.LoadFromFile('statement.pdf') > 0 then
    begin
      // Den Kontonummern-Bereich auf Seite 1 mit durchgehendem Schwarz abdecken.
      // Koordinaten sind im PDF-Benutzerraum: Ursprung unten links, Punkte.
      Pdf.RedactLoadedRect(0, 56, 690, 320, 706, 0, 0, 0);
      Pdf.SaveLoadedDocument('statement-covered.pdf');
    end;
  finally
    Pdf.Free;
  end;
end;

Unter der Haube gibt die Methode drei Operatoren in den Content-Stream aus: eine Füllfarbe in DeviceRGB (r g b rg), einen Rechteckpfad (x y w h re) und eine Füllung (f). Breite und Höhe werden als X2 - X1 und Y2 - Y1 berechnet, sodass Sie zwei gegenüberliegende Ecken übergeben und die Methode den Bereich berechnen lassen. Übergeben Sie 0, 0, 0 für die Farbe, um einen schwarzen Balken zu erhalten; übergeben Sie 1, 1, 1 für einen weißen Balken, der zu einer weißen Seite passt. Die Koordinaten beziehen sich auf den eigenen Benutzerraum der geladenen Seite, was bedeutet, dass der Ursprung die linke untere Ecke ist und die Einheiten in Punkten angegeben werden. Dies bedeutet auch, dass Sie die /MediaBox der Seite benötigen, um etwas präzise zu platzieren; GetLoadedPageBox mit pbMediaBox liefert Ihnen diese

Lesen Sie dies zweimal: Ein gefülltes Rechteck deckt Inhalte visuell ab, entfernt sie jedoch nicht. Der Text, das Bild oder die Vektorgrafik unter dem Rechteck ist weiterhin in der PDF-Datei vorhanden, weiterhin im Objektgraphen und kann von jedem extrahiert werden, der die Seite kopiert, ein Textextraktionswerkzeug ausführt oder einfach Ihr Rechteck aus dem Content-Stream löscht. Dies ist eine visuelle Maskierung, keine Schwärzung im rechtlichen oder sicherheitsbezogenen Sinne. Wenn Sie wirklich sensible Daten verbergen – Kontonummern, Krankenakten, Identitäten oder regulierte Informationen –, ist das Abdecken mit einem schwarzen Feld und das Versenden der Datei ein vorprogrammiertes Datenleck. Eine echte Schwärzung erfordert das Löschen der zugrunde liegenden Inhaltsobjekte, nicht das Übermalen

HotPDF: Eine abgedeckte Kontonummer überlebt das Schwärzen durch Malen: der Viewer zeigt ein massives dunkles Band über der Kontenzeile, während der Content Stream weiterhin den ACCT-String listet und jeder Textextraktor ihn unverändert zurückdruckt
Die Operatoren r g b rg, re und f fügen nur oben Pixel hinzu — das ursprüngliche Textobjekt bleibt im Objektgraph lebendig, daher gewinnt ein Kopier-und-Extrahieren-Durchlauf jedes Zeichen zurück, das der schwarze Balken verbirgt

Der Methodenname sagt „Redact“, und das ist eine nützliche Warnung, wie das Ergebnis missverstanden wird, kein Versprechen darüber, was gelöscht wird. RedactLoadedRect ist von der Konstruktion her ein visuelles Schwärzungsprimitiv; Schwärzen, das Inhalte entfernt, ist eine andere Operation, die die vorhandenen Operatoren des Content-Streams durchläuft und umschreibt. Die sichere Regel ist daher eng gefasst: Verwenden Sie RedactLoadedRect für unempfindliche kosmetische Maskierungen – ein Entwurfswasserzeichen ausblenden, einen Bereich vor einem Screenshot abdecken, ein veraltetes Logo auf einem internen Korrekturabzug überdecken. Sobald das, was unter dem Feld liegt, im Fall eines Lecks relevant wäre, ist diese Methode das falsche Werkzeug, und die richtige Antwort ist, das Dokument ohne die Daten neu zu erzeugen oder eine echte Pipeline zur Inhaltsentfernung zu verwenden

StitchLoadedPage: Skalieren, verschieben, zeichnen

Die N-up-Ausschießseite ist das einfachere Problem, da nichts verborgen, sondern nur neu angeordnet wird. StitchLoadedPage übernimmt einen Zielseitenindex, einen Quellseitenindex, einen X/Y-Versatz und einen Skalierungsfaktor und zeichnet die Quellseite in dieser Position und Größe auf das Ziel:

// Seite 2 (Index 1) über Seite 1 (Index 0) legen,
// auf 70% skaliert und nach oben rechts verschoben.
Pdf.StitchLoadedPage(0, 1, 40, 380, 0.7);

// Praktisches 2-auf-eins: Quellseite auf der rechten Hälfte des Ziels.
Pdf.StitchLoadedPageSideBySide(0, 1);

Die angehängte Operatorzeichenfolge ist eine standardmäßige Transformations- und Zeichensequenz: q zum Speichern des Grafikzustands, eine cm-Matrix, die die Skalierung auf der Diagonale und den Versatz in den Translationsfeldern enthält, /StitchSrc Do zum Aufrufen eines externen Objekts und Q zum Wiederherstellen des Zustands. Das q/Q-Paar ist wichtig: Es isoliert die Transformation, sodass die gestitchte Seite ihr Koordinatensystem nicht in nachfolgend angehängte Elemente überträgt. Die Methode beugt auch offensichtlichen Fehlern vor – Indizes außerhalb des Bereichs, Ziel identisch mit der Quelle, eine nicht-positive Skalierung (die sie auf 1.0 begrenzt) – und bricht geräuschlos ab, anstatt eine Ausnahme auszulösen. Überprüfen Sie also Ihre Eingaben, da ein stiller Fehlschlag identisch mit einem Erfolg aussieht

StitchLoadedPageSideBySide ist eine einfache Komfortfunktion über der allgemeinen Methode. Sie liest die Media-Box-Breite des Ziels, halbiert sie und ruft StitchLoadedPage mit dieser halben Breite als X-Versatz und einer festen Skalierung von 0.5 auf, wodurch die Quelle auf der rechten Hälfte platziert wird. Diese hartcodierte 0.5 setzt voraus, dass Quelle und Ziel die gleiche Breite haben. Wenn dies nicht der Fall ist, füllt die Quelle ihre Hälfte nicht sauber aus, und Sie müssen die allgemeine Methode StitchLoadedPage mit einer Skalierung verwenden, die Sie selbst aus beiden Media-Boxes berechnen

Wie der Stitch die Quellseite referenziert

Das ist das Detail, das Sie kennen sollten, bevor Sie der Ausgabe über verschiedene Viewer hinweg vertrauen. Ein klassisches N-up-Ausschießen verpackt den Inhalt der Quellseite in ein Form XObject – ein in sich geschlossenes zeichenbares Objekt, das laut ISO 32000-1 §8.10.1 /Type /XObject, /Subtype /Form und eine eigene /BBox als Clipping-Box mitbringen muss. StitchLoadedPage nimmt den leichteren Weg: Es registriert das Quell-Seiten-Dictionary selbst direkt unter den /Resources /XObject des Ziels unter dem Namen StitchSrc und zeichnet es dann mit Do. Ein Seiten-Dictionary und ein Form XObject teilen genug von ihrem Inhaltsmodell – beide verweisen auf einen Content-Stream und ein Ressourcen-Dictionary –, dass viele Reader das Ergebnis rendern

Weil das registrierte Objekt weder die Markierung /Subtype /Form noch eine eigene /BBox trägt, hat ein strenger Consumer das Recht, das Do zu ignorieren oder anders zu beschneiden, als Sie erwarten. Prüfen Sie gestitchte Ausgabe also in den konkreten Viewern, die Ihre Kunden einsetzen, nicht nur in dem auf Ihrem Rechner, und wo archivtaugliche oder validator-saubere PDFs gefragt sind, schießen Sie die Seiten bereits upstream durch einen vollständigen Form-XObject-Wrapper. Dieselbe Disziplin gilt für alles, was Sie auf dem geladenen Objektgraphen aufbauen – deshalb verdient ein PDF-Preflight-Durchlauf in Delphi seinen Platz in der Release-Pipeline, wann immer Sie Dokumente programmatisch verändern

HotPDF: Stitching hängt q, eine cm-Matrix mit Skalierung und Versatz, einen StitchSrc-Do-Aufruf und Q an die Zielseite, während das Ressourcenwörterbuch das Quellseitenwörterbuch selbst erhält, ohne Form-Subtyp und ohne BBox
Das q/Q-Paar klammert eine cm-Transformation gefolgt von /StitchSrc Do, aber weil dem registrierten Objekt /Subtype /Form und /BBox fehlen, braucht gestitchte Ausgabe visuelle Verifikation in jedem Viewer, den Ihre Kunden einsetzen

Wo diese Methoden passen und wo nicht

Beide Methoden sind Content-Stream-Werkzeuge, sodass das mentale Modell dasselbe ist, das Sie für das direkte Zeichnen verwenden. Wenn Sie mit der Komponente Seiten von Grund auf neu aufgebaut haben, werden Ihnen die Vektor- und Farboperatoren hinter diesen Aufrufen aus dem Zeichnen auf dem HotPDF-Canvas in Delphi bekannt vorkommen; der Unterschied besteht nur darin, dass Sie hier an einen Stream anhängen, den jemand anderes verfasst hat, anstatt an einen eigenen. Beachten Sie drei Grenzen:

  • Schwärzung ist kosmetisch. RedactLoadedRect übermalt Inhalte und löscht sie niemals. Generieren Sie bei sensiblen Inhalten die Quelle neu oder verwenden Sie eine echte Inhaltsentfernung – ein schwarzes Feld ist keine Sicherheit
  • Prüfen Sie gestitchte Seiten in Ihren Ziel-Viewern. Die Quellseite wird direkt referenziert und nicht über ein §8.10.1-Form-XObject mit /Subtype /Form und /BBox; bestätigen Sie das Rendering daher in Ihren Ziel-Viewern und schießen Sie bereits upstream, wo strenge Validierung verlangt wird
  • Koordinaten beziehen sich auf den Benutzerraum der Seite. Ursprung unten links, Einheiten in Punkten, gesteuert durch die eigene Media-Box der Seite. Lesen Sie die Box mit GetLoadedPageBox, bevor Sie etwas platzieren, da die geladene Seite möglicherweise nicht die von Ihnen angenommene Größe hat

Mit diesen Grenzen im Hinterkopf deckt das Paar einen echten Arbeitsablauf ab: Seiten für den Druck neu anordnen, unkritische Bereiche maskieren und das Ergebnis mit SaveLoadedDocument zurückschreiben – alles ohne vollständiges erneutes Rendern. Die API für geladene Dokumente, die diese Stitch- und Maskierungs-Primitiven enthält, wird mit der HotPDF Delphi Component für Delphi und C++Builder ausgeliefert, zusammen mit ihren Formularfeld-, Anmerkungs- und FDF-Methoden