Artykuł techniczny

Adnotacje tekstowe za pomocą PDFium QuadPoints w Delphi

Adnotacja wyróżnienia, którą FPDFPage_CreateAnnot zwrócił przed chwilą, raportuje FPDFAnnot_CountAttachmentPoints = 0, a FPDFAnnot_SetAttachmentPoints(Annot, 0, Quad) zwraca na niej 0, cokolwiek za współrzędnych byś nie podał. Współrzędne nie są problemem. Indeks 0 znaczy "zastąp istniejący czworokąt numer 0", nowa adnotacja nie ma żadnych czworokątów, a wywołaniem, które tworzy slot, jest FPDFAnnot_AppendAttachmentPoints

Mieści się to w jednym akapicie, a jednak łatwo stracić na tym godziny, bo naturalną reakcją na fałszywy wynik jest nieufność wobec geometrii. Ludzie przestawiają rogi, odwracają oś Y, przeliczają współrzędne do przestrzeni urządzenia i z powrotem. Nic z tego nie zmienia rezultatu. Dalej opisuję, co muszą zawierać czworokąty według ISO 32000-1, jak zapisywać je przez API komponentu i przez surowe funkcje C, zaznaczenia wielowierszowe oraz pułapkę indeksowania, która różni się między Delphi, Free Pascalem i C++Builderem. To odpowiednik artykułu o odczytywaniu i recenzowaniu istniejących adnotacji prowadzony od strony tworzenia: tamten tekst przechodzi te same struktury w drugą stronę

Co oznaczają QuadPoints w ISO 32000-1 §12.5.6.10

QuadPoints to wymagany wpis czterech podtypów znaczników tekstu: Highlight, Underline, Squiggly i StrikeOut. To tablica 8×n liczb opisująca n czworokątów w domyślnej przestrzeni użytkownika, gdzie każdy czworokąt obejmuje słowo lub grupę sąsiadujących słów w tekście pod adnotacją. Adnotacja wciąż niesie Rect, którego potrzebuje każda adnotacja, ale dla podtypów znaczników to czworokąty mówią, które glify są zakreślone, a Rect je tylko ogrodza. Czworokąty zamiast prostokątów dlatego, że tekst na stronie może być obrócony lub ścięty — każdy róg jest więc przechowywany jako niezależny punkt: x1 y1 x2 y2 x3 y3 x4 y4

Kolejność rogów to miejsce, w którym tekst specyfikacji rozstaje się z plikami w obiegu. §12.5.6.10 mówi, że cztery wierzchołki podaje się w kolejności przeciwnej do ruchu wskazówek zegara, i dodaje, że tekst orientowany jest względem krawędzi od (x1, y1) do (x2, y2). Acrobat i długi rząd narzędzi zbudowanych po to, by czytać to, co zapisuje Acrobat, używają wzoru Z: punkt 1 lewy górny, punkt 2 prawy górny, punkt 3 lewy dolny, punkt 4 prawy dolny. Ten układ wciąż spełnia zdanie o orientacji, bo krawędź 1–2 biegnie wzdłuż góry tekstu, ale nie jest obiegiem przeciwnym do zegara wokół kształtu. Pisz w kolejności Z. Dosłowna lista przeciwna do zegara (lewy górny, lewy dolny, prawy dolny, prawy górny) jest do obrony na papierze, ale czytnik, który przechodzi punkty jako Z, dostanie lewy górny, lewy dolny, prawy górny, prawy dolny — a te krawędzie krzyżują się w kokardę

Wszystkie współrzędne to współrzędne strony w punktach, początek w lewym dolnym rogu strony, Y rośnie w górę. Linia tekstu blisko góry strony A4 ma więc Y około 700 do 800, a jej górna krawędź ma większe Y. Specyfikacja daje też strumieniowi wyglądu (AP) pierwszeństwo przed QuadPoints, gdy oba są obecne, więc czworokąty znaczą najwięcej dla przeglądarek, które generują znacznik samodzielnie

Diagram geometrii QuadPoints we współrzędnych strony PDF pokazujący numerację rogów TL, TR, BL, BR w kolejności Z używaną przez adnotacje znaczników tekstu PDFium
PDFium oczekuje QuadPoints w kolejności Z, od lewej górnej do prawej górnej, potem od lewej dolnej do prawej dolnej, we współrzędnych strony, gdzie Y rośnie w górę

