Artículo técnico

Marcado de texto con QuadPoints de PDFium en Delphi

Una anotación de resaltado que FPDFPage_CreateAnnot acaba de devolver reporta FPDFAnnot_CountAttachmentPoints = 0, y FPDFAnnot_SetAttachmentPoints(Annot, 0, Quad) devuelve 0 contra ella sin importar qué coordenadas le pase. Las coordenadas no son el problema. El índice 0 significa "reemplazar el quad existente número 0", una anotación nueva no tiene ningún quad, y la llamada que crea un slot es FPDFAnnot_AppendAttachmentPoints

Eso cabe en un párrafo y, aun así, es fácil perder horas con ello, porque la reacción natural ante un retorno falso es desconfiar de la geometría. La gente transpone las esquinas, invierte 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 a través de la API del componente y de las funciones C crudas, las selecciones multilínea y una trampa de indexación que difiere entre Delphi, Free Pascal y C++Builder. Es el complemento del lado de la creación de el artículo sobre leer y revisar anotaciones existentes, que recorre las mismas estructuras en la dirección opuesta

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 arreglo de 8×n números que da n cuadriláteros en el espacio de usuario por defecto, donde cada cuadrilátero abarca una palabra o un grupo de palabras contiguas del texto bajo la anotación. La anotación sigue llevando un Rect, que toda anotación necesita, pero para los subtipos de marcado los quads dicen qué glifos están marcados y Rect solo los acota. Se usan cuadriláteros en lugar de rectángulos porque el texto puede estar rotado o sesgado en la página, así que cada esquina se guarda como un 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 archivos en circulación se separan. §12.5.6.10 dice que los cuatro vértices se dan en orden antihorario, y agrega que el texto se orienta respecto al borde que va de (x1, y1) a (x2, y2). Acrobat, y la larga fila de herramientas construidas para leer lo que Acrobat escribe, usan en cambio un patrón en Z: punto 1 superior izquierda, punto 2 superior derecha, punto 3 inferior izquierda, punto 4 inferior derecha. Esa disposición igual respeta la frase de la orientación, ya que el borde 1–2 corre a lo largo de la parte superior del texto, pero no es un recorrido antihorario alrededor de la forma. Escriba el orden Z. Una lista literalmente antihoraria (superior izquierda, inferior izquierda, inferior derecha, superior derecha) es defendible en el papel, pero un lector que recorre los puntos como una Z obtiene superior izquierda, inferior izquierda, superior derecha, inferior derecha, y esos bordes se cruzan formando un moño

Todas las coordenadas son coordenadas de página en puntos, con el origen en la esquina inferior izquierda de la página y Y creciendo hacia arriba. Una línea de texto cerca del tope de una página A4 tiene por lo tanto valores de Y de alrededor de 700 a 800, y su borde superior tiene la Y mayor. La especificación también da precedencia a un appearance stream (AP) sobre QuadPoints cuando ambos están presentes, así que los quads importan sobre todo para los visores que generan el marcado por su cuenta

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 superior izquierda a superior derecha y luego de inferior izquierda a inferior 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 existe. El header de PDFium enuncia el contrato directamente: el quad_index "needs to be within the result of FPDFAnnot_CountAttachmentPoints()". Toda anotación hecha por FPDFPage_CreateAnnot arranca con un conteo de cero, así que no hay índice 0 que reemplazar. FPDFAnnot_AppendAttachmentPoints agrega un slot y aumenta el conteo en uno; después de eso el índice 0 existe y Set lo acepta. Ambas funciones están marcadas como experimentales en los headers de PDFium, y ambas además ensanchan el cuadro delimitador de un appearance stream existente cuando el quad nuevo llega más lejos que el anterior

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 usted maneja un handle de anotación por su cuenta, decida 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 slot si existe; si no, agrega 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 está en la misma familia de funciones. FPDFAnnot_CountAttachmentPoints devuelve size_t, que es sin signo, así que el habitual for I := 0 to Count - 1 sobre una anotación sin quads calcula 0 − 1 en aritmética sin signo y da la vuelta hasta el valor más grande posible. Pruebe Count > 0 antes de entrar a cualquier bucle sobre quads, o convierta primero a un tipo con signo. El marcado que viene 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 usted nunca elige entre Append y Set. TPdf.CreateAnnotation y TPdf.SetAnnotation revisan ambas cuántos quads tiene ya la anotación, reemplazan los slots que existen y agregan el resto, así que la ruta de creación agrega y la ruta de actualización reemplaza. Lo que usted entrega es un registro TPdfAnnotation con Subtype, color, el quad y un Rectangle

