FPDFPage_CreateAnnot가 방금 돌려준 형광펜 주석은 FPDFAnnot_CountAttachmentPoints가 0이라고 보고하고, FPDFAnnot_SetAttachmentPoints(Annot, 0, Quad)는 어떤 좌표를 넘기든 그 주석에 대해 0을 반환합니다. 좌표가 문제가 아닙니다. 인덱스 0은 "기존 0번 쿼드를 교체하라"는 뜻인데 새 주석에는 쿼드가 하나도 없고, 슬롯을 만드는 호출은 FPDFAnnot_AppendAttachmentPoints입니다
한 문단으로 끝날 이야기지만 몇 시간을 잃기 쉽습니다. false 반환에 대한 자연스러운 반응이 기하학을 의심하는 것이기 때문입니다. 모서리를 뒤바꿔 보고, Y축을 뒤집어 보고, 디바이스 공간으로 변환했다가 되돌려 봅니다. 그 무엇도 결과를 바꾸지 못합니다. 이어지는 내용은 ISO 32000-1 기준으로 쿼드가 담아야 할 것, 컴포넌트 API와 raw C 함수로 쿼드를 쓰는 방법, 여러 줄 선택, 그리고 Delphi와 Free Pascal, C++Builder가 서로 다르게 잡는 인덱싱 함정을 다룹니다. 기존 주석을 읽고 검토하는 글의 생성 쪽 짝 문서로, 같은 구조를 반대 방향으로 걷습니다
ISO 32000-1 §12.5.6.10에서 QuadPoints가 뜻하는 것
QuadPoints는 네 텍스트 마크업 하위 타입(Highlight, Underline, Squiggly, StrikeOut)에 필수 항목입니다. 기본 사용자 공간에서 n개의 사각형을 나타내는 8×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보다 우선한다고 하므로, 쿼드가 가장 중요한 대상은 마크업을 자체 생성하는 뷰어입니다
FPDFAnnot_SetAttachmentPoints는 왜 false를 반환할까요?
FPDFAnnot_SetAttachmentPoints가 새 주석에서 false를 반환하는 이유는 이미 존재하는 쿼드만 교체하기 때문입니다. PDFium 헤더는 계약을 직접 밝힙니다. quad_index는 "FPDFAnnot_CountAttachmentPoints() 결과 안에 있어야 합니다". FPDFPage_CreateAnnot이 만드는 모든 주석은 카운트 0에서 시작하므로 교체할 인덱스 0이 없습니다. FPDFAnnot_AppendAttachmentPoints는 슬롯을 추가해 카운트를 하나 늘리고, 그 후에야 인덱스 0이 존재하며 Set이 받아들입니다. 두 함수 모두 PDFium 헤더에서 experimental로 표시되어 있고, 새 쿼드가 예전 것보다 멀리 뻗으면 기존 외형 스트림의 바운딩 박스도 넓힙니다
PDFium Component는 모든 FPDFAnnot_* 진입점을 PDFium.pas에 노출하고, FS_QUADPOINTSF 레코드와 size_t 별칭은 FPdfView.pas에 있습니다. 주석 핸들을 직접 쥐고 있다면 매 쓰기 전에 카운트로 분기하세요:
uses
SysUtils, PDFium, FPdfView;
// 활성 페이지의 AnnotIndex 주석에 Quad를 QuadIndex 위치에 쓴다:
// 슬롯이 이미 있으면 교체하고, 없으면 새로 추가한다
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을 검사하거나 부호 있는 타입으로 캐스트하세요. 다른 도구가 만든 마크업은 최소 쿼드 하나를 갖고 오는 것이 보통이지만, 갓 만든 주석은 0으로 옵니다
TPdf.CreateAnnotation으로 형광펜 주석 만들기
컴포넌트 API에서는 Append와 Set 사이를 고를 일이 없습니다. TPdf.CreateAnnotation과 TPdf.SetAnnotation은 모두 주석이 이미 보유한 쿼드 수를 확인해, 존재하는 슬롯은 교체하고 나머지는 추가합니다. 생성 경로는 append가 되고 갱신 경로는 replace가 되는 셈입니다. 개발자가 공급하는 것은 Subtype과 색상, 쿼드, Rectangle을 담은 TPdfAnnotation 레코드입니다
여기서 레코드 관련 세부 두 가지가 중요합니다. 레코드는 Default(TPdfAnnotation)으로 초기화하세요. 이 레코드는 문자열과 동적 배열을 담고 있어서 문자열을 이미 쥔 레코드에 FillChar를 때리면 그 문자열이 그냥 누수됩니다. 재사용하는 모든 레코드에 Default가 더 안전한 습관인 이유입니다. 그리고 Rectangle은 항상 채우세요. 컴포넌트는 생성과 갱신 때마다 이것을 주석의 Rect로 기록하므로, 0으로만 된 레코드는 쿼드가 옳아도 Rect가 [0 0 0 0]인 파일을 만듭니다. CreateAnnotation은 활성 페이지에서 동작하며, 활성 페이지는 새 페이지에는 AddPage가, 기존 문서에는 PageNumber가 정합니다. PDFium이 요청한 하위 타입을 만들 수 없으면 'Unsupported annotation subtype'을 raise합니다
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은 모든 쿼드를 TQuadrilateralPoint의 동적 배열인 AttachmentPointSets에 담고, 단일 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 Component 텍스트 추출 가이드가 CharacterRectangle과 관련 텍스트 페이지 호출을 다루고, 텍스트 측정과 워드랩 글은 앞으로 생성할 텍스트의 줄 범위 계산법을 보여줍니다
기존 마크업 주석의 편집은 Pdf.Annotation[Index] := A로, 내부적으로 SetAnnotation을 부릅니다. 레코드의 하위 타입이 저장된 것과 일치해야 하며, 그렇지 않으면 'Incorrect annotation subtype'을 raise합니다. 쿼드는 인덱스별로 다시 쓰이고 AttachmentPointSets의 초과 항목은 append됩니다. PDFium은 쿼드 하나만 지우는 호출을 노출하지 않으므로, 쿼드 셋에서 둘로 줄이려고 해도 세 번째가 파일에 남습니다. 형광펜을 줄이려면 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 양쪽에서 컴파일됩니다. 인덱스가 실행 시간에야 결정되기 때문입니다. Delphi 프로젝트 기본값인 범위 검사 off 상태에서는 인덱스 0의 쓰기가 배열 바로 앞 바이트, 즉 앞 레코드 필드 안에 착지하고 쿼드 자신은 0번 모서리를 빈 채로 둡니다. 아무것도 raise하지 않습니다
상수 인덱스는 사정이 다릅니다. 컴파일러가 무엇보다 실행 전에 선언된 경계와 비교할 수 있고, fpc 같은 컴파일러는 리터럴 AttachmentPoints[0]을 범위 오류로 거절합니다. 빠져나가는 것은 계산된 인덱스 형태입니다. 주석 코드를 믿기 전에 Delphi로 {$R+}를 켜서 최소 한 번, 또는 fpc로 한 번 빌드하세요. 범위 검사가 켜져 있으면 위의 실행 시간 루프는 인덱스 0에서 ERangeError를 raise합니다
C++Builder는 규칙을 뒤집습니다. 생성된 PDFium.hpp는 TQuadrilateralPoint를 System::StaticArray<TPdfPoint, 4>로 선언하고, C++ 정적 배열은 Pascal 하한이 뭐든 0에서 시작합니다. 따라서 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보다 낮으면 모서리가 거꾸로 들어간 것입니다. 쿼드는 다른 도구와 마크업을 주고받을 때도 주석과 함께 다닙니다. XFDF의 coords 속성이 쿼드당 여덟 숫자로 전부를 담으며, XFDF 내보내기와 가져오기 글에 설명되어 있습니다. 그다음에는 저장한 파일을 다른 뷰어에서 열어 색이 글리프 옆이 아니라 위에 앉는지 확인하세요. QuadPoints로 자체 외형을 만드는 뷰어가 바로 나쁜 모서리 순서를 폭로하는 주체니까요
이 글에서 쓴 주석 레코드, 다중 쿼드 배열, 카운트 인지형 라이터는 Delphi, C++Builder, Lazarus용 PDFium Component에 들어 있으며, 이 예제들이 의존하는 텍스트 검색과 추출 호출 옆에서 전체 주석 API 레퍼런스를 만날 수 있습니다