Technischer Artikel

Textmarkierungs-Annotationen mit PDFium QuadPoints in Delphi

Eine Highlight-Annotation, die FPDFPage_CreateAnnot gerade eben zurückgegeben hat, meldet FPDFAnnot_CountAttachmentPoints = 0, und FPDFAnnot_SetAttachmentPoints(Annot, 0, Quad) liefert darauf 0, ganz gleich welche Koordinaten man übergibt. Die Koordinaten sind nicht das Problem. Index 0 heißt „ersetze vorhandenes Quad Nummer 0“, eine neue Annotation hat überhaupt keine Quads, und der Aufruf, der einen Slot anlegt, ist FPDFAnnot_AppendAttachmentPoints

Das passt in einen Absatz, trotzdem verliert man darauf leicht Stunden, denn die naheliegende Reaktion auf ein false ist, der Geometrie zu misstrauen. Man vertauscht die Ecken, spiegelt die Y-Achse, rechnet in den Device Space und zurück. Nichts davon ändert das Ergebnis. Es folgt: was die Quads nach ISO 32000-1 enthalten müssen, wie man sie über die Component-API und über die rohen C-Funktionen schreibt, mehrzeilige Selektionen und eine Indexing-Falle, die sich zwischen Delphi, Free Pascal und C++Builder unterscheidet. Es ist das Erstellungs-Gegenstück zu dem Artikel über das Lesen und Prüfen vorhandener Annotationen, der dieselben Strukturen in der anderen Richtung durchläuft

Was QuadPoints in ISO 32000-1 §12.5.6.10 bedeuten

QuadPoints ist ein Pflichteintrag der vier Text-Markup-Subtypen Highlight, Underline, Squiggly und StrikeOut: ein Array aus 8×n Zahlen für n Vierecke im Default User Space, wobei jedes Viereck ein Wort oder eine Gruppe zusammenhängender Worte des Texts unter der Annotation umschließt. Die Annotation trägt weiterhin ein Rect, das jede Annotation braucht, aber bei Markup-Subtypen sagen die Quads, welche Glyphen markiert sind, und Rect umschließt sie nur. Vierecke statt Rechtecke, weil Text auf der Seite rotiert oder geschert sein kann; jede Ecke liegt daher als eigener Punkt vor: x1 y1 x2 y2 x3 y3 x4 y4

Bei der Eckenreihenfolge gehen der Specificationstext und die Dateien in Umlauf getrennte Wege. §12.5.6.10 sagt, die vier Eckpunkte seien gegen den Uhrzeigersinn angegeben, und ergänzt, der Text orientiere sich an der Kante von (x1, y1) nach (x2, y2). Acrobat und die lange Kette von Werkzeugen, die gebaut wurden, um zu lesen, was Acrobat schreibt, verwenden stattdessen ein Z-Muster: Punkt 1 oben links, Punkt 2 oben rechts, Punkt 3 unten links, Punkt 4 unten rechts. Dieses Layout hält die Orientierungsaussage ein, denn die Kante 1–2 läuft am oberen Rand des Texts entlang, aber es ist kein gegen den Uhrzeigersinn laufender Rundgang um die Form. Schreiben Sie die Z-Ordnung. Eine wörtlich gegen den Uhrzeigersinn laufende Liste (oben links, unten links, unten rechts, oben rechts) ist auf dem Papier vertretbar, aber ein Reader, der die Punkte als Z abläuft, erhält oben links, unten links, oben rechts, unten rechts, und diese Kanten kreuzen sich zu einer Fliege

Alle Koordinaten sind Seitenkoordinaten in Point, Ursprung unten links auf der Seite, Y wächst nach oben. Eine Textzeile nahe dem oberen Rand einer A4-Seite hat daher Y-Werte um 700 bis 800, und ihre obere Kante hat das größere Y. Die Specification gibt außerdem einem Appearance Stream (AP) Vorrang vor den QuadPoints, wenn beide vorhanden sind; die Quads zählen also vor allem für Viewer, die das Markup selbst erzeugen

