Artículo técnico

Anotaciones de texto con QuadPoints de PDFium en Delphi

Una anotación de resaltado que FPDFPage_CreateAnnot devolvió hace un momento reporta FPDFAnnot_CountAttachmentPoints = 0, y FPDFAnnot_SetAttachmentPoints(Annot, 0, Quad) devuelve 0 contra ella, pases las coordenadas que pases. Las coordenadas no son el problema. El índice 0 significa "reemplaza el quad número 0 existente", una anotación nueva no tiene ningún quad, y la llamada que crea un hueco es FPDFAnnot_AppendAttachmentPoints

Eso cabe en un párrafo, y aun así es fácil perder horas con ello, porque la reacción natural a un retorno falso es desconfiar de la geometría. La gente transpone esquinas, voltea el eje Y, convierte a espacio de dispositivo y de vuelta. Nada de eso cambia el resultado. Lo que sigue cubre qué deben contener los quads según ISO 32000-1, cómo escribirlos por la API del componente y por las funciones C en bruto, las selecciones multilínea, y una trampa de indexado que difiere entre Delphi, Free Pascal y C++Builder. Es el complemento del lado de creación del artículo sobre leer y revisar anotaciones existentes, que recorre las mismas estructuras en la dirección contraria

Qué significan los QuadPoints en ISO 32000-1 §12.5.6.10

QuadPoints es una entrada obligatoria en los cuatro subtipos de marcado de texto, Highlight, Underline, Squiggly y StrikeOut: un array de 8×n números que da n cuadriláteros en espacio de usuario por defecto, donde cada cuadrilátero abarca una palabra o grupo de palabras contiguas del texto bajo la anotación. La anotación sigue llevando un Rect, que toda anotación necesita, pero en los subtipos de marcado los quads dicen qué glifos están marcados y Rect solo los delimita. Se usan cuadriláteros en lugar de rectángulos porque el texto puede estar rotado o cizallado en la página, así que cada esquina se guarda como punto independiente: x1 y1 x2 y2 x3 y3 x4 y4

El orden de las esquinas es donde el texto de la especificación y los ficheros en circulación se separan. §12.5.6.10 dice que los cuatro vértices van en orden antihorario, y añade que el texto se orienta respecto a la arista de (x1, y1) a (x2, y2). Acrobat, y la larga estela de herramientas construidas para leer lo que escribe Acrobat, usan un patrón Z en su lugar: punto 1 arriba a la izquierda, punto 2 arriba a la derecha, punto 3 abajo a la izquierda, punto 4 abajo a la derecha. Esa disposición igualmente respeta la frase de la orientación, ya que la arista 1–2 corre por la parte superior del texto, pero no es un paseo antihorario alrededor de la forma. Escribe el orden Z. Una lista literalmente antihoraria (arriba izquierda, abajo izquierda, abajo derecha, arriba derecha) es defendible sobre el papel, pero un lector que recorre los puntos como una Z obtiene arriba-izquierda, abajo-izquierda, arriba-derecha, abajo-derecha, y esas aristas se cruzan en una pajarita

Todas las coordenadas son coordenadas de página en puntos, origen en la parte inferior izquierda de la página, Y creciendo hacia arriba. Una línea de texto cerca de la parte superior de una página A4 tiene por tanto valores de Y alrededor de 700 a 800, y su borde superior lleva la Y mayor. La especificación además da a un stream de apariencia (AP) precedencia sobre los QuadPoints cuando ambos están presentes, así que los quads importan más para los visores que generan el marcado ellos mismos

Diagrama de geometría de QuadPoints en coordenadas de página PDF mostrando la numeración de esquinas en orden Z: TL, TR, BL, BR usada por las anotaciones de marcado de texto de PDFium
PDFium espera QuadPoints en orden Z, de arriba-izquierda a arriba-derecha y luego de abajo-izquierda a abajo-derecha, en coordenadas de página donde Y crece hacia arriba

¿Por qué FPDFAnnot_SetAttachmentPoints devuelve falso?

FPDFAnnot_SetAttachmentPoints devuelve falso en una anotación nueva porque solo reemplaza un quad que ya exista. La cabecera de PDFium enuncia el contrato directamente: el quad_index "necesita estar dentro del resultado de FPDFAnnot_CountAttachmentPoints()". Toda anotación hecha por FPDFPage_CreateAnnot empieza con un conteo de cero, así que no hay índice 0 que reemplazar. FPDFAnnot_AppendAttachmentPoints añade un hueco y crece el conteo en uno; después de eso el índice 0 existe y Set lo aceptará. Ambas funciones están marcadas como experimentales en las cabeceras de PDFium, y ambas además ensanchan la caja envolvente de un stream de apariencia existente cuando el nuevo quad llega más lejos que el antiguo

