Техническая статья

Сравнение двух PDF-файлов в Delphi: структура и пиксели

Два PDF от одного генератора отчётов на одних и тех же данных, с прогона на прогон, редко совпадают байт в байт. Бинарное сравнение зажигает таблицу перекрёстных ссылок, номера объектов и часто программы шрифтов, тогда как оба файла печатают ровно одинаковые страницы. Сравнение отрисованных пикселей выглядит лекарством, пока кто-то не добавит титульный лист: с той поры каждая страница сидит на одну позицию дальше своей пары, и попиксельная проверка по страницам объявляет изменившимся весь документ. Сравнение, которое стоит автоматизировать, обязано отвечать на два разных вопроса — что изменилось внутри файла и увидел бы это читатель — и обязано знать, какая страница одного файла соответствует какой странице другого

Почему PDF-файлы могут отличаться побайтово, но быть визуально идентичными?

Большая часть байтового шума — учёт, который читатель никогда не видит. Номера объектов раздаются в том порядке, в каком райтеру случайно захотелось emit-ить объекты. Многие генераторы собирают подмножества шрифтов в порядке первого использования глифов, поэтому чуть иной обход даёт другие коды глифов, а значит и другие байты потока содержимого, для того же видимого текста. Смещения перекрёстных ссылок едут всякий раз, когда меняет длину что-то раньше по файлу, а это бывает почти всегда

Диаграмма HotPDF: структурный проход по графу объектов и проход по отрисованным пикселям на двух PDF-файлах в один JSON-отчёт сравнения
Оба прохода остаются внутри явных пределов, а JSON-отчёт спаривает identical с comparisonComplete и comparisonBudget, чтобы автоматизация никогда не приняла усечённый обход за настоящее различие

Так что номера объектов как межфайловая идентичность бесполезны. 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 отделяет их от настоящих правок

Диаграмма: наивное парное сопоставление страниц PDF позиция за позицией против сигнатурного выравнивания HotPDF через наибольшую возрастающую подпоследовательность
Выравнивание по подписям совмещает сдвинутые исходные страницы и изолирует вставленную обложку, превращая сотни ложных срабатываний в одну читаемую строку

Выровненные пары проходят ещё одну проверку в структурных режимах. Словарь страницы подписывается второй раз без /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 держат отчёты стабильными от прогона к прогону

Диаграмма двух порогов сходства в сравнении отрисованных страниц HotPDF: допуск цвета, доля изменённых пикселей и минимальное сходство
Пара схожа, только когда доля изменившихся пикселей и похожесть вместе проходят оба порога, а неудавшаяся отрисовка фиксируется, а не молча именуется идентичной

Изменённые пиксели группируются в регионы на сетке фиксированных плиток, по умолчанию 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