Dlaczego FPDFAnnot_SetAttachmentPoints zwraca false?

FPDFAnnot_SetAttachmentPoints zwraca false na nowej adnotacji, bo zastępuje wyłącznie czworokąt, który już istnieje. Nagłówek PDFium formułuje kontrakt wprost: quad_index "musi mieścić się w wyniku FPDFAnnot_CountAttachmentPoints()". Każda adnotacja utworzona przez FPDFPage_CreateAnnot startuje z licznikiem zero, więc nie ma indeksu 0 do zastąpienia. FPDFAnnot_AppendAttachmentPoints dodaje slot i powiększa licznik o jeden; od tego momentu indeks 0 istnieje i Set go przyjmie. Obie funkcje są oznaczone w nagłówkach PDFium jako eksperymentalne, a obie przy tym poszerzają ramkę istniejącego strumienia wyglądu, gdy nowy czworokąt sięga dalej niż stary

PDFium Component wystawia wszystkie punkty wejścia FPDFAnnot_* w PDFium.pas, a rekord FS_QUADPOINTSF i alias size_t mieszkają w FPdfView.pas. Jeśli trzymasz uchwyt adnotacji we własnym kodzie, rozgałęziaj się na liczniku przed każdym zapisem:

uses
  SysUtils, PDFium, FPdfView;

// Zapisuje Quad pod QuadIndex w adnotacji AnnotIndex aktywnej strony:
// zastępuje slot, jeśli istnieje, w przeciwnym razie dopisuje nowy
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;

Druga pułapka siedzi w tej samej rodzinie funkcji. FPDFAnnot_CountAttachmentPoints zwraca size_t, czyli typ bez znaku, więc znajome for I := 0 to Count - 1 na adnotacji bez czworokątów liczy 0 − 1 w arytmetyce bez znaku i zawija się do największej możliwej wartości. Testuj Count > 0 przed wejściem w jakąkolwiek pętlę po czworokątach albo najpierw zrzucaj na typ ze znakiem. Znaczniki od innych narzędzi prawie zawsze przychodzą z co najmniej jednym czworokątem. Świeżo utworzona adnotacja przychodzi z zerem

Tworzenie wyróżnienia za pomocą TPdf.CreateAnnotation

Przy API komponentu nigdy nie wybierasz między Append i Set. TPdf.CreateAnnotation i TPdf.SetAnnotation sprawdzają obie, ile czworokątów adnotacja już trzyma, zastępują istniejące sloty i dopisują resztę, więc ścieżka tworzenia dopisuje, a ścieżka aktualizacji zastępuje. Dostarczasz rekord TPdfAnnotation z Subtype, kolorem, czworokątem i Rectangle

Tu znaczą dwa szczegóły rekordu. Inicjalizuj rekord przez Default(TPdfAnnotation). Rekord trzyma stringi i tablice dynamiczne, a FillChar na rekordzie, który już przechowuje string, powoduje wyciek tego stringa, więc Default to bezpieczniejszy nawyk dla każdego rekordu, który używasz ponownie. I zawsze wypełniaj Rectangle: komponent zapisuje go jako Rect adnotacji przy każdym utworzeniu i aktualizacji, więc wyzerowany rekord wyprodukuje Rect [0 0 0 0], nawet gdy czworokąty są poprawne. CreateAnnotation działa na aktywnej stronie, którą ustawia AddPage dla nowej strony i PageNumber dla istniejącego dokumentu, i rzuca 'Unsupported annotation subtype', gdy PDFium nie potrafi utworzyć żądanego podtypu

var
  Pdf: TPdf;
  A: TPdfAnnotation;
