Technisch artikel

Tekstmarkeringsannotaties met PDFium QuadPoints in Delphi

Een highlight-annotatie die FPDFPage_CreateAnnot een ogenblik eerder teruggaf, meldt FPDFAnnot_CountAttachmentPoints = 0, en FPDFAnnot_SetAttachmentPoints(Annot, 0, Quad) geeft er 0 op terug, welke coördinaten u ook opgeeft. De coördinaten zijn niet het probleem. Index 0 betekent "vervang bestaande quad nummer 0", een nieuwe annotatie heeft helemaal geen quads, en de aanroep die een slot creëert is FPDFAnnot_AppendAttachmentPoints

Dat past in één alinea, maar het kan makkelijk uren kosten, want de natuurlijke reactie op een false-teruggave is aan de geometrie te twijfelen. Mensen verwisselen de hoeken, spiegelen de Y-as, converteren naar device space en weer terug. Niets daarvan verandert de uitkomst. Hieronder volgt wat de quads volgens ISO 32000-1 moeten bevatten, hoe u ze via de component-API en via de ruwe C-functies wegschrijft, meerregelige selecties, en een indexeringsvalkuil die verschilt tussen Delphi, Free Pascal en C++Builder. Het is de creatiezijde-broer van het artikel over bestaande annotaties lezen en beoordelen, dat dezelfde structuren in de andere richting bewandelt

Wat QuadPoints volgens ISO 32000-1 §12.5.6.10 betekenen

QuadPoints is een verplichte entry op de vier tekstmarkering-subtypes, Highlight, Underline, Squiggly en StrikeOut: een array van 8×n getallen die n vierhoeken geeft in default user space, waarbij elke vierhoek een woord of een groep aaneengesloten woorden in de tekst onder de annotatie omsluit. De annotatie draagt ook een Rect, die elke annotatie nodig heeft, maar bij de markup-subtypes zeggen de quads welke glyphs gemarkeerd zijn en begrenst Rect ze alleen. Er worden vierhoeken gebruikt in plaats van assuitige rechthoeken omdat tekst op de pagina gedraaid of geschuind kan zijn, dus elke hoek wordt als onafhankelijk punt opgeslagen: x1 y1 x2 y2 x3 y3 x4 y4

De hoekvolgorde is waar de specificatietekst en de bestanden in omloop uit elkaar gaan. §12.5.6.10 zegt dat de vier hoekpunten tegenwijzerzin worden gegeven, en voegt toe dat de tekst georiënteerd is ten opzichte van de rand van (x1, y1) naar (x2, y2). Acrobat, en de lange rij tools die gebouwd zijn om te lezen wat Acrobat schrijft, gebruiken in plaats daarvan een Z-patroon: punt 1 linksboven, punt 2 rechtsboven, punt 3 linksonder, punt 4 rechtsonder. Die indeling eert de oriëntatiezin nog steeds, want de rand 1–2 loopt langs de bovenkant van de tekst, maar het is geen rondgang tegenwijzerzin om de vorm. Schrijf de Z-volgorde. Een letterlijke tegenwijzerzin-lijst (linksboven, linksonder, rechtsonder, rechtsboven) is op papier verdedigbaar, maar een reader die de punten als Z doorloopt krijgt linksboven, linksonder, rechtsboven, rechtsonder, en die randen kruisen tot een strik

Alle coördinaten zijn pagina-coördinaten in punten, oorsprong linksonder op de pagina, Y omhoog groeiend. Een tekstregel nabij de bovenkant van een A4-pagina heeft dus Y-waarden rond 700 tot 800, en zijn bovenrand heeft de grootste Y. De specificatie geeft ook een appearance stream (AP) voorrang boven QuadPoints als beide aanwezig zijn, dus de quads doen er vooral toe voor viewers die de markering zelf genereren

QuadPoints-geometriediagram in PDF-pagina-coördinaten met de Z-volgorde hoeknummering TL, TR, BL, BR gebruikt door PDFium tekstmarkuperingsannotaties
PDFium verwacht QuadPoints in Z-volgorde, linksboven naar rechtsboven en dan linksonder naar rechtsonder, in pagina-coördinaten waar Y omhoog groeit

Waarom retourneert FPDFAnnot_SetAttachmentPoints false?

FPDFAnnot_SetAttachmentPoints geeft false terug op een nieuwe annotatie omdat hij alleen een quad vervangt die al bestaat. De PDFium-header formuleert het contract rechtstreeks: de quad_index "moet binnen het resultaat van FPDFAnnot_CountAttachmentPoints() liggen". Elke annotatie van FPDFPage_CreateAnnot begint met een telling van nul, dus er is geen index 0 om te vervangen. FPDFAnnot_AppendAttachmentPoints voegt een slot toe en laat de telling met één groeien; daarna bestaat index 0 en accepteert Set hem. Beide functies staan als experimental vermeld in de PDFium-headers, en beide vergroten ook de bounding box van een bestaande appearance stream zodra de nieuwe quad verder reikt dan de oude

