同一个报表生成器、同一份数据,跑两次得到的两份 PDF,很少逐字节一致。二进制 diff 把交叉引用表、对象编号乃至字体程序全部点亮,而两份文件打印出来的页面一模一样。比较渲染像素看似是解药——直到有人加了一张封面:从那一刻起,每一页都比自己的对手靠后一个位置,逐页像素检查报告整个文档都变了。一份值得自动化的比较必须回答两个不同的问题:文件内部什么变了,读者会不会看出来;还必须知道一份文件的哪一页对应另一份的哪一页
为什么看起来一样的两份 PDF 字节不同?
字节层面的大部分抖动来自读者永远看不到的记账。对象编号按写方碰巧发出对象的顺序分配。很多生成器按字形首次使用的顺序构建字体子集,所以一次略有不同的遍历就会为同一段可见文本产生不同的字形码,进而产生不同的内容流字节。文件里任何靠前的东西长度一变,交叉引用偏移就跟着挪——而它几乎总在变
所以对象编号当不了跨文件的身份。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 页手册,页面级条目收敛为一条 pageInserted——按位置配对会产出 400 条变化。对象趟按路径工作,所以挪了位的页面对象通常仍以 objectMoved 出现在那里,按 type 字段过滤即可把它们与真实编辑分开
结构模式里,对齐的配对还要多过一道检查。页面字典在去掉 /Contents、/Resources 和 /Parent 之后再签一次,签名不同则该配对报为 pageChanged,细节是 page metadata changed。这抓住的是文本完全一致但 /MediaBox 或 /Rotate 动了的页面——纯文本对齐会把这种变化配成对、挥手放行
跑一次结构比较并读懂结论
一次比较接受两个已加载的 THotPDF 实例和一个模式,以 AnsiString 返回 JSON 报告。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 置为假:页面或对象遍历被截断、某份文件里一个间接引用解析不了、差异超过 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。零或负的字段回退到默认值,所以填了一半的记录不会变成无限制的记录。记录还带一个 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 × 792 磅)文档,默认 72 DPI 下每对页面约 97 万像素,默认 5 亿的 MaxTotalPixels 覆盖 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 组件页面上