begin
  Pdf := TPdf.Create(nil);
  try
    Pdf.CreateDocument;
    Pdf.AddPage(0, 595, 842);                // A4, staje się aktywną stroną

    A := Default(TPdfAnnotation);
    A.Subtype := anHighlight;
    A.HasColor := True;
    A.Color := clYellow;
    A.ColorAlpha := $80;                     // alpha idzie razem z kolorem
    A.HasAttachmentPoints := True;
    A.AttachmentPoints[1].X := 50;  A.AttachmentPoints[1].Y := 700;  // lewy górny
    A.AttachmentPoints[2].X := 250; A.AttachmentPoints[2].Y := 700;  // prawy górny
    A.AttachmentPoints[3].X := 50;  A.AttachmentPoints[3].Y := 680;  // lewy dolny
    A.AttachmentPoints[4].X := 250; A.AttachmentPoints[4].Y := 680;  // prawy dolny
    A.Rectangle.Left := 50;   A.Rectangle.Top := 700;                // otacza czworokąt
    A.Rectangle.Right := 250; A.Rectangle.Bottom := 680;
    A.ContentsText := 'Highlighted region';
    Pdf.CreateAnnotation(A);

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

Zmiana dekoracji kosztuje jedną linijkę. anUnderline, anStrikeout i anSquiggly biorą identyczny rekord, z czworokątami i całą resztą; ISO 32000-1 opisuje te cztery razem, a różnią się tylko sposobem malowania obszaru czworokąta. Podtypy spoza tej rodziny, jak anSquare, anCircle i anText, pozycjonują się z samego Rectangle; zostaw im HasAttachmentPoints na False i puste AttachmentPointSets, a żaden czworokąt nie zostanie zapisany

Zaznaczenia wielowierszowe: jedna adnotacja, kilka czworokątów

Zaznaczenie łamiące się na trzy wiersze potrzebuje trzech czworokątów, po jednym na wiersz, bo pojedynczy czworokąt rozpięty na wszystkie trzy domalowałby też prawy koniec wiersza pierwszego i lewy koniec wiersza trzeciego. TPdfAnnotation niesie każdy czworokąt w AttachmentPointSets, tablicy dynamicznej TQuadrilateralPoint; pojedyncze pole AttachmentPoints zostaje jako alias pierwszego wpisu. Gdy AttachmentPointSets jest niepuste, CreateAnnotation zapisuje wszystkie jego wpisy po kolei, a pojedyncze pole ignoruje

Możesz zamiast tego utworzyć jedną adnotację na wiersz. Renderuje się tak samo, ale recenzent widzi wtedy trzy komentarze, trzy popupy i trzy pozycje do usunięcia tam, gdzie było jedno wyróżnienie. Umieść wiersze w jednej adnotacji. Geometrię najłatwiej wziąć z wyszukiwania, bo TPdf.CreateDocumentSearch zwraca każde trafienie z tablicą Rectangles, trzymającą po jednym prostokącie na przebieg tekstu w wierszu, już we współrzędnych strony:

function QuadFromRect(const R: TPdfRectangle): TQuadrilateralPoint;
begin
  Result[1].X := R.Left;  Result[1].Y := R.Top;     // lewy górny
  Result[2].X := R.Right; Result[2].Y := R.Top;     // prawy górny
  Result[3].X := R.Left;  Result[3].Y := R.Bottom;  // lewy dolny
  Result[4].X := R.Right; Result[4].Y := R.Bottom;  // prawy dolny
end;

// Własny helper, nie część biblioteki: suma prostokątów wiersza
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
  // Zbierz wszystkie trafienia, zanim edytujesz jakąkolwiek stronę
  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;

Prostokąty z wyszukiwania są wyrównane do osi, po cztery liczby każdy, więc na tekście obróconym wynikowy czworokąt pokrywa ramkę otaczającą przebieg, zamiast iść po pochyłości. Dla prostego tekstu poziomego — czyli większości tego, co się wyróżnia — ramka i obszar glifów się pokrywają. Jeśli potrzebujesz geometrii per znak, przewodnik po ekstrakcji tekstu z PDFium Component opisuje CharacterRectangle i pokrewne wywołania stron tekstowych, a artykuł o pomiarze tekstu i zawijaniu wierszy pokazuje, jak liczyć zasięgi linii dla tekstu, który dopiero zamierzasz wygenerować

Wielowierszowe wyróżnienie zbudowane z trzech czworokątów dopisywanych po kolei do jednej adnotacji PDFium utworzonej w Delphi
Zaznaczenie obejmujące trzy wiersze staje się jedną adnotacją niosącą trzy czworokąty, zbudowaną wywołaniami AppendAttachmentPoints, które podnoszą liczbę slotów