De PDFium Component stelt alle FPDFAnnot_*-entrypoints bloot in PDFium.pas, en het record FS_QUADPOINTSF en de alias size_t wonen in FPdfView.pas. Houdt u zelf een annotatie-handle vast, dan routeert u op de telling vóór elke schrijfbeurt:

uses
  SysUtils, PDFium, FPdfView;

// Schrijft Quad op QuadIndex van annotatie AnnotIndex op de actieve pagina:
// vervangt het slot als het bestaat, anders wordt er een nieuw toegevoegd
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;

Een tweede valkuil zit in dezelfde functiefamilie. FPDFAnnot_CountAttachmentPoints geeft size_t terug, dat unsigned is, dus de vertrouwde for I := 0 to Count - 1 op een annotatie zonder quads rekent 0 − 1 uit in unsigned-rekenkunde en loopt over naar de grootst mogelijke waarde. Test Count > 0 vóór elke lus over quads, of cast eerst naar een signed type. Markup van andere tools komt bijna altijd met minstens één quad binnen. Een vers aangemaakte annotatie komt met nul binnen

Een markering maken met TPdf.CreateAnnotation

Met de component-API kiest u nooit zelf tussen Append en Set. TPdf.CreateAnnotation en TPdf.SetAnnotation tellen beide eerst hoeveel quads de annotatie al heeft, vervangen de bestaande slots en voegen de rest toe, dus de creatieroute voegt toe en de updateroute vervangt. Wat u aanlevert is een record TPdfAnnotation met Subtype, kleur, de quad en een Rectangle

Twee recorddetails doen er hier toe. Initialiseer het record met Default(TPdfAnnotation). Het record bevat strings en dynamic arrays, en FillChar over een record dat al een string draagt lekt die gewoon weg, dus Default is de veiligere gewoonte voor elk record dat u hergebruikt. En vul altijd Rectangle in: de component schrijft hem bij elke create en update als de Rect van de annotatie, dus een op nul gezet record levert een Rect van [0 0 0 0] op, ook als de quads kloppen. CreateAnnotation werkt op de actieve pagina, die AddPage instelt voor een nieuwe pagina en PageNumber voor een bestaand document, en hij werpt 'Unsupported annotation subtype' op als PDFium het gevraagde subtype niet kan maken

var
  Pdf: TPdf;
  A: TPdfAnnotation;
begin
  Pdf := TPdf.Create(nil);
  try
    Pdf.CreateDocument;
    Pdf.AddPage(0, 595, 842);                // A4, wordt de actieve pagina

    A := Default(TPdfAnnotation);
    A.Subtype := anHighlight;
    A.HasColor := True;
    A.Color := clYellow;
    A.ColorAlpha := $80;                     // alpha gaat mee met de kleur
    A.HasAttachmentPoints := True;
    A.AttachmentPoints[1].X := 50;  A.AttachmentPoints[1].Y := 700;  // linksboven
    A.AttachmentPoints[2].X := 250; A.AttachmentPoints[2].Y := 700;  // rechtsboven
    A.AttachmentPoints[3].X := 50;  A.AttachmentPoints[3].Y := 680;  // linksonder
    A.AttachmentPoints[4].X := 250; A.AttachmentPoints[4].Y := 680;  // rechtsonder
    A.Rectangle.Left := 50;   A.Rectangle.Top := 700;                // omsluit de 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;

De decoratie omwisselen kost één regel. anUnderline, anStrikeout en anSquiggly nemen exact hetzelfde record, quads en al; ISO 32000-1 beschrijft de vier samen, en ze verschillen alleen in hoe het quadgebied wordt geschilderd. Subtypes buiten die familie, zoals anSquare, anCircle en anText, positioneren zichzelf op basis van Rectangle alleen; laat voor die HasAttachmentPoints op False en AttachmentPointSets leeg, en er wordt geen quad geschreven

Meerregelige selecties: één annotatie, meerdere quads

Een selectie die over drie regels doorloopt, heeft drie quads nodig, één per regel, want één vierhoek over alle drie zou ook het rechtereinde van regel één en het linkereinde van regel drie meeschilderen. TPdfAnnotation draagt elke quad in AttachmentPointSets, een dynamic array van TQuadrilateralPoint; het enkele veld AttachmentPoints blijft als alias voor de eerste entry bestaan. Als AttachmentPointSets niet leeg is, schrijft CreateAnnotation al zijn entries op volgorde en wordt het enkele veld genegeerd

U kunt in plaats daarvan ook één annotatie per regel maken. Dat rendert hetzelfde, maar een reviewer ziet dan drie commentaren, drie popups en drie items om te verwijderen voor wat één markering was. Zet de regels in één annotatie. De geometrie is makkelijk uit een zoekactie te halen, want TPdf.CreateDocumentSearch geeft elke match terug met een array Rectangles met één rechthoek per tekstloop op een regel, al in pagina-coördinaten:

function QuadFromRect(const R: TPdfRectangle): TQuadrilateralPoint;
begin
  Result[1].X := R.Left;  Result[1].Y := R.Top;     // linksboven
  Result[2].X := R.Right; Result[2].Y := R.Top;     // rechtsboven
  Result[3].X := R.Left;  Result[3].Y := R.Bottom;  // linksonder
  Result[4].X := R.Right; Result[4].Y := R.Bottom;  // rechtsonder
