Два PDF от одного генератора отчётов на одних и тех же данных, с прогона на прогон, редко совпадают байт в байт. Бинарное сравнение зажигает таблицу перекрёстных ссылок, номера объектов и часто программы шрифтов, тогда как оба файла печатают ровно одинаковые страницы. Сравнение отрисованных пикселей выглядит лекарством, пока кто-то не добавит титульный лист: с той поры каждая страница сидит на одну позицию дальше своей пары, и попиксельная проверка по страницам объявляет изменившимся весь документ. Сравнение, которое стоит автоматизировать, обязано отвечать на два разных вопроса — что изменилось внутри файла и увидел бы это читатель — и обязано знать, какая страница одного файла соответствует какой странице другого
Почему PDF-файлы могут отличаться побайтово, но быть визуально идентичными?
Большая часть байтового шума — учёт, который читатель никогда не видит. Номера объектов раздаются в том порядке, в каком райтеру случайно захотелось emit-ить объекты. Многие генераторы собирают подмножества шрифтов в порядке первого использования глифов, поэтому чуть иной обход даёт другие коды глифов, а значит и другие байты потока содержимого, для того же видимого текста. Смещения перекрёстных ссылок едут всякий раз, когда меняет длину что-то раньше по файлу, а это бывает почти всегда
Так что номера объектов как межфайловая идентичность бесполезны. THPDFDocComparison в HotPDF называет каждый объект путём, который первым до него добирается в обходе в ширину от каталога документа. Ключи словарей обходятся в байтовом порядке, элементы массивов — по индексу, что делает обход детерминированным: ресурс шрифта на первой странице в обоих файлах обычно получает что-то вроде $Catalog/Pages/Kids[0]/Resources/Font/F1, какой бы номер объекта ни дал ему каждый генератор. Необычные байты в ключе эскейпятся как #xx, а путь длиннее MaxPathBytes обрезается и достраивается хешем полного пути, так что два длинных пути с общим префиксом остаются различимы
Каждый объект затем получает сигнатуру SHA-256 над собственным содержимым. Косвенная ссылка вносит лишь факт, что ссылка тут сидит, никогда — номер объекта, на который она указывает, а цель ставится в очередь на самостоятельное подписание. Перенумерация всех объектов файла потому не даёт ни одного отличия. А когда меняется один словарь шрифта, отчёт называет путь того шрифта как objectChanged вместо флага на странице, словаре ресурсов и дереве страниц над ними. Объект, чья сигнатура совпала, но путь уехал (скажем, страница переехала в другую ветку дерева страниц), показывается как objectMoved; остальные — objectInserted или objectDeleted
Объекты, до которых не дотягивается ни один путь из каталога, тоже подписываются — под синтетическим путём вроде $Unreachable[42:0], несущим номер объекта и поколение. Осиротевшее содержимое — настоящее отличие двух файлов, даже если ни один вьювер его никогда не покажет. Данные потоков хешируются куском по 64 КБ прямо из stream, и позиция потока возвращается на место, так что сравнение двух больших файлов не означает держать в памяти копию каждого stream
Выравнивание страниц, когда один документ обзавёлся обложкой
Ставить страницу 1 в пару со страницей 1 и страницу 2 со страницей 2 верно лишь до первой вставки. С новой обложкой спереди позиционное парование объявляет изменившейся каждую страницу, что технически правда и не говорит рецензенту ничего
Каждый режим, осматривающий страницы, сперва их выравнивает. Каждая страница получает сигнатуру из извлечённого текста; страницы без извлекаемого текста откатываются к сигнатуре словаря страницы плюс её потока содержимого. Страницы с точно совпавшими сигнатурами ставятся в пары, и сравнение затем берёт наибольшую возрастающую подпоследовательность этих пар, упорядоченную по их позиции во втором файле. Пары внутри подпоследовательности просто сдвинулись вместе со вставкой или удалением. Пары вне её действительно переставлены и репортятся как pageMoved. Всё, что не сматчилось вовсе, паруется по порядку как pageChanged, а излишек становится pageInserted или pageDeleted. Для 400-страничного руководства с одной новой титульной записью записи уровня страниц сходятся к единственному pageInserted там, где позиционное парование выдало бы 400 изменений. Объектный проход работает по путям, так что сдвинувшиеся объекты страниц обычно всё же появляются там как objectMoved, и фильтр по полю type отделяет их от настоящих правок
Выровненные пары проходят ещё одну проверку в структурных режимах. Словарь страницы подписывается второй раз без /Contents, /Resources и /Parent, и если та сигнатура различается, пара репортится как pageChanged с деталью page metadata changed. Это ловит страницу, чей текст идентичен, но /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 — реально перечисленное число. Когда обход упирается в лимит, запись comparisonBudget в массиве differences говорит, что именно урезано: обход страниц или обход объектов
Несколько вещей ставят comparisonComplete в false: усечённый обход страниц или объектов, косвенная ссылка, не разрешающаяся в одном из файлов, отличий больше, чем позволяет 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;
Считайте «incomplete» отдельным исходом сборки. Задание, мапящее его на «разные», шлёт инженеров искать регрессию, которая на самом деле кривой вход или лимит, поставленный слишком низко, а задание, мапящее на «одинаковые», пропускает в релиз усечённый обход
Что удерживает обход в рамках на файлах, которые вы не производили?
THPDFStructuralCompareLimits.Default размечен под реальные документы: 250 000 объектов, 2 000 000 отслеженных ссылок, 250 000 страниц, глубина вложенности 128, 10 000 перечисленных отличий, 64 МБ чтения из любого одиночного stream и 512 МБ со всех stream вместе, 1 МБ на строковое или name-значение, 4 096 байтов на путь и потолок 16 МБ на сериализованный отчёт. Нулевое или отрицательное поле откатывается к своему дефолту, так что частично заполненная запись никогда не превращается в неограниченную. Запись вдобавок несёт 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 каждая пара страниц стоит около 0,97 млн пикселей, и дефолтный MaxTotalPixels в 500 млн покрывает больше 500 пар. При 300 DPI одна пара — примерно 16,8 млн пикселей, и бюджет кончается после 29 пар. Проход затем записывает renderBudget, помечает ту страницу budgetExceeded и останавливается, оставляя renderComparisonComplete ложным
Насколько похожее — достаточно похожее?
С опциями по умолчанию пиксельный проход требует точного совпадения: ColorTolerance 0, MinimumSimilarity 1.0 и MaxChangedPixelRatio 0. Строгость по умолчанию держит решение о послаблении явным: кто-то обязан его записать, а конвейеру стоит ослаблять пороги только после того, как он увидел, как в его собственных рендерах выглядит шум антиалиасинга
Попиксельно дельта в режиме rccRGB — крупнейшая из разниц по красному, зелёному и синему каналам; в режиме rccLuminance — разница яркости по Rec. 709. Пиксель считается изменённым, когда его дельта превышает ColorTolerance. Цифра сходства — балл структурного сходства (SSIM), посчитанный по яркости всей страницы разом. Пара similar только когда доля изменённых пикселей не выше MaxChangedPixelRatio, а сходство не ниже MinimumSimilarity. Двое ворот, потому что пара сотен наглухо неверных пикселей в штрихкоде и лёгкий оттенок через всю страницу — разные виды сбоя, и каждый конвейер терпит их по-своему. Проверки порогов используют неокруглённые значения; шесть десятичных знаков в JSON держат отчёты стабильными от прогона к прогону
Изменённые пиксели группируются в регионы на сетке фиксированных плиток, по умолчанию 64 пикселя в квадрате, сращённых через четырёх соседей по рёбрам. Каждый регион в changedRegions даёт bounding box, счёт изменённых пикселей и крупнейшую дельту. Перечисляется не более MaxChangedRegions (по умолчанию 256); changedRegionCount всё равно репортит истинное число, а при урезанном списке взводится changedRegionsTruncated и пиксельный проход считается неполным. Со включённым GenerateHeatmaps каждая страница с изменёнными пикселями получает PNG с именем вроде page-000003-diff.png в HeatmapDirectory: страница первого файла с изменёнными пикселями, подкрашенными от жёлтого (едва за порогом) до красного (максимальная дельта), а её путь фигурирует в отчёте как overlayPath
Сбои репортятся, но никогда не проглатываются. Исключение рендерера, отсутствующий битмап или неверный размер страницы становятся записью renderError с сообщением, запись страницы получает статус error, а renderComparisonComplete уходит в false. Два рендера с разными пиксельными размерами получают статус sizeMismatch и отличие renderedImageSize с обоими размерами. Страница, которую никто не сумел сравнить, никогда не считается идентичной
Где какому режиму место в конвейере
Пиксельный проход парует страницы строго по индексу, страница i против страницы i, до конца более короткого документа. Выравнивание страниц бежит во всех режимах, кроме cmPageCount и cmRenderedImage. Со вставленной обложкой один cmRenderedImage пометит каждую страницу после неё, а cmFull даст выравнивание из структурной половины рядом с этими позиционными пиксельными результатами. Читайте структурный вердикт первым и верьте пиксельным результатам, только когда списки страниц сходятся
Гоняйте cmStructural на каждой сборке. Он дёшев, называет путь, индекс страницы и номера объектов, а неожиданный objectChanged указывает прямиком на код, который его породил. Держите cmFull с тепловыми картами для релиз-кандидатов и для проверки, что оптимизирующий проход действительно был без потерь, — когда рядом есть кто-то, кто взглянет на наложения. cmPageText подходит документам, где важно одно лишь слово. Есть и вариант рецензии на уровне разметки: экспорт страниц PDF в SVG даёт текстовый вид, который читают обычные инструменты сравнения, а проверки из статьи о автоматизации preflight-отчётов покрывают вопросы соответствия, на которые ни один режим сравнения не замахивается
Сравнение, preflight и рендеринг работают с одним и тем же загруженным документом THotPDF, так что одна загрузка может обслужить все три задачи. Всё, что компонент покрывает для разработчиков на Delphi и C++Builder, — на странице компонента HotPDF Delphi PDF