Edycja istniejącej adnotacji znacznika idzie przez Pdf.Annotation[Index] := A, co wywołuje SetAnnotation; podtyp w rekordzie musi zgadzać się z zapisanym, bo wywołanie rzuca 'Incorrect annotation subtype'. Czworokąty są przepisywane indeks po indeksie, a nadmiarowe wpisy w AttachmentPointSets są dopisywane. PDFium nie wystawia wywołania usuwającego pojedynczy czworokąt, więc zejście z trzech czworokątów do dwóch zostawia trzeci w pliku. Żeby skrócić wyróżnienie, usuń je przez DeleteAnnotation i utwórz ponownie z krótszą tablicą

AttachmentPoints indeksuje od 1, z wyjątkiem C++

TQuadrilateralPoint jest zadeklarowany jako array [1..4] of TPdfPoint, a numeracja odpowiada numerom rogów ze specyfikacji: element 1 to (x1, y1), element 4 to (x4, y4). Kod pisany z pamięci z nawykami od zera robi to błędnie w sposób, który kompilator nie zawsze wyłapie. Pętla typu for I := 0 to 3 do A.AttachmentPoints[I] := ... kompiluje się i w Delphi, i w Free Pascalu, bo indeks jest znany dopiero w czasie wykonania. Przy wyłączonym sprawdzaniu zakresów — domyślnym w projekcie Delphi — zapis dla indeksu 0 ląduje na bajtach tuż przed tablicą, w polach rekordu poprzedzających, a sam czworokąt zachowuje zerowy róg. Nic nie rzuca wyjątku

Stały indeks to inna sprawa. Kompilator może porównać go z zadeklarowanymi granicami, zanim cokolwiek ruszy, i fpc między innymi odrzuca literał AttachmentPoints[0] błędem zakresu. Prześlizguje się forma z indeksem wyliczanym. Zbuduj kod adnotacji przynajmniej raz z {$R+} w Delphi albo przez fpc, zanim mu zaufasz; przy włączonym sprawdzaniu zakresów pętla z czasu wykonania powyżej rzuca ERangeError na indeksie 0

C++Builder odwraca regułę. Generowany PDFium.hpp deklaruje TQuadrilateralPoint jako System::StaticArray<TPdfPoint, 4>, a statyczna tablica C++ startuje od zera, niezależnie od dolnej granicy Pascala. W C++ rogi to więc AttachmentPoints[0] przez AttachmentPoints[3], wciąż w kolejności Z. Przenoszenie przykładowego kodu z Delphi linia po linii zachowuje indeksy 1 do 4, co przesuwa każdy róg o jeden i zapisuje ostatni za końcem tablicy

Czytanie czworokątów z powrotem

Najszybszy sprawdzian, czy adnotacja znacznika wylądowała poprawnie, to odczytać ją z powrotem tym samym API. Pdf.Annotation[Index] wypełnia AttachmentPointSets każdym czworokątem zapisanym na adnotacji, a HasAttachmentPoints jest True, gdy jest ich co najmniej jeden:

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;

Dla pojedynczego wyróżnienia utworzonego wcześniej oczekiwana linia to annot 0 quad 0: TL (50.0, 700.0) BR (250.0, 680.0); Y lewego górnego rogu niższy niż Y prawego dolnego znaczy, że rogi weszły do góry nogami. Czworokąty podróżują też razem z adnotacją, gdy wymieniasz znaczniki z innymi narzędziami: atrybut coords w XFDF trzyma je wszystkie, po osiem liczb na czworokąt, jak opisano w artykule o eksporcie i imporcie XFDF. Potem otwórz zapisany plik w drugiej przeglądarce i sprawdź, czy kolor siedzi na glifach, a nie obok nich — to przeglądarka budująca własny wygląd z QuadPoints demaskuje złą kolejność rogów

Rekord adnotacji, tablica wielu czworokątów i liczący sloty zapisywacz używane w tym artykule od początku do końca są częścią PDFium Component dla Delphi, C++Builder i Lazarus, gdzie pełna dokumentacja API adnotacji siedzi obok wywołań wyszukiwania i ekstrakcji tekstu, na których opierają się te przykłady