El PDFium Component expone todos los puntos de entrada FPDFAnnot_* en PDFium.pas, y el registro FS_QUADPOINTSF y el alias size_t viven en FPdfView.pas. Si sostienes tú mismo un handle de anotación, enruta según el conteo antes de cada escritura:

uses
  SysUtils, PDFium, FPdfView;

// Escribe Quad en QuadIndex de la anotación AnnotIndex de la página activa:
// reemplaza el hueco si existe, si no, añade uno nuevo
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;

Una segunda trampa se sienta en la misma familia de funciones. FPDFAnnot_CountAttachmentPoints devuelve size_t, que es sin signo, así que el familiar for I := 0 to Count - 1 sobre una anotación sin quads calcula 0 − 1 en aritmética sin signo y da la vuelta al mayor valor posible. Comprueba Count > 0 antes de entrar en cualquier bucle sobre quads, o haz cast a un tipo con signo primero. El marcado de otras herramientas casi siempre llega con al menos un quad. Una anotación recién creada llega con cero

Crear un resaltado con TPdf.CreateAnnotation

Con la API del componente nunca eliges entre Append y Set. TPdf.CreateAnnotation y TPdf.SetAnnotation comprueban ambos cuántos quads ya contiene la anotación, reemplazan los huecos que existan y añaden el resto, así que el camino de creación añade y el de actualización reemplaza. Lo que suministras es un registro TPdfAnnotation con Subtype, color, el quad y un Rectangle

Dos detalles del registro importan aquí. Inicializa el registro con Default(TPdfAnnotation). El registro contiene strings y arrays dinámicos, y un FillChar sobre uno que ya lleva una string simplemente provoca un leak, así que Default es el hábito más seguro para cada registro que reutilices. Y rellena siempre Rectangle: el componente lo escribe como el Rect de la anotación en cada creación y actualización, así que un registro a ceros produce un Rect de [0 0 0 0] aunque los quads estén bien. CreateAnnotation trabaja sobre la página activa, que AddPage fija para una página nueva y PageNumber para un documento existente, y eleva 'Unsupported annotation subtype' cuando PDFium no puede crear el subtipo pedido

var
  Pdf: TPdf;
  A: TPdfAnnotation;
begin
  Pdf := TPdf.Create(nil);
  try
    Pdf.CreateDocument;
    Pdf.AddPage(0, 595, 842);                // A4, pasa a ser la página activa

    A := Default(TPdfAnnotation);
    A.Subtype := anHighlight;
    A.HasColor := True;
    A.Color := clYellow;
    A.ColorAlpha := $80;                     // el alpha se pasa junto con el color
    A.HasAttachmentPoints := True;
    A.AttachmentPoints[1].X := 50;  A.AttachmentPoints[1].Y := 700;  // arriba a la izquierda
    A.AttachmentPoints[2].X := 250; A.AttachmentPoints[2].Y := 700;  // arriba a la derecha
    A.AttachmentPoints[3].X := 50;  A.AttachmentPoints[3].Y := 680;  // abajo a la izquierda
    A.AttachmentPoints[4].X := 250; A.AttachmentPoints[4].Y := 680;  // abajo a la derecha
    A.Rectangle.Left := 50;   A.Rectangle.Top := 700;                // envuelve el 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;

Cambiar el tipo de decoración cuesta una línea. anUnderline, anStrikeout y anSquiggly toman el registro idéntico, quads incluidos; ISO 32000-1 describe los cuatro juntos, y solo difieren en cómo se pinta la región del quad. Los subtipos fuera de esa familia, como anSquare, anCircle y anText, se posicionan desde el Rectangle a solas; deja HasAttachmentPoints a False y AttachmentPointSets vacío para ellos, y no se escribirá ningún quad

Selecciones multilínea: una anotación, varios quads

Una selección que salta a lo largo de tres líneas necesita tres quads, uno por línea, porque un único cuadrilátero que abarcara las tres pintaría también el extremo derecho de la línea uno y el extremo izquierdo de la línea tres. TPdfAnnotation lleva cada quad en AttachmentPointSets, un array dinámico de TQuadrilateralPoint; el campo único AttachmentPoints sigue ahí como alias de la primera entrada. Cuando AttachmentPointSets no está vacío, CreateAnnotation escribe todas sus entradas en orden y el campo único se ignora

Podrías crear en cambio una anotación por línea. Se renderiza igual, pero quien revise verá tres comentarios, tres popups y tres elementos que borrar por lo que fue un solo resaltado. Pon las líneas en una anotación. La geometría sale fácil de una búsqueda, porque TPdf.CreateDocumentSearch devuelve cada coincidencia con un array Rectangles que lleva un rectángulo por tirada de texto en una línea, ya en coordenadas de página:

