Article technique

Annotations de texte avec QuadPoints PDFium en Delphi

Une annotation de surbrillance que FPDFPage_CreateAnnot vient de renvoyer rapporte FPDFAnnot_CountAttachmentPoints = 0, et FPDFAnnot_SetAttachmentPoints(Annot, 0, Quad) renvoie 0 face à elle quelles que soient les coordonnées que vous passez. Les coordonnées ne sont pas le problème. L'index 0 signifie « remplacer le quad numéro 0 existant », une annotation neuve n'a aucun quad, et l'appel qui crée une case est FPDFAnnot_AppendAttachmentPoints

Cela tient en un paragraphe, et pourtant on y perd des heures facilement, parce que la réaction naturelle face à un retour faux est de se méfier de la géométrie. On échange les coins, on retourne l'axe Y, on convertit vers l'espace périphérique et retour. Rien de tout cela ne change le résultat. Ce qui suit couvre ce que les quads doivent contenir d'après l'ISO 32000-1, comment les écrire via l'API du composant et via les fonctions C brutes, les sélections multi-lignes, et un piège d'indexation qui diffère entre Delphi, Free Pascal et C++Builder. C'est le compagnon côté création de l'article sur la lecture et la revue des annotations existantes, qui parcourt les mêmes structures dans l'autre sens

Ce que signifient les QuadPoints dans ISO 32000-1 §12.5.6.10

QuadPoints est une entrée requise sur les quatre sous-types de balisage de texte, Highlight, Underline, Squiggly et StrikeOut : un tableau de 8×n nombres donnant n quadrilatères en espace utilisateur par défaut, où chaque quadrilatère englobe un mot ou un groupe de mots contigus du texte sous l'annotation. L'annotation porte toujours un Rect, que toute annotation exige, mais pour les sous-types de balisage ce sont les quads qui disent quels glyphes sont marqués et Rect ne fait que les borner. Des quadrilatères plutôt que des rectangles, parce que le texte peut être pivoté ou incliné sur la page ; chaque coin est donc stocké comme un point indépendant : x1 y1 x2 y2 x3 y3 x4 y4

L'ordre des coins est l'endroit où le texte de la spécification et les fichiers en circulation se séparent. Le §12.5.6.10 dit que les quatre sommets sont donnés dans le sens antihoraire, et ajoute que le texte est orienté par rapport à l'arête qui va de (x1, y1) à (x2, y2). Acrobat, et la longue lignée d'outils construits pour lire ce qu'écrit Acrobat, utilisent plutôt un motif en Z : point 1 en haut à gauche, point 2 en haut à droite, point 3 en bas à gauche, point 4 en bas à droite. Cette disposition honore quand même la phrase d'orientation, puisque l'arête 1–2 court le long du haut du texte, mais ce n'est pas un tour antihoraire de la forme. Écrivez l'ordre Z. Une liste littéralement antihoraire (haut gauche, bas gauche, bas droite, haut droite) se défend sur le papier, mais un lecteur qui parcourt les points en Z obtient haut gauche, bas gauche, haut droite, bas droite, et ces arêtes se croisent en nœud papillon

Toutes les coordonnées sont des coordonnées de page en points, origine en bas à gauche de la page, Y croissant vers le haut. Une ligne de texte près du haut d'une page A4 a donc des Y autour de 700 à 800, et son bord supérieur porte le Y le plus grand. La spécification donne aussi à un flux d'apparence (AP) la priorité sur les QuadPoints quand les deux sont présents, donc les quads comptent surtout pour les lecteurs qui génèrent eux-mêmes le balisage

Diagramme de géométrie des QuadPoints en coordonnées de page PDF montrant la numérotation des coins en ordre Z — TL, TR, BL, BR — utilisée par les annotations de balisage de texte PDFium
PDFium attend des QuadPoints en ordre Z, de haut gauche vers haut droite puis de bas gauche vers bas droite, en coordonnées de page où Y croît vers le haut

Pourquoi FPDFAnnot_SetAttachmentPoints renvoie-t-elle faux ?

FPDFAnnot_SetAttachmentPoints renvoie faux sur une annotation neuve parce qu'elle ne fait que remplacer un quad déjà existant. L'en-tête PDFium énonce le contrat directement : le quad_index « doit être dans le résultat de FPDFAnnot_CountAttachmentPoints() ». Toute annotation créée par FPDFPage_CreateAnnot démarre avec un compte de zéro, donc il n'existe pas d'index 0 à remplacer. FPDFAnnot_AppendAttachmentPoints ajoute une case et augmente le compte de un ; après quoi l'index 0 existe et Set l'accepte. Les deux fonctions sont marquées expérimentales dans les en-têtes PDFium, et toutes deux élargissent aussi la boîte englobante d'un flux d'apparence existant quand le nouveau quad dépasse l'ancien

Le composant PDFium expose tous les points d'entrée FPDFAnnot_* dans PDFium.pas, et l'enregistrement FS_QUADPOINTSF ainsi que l'alias size_t vivent dans FPdfView.pas. Si vous tenez vous-même un handle d'annotation, aiguillez sur le compte avant chaque écriture :

