Техническая статья

Текстовые аннотации разметки через QuadPoints в PDFium

Аннотация выделения, которую FPDFPage_CreateAnnot вернула мгновение назад, сообщает FPDFAnnot_CountAttachmentPoints = 0, и FPDFAnnot_SetAttachmentPoints(Annot, 0, Quad) возвращает на ней 0, какие бы координаты вы ни передавали. Координаты не при чем. Индекс 0 означает «заменить существующий квад номер 0», у новой аннотации квадов нет вообще, а вызов, создающий слот, — это FPDFAnnot_AppendAttachmentPoints

Это умещается в один абзац, но на этом легко потерять часы, потому что естественная реакция на false — подозревать геометрию. Люди меняют местами углы, переворачивают ось Y, переводят координаты в устройство и обратно. Ничто из этого не меняет результат. Далее — что должны содержать квады по ISO 32000-1, как записывать их через API компонента и через сырые C-функции, многострочные выделения и ловушка с индексацией, которая различается между Delphi, Free Pascal и C++Builder. Это создание — компаньон к статье о чтении и проверке существующих аннотаций, которая проходит те же структуры в обратном направлении

Что означают QuadPoints в ISO 32000-1 §12.5.6.10

QuadPoints — обязательная запись четырех подтипов текстовой разметки, Highlight, Underline, Squiggly и StrikeOut: массив из 8×n чисел, задающий n четырехугольников в пользовательском пространстве по умолчанию, где каждый четырехугольник охватывает слово или группу смежных слов в тексте под аннотацией. Аннотация по-прежнему несет Rect, который нужен каждой аннотации, но для подтипов разметки квады говорят, какие глифы помечены, а Rect лишь ограничивает их. Четырехугольники вместо прямоугольников — потому что текст может быть повернут или скошен на странице, так что каждый угол хранится как независимая точка: x1 y1 x2 y2 x3 y3 x4 y4

Порядок углов — то место, где текст спецификации и файлы в обращении расходятся. §12.5.6.10 говорит, что четыре вершины задаются в порядке против часовой стрелки, и добавляет, что текст ориентирован относительно ребра из (x1, y1) в (x2, y2). Acrobat и длинная череда инструментов, построенных читать то, что пишет Acrobat, используют вместо этого Z-шаблон: точка 1 — верхний левый, точка 2 — верхний правый, точка 3 — нижний левый, точка 4 — нижний правый. Такая раскладка все еще соблюдает фразу про ориентацию, поскольку ребро 1–2 идет вдоль верха текста, но это не обход фигуры против часовой стрелки. Пишите Z-порядок. Буквальный список против часовой (верхний левый, нижний левый, нижний правый, верхний правый) защищаем на бумаге, но читатель, идущий по точкам как по Z, получает верхний левый, нижний левый, верхний правый, нижний правый — и эти ребра перекрещиваются в бабочку

Все координаты — координаты страницы в пунктах, начало в левом нижнем углу страницы, Y растет вверх. Строка текста у верха страницы A4 имеет, таким образом, значения Y порядка 700–800, и ее верхнее ребро несет больший Y. Спецификация также ставит поток появления (AP) выше QuadPoints, когда присутствуют оба, так что квады важнее всего для просмотрщиков, генерирующих разметку сами

Диаграмма геометрии QuadPoints в координатах страницы PDF: нумерация углов в Z-порядке TL, TR, BL, BR, используемая текстовыми разметочными аннотациями PDFium
PDFium ждёт QuadPoints в Z-порядке — слева направо по верху, затем слева направо по низу, — в координатах страницы, где Y растёт вверх

Почему FPDFAnnot_SetAttachmentPoints возвращает false?

FPDFAnnot_SetAttachmentPoints возвращает false на новой аннотации, потому что она только заменяет квад, который уже существует. Заголовок PDFium формулирует контракт прямо: quad_index «должен быть в пределах результата FPDFAnnot_CountAttachmentPoints()». Каждая аннотация, созданная FPDFPage_CreateAnnot, стартует со счетчиком ноль, так что индекса 0 для замены нет. FPDFAnnot_AppendAttachmentPoints добавляет слот и наращивает счетчик на единицу; после этого индекс 0 существует, и Set его примет. Обе функции помечены как experimental в заголовках PDFium, и обе расширяют ограничивающую рамку существующего потока появления, когда новый квад простирается дальше старого

Компонент PDFium выставляет наружу все точки входа FPDFAnnot_* в PDFium.pas, а запись FS_QUADPOINTSF и псевдоним size_t живут в FPdfView.pas. Если вы держите хэндл аннотации сами, разветвляйтесь по счетчику перед каждой записью:

uses
  SysUtils, PDFium, FPdfView;

