책상 위에 이런 요청이 올라온다. 이미 렌더링된 명세서 묶음에서 계좌번호를 검게 가리고, 종이를 아끼기 위해 한 장에 두 페이지씩 실어 보내 달라는 것이다. 이 작업의 두 절반 모두 당신이 직접 만든 적 없는 PDF에 대한 content-stream 수술이다. 그래서 편하게 그릴 수 있는 page canvas도 없고, 기대고 쓸 font manager도 없다. 다른 도구가 배치해 둔 페이지에 raw drawing operator를 덧붙이면서, 로드된 문서의 object graph를 직접 편집하고 있는 셈이다. HotPDF는 이 용도에 정확히 두 개의 진입점을 제공하는데, 더 위험한 쪽이 겉보기에는 오히려 무해해 보인다
HotPDF는 Delphi와 C++Builder용 네이티브 VCL PDF 컴포넌트이며, 로드된 문서 API에는 디스크에서 열어 온 페이지, 그러니까 처음부터 새로 만든 페이지가 아니라 기존 페이지 위에 완전히 새로운 내용을 생성하는 메서드들이 포함돼 있다. 여기서 다루는 두 메서드는 RedactLoadedRect와 StitchLoadedPage다. 전자는 특정 영역 위를 불투명 사각형으로 칠하고, 후자는 한 페이지를 축소해 다른 페이지 위에 그린다. 둘 다 ISO 32000-1 §8.5의 content-stream operator를 페이지의 /Contents stream에 써 넣는 방식으로 동작한다. 그 operator가 무엇을 하는지, 그리고 그만큼 중요한 문제로 무엇을 하지 않는지를 이해해야 도구가 제대로 작동하고, 데이터 유출도 피할 수 있다
로드된 페이지에 operator 덧붙이기
일반적인 HotPDF API로 페이지를 만들 때는 컴포넌트가 content stream을 소유하고, TextOut과 vector 호출을 대신 직렬화해 준다. 하지만 로드된 페이지는 다르다. 그 페이지의 /Contents는 이미 존재하는 stream object이며, 공유돼 있을 수도 있고 content array의 일부일 수도 있어서, 기존 내용을 망가뜨리지 않고 그 안에 끼워 넣어야 한다. 이를 안전하게 만들어 주는 건 세 가지 작은 helper다. NewIndirectStream은 빈 버퍼와 /Length 0 항목을 가진 새로운 간접 THPDFStreamObject를 할당하고, ResolveLoadedStream은 indirect reference를 따라 실제 stream까지 내려가며, AppendLoadedStream은 stream 끝에 raw byte를 쓰고 /Length를 다시 기록해 저장된 object가 올바른 형태를 유지하게 한다
두 public method가 따르는 패턴은 같다. 페이지의 /Contents를 찾고, 그것을 stream으로 해석하며, 쓸 수 있는 stream이 없으면 새로 만들어 연결한다. 그런 다음 operator를 덧붙인다. 새 바이트는 stream의 끝에 들어가므로, painter 모델에 따라 원래 레이아웃이 그려 놓은 모든 것 위에 렌더링된다. 이 순서가 redaction 사각형이 동작하는 전부이며, 동시에 그 사각형이 많은 사람이 생각하는 것과 다른 이유이기도 하다
RedactLoadedRect: 삭제가 아니라 불투명 덮개
RedactLoadedRect는 zero-based 페이지 인덱스, 네 개의 user-space 좌표, 그리고 0에서 1 범위의 color component 세 개를 받는다:
var
Pdf: THotPDF;
begin
Pdf := THotPDF.Create(nil);
try
if Pdf.LoadFromFile('statement.pdf') > 0 then
begin
// 페이지 1의 계좌번호 영역을 검은색으로 덮습니다.
// 좌표는 PDF user space 기준: 원점 좌하단, 단위는 point.
Pdf.RedactLoadedRect(0, 56, 690, 320, 706, 0, 0, 0);
Pdf.SaveLoadedDocument('statement-covered.pdf');
end;
finally
Pdf.Free;
end;
end;
내부적으로 이 메서드는 content stream에 세 가지 operator를 기록한다. DeviceRGB에서의 fill-color 설정(r g b rg), 사각형 path(x y w h re), 그리고 fill(f)이다. 너비와 높이는 X2 - X1, Y2 - Y1로 계산되므로, 사용자는 마주 보는 두 꼭짓점만 넘기면 되고 메서드가 범위를 계산한다. 색으로 0, 0, 0을 넘기면 검은 막대가 나오고, 1, 1, 1을 넘기면 흰 페이지와 맞는 흰 막대가 나온다. 좌표는 로드된 페이지 자체의 user space 기준이므로 원점은 좌하단이고 단위는 point다. 정확히 배치하려면 페이지의 /MediaBox를 알아야 하며, GetLoadedPageBox에 pbMediaBox를 넘기면 그 정보를 얻을 수 있다
이 문장은 두 번 읽어야 한다. 채워진 사각형은 내용을 시각적으로 가릴 뿐, 제거하지 않는다. 사각형 아래의 텍스트, 이미지, vector art는 여전히 PDF 안에 있고, 여전히 object graph 안에 있으며, 페이지를 복사하거나 text extractor를 돌리거나 content stream에서 그 사각형을 지워 버릴 수 있는 누구에게나 다시 추출 가능하다. 이것은 법적 또는 보안 의미의 redaction이 아니라 visual masking이다. 계좌번호, 의료 기록, 신원 정보처럼 정말 민감한 데이터를 숨기려는 상황이라면, 검은 상자를 올려놓고 파일을 내보내는 것은 나중에 반드시 드러날 데이터 유출이다. 진짜 redaction은 밑에 깔린 content object를 삭제해야 하며, 그 위를 칠하는 것으로 끝나지 않는다
메서드 이름에 "Redact"가 들어가 있는 것은 결과가 어떻게 오해될지를 경고해 주는 데는 유용하지만, 무엇을 삭제해 주다는 약속은 아니다. RedactLoadedRect는 설계상 visual redaction primitive다. 내용을 실제로 제거하는 redaction은 별개의 작업으로, content stream의 기존 operator를 순회하며 재작성해 나가는 방식이다. 따라서 안전한 규칙은 아주 좁다. RedactLoadedRect는 민감하지 않은 미관상의 가림에만 써야 한다. draft watermark를 숨기거나, 스크린샷 전에 일부 영역을 비우거나, 내부 검토용 proof에서 오래된 로고를 덮는 경우다. 상자 아래의 내용이 유출됐을 때 문제가 된다면, 이 메서드는 잘못된 도구이고, 올바른 답은 해당 데이터 없이 문서를 다시 생성하거나 진짜 content-removal pipeline을 쓰는 것이다
StitchLoadedPage: 축소하고, 이동하고, 그리기
N-up 배치는 훨씬 다루기 쉬운 문제다. 숨기는 내용은 없고, 단지 재배치만 하기 때문이다. StitchLoadedPage는 대상 페이지 인덱스, 원본 페이지 인덱스, X/Y 오프셋, scale factor를 받아, 그 위치와 크기로 원본 페이지를 대상 페이지 위에 그린다:
// 페이지 2(인덱스 1)를 페이지 1(인덱스 0) 위에 겹칩니다,
// 70%로 축소하고 오른쪽 위로 살짝 이동합니다.
Pdf.StitchLoadedPage(0, 1, 40, 380, 0.7);
// 편의용 2-up: 원본 페이지를 대상의 오른쪽 절반에 놓습니다.
Pdf.StitchLoadedPageSideBySide(0, 1);
이 메서드가 덧붙이는 operator 문자열은 표준적인 transform-and-paint 시퀀스다. graphics state를 저장하는 q, 대각선에 scale을 넣고 translation 슬롯에 offset을 넣는 cm matrix, external object를 호출하는 /StitchSrc Do, 그리고 상태를 복원하는 Q가 이어진다. q/Q 쌍은 중요하다. 이 쌍이 transform을 고립시켜, stitch된 페이지의 좌표계가 이후에 덧붙이는 다른 내용으로 새지 않게 한다. 또한 이 메서드는 obvious mistake도 막는다. 인덱스 범위 오류, target과 source가 같은 경우, 0 이하의 scale은 감지해 1.0으로 보정하며, 예외를 던지지 않고 조용히 빠져나간다. 그래서 입력을 직접 확인해야 한다. 조용한 no-op는 겉으로는 성공과 구분되지 않기 때문이다
StitchLoadedPageSideBySide는 일반 메서드 위에 얇게 씌운 convenience helper다. target의 media-box 너비를 읽어 절반으로 나누고, 그 절반 너비를 X offset으로, 고정된 0.5 scale을 사용해 StitchLoadedPage를 호출함으로써 source를 오른쪽 절반에 놓는다. 이 하드코딩된 0.5는 source와 target이 같은 너비를 공유한다고 가정한다. 그렇지 않으면 source가 자기 절반을 깔끔하게 채우지 못하므로, 두 media box를 기준으로 직접 scale을 계산해 일반 StitchLoadedPage를 써야 한다
스티치가 원본 페이지를 참조하는 방식
출력을 여러 viewer에서 믿기 전에 알아 둘 세부 사항이 이것이다. 전통적인 N-up 배치는 원본 페이지의 content를 Form XObject로 감싼다. ISO 32000-1 §8.10.1이 /Type /XObject, /Subtype /Form, 그리고 자체 /BBox clipping box를 가져야 한다고 요구하는, 자기 완결형 drawable object다. StitchLoadedPage는 더 가벼운 길을 택한다. 원본 page dictionary 자체를 StitchSrc라는 이름으로 대상의 /Resources /XObject 바로 아래에 등록하고, Do로 그린다. page dict와 Form XObject는 content stream과 resource dictionary를 참조한다는 점 등 content model을 충분히 공유하기 때문에, 상당수 reader는 결과를 렌더링해 준다
등록된 object에는 /Subtype /Form 표시도 없고 자체 /BBox도 없다. 그래서 엄격한 소비자 쪽에서 Do를 무시하거나 예상과 다르게 clipping해도 그것은 정당한 권리다. 따라서 stitch 결과는 내 머신의 viewer 하나가 아니라 고객이 실제로 쓰는 viewer들에서 확인해야 하고, archival 용도나 엄격한 validator 통과가 필요한 PDF라면 페이지 배치는 상류에서 완전한 Form XObject wrapper를 통해 수행한다. 로드된 object graph 위에 만드는 모든 것에 같은 규율이 적용된다. 문서를 프로그래밍 방식으로 변경할 때마다 Delphi에서의 PDF preflight 패스가 릴리스 파이프라인에서 가치를 인정받는 이유도 여기에 있다
이 메서드들이 맞는 곳과 맞지 않는 곳
두 메서드 모두 content-stream 도구이므로, 사고방식은 직접 drawing을 할 때와 같다. 컴포넌트로 새 페이지를 만들어 본 적이 있다면, 이 호출 뒤에 있는 vector와 color operator는 Delphi의 HotPDF canvas drawing 글에서 본 것들과 익숙할 것이다. 차이는 단 하나, 여기서는 자신이 소유한 stream이 아니라 다른 누군가가 작성한 stream에 덧붙인다는 점뿐이다. 다음 세 가지 경계는 꼭 기억해야 한다
- Redaction은 외형적 처리일 뿐이다.
RedactLoadedRect는 내용 위를 칠할 뿐이며 절대 삭제하지 않는다. 민감한 정보라면 소스를 다시 생성하거나 진짜 content removal을 사용해야 한다. 검은 상자는 보안이 아니다 - stitch한 페이지는 대상 viewer에서 확인한다. 원본 페이지는 §8.10.1의
/Subtype /Form과/BBox를 갖춘 Form XObject를 거치지 않고 직접 참조된다. 따라서 대상 viewer에서 렌더링을 확인하고, 엄격한 검증이 필요한 상황에서는 상류에서 배치를 수행한다 - 좌표는 페이지 user space 기준이다. 원점은 좌하단이고 단위는 point이며, 페이지 자신의 media box가 기준이 된다. 무엇을 배치하기 전에
GetLoadedPageBox로 box를 읽어야 한다. 로드한 페이지 크기가 당신이 가정한 것과 다를 수 있기 때문이다
이런 경계를 염두에 두고 쓰면, 이 조합은 꽤 실용적인 workflow를 커버한다. 인쇄용으로 페이지를 재배치하고, 기밀이 아닌 영역을 가리고, SaveLoadedDocument로 다시 저장하는 일까지, 전체 재렌더링 없이 끝낼 수 있다. 이런 stitch 및 mask primitive를 포함한 loaded-document API는 Delphi와 C++Builder용 HotPDF Delphi Component에 들어 있으며, form-field, annotation, FDF 메서드들과 함께 제공된다