QuadPoints-Geometriediagramm in PDF-Seitenkoordinaten mit der Z-Reihenfolge der Eckennummerierung TL, TR, BL, BR, die PDFium-Textmarkierungs-Annotationen verwenden
PDFium erwartet QuadPoints in Z-Reihenfolge, oben links nach oben rechts, dann unten links nach unten rechts, in Seitenkoordinaten, in denen Y nach oben wächst

Warum gibt FPDFAnnot_SetAttachmentPoints false zurück?

FPDFAnnot_SetAttachmentPoints liefert bei einer neuen Annotation false, weil es nur ein bereits existierendes Quad ersetzt. Der PDFium-Header sagt den Vertrag direkt: Der quad_index muss „within the result of FPDFAnnot_CountAttachmentPoints()“ liegen. Jede Annotation aus FPDFPage_CreateAnnot startet mit Zählerstand null, also gibt es keinen Index 0 zum Ersetzen. FPDFAnnot_AppendAttachmentPoints legt einen Slot an und wächst den Zähler um eins; danach existiert Index 0, und Set nimmt ihn an. Beide Funktionen sind in den PDFium-Headern als experimentell markiert, und beide weiten auch die Bounding Box eines vorhandenen Appearance Streams, wenn das neue Quad weiter hinausreicht als das alte

Die PDFium Component legt alle FPDFAnnot_*-Einsprungpunkte in PDFium.pas offen, und der FS_QUADPOINTSF-Record samt dem size_t-Alias liegt in FPdfView.pas. Wenn Sie einen Annotation-Handle selbst halten, verzweigen Sie vor jedem Schreiben nach dem Zählerstand:

uses
  SysUtils, PDFium, FPdfView;

// Schreibt Quad an QuadIndex in die Annotation AnnotIndex der aktiven Seite:
// ersetzt den Slot, wenn er existiert, hängt sonst einen neuen an
procedure WriteQuad(Pdf: TPdf; AnnotIndex: Integer; QuadIndex: size_t;
  var Quad: FS_QUADPOINTSF);
var
  Annot: FPDF_ANNOTATION;
  Count: size_t;
  Ok: Boolean;
begin
  Annot := FPDFPage_GetAnnot(Pdf.Page, AnnotIndex);
  if Annot = nil then
    raise Exception.CreateFmt('No annotation at index %d', [AnnotIndex]);
  try
    Count := FPDFAnnot_CountAttachmentPoints(Annot);
    if QuadIndex < Count then
      Ok := FPDFAnnot_SetAttachmentPoints(Annot, QuadIndex, Quad) <> 0
    else
      Ok := FPDFAnnot_AppendAttachmentPoints(Annot, Quad) <> 0;
    if not Ok then
      raise Exception.Create('PDFium rejected the quad');
  finally
    FPDFPage_CloseAnnot(Annot);
  end;
end;

Eine zweite Falle sitzt in derselben Funktionsfamilie. FPDFAnnot_CountAttachmentPoints liefert size_t, also vorzeichenlos, daher berechnet das gewohnte for I := 0 to Count - 1 bei einer Annotation ohne Quads 0 − 1 in vorzeichenloser Arithmetik und läuft in den größtmöglichen Wert über. Prüfen Sie Count > 0, bevor Sie irgendeine Schleife über Quads betreten, oder casten Sie vorher auf einen vorzeichenbehafteten Typ. Markup anderer Werkzeuge kommt fast immer mit mindestens einem Quad an. Eine frisch erzeugte Annotation kommt mit null an

Eine Hervorhebung mit TPdf.CreateAnnotation erzeugen

Mit der Component-API wählen Sie nie selbst zwischen Append und Set. TPdf.CreateAnnotation und TPdf.SetAnnotation prüfen beide, wie viele Quads die Annotation bereits hält, ersetzen die vorhandenen Slots und hängen den Rest an; der Erstellungspfad hängt also an, der Aktualisierungspfad ersetzt. Was Sie liefern, ist ein TPdfAnnotation-Record mit Subtype, Farbe, dem Quad und einem Rectangle