// Записывает Quad по индексу QuadIndex в аннотацию AnnotIndex активной страницы:
// заменяет слот, если он существует, иначе добавляет новый
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;

Вторая ловушка сидит в том же семействе функций. FPDFAnnot_CountAttachmentPoints возвращает size_t, который беззнаковый, так что привычное for I := 0 to Count - 1 на аннотации без квадов вычисляет 0 − 1 в беззнаковой арифметике и заворачивает в наибольшее возможное значение. Проверяйте Count > 0 перед любым циклом по квадам или приводите к знаковому типу заранее. Разметка от других инструментов почти всегда приходит хотя бы с одним квадом. Свежесозданная аннотация приходит с нулем

Создание выделения с помощью TPdf.CreateAnnotation

С API компонента вы вообще не выбираете между Append и Set. TPdf.CreateAnnotation и TPdf.SetAnnotation оба проверяют, сколько квадов аннотация уже держит, заменяют существующие слоты и добавляют остальные, так что путь создания добавляет, а путь обновления заменяет. Вы подаете запись TPdfAnnotation с Subtype, цветом, квадом и Rectangle

Здесь важны две детали записи. Инициализируйте запись через Default(TPdfAnnotation). Запись держит строки и динамические массивы, и FillChar поверх той, что уже несет строку, просто утекает ее, так что Default — более безопасная привычка для каждой записи, которую вы переиспользуете. И всегда заполняйте Rectangle: компонент пишет его как Rect аннотации при каждом создании и обновлении, так что обнуленная запись даст Rect из [0 0 0 0], даже когда квады правильные. CreateAnnotation работает на активной странице, которую AddPage задает для новой страницы, а PageNumber — для существующего документа, и бросает 'Unsupported annotation subtype', когда PDFium не может создать запрошенный подтип

var
  Pdf: TPdf;
  A: TPdfAnnotation;
begin
  Pdf := TPdf.Create(nil);
  try
    Pdf.CreateDocument;
    Pdf.AddPage(0, 595, 842);                // A4, становится активной страницей

    A := Default(TPdfAnnotation);
    A.Subtype := anHighlight;
    A.HasColor := True;
    A.Color := clYellow;
    A.ColorAlpha := $80;                     // альфа передается вместе с цветом
    A.HasAttachmentPoints := True;
    A.AttachmentPoints[1].X := 50;  A.AttachmentPoints[1].Y := 700;  // верхний левый
    A.AttachmentPoints[2].X := 250; A.AttachmentPoints[2].Y := 700;  // верхний правый
    A.AttachmentPoints[3].X := 50;  A.AttachmentPoints[3].Y := 680;  // нижний левый
    A.AttachmentPoints[4].X := 250; A.AttachmentPoints[4].Y := 680;  // нижний правый
    A.Rectangle.Left := 50;   A.Rectangle.Top := 700;                // охватывает квад
    A.Rectangle.Right := 250; A.Rectangle.Bottom := 680;
    A.ContentsText := 'Highlighted region';
    Pdf.CreateAnnotation(A);

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

Смена оформления стоит одной строки. anUnderline, anStrikeout и anSquiggly берут идентичную запись, квады и все остальное; ISO 32000-1 описывает все четыре вместе, и различаются они лишь тем, как рисуется область квада. Подтипы вне этого семейства, такие как anSquare, anCircle и anText, позиционируются по одному Rectangle; оставьте для них HasAttachmentPoints в False и AttachmentPointSets пустым, и никакой квад не будет записан

Многострочные выделения: одна аннотация, несколько квадов

Выделение, заворачивающее на три строки, требует трех квадов, по одному на строку, потому что один четырехугольник, накрывающий все три, нарисовал бы и правый конец первой строки, и левый конец третьей. TPdfAnnotation несет все квады в AttachmentPointSets, динамическом массиве TQuadrilateralPoint; одиночное поле AttachmentPoints осталось как псевдоним первой записи. Когда AttachmentPointSets непустой, CreateAnnotation пишет все его записи по порядку, а одиночное поле игнорируется

Вместо этого можно создать по аннотации на строку. Отрисуется так же, но рецензент увидит три комментария, три попапа и три предмета удаления там, где было одно выделение. Кладите строки в одну аннотацию. Геометрию легко получить из поиска: TPdf.CreateDocumentSearch возвращает каждое совпадение с массивом Rectangles, где на каждую цепочку текста в строке приходится по прямоугольнику, уже в координатах страницы:

function QuadFromRect(const R: TPdfRectangle): TQuadrilateralPoint;
begin
  Result[1].X := R.Left;  Result[1].Y := R.Top;     // верхний левый
  Result[2].X := R.Right; Result[2].Y := R.Top;     // верхний правый
  Result[3].X := R.Left;  Result[3].Y := R.Bottom;  // нижний левый
  Result[4].X := R.Right; Result[4].Y := R.Bottom;  // нижний правый