uses
  SysUtils, PDFium, FPdfView;

// Écrit Quad à QuadIndex sur l'annotation AnnotIndex de la page active :
// remplace la case si elle existe, sinon en ajoute une nouvelle
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;

Un second piège se cache dans la même famille de fonctions. FPDFAnnot_CountAttachmentPoints renvoie un size_t, donc non signé, et le familier for I := 0 to Count - 1 sur une annotation sans quad calcule 0 − 1 en arithmétique non signée et boucle vers la plus grande valeur possible. Testez Count > 0 avant toute boucle sur les quads, ou convertissez d'abord vers un type signé. Le balisage venu d'autres outils arrive presque toujours avec au moins un quad. Une annotation fraîchement créée arrive avec zéro

Créer une surbrillance avec TPdf.CreateAnnotation

Avec l'API du composant, vous ne choisissez jamais entre Append et Set. TPdf.CreateAnnotation et TPdf.SetAnnotation regardent tous deux combien de quads l'annotation porte déjà, remplacent les cases qui existent et ajoutent le reste, si bien que le chemin de création ajoute et le chemin de mise à jour remplace. Ce que vous fournissez est un enregistrement TPdfAnnotation avec Subtype, la couleur, le quad et un Rectangle

Deux détails de l'enregistrement comptent ici. Initialisez l'enregistrement avec Default(TPdfAnnotation). L'enregistrement porte des chaînes et des tableaux dynamiques, et un FillChar sur un enregistrement qui porte déjà une chaîne la fuit simplement, donc Default est la meilleure habitude pour chaque enregistrement que vous réutilisez. Et remplissez toujours Rectangle : le composant l'écrit comme Rect de l'annotation à chaque création et mise à jour, donc un enregistrement à zéro produit un Rect de [0 0 0 0] même quand les quads sont justes. CreateAnnotation travaille sur la page active, que AddPage définit pour une nouvelle page et PageNumber pour un document existant, et il lève 'Unsupported annotation subtype' quand PDFium ne peut pas créer le sous-type demandé

var
  Pdf: TPdf;
  A: TPdfAnnotation;
begin
  Pdf := TPdf.Create(nil);
  try
    Pdf.CreateDocument;
    Pdf.AddPage(0, 595, 842);                // A4, devient la page active

    A := Default(TPdfAnnotation);
    A.Subtype := anHighlight;
    A.HasColor := True;
    A.Color := clYellow;
    A.ColorAlpha := $80;                     // l'alpha passe avec la couleur
    A.HasAttachmentPoints := True;
    A.AttachmentPoints[1].X := 50;  A.AttachmentPoints[1].Y := 700;  // haut gauche
    A.AttachmentPoints[2].X := 250; A.AttachmentPoints[2].Y := 700;  // haut droite
    A.AttachmentPoints[3].X := 50;  A.AttachmentPoints[3].Y := 680;  // bas gauche
    A.AttachmentPoints[4].X := 250; A.AttachmentPoints[4].Y := 680;  // bas droite
    A.Rectangle.Left := 50;   A.Rectangle.Top := 700;                // englobe le 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;

Changer de décoration coûte une ligne. anUnderline, anStrikeout et anSquiggly prennent l'enregistrement identique, quads compris ; ISO 32000-1 décrit les quatre ensemble, et ils ne diffèrent que par la façon dont la zone du quad est peinte. Les sous-types hors de cette famille, comme anSquare, anCircle et anText, se positionnent depuis Rectangle seul ; laissez HasAttachmentPoints à False et AttachmentPointSets vide pour eux, et aucun quad n'est écrit

Sélections multi-lignes : une annotation, plusieurs quads

Une sélection qui s'étire sur trois lignes demande trois quads, un par ligne, parce qu'un seul quadrilatère couvrant les trois peindrait aussi la fin droite de la ligne un et le début gauche de la ligne trois. TPdfAnnotation porte chaque quad dans AttachmentPointSets, un tableau dynamique de TQuadrilateralPoint ; le champ unique AttachmentPoints reste un alias de la première entrée. Quand AttachmentPointSets n'est pas vide, CreateAnnotation écrit toutes ses entrées dans l'ordre et le champ unique est ignoré

Vous pourriez plutôt créer une annotation par ligne. Le rendu est le même, mais un relecteur voit alors trois commentaires, trois popups et trois éléments à supprimer pour ce qui était une seule surbrillance. Mettez les lignes dans une seule annotation. La géométrie est facile à obtenir depuis une recherche, parce que TPdf.CreateDocumentSearch renvoie chaque correspondance avec un tableau Rectangles tenant un rectangle par suite de texte sur une ligne, déjà en coordonnées de page :

function QuadFromRect(const R: TPdfRectangle): TQuadrilateralPoint;
begin
  Result[1].X := R.Left;  Result[1].Y := R.Top;     // haut gauche
  Result[2].X := R.Right; Result[2].Y := R.Top;     // haut droite
  Result[3].X := R.Left;  Result[3].Y := R.Bottom;  // bas gauche
  Result[4].X := R.Right; Result[4].Y := R.Bottom;  // bas droite