Zwei Record-Details zählen hier. Initialisieren Sie den Record mit Default(TPdfAnnotation). Der Record hält Strings und dynamische Arrays, und FillChar über einen Record, der bereits einen String trägt, leakt ihn einfach; Default ist daher die sicherere Gewohnheit für jeden Record, den Sie wiederverwenden. Und füllen Sie Rectangle immer: Die Component schreibt ihn bei jedem Erzeugen und Aktualisieren als Rect der Annotation, also produziert ein genullter Record ein Rect von [0 0 0 0], selbst wenn die Quads stimmen. CreateAnnotation arbeitet auf der aktiven Seite, die AddPage für eine neue Seite und PageNumber für ein vorhandenes Dokument setzt, und wirft 'Unsupported annotation subtype', wenn PDFium den gewünschten Subtyp nicht erzeugen kann

var
  Pdf: TPdf;
  A: TPdfAnnotation;
begin
  Pdf := TPdf.Create(nil);
  try
    Pdf.CreateDocument;
    Pdf.AddPage(0, 595, 842);                // A4, wird die aktive Seite

    A := Default(TPdfAnnotation);
    A.Subtype := anHighlight;
    A.HasColor := True;
    A.Color := clYellow;
    A.ColorAlpha := $80;                     // Alpha wird zusammen mit der Farbe durchgereicht
    A.HasAttachmentPoints := True;
    A.AttachmentPoints[1].X := 50;  A.AttachmentPoints[1].Y := 700;  // oben links
    A.AttachmentPoints[2].X := 250; A.AttachmentPoints[2].Y := 700;  // oben rechts
    A.AttachmentPoints[3].X := 50;  A.AttachmentPoints[3].Y := 680;  // unten links
    A.AttachmentPoints[4].X := 250; A.AttachmentPoints[4].Y := 680;  // unten rechts
    A.Rectangle.Left := 50;   A.Rectangle.Top := 700;                // umschließt das Quad
    A.Rectangle.Right := 250; A.Rectangle.Bottom := 680;
    A.ContentsText := 'Highlighted region';
    Pdf.CreateAnnotation(A);

    Pdf.SaveAs('highlighted.pdf');
  finally
    Pdf.Free;
  end;
end;

Die Dekoration zu wechseln kostet eine Zeile. anUnderline, anStrikeout und anSquiggly nehmen denselben Record samt Quads; ISO 32000-1 beschreibt die vier zusammen, und sie unterscheiden sich nur darin, wie die Quad-Region gemalt wird. Subtypen außerhalb dieser Familie wie anSquare, anCircle und anText positionieren sich allein über Rectangle; lassen Sie für die HasAttachmentPoints auf False und AttachmentPointSets leer, dann wird kein Quad geschrieben

Mehrzeilige Selektionen: eine Annotation, mehrere Quads

Eine Selektion, die über drei Zeilen läuft, braucht drei Quads, einen pro Zeile, denn ein einzelnes Viereck über alle drei würde auch das rechte Ende von Zeile eins und das linke Ende von Zeile drei malen. TPdfAnnotation trägt alle Quads in AttachmentPointSets, einem dynamischen Array aus TQuadrilateralPoint; das einzelne Feld AttachmentPoints bleibt als Alias für den ersten Eintrag. Ist AttachmentPointSets nicht leer, schreibt CreateAnnotation alle seine Einträge der Reihe nach, und das Einzelfeld wird ignoriert

Stattdessen könnte man eine Annotation pro Zeile anlegen. Das rendiert gleich, aber ein Prüfer sieht dann drei Kommentare, drei Popups und drei Dinge zum Löschen für das, was eine Hervorhebung war. Legen Sie die Zeilen in einer Annotation ab. Die Geometrie liefert die Suche bequem, denn TPdf.CreateDocumentSearch liefert jeden Treffer mit einem Rectangles-Array, das pro Textlauf auf einer Zeile ein Rechteck hält, bereits in Seitenkoordinaten:

function QuadFromRect(const R: TPdfRectangle): TQuadrilateralPoint;
begin
  Result[1].X := R.Left;  Result[1].Y := R.Top;     // oben links
  Result[2].X := R.Right; Result[2].Y := R.Top;     // oben rechts
  Result[3].X := R.Left;  Result[3].Y := R.Bottom;  // unten links
  Result[4].X := R.Right; Result[4].Y := R.Bottom;  // unten rechts