end;

// Eigen hulpfunctie, geen deel van de bibliotheek: de vereniging van de regelrechthoeken
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
  // Verzamel elke match vóór er een pagina wordt bewerkt
  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;

De zoekrechthoeken zijn asuitgelijnd, telkens vier getallen, dus bij gedraaide tekst dekt de quad de bounding box van de tekstloop in plaats van de helling te volgen. Bij kaarsrechte horizontale tekst, het grootste deel van wat gemarkeerd wordt, vallen box en glyphgebied samen. Heeft u per-teken-geometrie nodig, dan behandelt de gids over tekstextractie met de PDFium Component CharacterRectangle en de verwante tekstpagina-aanroepen, en het artikel over tekstmeting en word wrap laat zien hoe u regelomvang berekent voor tekst die u op het punt staat te genereren

Meerregelig highlight opgebouwd uit drie vierhoeken één voor één toegevoegd aan één PDFium-annotatie gecreëerd in Delphi
Een selectie over drie regels wordt één annotatie met drie quads, opgebouwd met AppendAttachmentPoints-aanroepen die het slotaantal laten groeien

Een bestaande markup-annotatie bewerken loopt via Pdf.Annotation[Index] := A, wat SetAnnotation aanroept; het subtype in het record moet overeenkomen met het opgeslagen subtype, anders werpt de aanroep 'Incorrect annotation subtype' op. Quads worden index voor index herschreven, en extra entries in AttachmentPointSets worden toegevoegd. PDFium stelt geen aanroep bloot die één enkele quad verwijdert, dus van drie quads naar twee laat de derde in het bestand staan. Wilt u een markering kleiner maken, verwijder hem dan met DeleteAnnotation en maak hem opnieuw aan met de kortere array

AttachmentPoints telt vanaf 1, behalve in C++

TQuadrilateralPoint is gedeclareerd als array [1..4] of TPdfPoint, en de nummering komt overeen met de hoeknummers in de specificatie: element 1 is (x1, y1), element 4 is (x4, y4). Code die uit het hoofd met zero-based gewoonten wordt geschreven, gaat hier mis op een manier die de compiler niet altijd vangt. Een lus als for I := 0 to 3 do A.AttachmentPoints[I] := ... compileert in zowel Delphi als Free Pascal, want de index staat pas tijdens run time vast. Met range checking uit, de Delphi-projectdefault, belandt de schrijfbeurt voor index 0 op de bytes vlak vóór de array, binnen de voorafgaande recordvelden, en houdt de quad zelf een nulhoek over. Er wordt niets opgegooid

Een constante index is iets anders. De compiler kan die vergelijken met de gedeclareerde grenzen voordat er iets draait, en fpc bijvoorbeeld verwerpt een letterlijke AttachmentPoints[0] met een range error. De berekende index is de vorm die erdoorheen glipt. Bouw annotatiecode minstens één keer met {$R+} in Delphi, of via fpc, voordat u hem vertrouwt; met range checking aan werpt de runtimelus hierboven ERangeError op bij index 0

C++Builder draait de regel om. De gegenereerde PDFium.hpp declareert TQuadrilateralPoint als System::StaticArray<TPdfPoint, 4>, en een C++ static array begint op nul, welke Pascal-ondergrens er ook stond. In C++ heten de hoeken dus AttachmentPoints[0] tot en met AttachmentPoints[3], nog steeds in Z-volgorde. Delphi-voorbeeldcode regel voor regel overzetten houdt indices 1 tot 4 aan, wat elke hoek één plaats opschuift en de laatste voorbij het einde van de array schrijft

De quads teruglezen

De snelste check dat een markup-annotatie goed is aangekomen, is hem door dezelfde API teruglezen. Pdf.Annotation[Index] vult AttachmentPointSets met elke quad die op de annotatie staat, en HasAttachmentPoints is True zodra er minstens één is:

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;

Voor de enkele highlight van eerder is de verwachte regel annot 0 quad 0: TL (50.0, 700.0) BR (250.0, 680.0); een Y linksboven lager dan de Y rechtsonder betekent dat de hoeken ondersteboven naar binnen gingen. De quads reizen ook met de annotatie mee wanneer u markup met andere tools uitwisselt: het attribuut coords in XFDF bevat ze allemaal, acht getallen per quad, zoals beschreven in het XFDF-export- en importartikel. Open daarna het opgeslagen bestand in een tweede viewer en controleer dat de kleur op de glyphs zit en niet ernaast, want een viewer die zijn eigen appearance uit QuadPoints bouwt is degene die een verkeerde hoekvolgorde aan het licht brengt

Het annotatierecord, de multi-quad-array en de telling-bewuste writer die door dit artikel lopen, worden geleverd in de PDFium Component for Delphi, C++Builder and Lazarus, waar de volledige annotatie-API-referentie naast de tekstzoek- en extractie-aanroepen staat waarop deze voorbeelden steunen