function QuadFromRect(const R: TPdfRectangle): TQuadrilateralPoint;
begin
  Result[1].X := R.Left;  Result[1].Y := R.Top;     // arriba a la izquierda
  Result[2].X := R.Right; Result[2].Y := R.Top;     // arriba a la derecha
  Result[3].X := R.Left;  Result[3].Y := R.Bottom;  // abajo a la izquierda
  Result[4].X := R.Right; Result[4].Y := R.Bottom;  // abajo a la derecha
end;

// Tu propio ayudante, no forma parte de la biblioteca: unión de los rectángulos de línea
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
  // Recoge todas las coincidencias antes de editar cualquier página
  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;

Los rectángulos de la búsqueda están alineados a los ejes, cuatro números cada uno, así que sobre texto rotado el quad resultante cubre la caja envolvente de la tirada en lugar de seguir la inclinación. Para texto horizontal recto, que es la mayor parte de lo que se resalta, la caja y el área de glifos coinciden. Si necesitas en su lugar geometría por carácter, la guía de extracción de texto con el PDFium Component cubre CharacterRectangle y las llamadas relacionadas de página de texto, y el artículo de medición de texto y word wrap muestra cómo calcular extensiones de línea para texto que vas a generar

Resaltado multilínea construido a partir de tres cuadriláteros añadidos uno a uno a una única anotación PDFium creada en Delphi
Una selección que abarca tres líneas se convierte en una anotación que lleva tres quads, construida con llamadas AppendAttachmentPoints que hacen crecer el conteo de huecos

Editar una anotación de marcado existente pasa por Pdf.Annotation[Index] := A, que llama a SetAnnotation; el subtipo del registro debe coincidir con el almacenado, o la llamada eleva 'Incorrect annotation subtype'. Los quads se reescriben índice a índice, y las entradas extra de AttachmentPointSets se añaden. PDFium no expone ninguna llamada que quite un solo quad, así que bajar de tres quads a dos deja el tercero en el fichero. Para encoger un resaltado, bórralo con DeleteAnnotation y créalo otra vez con el array más corto

AttachmentPoints cuenta desde 1, salvo en C++

TQuadrilateralPoint está declarado como array [1..4] of TPdfPoint, y la numeración casa con los números de esquina de la especificación: el elemento 1 es (x1, y1), el elemento 4 es (x4, y4). El código escrito de memoria con hábitos basados en cero se equivoca aquí de una forma que el compilador no siempre caza. Un bucle como for I := 0 to 3 do A.AttachmentPoints[I] := ... compila tanto en Delphi como en Free Pascal, porque el índice solo se conoce en tiempo de ejecución. Con la comprobación de rangos apagada, que es el valor por defecto de un proyecto Delphi, la escritura del índice 0 aterriza en los bytes justo delante del array, dentro de los campos del registro precedentes, y el quad en sí conserva una esquina a cero. Nada eleva una excepción

Un índice constante es otra historia. El compilador puede compararlo con los límites declarados antes de que nada corra, y fpc, por ejemplo, rechaza un AttachmentPoints[0] literal con un error de rango. La forma que se cuela es el índice calculado. Compila el código de anotaciones al menos una vez con {$R+} en Delphi, o con fpc, antes de fiarte de él; con la comprobación de rangos activada, el bucle en tiempo de ejecución de arriba eleva ERangeError en el índice 0

C++Builder da la vuelta a la regla. El PDFium.hpp generado declara TQuadrilateralPoint como System::StaticArray<TPdfPoint, 4>, y un array estático de C++ empieza en cero sea cual sea el límite inferior de Pascal. En C++ las esquinas son por tanto AttachmentPoints[0] a AttachmentPoints[3], siempre en orden Z. Portar código de ejemplo Delphi línea a línea conserva los índices 1 a 4, lo que desplaza cada esquina en uno y escribe la última más allá del final del array

Leer los quads de vuelta

La comprobación más rápida de que una anotación de marcado aterrizó bien es leerla de vuelta por la misma API. Pdf.Annotation[Index] rellena AttachmentPointSets con cada quad guardado en la anotación, y HasAttachmentPoints es True cuando hay al menos uno:

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;

Para el único resaltado creado antes, la línea esperada es annot 0 quad 0: TL (50.0, 700.0) BR (250.0, 680.0); una Y de arriba-izquierda menor que la Y de abajo-derecha significa que las esquinas entraron del revés. Los quads también viajan con la anotación cuando intercambias marcado con otras herramientas: el atributo coords de XFDF los guarda todos, ocho números por quad, como describe el artículo de exportación e importación XFDF. Después de eso, abre el fichero guardado en un segundo visor y comprueba que el color cae sobre los glifos y no al lado, porque un visor que construye su propia apariencia desde los QuadPoints es el que destapa un orden de esquinas malo

El registro de anotación, el array multi-quad y el escritor consciente del conteo usados a lo largo de este artículo vienen en el PDFium Component para Delphi, C++Builder y Lazarus, donde la referencia completa de la API de anotaciones está al lado de las llamadas de búsqueda y extracción de texto de las que se fían estos ejemplos