end;

// Eigener Helper, nicht Teil der Bibliothek: Vereinigung der Zeilenrechtecke
function UnionRect(const Rects: TPdfRectangles): TPdfRectangle;
var
  I: Integer;
begin
  Result := Rects[0];
  for I := 1 to High(Rects) do
  begin
    if Rects[I].Left < Result.Left then Result.Left := Rects[I].Left;
    if Rects[I].Right > Result.Right then Result.Right := Rects[I].Right;
    if Rects[I].Top > Result.Top then Result.Top := Rects[I].Top;
    if Rects[I].Bottom < Result.Bottom then Result.Bottom := Rects[I].Bottom;
  end;
end;

procedure HighlightMatches(Pdf: TPdf; const Needle: WString);
var
  Search: TPdfDocumentSearch;
  Match: TPdfDocumentSearchResult;
  Found: array of TPdfDocumentSearchResult;
  A: TPdfAnnotation;
  I, J: Integer;
begin
  // Alle Treffer sammeln, bevor irgendeine Seite bearbeitet wird
  Search := Pdf.CreateDocumentSearch(Needle, [seWholeWord]);
  try
    while Search.Next(Match) do
      if Length(Match.Rectangles) > 0 then
      begin
        SetLength(Found, Length(Found) + 1);
        Found[High(Found)] := Match;
      end;
  finally
    Search.Free;
  end;

  for I := 0 to High(Found) do
  begin
    Pdf.PageNumber := Found[I].PageNumber;
    A := Default(TPdfAnnotation);
    A.Subtype := anHighlight;
    A.HasColor := True;
    A.Color := clYellow;
    A.ColorAlpha := $80;
    SetLength(A.AttachmentPointSets, Length(Found[I].Rectangles));
    for J := 0 to High(Found[I].Rectangles) do
      A.AttachmentPointSets[J] := QuadFromRect(Found[I].Rectangles[J]);
    A.Rectangle := UnionRect(Found[I].Rectangles);
    A.ContentsText := Found[I].Text;
    Pdf.CreateAnnotation(A);
  end;
end;

Die Suchrechtecke sind achsenparallel, je vier Zahlen, daher deckt das entstehende Quad bei rotiertem Text die Bounding Box des Textlaufs ab, statt der Schräge zu folgen. Bei geradem horizontalem Text, dem Großteil dessen, was hervorgehoben wird, fallen Box und Glyphenfläche zusammen. Wer stattdessen Geometrie pro Zeichen braucht: Der Leitfaden zur Textextraktion mit der PDFium Component behandelt CharacterRectangle und die verwandten Text-Page-Aufrufe, und der Artikel zu Textmessung und Word Wrap zeigt, wie man Zeilenausmaße für Text berechnet, der erst noch erzeugt werden soll

Mehrzeilige Hervorhebung, aufgebaut aus drei Vierecken, die nacheinander an eine einzelne in Delphi erzeugte PDFium-Annotation angehängt werden
Eine Auswahl über drei Zeilen wird zu einer Annotation mit drei Quads, aufgebaut mit AppendAttachmentPoints-Aufrufen, die die Slot-Anzahl wachsen lassen

Eine vorhandene Markup-Annotation zu bearbeiten läuft über Pdf.Annotation[Index] := A, das SetAnnotation aufruft; der Subtyp im Record muss zum gespeicherten passen, sonst wirft der Aufruf 'Incorrect annotation subtype'. Quads werden Index für Index neu geschrieben, und zusätzliche Einträge in AttachmentPointSets werden angehängt. PDFium stellt keinen Aufruf bereit, der ein einzelnes Quad entfernt, daher bleibt beim Übergang von drei auf zwei Quads das dritte in der Datei. Um eine Hervorhebung zu verkleinern, löschen Sie sie mit DeleteAnnotation und legen sie mit dem kürzeren Array neu an

AttachmentPoints zählen ab 1, außer in C++

