同一個報表產生器、同一份資料,跑兩次產出的兩份 PDF,很少有逐位元組相同的。二進位 diff 亮起交叉參考表、物件編號,常常連字型程式一起亮,兩份檔案印出來的頁面卻一模一樣。比對渲染像素看似解方——直到有人加了一張封面:從此每一頁都比對應頁晚一個位置,逐頁像素檢查把整份文件回報成「全變了」。值得自動化的比對得回答兩個不同的問題——檔案內部什麼變了、讀者看不看得出來——還得知道一個檔案裡的哪一頁對應另一個檔案裡的哪一頁
兩份看起來一樣的 PDF,為什麼逐位元組都不同?
大部分位元組攪動來自讀者永遠看不到的簿記。物件編號按寫入端碰巧輸出的順序發放。很多產生器按字形首次使用的順序建子集,走訪順序稍有不同,字形碼就不同,同樣的可見文字於是寫出不同的內容串流位元組。交叉參考偏移在檔案前面任何東西變長時都要挪動——而那幾乎總是發生
所以物件編號當身分識別,跨檔案毫無用處。HotPDF 的 THPDFDocComparison 用「從文件目錄出發的廣度優先走訪中,第一個抵達它的路徑」為每個物件命名。字典鍵按位元組順序走訪、陣列元素按索引,走訪因此是確定性的:第一頁的字型資源在兩份檔案裡通常都叫 $Catalog/Pages/Kids[0]/Resources/Font/F1,不管各產生器給了它什麼物件編號。鍵裡的特殊位元組轉義成 #xx;超過 MaxPathBytes 的路徑被截斷、以完整路徑的雜湊收尾,共享前綴的兩條長路徑因此仍能區分
每個物件再對自身內容取一個 SHA-256 簽章。間接參照只貢獻「這裡有一個參照」這件事,絕不貢獻它指向的物件編號,目標物件另外排隊等自己的簽章。把整份檔案的物件重新編號,因此產不出任何差異。某一個字型字典變了,報告把那個字型的路徑標成 objectChanged,而不是把頁面、資源字典與上方的頁面樹一起點名。簽章相同但路徑搬了家的物件(比如頁面挪到頁面樹的另一支),標成 objectMoved;其餘是 objectInserted 或 objectDeleted
目錄任何路徑都到不了的物件照樣被簽章,路徑是帶物件與 generation 編號的合成形式,例如 $Unreachable[42:0]。孤兒內容是兩份檔案之間的真差異,哪怕沒有任何檢視器會顯示它。串流資料按 64 KB 區塊直接從串流雜湊,事後把串流位置放回去,比對兩個大檔因此不必把每條串流的副本都抱在記憶體裡
一份文件多了封面時,怎麼對齊頁面
第 1 頁配第 1 頁、第 2 頁配第 2 頁,只在沒有插入時正確。前面多了一張新封面,逐位配對把每一頁都報成變更——技術上沒錯,對審閱者卻一無所用
所有檢視頁面的模式都先對齊。每頁從抽出的文字取簽章;抽不出文字的頁面退回「頁面字典加內容串流」的簽章。簽章精確相符的頁面先配對,然後取這些配對按第二份檔案中位置排序後的最長遞增子序列。子序列裡的配對只是隨插入或刪除平移;子序列外的配對真的被重排過,回報 pageMoved。完全沒配上按順序配成 pageChanged,多出來的分別成為 pageInserted 或 pageDeleted。四百頁手冊加一張封面,頁面層級的條目只剩一條 pageInserted——逐位配對會給出四百條變更。物件道按路徑工作,被移位的頁面物件通常仍以 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 壓成 false:頁面或物件走訪被截斷、間接參照在其中一份檔案裡解不開、差異超過 MaxDifferences、某頁的結構(在 cmPageText 裡則是文字)讀不出來、像素道沒跑完。每一種也都強制 identical 為 false——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 萬像素,預設 MaxTotalPixels 五億蓋得住五百多對;300 DPI 時一對約 1,680 萬像素,預算在 29 對之後見底。之後它記一條 renderBudget、把該頁標成 budgetExceeded 並停手,renderComparisonComplete 留在 false
多像才算像?
預設選項下像素道要求完全一致:ColorTolerance 0、MinimumSimilarity 1.0、MaxChangedPixelRatio 0。預設保持嚴格,放寬的決定就必須白紙黑字:總得有人把它寫下來,而管線應該先看過反鋸齒噪聲在自己渲染裡的長相,再放鬆門檻
逐像素看,rccRGB 模式的 delta 是紅綠藍三通道差異的最大值;rccLuminance 模式是 Rec. 709 亮度之差。delta 超過 ColorTolerance 的像素算變更。相似度是對整頁亮度一次算出的結構相似性(SSIM)分數。變更像素比例不大於 MaxChangedPixelRatio 且相似度不低於 MinimumSimilarity,這一對才叫 similar。兩道門,因為條碼裡幾百個錯得離譜的像素、與整頁淡淡的色偏,是兩種不同的失敗,各工作流程對它們的容忍也不同。門檻判斷用未捨入的值;JSON 裡的六位小數是為了讓報告逐執行一致
變更像素按固定的 tile 網格(預設 64 像素見方)分組成區域,經四鄰邊相連。changedRegions 裡每個區域給邊界框、變更像素數與最大 delta。最多列 MaxChangedRegions 條(預設 256);changedRegionCount 仍回報真實數量,清單被截時 changedRegionsTruncated 置位、像素道算未完成。GenerateHeatmaps 開啟時,每個有變更像素的頁面都在 HeatmapDirectory 得到一張形如 page-000003-diff.png 的 PNG:第一份檔案的頁面按變更程度從黃(剛過容差)到紅(最大 delta)著色,路徑以 overlayPath 出現在報告裡
失敗被回報,絕不被吸收。渲染器例外、缺點陣圖、無效頁面尺寸,都成為帶訊息的 renderError 條目,頁面條目狀態 error,renderComparisonComplete 轉 false。像素尺寸不同的兩次渲染得狀態 sizeMismatch,附列兩個尺寸的 renderedImageSize 差異。誰也比不成的頁面,永遠不會被算成相同
管線裡各模式的位置
像素道嚴格按索引配頁:第 i 頁對第 i 頁,到較短文件為止。頁面對齊在除 cmPageCount 與 cmRenderedImage 外的每個模式都跑。加了封面的情況下,單跑 cmRenderedImage 會把封面之後每一頁都點名;cmFull 則在那些位置式像素結果之外,附上結構半場的對齊。先讀結構判決,頁面清單對得上時才信像素結果
每次建置跑 cmStructural:便宜、點名路徑、頁索引與物件編號,意外的 objectChanged 直指產出它的程式碼。cmFull 加熱圖留給候選發布版,以及「確認某次最佳化真的無損」這種有人在旁邊看覆蓋圖的場合。cmPageText 適合只有措辭要緊的文件。標記層級的審閱是另一個選項:把 PDF 頁面匯出成 SVG 給出普通 diff 工具讀得懂的文字視圖,預檢報告自動化裡的檢查則覆蓋兩種比對模式都不打算回答的合規問題
比對、預檢與渲染都作用在同一份已載入的 THotPDF 文件上,一次載入可以服務三者。元件為 Delphi 與 C++Builder 開發者覆蓋的一切,都在HotPDF Delphi PDF 元件頁