end;

// Ваш собственный помощник, не часть библиотеки: объединение прямоугольников строк
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
  // Соберите все совпадения до правки любой страницы
  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;

Прямоугольники поиска выровнены по осям, по четыре числа каждый, так что на повернутом тексте получающийся квад накрывает ограничивающую рамку цепочки, а не следует за наклоном. Для прямого горизонтального текста — а это почти все, что подсвечивают, — рамка и область глифов совпадают. Если вам нужна геометрия по символам, руководство по извлечению текста с компонентом PDFium разбирает CharacterRectangle и соседние вызовы текстовых страниц, а статья об измерении текста и переносе слов показывает, как считать протяженности строк для текста, который вы собираетесь сгенерировать

Многострочная подсветка из трёх четырёхугольников, добавляемых по одному в единственную аннотацию PDFium, созданную в Delphi
Выделение через три строки становится одной аннотацией с тремя квадами, собранной вызовами AppendAttachmentPoints, наращивающими число слотов

Правка существующей разметки идет через Pdf.Annotation[Index] := A, что вызывает SetAnnotation; подтип в записи должен совпадать с сохраненным, иначе вызов бросает 'Incorrect annotation subtype'. Квады переписываются индекс за индексом, а лишние записи в AttachmentPointSets добавляются. PDFium не выставляет вызова, удаляющего одиночный квад, так что переход с трех квадов на два оставляет третий в файле. Чтобы уменьшить выделение, удалите его через DeleteAnnotation и создайте заново с более коротким массивом

AttachmentPoints считает с 1, кроме C++

TQuadrilateralPoint объявлен как array [1..4] of TPdfPoint, и нумерация совпадает с номерами углов в спецификации: элемент 1 — это (x1, y1), элемент 4 — это (x4, y4). Код, написанный по памяти с привычкой к нулю, ошибается так, что компилятор не всегда ловит. Цикл вроде for I := 0 to 3 do A.AttachmentPoints[I] := ... компилируется и в Delphi, и в Free Pascal, потому что индекс становится известен только во время выполнения. С выключенной проверкой диапазонов — а это умолчание проекта Delphi — запись для индекса 0 попадает на байты прямо перед массивом, внутри предшествующих полей записи, а сам квад остается с нулевым углом. Ничто не бросается

Константный индекс — другое дело. Компилятор может сверить его с объявленными границами до всякого запуска, и fpc, например, отвергает литеральный AttachmentPoints[0] ошибкой диапазона. Проскальзывает именно вычисляемый индекс. Соберите код аннотаций хотя бы раз с {$R+} в Delphi или через fpc, прежде чем ему доверять; с включенной проверкой диапазонов показанный выше цикл во время выполнения бросает ERangeError на индексе 0

C++Builder выворачивает правило. Сгенерированный PDFium.hpp объявляет TQuadrilateralPoint как System::StaticArray<TPdfPoint, 4>, а статический массив C++ начинается с нуля, какой ни была нижняя граница Паскаля. В C++ углы, следовательно, от AttachmentPoints[0] до AttachmentPoints[3], все еще в Z-порядке. Портирование образцов Delphi построчно сохраняет индексы 1–4, что сдвигает каждый угол на единицу и пишет последний за конец массива

Читаем квады обратно

Быстрейшая проверка, что разметка легла правильно, — прочитать ее обратно через тот же API. Pdf.Annotation[Index] заполняет AttachmentPointSets всеми квадами, сохраненными на аннотации, а HasAttachmentPoints равен True, когда есть хотя бы один:

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;

Для одиночного выделения, созданного ранее, ожидаемая строка — annot 0 quad 0: TL (50.0, 700.0) BR (250.0, 680.0); верхний левый Y ниже нижнего правого Y означает, что углы легли вверх ногами. Квады путешествуют вместе с аннотацией и при обмене разметкой с другими инструментами: атрибут coords в XFDF держит их все, по восемь чисел на квад, как описано в статье об экспорте и импорте XFDF. После этого откройте сохраненный файл во втором просмотрщике и проверьте, что цвет сидит на глифах, а не рядом с ними, поскольку плохой порядок углов выдаёт именно тот просмотрщик, который строит внешний вид сам из QuadPoints

Запись аннотации, массив квадов и учитывающий счетчик писатель, использованные в этой статье, поставляются в составе PDFium Component для Delphi, C++Builder и Lazarus, где полный справочник по API аннотаций лежит рядом с вызовами текстового поиска и извлечения, на которые опираются эти примеры