TQuadrilateralPoint ist als array [1..4] of TPdfPoint deklariert, und die Nummerierung entspricht den Eckennummern der Specification: Element 1 ist (x1, y1), Element 4 ist (x4, y4). Code, der aus dem Gedächtnis mit Nullbasiert-Gewohnheiten geschrieben wird, macht das falsch, und zwar auf eine Art, die der Compiler nicht immer abfängt. Eine Schleife wie for I := 0 to 3 do A.AttachmentPoints[I] := ... kompiliert in Delphi wie in Free Pascal, weil der Index erst zur Laufzeit bekannt ist. Mit ausgeschalteter Range-Prüfung, dem Delphi-Projektdefault, landet der Schreibzugriff für Index 0 auf den Bytes direkt vor dem Array, in den vorausgehenden Record-Feldern, und das Quad selbst behält eine Nullecke. Nichts wirft

Ein konstanter Index ist etwas anderes. Der Compiler kann ihn mit den deklarierten Grenzen vergleichen, bevor irgendetwas läuft, und fpc etwa weist ein literales AttachmentPoints[0] mit einem Range-Fehler zurück. Die Form, die durchrutscht, ist der berechnete Index. Bauen Sie Annotationscode mindestens einmal mit {$R+} in Delphi oder über fpc, bevor Sie ihm vertrauen; mit eingeschalteter Range-Prüfung wirft die Laufzeit-Schleife oben bei Index 0 eine ERangeError

C++Builder dreht die Regel um. Das generierte PDFium.hpp deklariert TQuadrilateralPoint als System::StaticArray<TPdfPoint, 4>, und ein C++-Static-Array startet bei null, egal welche untere Grenze Pascal hatte. In C++ liegen die Ecken daher bei AttachmentPoints[0] bis AttachmentPoints[3], weiterhin in Z-Ordnung. Delphi-Beispielcode Zeile für Zeile zu portieren behält Indizes 1 bis 4 bei, was jede Ecke um eins verschiebt und die letzte hinter das Array-Ende schreibt

Die Quads zurücklesen

Die schnellste Kontrolle, ob eine Markup-Annotation korrekt gelandet ist, ist das Zurücklesen über dieselbe API. Pdf.Annotation[Index] füllt AttachmentPointSets mit jedem auf der Annotation gespeicherten Quad, und HasAttachmentPoints ist True, wenn mindestens eines da ist:

var
  I, Q: Integer;
  B: TPdfAnnotation;
begin
  Pdf.PageNumber := 1;
  for I := 0 to Pdf.AnnotationCount - 1 do
  begin
    B := Pdf.Annotation[I];
    if B.Subtype in [anHighlight, anUnderline, anStrikeout, anSquiggly] then
      for Q := 0 to High(B.AttachmentPointSets) do
        Writeln(Format('annot %d quad %d: TL (%.1f, %.1f)  BR (%.1f, %.1f)',
          [I, Q,
           B.AttachmentPointSets[Q][1].X, B.AttachmentPointSets[Q][1].Y,
           B.AttachmentPointSets[Q][4].X, B.AttachmentPointSets[Q][4].Y]));
  end;
end;

Für die einzelne Hervorhebung von vorhin lautet die erwartete Zeile annot 0 quad 0: TL (50.0, 700.0) BR (250.0, 680.0); ein TL-Y unterhalb des BR-Y heißt, die Ecken kamen kopfüber hinein. Die Quads reisen auch mit der Annotation, wenn Sie Markup mit anderen Werkzeugen austauschen: Das coords-Attribut in XFDF hält alle, acht Zahlen pro Quad, wie der Artikel zu XFDF-Export und -Import beschreibt. Danach: Öffnen Sie die gespeicherte Datei in einem zweiten Viewer und kontrollieren, dass die Farbe auf den Glyphen sitzt und nicht daneben, denn ein Viewer, der sein eigenes Erscheinungsbild aus den QuadPoints baut, ist der, der eine schlechte Eckenreihenfolge offenlegt

Der Annotations-Record, das Multi-Quad-Array und der durchgehend verwendete count-bewusste Writer liegen in der PDFium Component für Delphi, C++Builder und Lazarus, wo die vollständige Annotations-API-Referenz neben den Text-Such- und Extraktionsaufrufen sitzt, auf die diese Beispiele bauen