end;

// Votre propre helper, hors de la bibliothèque : union des rectangles des lignes
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
  // Collectez toutes les correspondances avant de toucher à une page
  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;

Les rectangles de recherche sont alignés sur les axes, quatre nombres chacun, donc sur du texte pivoté le quad résultant couvre la boîte englobante de la suite de texte plutôt que de suivre l'inclinaison. Pour du texte horizontal droit, l'essentiel de ce qui est surligné, la boîte et la zone des glyphes coïncident. Si vous avez besoin d'une géométrie par caractère, le guide d'extraction de texte avec le composant PDFium couvre CharacterRectangle et les appels de page de texte associés, et l'article sur la mesure du texte et la coupure de mots montre comment calculer l'étendue des lignes d'un texte que vous allez générer

Surlignage multiligne construit à partir de trois quadrilatères ajoutés un par un à une seule annotation PDFium créée en Delphi
Une sélection couvrant trois lignes devient une annotation portant trois quadrilatères, construite par des appels AppendAttachmentPoints qui accroissent le nombre d'emplacements

Modifier une annotation de balisage existante passe par Pdf.Annotation[Index] := A, qui appelle SetAnnotation ; le sous-type dans l'enregistrement doit correspondre à celui stocké, sinon l'appel lève 'Incorrect annotation subtype'. Les quads sont réécrits index par index, et les entrées supplémentaires de AttachmentPointSets sont ajoutées. PDFium n'expose aucun appel qui retire un seul quad, donc passer de trois quads à deux laisse le troisième dans le fichier. Pour réduire une surbrillance, supprimez-la avec DeleteAnnotation et recréez-la avec le tableau plus court

AttachmentPoints compte à partir de 1, sauf en C++

TQuadrilateralPoint est déclaré comme array [1..4] of TPdfPoint, et la numérotation suit les numéros de coins de la spécification : l'élément 1 est (x1, y1), l'élément 4 est (x4, y4). Du code écrit de mémoire avec des habitudes en base 0 se trompe là-dessus d'une façon que le compilateur n'attrape pas toujours. Une boucle comme for I := 0 to 3 do A.AttachmentPoints[I] := ... compile aussi bien en Delphi qu'en Free Pascal, parce que l'index ne se connaît qu'à l'exécution. Avec le contrôle de bornes coupé, qui est le défaut des projets Delphi, l'écriture pour l'index 0 atterrit sur les octets juste devant le tableau, dans les champs d'enregistrement précédents, et le quad garde lui un coin à zéro. Rien ne lève

Un index constant est une autre affaire. Le compilateur peut le comparer aux bornes déclarées avant que quoi que ce soit ne tourne, et fpc, pour ne citer que lui, rejette un AttachmentPoints[0] littéral avec une erreur de bornes. L'index calculé est la forme qui passe. Compilez du code d'annotation au moins une fois avec {$R+} en Delphi, ou via fpc, avant de lui faire confiance ; avec le contrôle de bornes activé, la boucle d'exécution ci-dessus lève ERangeError à l'index 0

C++Builder retourne la règle. Le PDFium.hpp généré déclare TQuadrilateralPoint comme System::StaticArray<TPdfPoint, 4>, et un tableau statique C++ démarre à zéro quelle qu'ait été la borne inférieure Pascal. En C++, les coins sont donc AttachmentPoints[0] à AttachmentPoints[3], toujours en ordre Z. Porter du code d'exemple Delphi ligne par ligne garde les index 1 à 4, ce qui décale chaque coin de un et écrit le dernier au-delà de la fin du tableau

Relire les quads

Le contrôle le plus rapide qu'une annotation de balisage s'est bien posée est de la relire via la même API. Pdf.Annotation[Index] remplit AttachmentPointSets avec chaque quad stocké sur l'annotation, et HasAttachmentPoints est True quand il y en a au moins un :

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;

Pour la surbrillance unique créée plus tôt, la ligne attendue est annot 0 quad 0: TL (50.0, 700.0) BR (250.0, 680.0) ; un Y haut gauche inférieur au Y bas droite signifie que les coins sont entrés à l'envers. Les quads voyagent aussi avec l'annotation quand vous échangez du balisage avec d'autres outils : l'attribut coords en XFDF les tient tous, huit nombres par quad, comme le décrit l'article sur l'export et l'import XFDF. Après quoi, ouvrez le fichier sauvegardé dans un second lecteur et vérifiez que la couleur couvre les glyphes et non le voisinage, parce qu'un lecteur qui construit sa propre apparence depuis les QuadPoints est justement celui qui expose un mauvais ordre de coins

L'enregistrement d'annotation, le tableau multi-quads et l'écrivain conscient du compte utilisés tout au long de cet article sont livrés dans le PDFium Component pour Delphi, C++Builder et Lazarus, où la référence complète de l'API d'annotation se trouve à côté des appels de recherche et d'extraction de texte dont ces exemples dépendent