Dos detalles del registro importan aquí. Inicialice el registro con Default(TPdfAnnotation). El registro contiene strings y arreglos dinámicos, y un FillChar sobre uno que ya lleva un string simplemente lo fuga, así que Default es el hábito más seguro para cualquier registro que reutilice. Y llene siempre Rectangle: el componente lo escribe como el Rect de la anotación en cada creación y actualización, así que un registro en ceros produce un Rect de [0 0 0 0] aun cuando los quads estén correctos. CreateAnnotation trabaja sobre la página activa, que AddPage fija para una página nueva y PageNumber fija para un documento existente, y lanza '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, se vuelve la página activa

    A := Default(TPdfAnnotation);
    A.Subtype := anHighlight;
    A.HasColor := True;
    A.Color := clYellow;
    A.ColorAlpha := $80;                     // el alfa se pasa junto con el color
    A.HasAttachmentPoints := True;
    A.AttachmentPoints[1].X := 50;  A.AttachmentPoints[1].Y := 700;  // superior izquierda
    A.AttachmentPoints[2].X := 250; A.AttachmentPoints[2].Y := 700;  // superior derecha
    A.AttachmentPoints[3].X := 50;  A.AttachmentPoints[3].Y := 680;  // inferior izquierda
    A.AttachmentPoints[4].X := 250; A.AttachmentPoints[4].Y := 680;  // inferior derecha
    A.Rectangle.Left := 50;   A.Rectangle.Top := 700;                // encierra 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 la 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 difieren solo en cómo se pinta la región del quad. Los subtipos fuera de esa familia, como anSquare, anCircle y anText, se posicionan solo a partir de Rectangle; deje HasAttachmentPoints en False y AttachmentPointSets vacío para ellos, y no se escribe ningún quad

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

Una selección que se extiende por tres líneas necesita tres quads, uno por línea, porque un solo cuadrilátero que abarcara las tres también pintaría el extremo derecho de la línea uno y el extremo izquierdo de la línea tres. TPdfAnnotation lleva todos los quads en AttachmentPointSets, un arreglo dinámico de TQuadrilateralPoint; el campo único AttachmentPoints se mantiene 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ía en cambio crear una anotación por línea. Se renderiza igual, pero un revisor entonces ve tres comentarios, tres popups y tres elementos que borrar para lo que fue un solo resaltado. Ponga las líneas en una sola anotación. La geometría es fácil de obtener de una búsqueda, porque TPdf.CreateDocumentSearch devuelve cada coincidencia con un arreglo Rectangles que contiene un rectángulo por tramo 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;     // superior izquierda
  Result[2].X := R.Right; Result[2].Y := R.Top;     // superior derecha
  Result[3].X := R.Left;  Result[3].Y := R.Bottom;  // inferior izquierda
  Result[4].X := R.Right; Result[4].Y := R.Bottom;  // inferior derecha
end;

// Helper propio, no es 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
  // Reúna 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 búsqueda están alineados a los ejes, cuatro números cada uno, así que sobre texto rotado el quad resultante cubre el cuadro delimitador del tramo en lugar de seguir la inclinación. Para texto horizontal recto, que es la mayor parte de lo que se resalta, el cuadro y el área del glifo coinciden. Si en cambio necesita geometría por carácter, la guía de extracción de texto con el PDFium Component cubre CharacterRectangle y las llamadas de página de texto relacionadas, y el artículo sobre medición de texto y ajuste de línea muestra cómo calcular la extensión de las líneas para texto que está por generar

Resaltado multilínea construido a partir de tres cuadriláteros agregados uno por uno a una sola anotación de 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 agrandan el conteo de slots

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 lanza 'Incorrect annotation subtype'. Los quads se reescriben índice por índice, y las entradas extra de AttachmentPointSets se agregan al final. PDFium no expone ninguna llamada que elimine un solo quad, así que pasar de tres quads a dos deja el tercero en el archivo. Para achicar un resaltado, bórrelo con DeleteAnnotation y créelo de nuevo con el arreglo más corto

AttachmentPoints cuenta desde 1, salvo en C++

TQuadrilateralPoint se declara como array [1..4] of TPdfPoint, y la numeración coincide 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 de base cero se equivoca aquí de una manera que el compilador no siempre detecta. 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 verificación de rango apagada, que es el valor por defecto de un proyecto Delphi, la escritura del índice 0 cae en los bytes justo antes del arreglo, dentro de los campos anteriores del registro, y el propio quad se queda con una esquina en cero. Nada lanza excepción

Un índice constante es otro asunto. 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. El índice calculado es la forma que se cuela. Compile el código de anotaciones al menos una vez con {$R+} en Delphi, o con fpc, antes de confiar en él; con la verificación de rango encendida, el bucle en tiempo de ejecución de arriba lanza ERangeError en el índice 0

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

Leer los quads de vuelta

La comprobación más rápida de que una anotación de marcado quedó bien es leerla de vuelta por la misma API. Pdf.Annotation[Index] llena AttachmentPointSets con cada quad almacenado 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 resaltado único creado antes, la línea esperada es annot 0 quad 0: TL (50.0, 700.0) BR (250.0, 680.0); una Y superior izquierda menor que la Y inferior derecha significa que las esquinas entraron al revés. Los quads también viajan con la anotación cuando intercambia marcado con otras herramientas: el atributo coords de XFDF los contiene todos, ocho números por quad, como se describe en el artículo sobre exportar e importar XFDF. Después de eso, abra el archivo guardado en un segundo visor y compruebe que el color caiga sobre los glifos y no al lado, ya que un visor que construye su propia apariencia a partir de QuadPoints es el que deja en evidencia un mal orden de esquinas

El registro de anotación, el arreglo 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á junto a las llamadas de búsqueda y extracción de texto en que se apoyan estos ejemplos