FPDFPage_CreateAnnot がつい先ほど返したばかりのハイライト注釈は、FPDFAnnot_CountAttachmentPoints が 0 と報告し、そこへ FPDFAnnot_SetAttachmentPoints(Annot, 0, Quad) を投げても、座標をどう変えようが 0 が返ります。座標は原因ではありません。インデックス 0 は「既存の 0 番のクアッドを置き換える」の意味であり、新しい注釈にはクアッドが1つもなく、スロットを作る呼び出しは FPDFAnnot_AppendAttachmentPoints のほうです
1段落で済む話なのに、何時間も失いがちです。False の返り値に対する自然な反応が、ジオメトリを疑うことだからです。角を入れ替え、Y 軸を反転させ、デバイス空間へ変換してまた戻す。どれも結果を変えません。以下では、ISO 32000-1 がクアッドに何を求めるか、コンポーネント API と生の C 関数それぞれからの書き方、複数行の選択範囲、そして Delphi と Free Pascal と C++Builder で挙動の違うインデックスの罠を扱います。同じ構造を逆方向にたどる既存注釈の読み取りとレビューの記事に対する、作成側の姉妹編です
ISO 32000-1 §12.5.6.10 における QuadPoints の意味
QuadPoints は、Highlight、Underline、Squiggly、StrikeOut という4つのテキストマークアップサブタイプで必須のエントリです。デフォルトユーザー空間での n 個の四角形を与える 8×n 個の数値の配列で、各四角形は注釈の下にあるテキストの、1語または連続する語のグループを囲みます。注釈にはどの注釈にも必要な Rect も依然として付きますが、マークアップサブタイプでは、どのグリフをマークするかをクアッドが決め、Rect はそれを囲むだけです。矩形ではなく四角形を使うのは、テキストはページ上で回転したり斜めに剪断されたりしうるからで、各頂点は独立した点として x1 y1 x2 y2 x3 y3 x4 y4 と格納されます
頂点の順序は、仕様の文章と、流通しているファイルとが別れ道になる場所です。§12.5.6.10 は4つの頂点を反時計回りで与えると言い、テキストの向きは (x1, y1) から (x2, y2) へのエッジを基準にするとも言っています。Acrobat と、Acrobat の書くものを読むために作られた長い系譜のツールは、代わりに Z パターンを使います。点1が左上、点2が右上、点3が左下、点4が右下です。この並びでも向きの文章は守られています。1–2 のエッジがテキストの上端に沿って走るからです。ただし図形を反時計回りに一周してはいません。Z 順で書いてください。文字どおりの反時計回り(左上、左下、右下、右上)も紙の上では弁護できますが、点を Z のつもりでたどるリーダーには左上、左下、右上、右下に見え、そのエッジは交差して蝶ネクタイになります
座標はすべてポイント単位のページ座標で、原点はページの左下、Y は上向きに伸びます。A4 ページの上端近くのテキスト行なら Y は 700 から 800 あたりになり、上端のエッジのほうが Y が大きくなります。仕様は、両方がある場合には外観ストリーム(AP)を QuadPoints より優先させるとしているため、クアッドが最も効いてくるのは、マークアップを自前で描画するビューアです
FPDFAnnot_SetAttachmentPoints はなぜ false を返すのか
FPDFAnnot_SetAttachmentPoints が新しい注釈に対して false を返すのは、既存のクアッドを置き換えることしかしないからです。PDFium のヘッダは契約をそのまま書いています。quad_index は「FPDFAnnot_CountAttachmentPoints() の結果の範囲内でなければならない」。FPDFPage_CreateAnnot が作る注釈はどれもカウント 0 から始まるため、置き換えるべきインデックス 0 が存在しません。FPDFAnnot_AppendAttachmentPoints はスロットを1つ追加してカウントを1増やします。その後ならインデックス 0 が存在し、Set も受け付けます。両関数とも PDFium のヘッダでは experimental の印が付いており、新しいクアッドが古いクアッドより遠くまで届くときは、既存の外観ストリームのバウンディングボックスを広げるのも両方です
PDFium Component は FPDFAnnot_* のエントリポイントをすべて PDFium.pas に出しており、FS_QUADPOINTSF レコードと size_t エイリアスは FPdfView.pas にあります。注釈ハンドルを自分で持つなら、書き込みのたびにカウントで分岐してください:
uses
SysUtils, PDFium, FPdfView;
// アクティブページの AnnotIndex 番の注釈の QuadIndex 番に Quad を書く:
// スロットがあれば置換し、なければ新しく追加する
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;
2つ目の罠は同じ関数ファミリーの中にあります。FPDFAnnot_CountAttachmentPoints は符号なしの size_t を返すため、クアッドを1つも持たない注釈に対するおなじみの for I := 0 to Count - 1 は、符号なし算術で 0 − 1 を計算し、最大値へ折り返します。クアッドを回すループに入る前に Count > 0 を確かめるか、先に符号付き型へキャストしてください。他のツールが作ったマークアップには、ほぼ必ず1つ以上のクアッドが付いてきます。生まれたばかりの注釈は 0 でやってきます
TPdf.CreateAnnotation でハイライトを作る
コンポーネント API では、Append と Set の選択は不要です。TPdf.CreateAnnotation と TPdf.SetAnnotation はどちらも、注釈がすでに持つクアッド数を確かめ、存在するスロットは置換し、残りを追加します。作成パスは追加になり、更新パスは置換になるわけです。こちらが渡すのは Subtype、色、クアッド、Rectangle を持つ TPdfAnnotation レコードです
レコードの細部で重要な点が2つあります。レコードは Default(TPdfAnnotation) で初期化してください。レコードは文字列と動的配列を保持するため、すでに文字列を抱えたものへ FillChar すると、それをそのまま漏棄します。再利用するレコードすべてに Default のほうが安全な習慣です。そして Rectangle は必ず埋めてください。コンポーネントは作成でも更新でも、これを注釈の Rect として書き込むため、ゼロのままだとクアッドが正しくても Rect が [0 0 0 0] になります。CreateAnnotation はアクティブページに対して働きます。新規ページなら AddPage が、既存文書なら PageNumber がそれを設定し、PDFium が要求されたサブタイプを作れないときは 'Unsupported annotation subtype' を上げます
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;
装飾の切り替えは1行で済みます。anUnderline、anStrikeout、anSquiggly はクアッド込みでまったく同じレコードを受け取ります。ISO 32000-1 は4つをまとめて記述していて、違いはクアッド領域の塗り方だけです。そのファミリーの外のサブタイプ、anSquare、anCircle、anText などは Rectangle だけから位置を決めます。これらでは HasAttachmentPoints を False のまま、AttachmentPointSets を空にしておけば、クアッドは書かれません
複数行の選択範囲: 1つの注釈に複数のクアッド
3行にまたがる選択範囲には、クアッドが3つ、行ごとに1つ要ります。3行をまとめて覆う1つの四角形では、1行目の右端と3行目の左端まで塗られてしまうからです。TPdfAnnotation は全クアッドを AttachmentPointSets、つまり TQuadrilateralPoint の動的配列で運びます。単独の AttachmentPoints フィールドは、最初のエントリへのエイリアスとして残っています。AttachmentPointSets が空でなければ、CreateAnnotation はそのエントリをすべて順に書き、単独フィールドは無視されます
行ごとに注釈を1つ作る道もあります。描画結果は同じですが、レビューアからは、1つのハイライトのはずのものに、コメント3つ、ポップアップ3つ、削除すべき項目3つが見えます。行は1つの注釈に入れてください。ジオメトリは検索から簡単に取れます。TPdf.CreateDocumentSearch は各マッチに Rectangles 配列を付けて返し、行上のテキストの連なりごとに矩形1つ、すでにページ座標で入っています:
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;
検索の矩形は軸に平行で、数値は各4つです。回転したテキストでは、結果のクアッドは傾きに追従せず、連なりのバウンディングボックスを覆います。ハイライトされるものの大半を占める水平のまっすぐなテキストなら、ボックスとグリフ領域は一致します。文字ごとのジオメトリが必要な場合は、PDFium Component によるテキスト抽出ガイドが CharacterRectangle と関連するテキストページ呼び出しを扱い、テキスト測定とワードラップの記事が、これから生成するテキストの行幅の計算方法を示しています
既存のマークアップ注釈の編集は Pdf.Annotation[Index] := A、つまり SetAnnotation の呼び出しを通ります。レコード内のサブタイプは保存済みのものと一致しなければならず、一致しないと 'Incorrect annotation subtype' を上げます。クアッドはインデックスごとに書き直され、AttachmentPointSets の余分なエントリは追加されます。PDFium にはクアッドを1つだけ取り除く呼び出しがないため、3つから2つへ減らしても3つ目はファイルに残ります。ハイライトを縮めるには、DeleteAnnotation で削除し、短い配列で作り直してください
AttachmentPoints の番号は 1 から、ただし C++ では除く
TQuadrilateralPoint は array [1..4] of TPdfPoint として宣言され、番号は仕様の頂点番号と一致します。要素1が (x1, y1)、要素4が (x4, y4) です。0 始まりの癖で記憶から書いたコードは、コンパイラが捕捉しきれない形でここを間違えます。for I := 0 to 3 do A.AttachmentPoints[I] := ... のようなループは、インデックスが実行時まで確定しないため、Delphi でも Free Pascal でもコンパイルが通ります。範囲チェックが off、つまり Delphi プロジェクトのデフォルトでは、インデックス 0 への書き込みは配列の直前のバイト、前のレコードフィールドの内側に着地し、クアッド自身はゼロの頂点を抱えたままです。何も上げません
定数インデックスは話が別です。コンパイラは何かが走る前に、宣言された境界と比較できます。fpc はその好例で、リテラルの AttachmentPoints[0] を範囲エラーで拒否します。すり抜けるのは計算されたインデックスのほうです。注釈コードは、Delphi なら {$R+} を付けて、あるいは fpc で、信頼する前に少なくとも1回ビルドしてください。範囲チェック有効時、上の実行時ループはインデックス 0 で ERangeError を上げます
C++Builder はこの規則をひっくり返します。生成された PDFium.hpp は TQuadrilateralPoint を System::StaticArray<TPdfPoint, 4> と宣言し、C++ の静的配列は Pascal の下限が何であれ 0 から始まります。C++ では頂点は AttachmentPoints[0] から AttachmentPoints[3] で、やはり Z 順です。Delphi のサンプルコードを1行ずつ移植するとインデックス 1 から 4 のままになり、全頂点が1つずれ、最後の1つは配列の終わりの先へ書き込まれます
クアッドを読み返す
マークアップ注釈が正しく着地したかの最速の確認は、同じ API で読み返すことです。Pdf.Annotation[Index] は注釈に保存された全クアッドを AttachmentPointSets に入れ、1つでもあれば 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 より低ければ、頂点が上下逆に入った証拠です。クアッドは、他のツールとマークアップをやり取りするときも注釈と一緒に旅します。XFDF の coords 属性がクアッドごとに8つの数値ですべてを保持する話は、XFDF エクスポートとインポートの記事にあります。そのうえで、保存したファイルを別のビューアで開き、色がグリフの横ではなくグリフに乗っていることを確かめてください。QuadPoints から自前の外観を組み立てるビューアこそが、悪い頂点順を暴き出すからです
この記事で使った注釈レコード、複数クアッド配列、カウントを見て分岐するライターは、Delphi、C++Builder、Lazarus 向け PDFium Component に同梱されています。注釈 API の完全なリファレンスが、これらの例が頼るテキスト検索・抽出の呼び出しの隣に並んでいます