Artigo Técnico

Anotações de marcação de texto com QuadPoints no PDFium

Uma anotação de realce que FPDFPage_CreateAnnot devolveu há um instante reporta FPDFAnnot_CountAttachmentPoints = 0, e FPDFAnnot_SetAttachmentPoints(Annot, 0, Quad) devolve 0 contra ela, com as coordenadas que você passar. As coordenadas não são o problema. O índice 0 significa "substituir o quadrilátero 0 existente", uma anotação nova não tem quadrilátero algum, e a chamada que cria uma posição é FPDFAnnot_AppendAttachmentPoints

Isso cabe em um parágrafo, mas é fácil perder horas com isso, porque a reação natural a um devolve-falso é desconfiar da geometria. A gente troca os cantos de lugar, inverte o eixo Y, converte para espaço de dispositivo e volta. Nada disso muda o resultado. O que segue cobre o que os quadriláteros devem conter de acordo com a ISO 32000-1, como escrevê-los pela API do componente e pelas funções C brutas, seleções de várias linhas e uma armadilha de indexação que muda entre Delphi, Free Pascal e C++Builder. É o complemento, do lado da criação, do artigo sobre ler e revisar anotações existentes, que percorre as mesmas estruturas na direção oposta

O que os QuadPoints significam na ISO 32000-1 §12.5.6.10

QuadPoints é uma entrada obrigatória nos quatro subtipos de marcação de texto, Highlight, Underline, Squiggly e StrikeOut: um array de 8×n números que descreve n quadriláteros no user space padrão, em que cada quadrilátero abrange uma palavra ou um grupo de palavras contíguas do texto sob a anotação. A anotação continua carregando um Rect, que toda anotação precisa ter, mas nos subtipos de marcação são os quadriláteros que dizem quais glifos estão marcados, e o Rect apenas os delimita. Quadriláteros em vez de retângulos porque o texto pode estar rotacionado ou cisalhado na página, então cada canto é guardado como um ponto independente: x1 y1 x2 y2 x3 y3 x4 y4

A ordem dos cantos é onde o texto da especificação e os arquivos em circulação se separam. A §12.5.6.10 diz que os quatro vértices vêm em sentido anti-horário, e acrescenta que o texto se orienta pela aresta de (x1, y1) a (x2, y2). O Acrobat, e a longa fila de ferramentas construídas para ler o que o Acrobat escreve, usam um padrão em Z: ponto 1 superior esquerdo, ponto 2 superior direito, ponto 3 inferior esquerdo, ponto 4 inferior direito. Esse arranjo continua respeitando a frase sobre orientação, já que a aresta 1–2 corre ao longo da parte de cima do texto, mas não é um passeio anti-horário ao redor da forma. Escreva em ordem Z. Uma lista literalmente anti-horária (superior esquerdo, inferior esquerdo, inferior direito, superior direito) se defende no papel, mas um leitor que percorre os pontos em Z lê superior esquerdo, inferior esquerdo, superior direito, inferior direito, e essas arestas se cruzam formando um laço

Todas as coordenadas são coordenadas de página em pontos, origem no canto inferior esquerdo da página, Y crescendo para cima. Uma linha de texto perto do topo de uma página A4 tem valores de Y em torno de 700 a 800, e a borda superior dela tem o maior Y. A especificação também dá a um appearance stream (AP) precedência sobre os QuadPoints quando ambos existem, então os quadriláteros importam mais para os visualizadores que geram a marcação por conta própria

Diagrama da geometria de QuadPoints em coordenadas de página de PDF mostrando a numeração de cantos em ordem Z, TL, TR, BL, BR, usada pelas anotações de marcação de texto do PDFium
O PDFium espera QuadPoints em ordem Z, do superior esquerdo ao superior direito e depois do inferior esquerdo ao inferior direito, em coordenadas de página em que Y cresce para cima

Por que FPDFAnnot_SetAttachmentPoints devolve false?

FPDFAnnot_SetAttachmentPoints devolve false em uma anotação nova porque ela só substitui um quadrilátero que já existe. O cabeçalho do PDFium declara o contrato diretamente: o quad_index "precisa estar dentro do resultado de FPDFAnnot_CountAttachmentPoints()". Toda anotação criada por FPDFPage_CreateAnnot começa com contagem zero, então não existe índice 0 a substituir. FPDFAnnot_AppendAttachmentPoints acrescenta uma posição e faz a contagem crescer um; depois disso, o índice 0 existe e o Set o aceita. As duas funções estão marcadas como experimentais nos cabeçalhos do PDFium, e as duas também alargam a caixa delimitadora de um appearance stream existente quando o novo quadrilátero alcança mais longe que o antigo

O PDFium Component expõe todos os pontos de entrada FPDFAnnot_* em PDFium.pas, e o registro FS_QUADPOINTSF e o alias size_t vivem em FPdfView.pas. Se você segura um handle de anotação por conta própria, consulte a contagem antes de cada escrita:

uses
  SysUtils, PDFium, FPdfView;

// Escreve Quad em QuadIndex na anotação AnnotIndex da página ativa:
// substitui a posição se ela existe e, senão, acrescenta uma nova
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;

Uma segunda armadilha mora na mesma família de funções. FPDFAnnot_CountAttachmentPoints devolve size_t, que é sem sinal, então o familiar for I := 0 to Count - 1 em uma anotação sem quadriláteros calcula 0 − 1 em aritmética sem sinal e dá a volta para o maior valor possível. Teste Count > 0 antes de entrar em qualquer loop sobre quadriláteros, ou faça cast para um tipo com sinal antes. Marcação vinda de outras ferramentas quase sempre chega com pelo menos um quadrilátero. Uma anotação recém-criada chega com zero

Criando um realce com TPdf.CreateAnnotation

Pela API do componente você nunca escolhe entre Append e Set. TPdf.CreateAnnotation e TPdf.SetAnnotation verificam quantos quadriláteros a anotação já tem, substituem as posições que existem e acrescentam o restante, então o caminho de criação acrescenta e o caminho de atualização substitui. O que você fornece é um registro TPdfAnnotation com Subtype, cor, o quadrilátero e um Rectangle

Dois detalhes do registro importam aqui. Inicialize o registro com Default(TPdfAnnotation). O registro contém strings e arrays dinâmicos, e um FillChar sobre um que já carrega uma string simplesmente vaza essa string, então Default é o hábito mais seguro para todo registro que você reutilizar. E sempre preencha o Rectangle: o componente o escreve como o Rect da anotação em toda criação e atualização, então um registro zerado produz um Rect [0 0 0 0] mesmo quando os quadriláteros estão certos. CreateAnnotation trabalha na página ativa, que AddPage define para uma página nova e PageNumber define para um documento existente, e ele lança 'Unsupported annotation subtype' quando o PDFium não consegue criar o subtipo pedido

var
  Pdf: TPdf;
  A: TPdfAnnotation;
begin
  Pdf := TPdf.Create(nil);
  try
    Pdf.CreateDocument;
    Pdf.AddPage(0, 595, 842);                // A4, torna-se a página ativa

    A := Default(TPdfAnnotation);
    A.Subtype := anHighlight;
    A.HasColor := True;
    A.Color := clYellow;
    A.ColorAlpha := $80;                     // o alpha é passado junto com a cor
    A.HasAttachmentPoints := True;
    A.AttachmentPoints[1].X := 50;  A.AttachmentPoints[1].Y := 700;  // superior esquerdo
    A.AttachmentPoints[2].X := 250; A.AttachmentPoints[2].Y := 700;  // superior direito
    A.AttachmentPoints[3].X := 50;  A.AttachmentPoints[3].Y := 680;  // inferior esquerdo
    A.AttachmentPoints[4].X := 250; A.AttachmentPoints[4].Y := 680;  // inferior direito
    A.Rectangle.Left := 50;   A.Rectangle.Top := 700;                // envolve o quadrilátero
    A.Rectangle.Right := 250; A.Rectangle.Bottom := 680;
    A.ContentsText := 'Highlighted region';
    Pdf.CreateAnnotation(A);

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

Trocar a decoração custa uma linha. anUnderline, anStrikeout e anSquiggly aceitam o registro idêntico, quadriláteros e tudo; a ISO 32000-1 descreve os quatro juntos, e eles só diferem em como a região do quadrilátero é pintada. Subtipos fora dessa família, como anSquare, anCircle e anText, se posicionam apenas pelo Rectangle; deixe HasAttachmentPoints em False e AttachmentPointSets vazio para eles, e nenhum quadrilátero é escrito

Seleções de várias linhas: uma anotação, vários quadriláteros

Uma seleção que quebra em três linhas precisa de três quadriláteros, um por linha, porque um único quadrilátero cobrindo as três também pintaria o fim da primeira linha e o começo da terceira. TPdfAnnotation carrega todos os quadriláteros em AttachmentPointSets, um array dinâmico de TQuadrilateralPoint; o campo único AttachmentPoints permanece como alias da primeira entrada. Quando AttachmentPointSets não está vazio, CreateAnnotation escreve todas as suas entradas em ordem e o campo único é ignorado

Você também poderia criar uma anotação por linha. Renderiza igual, mas um revisor então vê três comentários, três popups e três itens para apagar no lugar do que era um realce. Coloque as linhas em uma anotação. A geometria vem fácil de uma busca, porque TPdf.CreateDocumentSearch devolve cada ocorrência com um array Rectangles contendo um retângulo por trecho de texto na linha, já em coordenadas de página:

function QuadFromRect(const R: TPdfRectangle): TQuadrilateralPoint;
begin
  Result[1].X := R.Left;  Result[1].Y := R.Top;     // superior esquerdo
  Result[2].X := R.Right; Result[2].Y := R.Top;     // superior direito
  Result[3].X := R.Left;  Result[3].Y := R.Bottom;  // inferior esquerdo
  Result[4].X := R.Right; Result[4].Y := R.Bottom;  // inferior direito
end;

// Helper seu, fora da biblioteca: união dos retângulos de linha
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
  // Coleta todas as ocorrências antes de editar qualquer 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;

Os retângulos da busca são alinhados aos eixos, quatro números cada, então em texto rotacionado o quadrilátero resultante cobre a caixa delimitadora do trecho em vez de seguir a inclinação. Para texto horizontal reto, que é a maior parte do que se realça, a caixa e a área dos glifos coincidem. Se você precisa de geometria por caractere, o guia de extração de texto com o PDFium Component cobre CharacterRectangle e as chamadas relacionadas de text page, e o artigo de medição de texto e quebra de linha mostra como calcular extensões de linha para texto que você está prestes a gerar

Realce de várias linhas montado a partir de três quadriláteros acrescentados um a um a uma única anotação do PDFium criada no Delphi
Uma seleção que atravessa três linhas vira uma anotação com três quadriláteros, montada com chamadas de AppendAttachmentPoints que fazem a contagem de posições crescer

Editar uma anotação de marcação existente passa por Pdf.Annotation[Index] := A, que chama SetAnnotation; o subtipo no registro deve bater com o armazenado, ou a chamada lança 'Incorrect annotation subtype'. Os quadriláteros são reescritos índice por índice, e entradas extras em AttachmentPointSets são acrescentadas. O PDFium não expõe chamada que remova um único quadrilátero, então sair de três quadriláteros para dois deixa o terceiro no arquivo. Para encolher um realce, apague-o com DeleteAnnotation e crie-o de novo com o array menor

AttachmentPoints conta a partir de 1, exceto no C++

TQuadrilateralPoint é declarado como array [1..4] of TPdfPoint, e a numeração casa com os números dos cantos na especificação: o elemento 1 é (x1, y1), o elemento 4 é (x4, y4). Código escrito de memória, com hábito zero-based, erra isso de um jeito que o compilador nem sempre pega. Um loop como for I := 0 to 3 do A.AttachmentPoints[I] := ... compila tanto no Delphi quanto no Free Pascal, porque o índice só é conhecido em tempo de execução. Com a verificação de faixa desligada, que é o padrão de projeto do Delphi, a escrita no índice 0 cai nos bytes logo antes do array, dentro dos campos do registro anterior, e o quadrilátero em si fica com um canto zero. Nada lança erro

Índice constante é outro bicho. O compilador pode compará-lo com os limites declarados antes de qualquer coisa rodar, e o fpc, por exemplo, rejeita um AttachmentPoints[0] literal com erro de faixa. A forma computada é a que escapa. Compile o código de anotações ao menos uma vez com {$R+} no Delphi, ou pelo fpc, antes de confiar nele; com a verificação de faixa ligada, o loop de tempo de execução acima lança ERangeError no índice 0

O C++Builder inverte a regra. O PDFium.hpp gerado declara TQuadrilateralPoint como System::StaticArray<TPdfPoint, 4>, e um array estático de C++ começa do zero, fosse qual fosse o limite inferior Pascal. No C++ os cantos são, portanto, AttachmentPoints[0] a AttachmentPoints[3], ainda em ordem Z. Portar código de exemplo Delphi linha a linha mantém os índices 1 a 4, o que desloca cada canto em um e escreve o último além do fim do array

Lendo os quadriláteros de volta

A conferência mais rápida de que uma anotação de marcação aterrissou certa é lê-la de volta pela mesma API. Pdf.Annotation[Index] enche AttachmentPointSets com todo quadrilátero guardado na anotação, e HasAttachmentPoints é True quando há pelo menos um:

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 o realce único criado antes, a linha esperada é annot 0 quad 0: TL (50.0, 700.0) BR (250.0, 680.0); um Y superior esquerdo menor que o Y inferior direito significa que os cantos entraram de cabeça para baixo. Os quadriláteros também viajam com a anotação quando você troca marcação com outras ferramentas: o atributo coords no XFDF guarda todos eles, oito números por quadrilátero, como descrito em o artigo de exportação e importação de XFDF. Depois disso, abra o arquivo salvo em um segundo visualizador e confira se a cor cai sobre os glifos e não ao lado deles, porque um visualizador que constrói a própria aparência a partir dos QuadPoints é justamente o que expõe uma ordem de cantos errada

O registro de anotação, o array de vários quadriláteros e o escritor ciente da contagem usados ao longo deste artigo vêm no PDFium Component para Delphi, C++Builder e Lazarus, onde a referência completa da API de anotações fica ao lado das chamadas de busca e extração de texto de que esses exemplos dependem