같은 데이터로 같은 보고서 생성기를 돌린 두 PDF는 한 차례 차이만 있어도 바이트 단위로 일치하는 일이 드뭅니다. 바이너리 diff는 크로스 레퍼런스 테이블과 객체 번호, 심하면 폰트 프로그램까지 점등하는데 두 파일은 정확히 같은 페이지를 인쇄합니다. 렌더링 픽셀 비교가 치료법처럼 보이다가 누군가 표지를 추가하면 무너집니다. 그 순간부터 모든 페이지가 짝보다 한 자리 뒤에 놓이고, 페이지별 픽셀 검사는 문서 전체가 바뀌었다고 보고합니다. 자동화할 가치가 있는 비교는 서로 다른 두 질문에 답해야 합니다. 파일 안에서 무엇이 바뀌었는지, 그리고 리더가 그것을 보게 될지이며, 한 파일의 어느 페이지가 다른 파일의 어느 페이지와 짝인지 알아야 합니다
똑같이 생긴 두 PDF는 왜 바이트 단위로 다를까?
바이트 출렁임의 대부분은 리더가 결코 보지 못하는 장부에서 나옵니다. 객체 번호는 라이터가 객체를 내보내는 우연한 순서대로 나눠집니다. 많은 생성기가 글리프가 처음 쓰인 순서로 폰트 서브셋을 만들므로, 살짝 다른 순회는 같은 보이는 텍스트에 서로 다른 글리프 코드, 즉 서로 다른 콘텐츠 스트림 바이트를 냅니다. 크로스 레퍼런스 오프셋은 파일 앞쪽의 무엇이든 길이가 바뀌면 움직이는데, 그건 거의 언제나 그렇습니다
그래서 객체 번호는 두 파일 사이의 신원으로 쓸모가 없습니다. HotPDF의 THPDFDocComparison은 문서 카탈로그에서 너비 우선 순회로 처음 닿는 경로로 모든 객체를 이름 댑니다. 딕셔너리 키는 바이트 순서로, 배열 원소는 인덱스로 방문하므로 순회는 결정적입니다. 첫 페이지의 폰트 리소스는 각 생성기가 붙인 객체 번호와 무관하게 두 파일에서 흔히 $Catalog/Pages/Kids[0]/Resources/Font/F1 같은 이름으로 착지합니다. 키의 특이한 바이트는 #xx로 이스케이프되고, MaxPathBytes를 넘는 경로는 잘린 뒤 전체 경로의 해시로 끝맺음되므로 접두부를 공유하는 두 긴 경로도 여전히 구별됩니다
객체마다 자기 콘텐츠 위에 SHA-256 서명이 붙습니다. 간접 참조는 참조가 그 자리에 있다는 사실만 기여하고 그것이 가리키는 객체 번호는 절대 기여하지 않으며, 대상은 따로 서명하러 큐에 들어갑니다. 따라서 파일의 모든 객체를 다시 번호 매겨도 차이가 하나도 생기지 않습니다. 폰트 딕셔너리 하나가 바뀌면 보고서는 그 위의 페이지와 리소스 딕셔너리, 페이지 트리를 지목하는 대신 그 폰트의 경로를 objectChanged로 이름 댑니다. 서명은 일치하는데 경로가 옮겨진 객체(이를 테면 페이지 트리의 다른 가지로 밀린 페이지)는 objectMoved로 나타나고 나머지는 objectInserted나 objectDeleted입니다
카탈로그에서 오는 어떤 경로도 닿지 않는 객체도 $Unreachable[42:0] 같은, 객체 번호와 세대 번호를 실은 합성 경로 아래에서 서명됩니다. 고아 콘텐츠는 어떤 뷰어도 표시하지 않더라도 두 파일 사이의 실제 차이입니다. 스트림 데이터는 스트림에서 곧장 64 KB 청크로 해시되고 스트림 위치는 그 뒤에 되돌려지므로, 두 큰 파일의 비교가 모든 스트림 사본을 메모리에 쥐는 걸 뜻하지 않습니다
한 문서에 표지가 생겼을 때 페이지 맞추기
페이지 1과 페이지 1, 페이지 2와 페이지 2를 짝짓는 것은 무언가 삽입되기 전까지만 옳습니다. 앞쪽에 새 표지가 생기면 위치 기반 짝짓기는 모든 페이지를 바뀌었다고 보고하는데, 기술적으로는 사실이지만 검토자에게 아무것도 말해 주지 않습니다
페이지를 살펴보는 모든 모드는 먼저 페이지를 맞춥니다. 각 페이지는 추출된 텍스트에서 서명을 얻고, 추출 가능한 텍스트가 없는 페이지는 페이지 딕셔너리와 콘텐츠 스트림의 서명으로 폴백합니다. 서명이 정확히 일치하는 페이지들을 짝짓고, 비교는 그 짝들 가운데 두 번째 파일에서의 위치 순서대로 가장 긴 증가 부분 수열을 뽑습니다. 그 수열 안의 짝들은 삽입이나 삭제를 따라 이동했을 뿐이고, 수열 밖의 짝들은 실제로 재배치된 것이므로 pageMoved로 보고됩니다. 아예 맞지 않은 것들은 순서대로 pageChanged로 짝지어지고 남는 것은 pageInserted나 pageDeleted가 됩니다. 새 표지 한 장이 더해진 400페이지 매뉴얼에서 페이지 수준 항목은 위치 기반 짝짓기라면 400개의 변경이 났을 자리를 pageInserted 하나로 줄입니다. 객체 패스는 경로로 일하므로 밀린 페이지 객체들은 보통 objectMoved로 그곳에 나타나고, type 필드로 걸러 내면 실제 편집과 갈라집니다
맞춰진 짝은 구조 모드에서 검사를 한 번 더 받습니다. 페이지 딕셔너리를 /Contents, /Resources, /Parent를 빼고 두 번째로 서명해서 그 서명이 다르면 짝은 상세 page metadata changed와 함께 pageChanged로 보고됩니다. 텍스트는 동일한데 /MediaBox나 /Rotate가 움직인 페이지, 즉 텍스트 기반 맞춤만으로는 짝 지어 흘려보내버릴 변경을 잡는 장치입니다
구조 비교 실행과 판정 읽기
비교는 적재된 THotPDF 인스턴스 둘과 모드를 받아 JSON 보고서를 AnsiString으로 돌려줍니다. cmStructural은 객체와 페이지 순회를, cmRenderedImage은 픽셀 패스를, cmFull은 둘 다 돌리고, cmPageCount, cmPageText, cmObjectCount는 스모크 테스트용 가벼운 검사입니다. Compare는 기본 한도와 옵션을 쓰고, CompareWithLimits와 CompareWithOptions는 여러분 것을 받습니다
uses
Classes, SysUtils, HPDFDoc, HPDFDocCompare;
function CompareFiles(const BaselineFile, CandidateFile: string): AnsiString;
var
DocA, DocB: THotPDF;
begin
Result := '';
DocA := THotPDF.Create(nil);
DocB := THotPDF.Create(nil);
try
if (DocA.LoadFromFile(BaselineFile) <= 0) or
(DocB.LoadFromFile(CandidateFile) <= 0) then
raise Exception.Create('Could not load one of the files');
Result := THPDFDocComparison.Compare(DocA, DocB, cmStructural);
with TFileStream.Create('diff.json', fmCreate) do
try
if Result <> '' then
WriteBuffer(Result[1], Length(Result));
finally
Free;
end;
finally
DocB.Free;
DocA.Free;
end;
end;
보고서는 불리언 하나가 뭉개버릴 최상위 사실 셋을 실어 나릅니다. identical은 차이가 기록되지 않았고 비교가 끝마쳤을 때만 참입니다. comparisonComplete는 끝마쳤는지를 말하고, differencesTruncated는 목록이 잘렸는지를 말하며, differenceCount는 진짜 총계를 reportedDifferenceCount는 실제 나열된 개수를 유지합니다. 순회가 한도에 걸리면 differences 배열의 comparisonBudget 항목이 페이지 순회였는지 객체 순회였는지를 말합니다
comparisonComplete를 거짓으로 만드는 것들이 몇 있습니다. 잘린 페이지나 객체 순회, 어느 한 파일에서 resolve되지 않는 간접 참조, MaxDifferences 허용치를 넘는 차이, 구조(cmPageText에서는 텍스트)를 읽지 못한 페이지, 불완전한 픽셀 패스입니다. 모두 identical도 거짓으로 밀어 버립니다. API는 일찍 멈춘 순회에서 동등을 보고하지 않습니다. 그래서 CI 게이트는 두 종류의 실패를 갈라 놓아야 합니다:
uses
SysUtils, HPDFJobJSON;
// 마친 비교에 차이가 없을 때만 True를 반환하고,
// 아니면 이유를 출력합니다. 게이트 자체는 여러분의 코드입니다
function DiffGatePasses(const Report: AnsiString): Boolean;
var
Parser: THPDFJSONParser;
Root, Diffs, Item: THPDFJSONValue;
I: Integer;
begin
Parser := THPDFJSONParser.Create(Report);
try
Root := Parser.Parse;
finally
Parser.Free;
end;
try
Result := Root.GetBool('identical');
if Result then
Exit;
if not Root.GetBool('comparisonComplete') then
Writeln('INCOMPLETE: a limit or unreadable input stopped the comparison');
Writeln(Format('%d difference(s), %d listed',
[Root.GetInt('differenceCount'), Root.GetInt('reportedDifferenceCount')]));
Diffs := Root.GetArr('differences');
if Diffs <> nil then
for I := 0 to Diffs.ItemCount - 1 do
begin
Item := Diffs.Item(I);
Writeln(Item.GetStr('type'), ' ', Item.GetStr('detail'), ' ',
Item.GetStr('pathA'), ' -> ', Item.GetStr('pathB'));
end;
finally
Root.Free;
end;
end;
'불완전'을 독자적인 빌드 결말로 다루세요. 그것을 '다름'에 매핑하는 작업은 엔지니어들이 실은 망가진 입력이나 너무 낮게 잡은 한도를 추구하느라 회귀를 찾아 헤매게 하고, '같음'에 매핑하는 작업은 잘린 순회가 릴리스를 통과하게 둡니다
여러분이 만들지 않은 파일에서 순회를 어떻게 제한하나?
THPDFStructuralCompareLimits.Default는 실세계 문서 기준으로 정해져 있습니다. 객체 250,000개, 추적 참조 2,000,000개, 페이지 250,000장, 중첩 깊이 128, 나열 차이 10,000개, 단일 스트림에서 64 MB와 전체 스트림 합산 512 MB 읽기, 문자열이나 이름 값마다 1 MB, 경로당 4,096바이트, 직렬화된 보고서의 16 MB 천장입니다. 0이나 음수 필드는 기본값으로 폴백하므로 부분만 채운 레코드가 무제한으로 변하는 일은 없습니다. 레코드는 CancellationToken과 비교가 작업 단위 사이에서, 페이지가 렌더링되는 동안에도 검사하는 Checkpoint 이벤트도 갖습니다
uses
SysUtils, HPDFDoc, HPDFDocCompare, HPDFTypes;
function CompareForRelease(DocA, DocB: THotPDF;
Token: THPDFCancellationToken): AnsiString;
var
Limits: THPDFStructuralCompareLimits;
Options: THPDFRenderedCompareOptions;
begin
Limits := THPDFStructuralCompareLimits.Default;
Limits.MaxDifferences := 200; // 목록을 짧게 유지. differenceCount는 여전히 전부 셉니다
Limits.MaxTotalStreamBytes := 128 * 1024 * 1024;
Limits.CancellationToken := Token; // 다른 스레드가 Token.Cancel을 부를 수 있습니다
Options := THPDFRenderedCompareOptions.Default;
Options.DPI := 150; // 기본값은 72
Options.ColorSpace := rccLuminance; // 밝기를 비교하고 색상만의 변화는 무시
Options.ColorTolerance := 2; // 1-2 단계의 델타는 세지 않습니다
Options.MinimumSimilarity := 0.9995;
Options.MaxChangedPixelRatio := 0.0005;
Options.GenerateHeatmaps := True;
Options.HeatmapDirectory := 'diff-overlays';
try
Result := THPDFDocComparison.CompareWithOptions(DocA, DocB, cmFull,
Limits, Options);
except
on EHPDFOperationCancelled do
Result := ''; // 취소됨. 보고서는 없습니다
end;
end;
취소는 부분 보고서를 돌려주는 대신 호출에서 EHPDFOperationCancelled를 던집니다. 취소된 비교는 돌려줄 보고서가 없고 그 예외가 API의 그런 말이입니다. 렌더 옵션은 한도와 같은 정규화를 받습니다. DPI는 2,400으로, ColorTolerance는 0-255로, TileSize는 8-1,024로 묶이고 0-1 밖(또는 NaN)의 유사도나 비율 임계값은 조용히 기본값으로 되돌아갑니다
픽셀 패스는 무엇이든 렌더링하기 전에 페이지 치수와 요청된 DPI로 각 페이지의 비트맵 크기를 추정하고, 그다음 실제 비트맵을 MaxPixelsPerPage로 다시 검사하므로 엉터리 지오메트리의 페이지가 추정을 슬쩍 넘을 수 없습니다. 비용은 DPI의 제곱으로 자랍니다. US Letter, 즉 612 x 792포인트 문서를 기본 72 DPI로 하면 페이지 쌍 하나가 약 97만 픽셀이고 기본 MaxTotalPixels 5억은 500쌍이 넘습니다. 300 DPI에서는 쌍 하나가 약 1,680만 픽셀이고 예산은 29쌍에서 바닥납니다. 패스는 그때 renderBudget 항목을 기록하고 그 페이지를 budgetExceeded로 표시한 뒤 멈춰 renderComparisonComplete를 거짓으로 남깁니다
얼마나 비슷해야 충분히 비슷할까?
기본 옵션에서 픽셀 패스는 정확한 일치를 요구합니다. ColorTolerance 0, MinimumSimilarity 1.0, MaxChangedPixelRatio 0입니다. 기본을 엄격하게 유지하면 느슨하게 하는 결정이 명시됩니다. 누군가 이를 적어야 하고, 파이프라인은 자기 렌더에서 앤티앨리어싱 노이즈가 어떻게 생기는지 본 뒤에야 임계값을 풀어야 합니다
픽셀별로 rccRGB 모드의 델타는 빨강, 초록, 파랑 채널 사이 가장 큰 차이이고, rccLuminance 모드에서는 Rec. 709 휘도의 차이입니다. 델타가 ColorTolerance를 넘으면 픽셀이 바뀐 것으로 셉니다. 유사도 수치는 전체 페이지 휘도를 한 번에 놓고 계산한 구조적 유사도(SSIM) 점수입니다. 짝은 바뀐 픽셀 비율이 MaxChangedPixelRatio 이하이고 유사도가 MinimumSimilarity 이상일 때만 similar입니다. 게이트가 둘인 이유는 바코드 안의 몇백 개의 심하게 틀린 픽셀과 페이지 전체에 깔린 옅은 색조가 다른 실패이고 워크플로마다 견디는 방식이 다르기 때문입니다. 임계값 검사는 반올림하지 않은 값으로 이뤄지고, JSON의 소수 여섯 자리는 보고서를 실행마다 안정적으로 유지합니다
바뀐 픽셀은 고정 타일 격자, 기본 64픽셀 정사각, 네 모서리 이웃으로 이어진 격자 위에서 영역으로 묶입니다. changedRegions의 각 영역은 경계 상자와 바뀐 픽셀 수, 가장 큰 델타를 줍니다. 최대 MaxChangedRegions(기본 256)개만 나열되고, changedRegionCount는 여전히 진짜 개수를 보고하며 목록이 잘리면 changedRegionsTruncated가 설정되고 픽셀 패스는 불완전으로 셉니다. GenerateHeatmaps가 켜지면 바뀐 픽셀을 가진 모든 페이지가 HeatmapDirectory에 page-000003-diff.png 같은 이름의 PNG를 받습니다. 첫 파일의 페이지에 바뀐 픽셀을 노랑(임계값을 막 넘음)부터 빨강(최대 델타)까지 물들인 것으로, 그 경로는 보고서에 overlayPath로 나타납니다
실패는 보고되지 흡수되지 않습니다. 렌더러 예외, 없는 비트맵, 잘못된 페이지 크기는 메시지를 실은 renderError 항목이 되고 페이지 항목은 상태 error를 얻으며 renderComparisonComplete는 거짓이 됩니다. 픽셀 차원이 다른 두 렌더는 상태 sizeMismatch와 양쪽 크기를 나열하는 renderedImageSize 차이를 받습니다. 비교해 본 적 없는 페이지가 동일으로 세어지는 일은 결코 없습니다
각 모드가 파이프라인에서 사는 자리
픽셀 패스는 페이지를 인덱스로 엄격하게, i 페이지를 i 페이지와, 짧은 문서까지 짝짓습니다. 페이지 맞춤은 cmPageCount와 cmRenderedImage를 제외한 모든 모드에서 돕니다. 삽입된 표지가 있으면 cmRenderedImage 하나는 그 뒤의 모든 페이지를 지목하고, cmFull은 구조 절반에서 온 맞춤을 그 위치 기반 픽셀 결과 곁에 줍니다. 구조 판정을 먼저 읽고, 페이지 목록이 일치할 때만 픽셀 결과를 믿으세요
매 빌드에 cmStructural을 돌리세요. 값싸고 경로와 페이지 인덱스, 관련 객체 번호를 이름 대며, 뜻밖의 objectChanged는 그것을 낸 코드를 곧장 가리킵니다. cmFull과 히트맵은 릴리스 후보와 최적화 패스가 정말 무손실이었는지 확인할 때, 오버레이를 볼 사람이 곁에 있을 때 켜 두세요. cmPageText는 문구만 중요한 문서에 어울립니다. 마크업 수준 검토도 선택지입니다. PDF 페이지를 SVG로 내보내기는 평범한 diff 도구가 읽을 수 있는 텍스트 뷰를 주고, 프리플라이트 보고서 자동화의 검사들은 어느 비교 모드도 답하려 하지 않는 규격 준수 질문을 커버합니다
비교와 프리플라이트, 렌더링은 모두 같은 로드된 THotPDF 문서에서 동작하므로 적재 한 번이 셋을 다 섬깁니다. 컴포넌트가 Delphi와 C++Builder 개발자를 위해 커버하는 모든 것은 HotPDF Delphi PDF 컴포넌트 페이지에 있습니다