ComparePDF проверяет два PDF-файла в текстовом или визуальном режиме, сообщает о совпадении либо различии и возвращает отдельный код результата, который удобно использовать в сценариях автоматической проверки. Текстовый режим сопоставляет извлечённое содержимое страниц, визуальный — их отрисованный вид, а параметр подробности позволяет оставить только код возврата или вывести краткое сообщение.

Работа начинается с одной команды, в которой указываются два файла: эталон и проверяемый документ. При совпадении программа завершает проверку с нулевым кодом, при различии текста, внешнего вида или количества страниц возвращает разные ненулевые значения, поэтому результат можно передавать сборочной системе, тестовому сценарию или пакетной обработке без разбора длинного отчёта.

Главное ограничение подхода состоит в том, что ComparePDF отвечает на вопрос о наличии различия, но не рисует его поверх страниц и не перечисляет изменённые фрагменты. Для надёжной работы нужно заранее выбрать подходящий режим, убедиться, что страницы сопоставлены в одинаковом порядке, а затем при ненулевом результате открыть пару в инструменте, который умеет визуально локализовать правки.

Как ComparePDF принимает решение о совпадении

ComparePDF не пытается превратить два документа в единую размеченную копию. Программа последовательно открывает оба файла, проверяет количество страниц и только затем сравнивает соответствующие страницы выбранным способом. Такой порядок важен: документ с добавленной или удалённой страницей получает отдельный код результата ещё до анализа текста или изображения, а последующие страницы не сдвигаются автоматически. Если один лист вставлен в середину, все пары после него считаются несопоставленными, поэтому перед запуском нужно либо привести документы к одинаковой структуре, либо сравнивать подготовленные фрагменты.

Проверка прекращается при первом установленном отличии. Это ускоряет простой контроль совпадает или нет, особенно в сборочном конвейере, но не даёт количества изменённых страниц и не гарантирует, что первое замеченное расхождение является единственным. Ненулевой код следует трактовать как сигнал для следующего шага: сохранить проблемную пару, запустить более подробный инструмент или открыть документы рядом. Попытка использовать краткое сообщение как полный протокол приводит к неверным выводам, потому что строка описывает только класс результата.

В программе нет проекта, списка заданий и окна предварительного просмотра. Все параметры задаются при каждом запуске, поэтому воспроизводимость зависит от команды, окружения и стабильности движка отрисовки. Хорошая практика — хранить рядом с тестами саму команду, ожидаемый код и сведения о том, какой режим считается значимым для конкретного документа. Тогда одинаковая пара проверяется одинаково на рабочем компьютере и в автоматической сборке.

Синтаксис команды и обязательные аргументы

Базовая форма состоит из имени команды, необязательных параметров и двух путей к PDF. Первый файл обычно назначают эталоном, второй — результатом новой сборки, хотя алгоритм сравнения симметричен и не выделяет старую или новую сторону. Оба имени должны иметь расширение PDF, а количество позиционных аргументов должно быть ровно два. При пропущенном пути или лишнем третьем файле проверка не начинается и возвращается ошибка ввода.

comparepdf [параметры] эталон.pdf результат.pdf

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

comparepdf -ct -v=2 '/data/reference/report final.pdf' '/data/build/report final.pdf'

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

Параметры режима

• Ключ -ct или --compare=text включает сравнение извлечённого текста; этот режим используется и без явного ключа.
• Ключ -ca или --compare=appearance включает сравнение отрисованного вида страниц.
• Ключ -v=0 отключает информационные сообщения, оставляя сценарию только код завершения.
• Ключ -v=1 сообщает об отличии, но молчит при полном совпадении.
• Ключ -v=2 сообщает и о различии, и об успешном совпадении.
• Ключи --help и --version выводят справочные сведения и не требуют пары документов.

Уровень подробности не меняет способ анализа и код результата. Он управляет только текстом в стандартном выводе, поэтому переход с -v=2 на -v=0 не делает проверку менее строгой. В автоматизации полезно отделять машинный канал от человеческого: код сохранять всегда, а сообщения включать при диагностике или писать в журнал только для проблемных пар.

Текстовый режим: что именно сопоставляется

В текстовом режиме каждая страница передаётся библиотеке Poppler, которая возвращает текстовые фрагменты. ComparePDF соединяет текст этих фрагментов в последовательность и сравнивает получившиеся строки для одинаковых номеров страниц. Поэтому режим реагирует на замену букв, цифр, пунктуации и доступного извлечению текста, но его результат зависит от того, как конкретный PDF кодирует символы и в каком порядке библиотека их извлекает.

Совпадение текста не означает совпадение оформления. Изменение шрифта, цвета, координат абзаца, толщины линии или рисунка может не затронуть извлечённую последовательность. Такой результат полезен для контроля смыслового содержимого отчётов, счетов и форм, где допустимо перераспределение строк, но опасен для полиграфических макетов и документов, в которых расположение элементов имеет юридическое или производственное значение.

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

Когда текстовый режим подходит лучше всего

1. Проверка автоматически сформированных отчётов, где числа и подписи должны остаться прежними, а перенос строк допускается.
2. Контроль счетов и актов после изменения шаблона, если требуется быстро отсеять документы с изменившимися реквизитами.
3. Регрессионный тест генератора PDF, в котором оформление проверяется отдельно, а здесь контролируется только читаемое содержимое.
4. Сопоставление двух экспортов из одной системы при стабильной структуре страниц и встроенном текстовом слое.
5. Проверка локализации, когда ожидается изменение конкретных строк и последующий ручной разбор ненулевого результата.

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

Визуальный режим: точное сравнение отрисованных страниц

В режиме appearance каждая соответствующая страница отрисовывается в изображение, после чего ComparePDF проверяет точное равенство полученных массивов пикселей. Этот метод обнаруживает изменения в расположении текста, картинках, линиях, цветах, шрифтах и других видимых элементах. Он подходит для регрессионной проверки шаблонов и макетов, когда любое изменение внешнего вида должно остановить процесс.

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

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

Почему визуально одинаковые файлы иногда различаются

• Один PDF использует встроенный шрифт, а другой ссылается на системную замену с немного иной метрикой.
• Прозрачность, тени или градиенты обрабатываются разными сборками библиотек с отличающимся округлением.
• В одном документе изменены координаты объекта на долю точки, что заметно после растеризации.
• Растровая картинка пережата другим кодеком или содержит другой профиль цвета.
• Скрытый слой, обрезка или порядок наложения объектов влияет на итоговый пиксель, хотя правка почти незаметна глазом.
• Страница имеет иной размер, поворот или рамки MediaBox и CropBox.

Если процесс допускает незначительные пиксельные отклонения, ComparePDF не сможет выразить такой допуск. Следует либо стабилизировать окружение, либо применять инструмент с настраиваемым порогом и отчётом. Снижать строгость переходом в текстовый режим допустимо только тогда, когда внешний вид действительно не входит в критерий качества.

Коды завершения и надёжная автоматизация

Код завершения является главным машинным результатом. Ноль означает, что выбранная проверка не нашла различий. Единица относится к ошибкам выполнения или ввода, двойка — к ошибке разбора параметров, десять — к различию внешнего вида, тринадцать — к различию текста, пятнадцать — к неодинаковому количеству страниц. Эти значения позволяют отличить дефект документа от неверного запуска и не смешивать все ненулевые результаты в одно сообщение.

Код	Значение	Рекомендуемое действие
0	Совпадение	Продолжить процесс и отметить тест успешным.
1	Ошибка чтения или аргументов	Проверить пути, доступ, блокировку и целостность файлов.
2	Ошибка параметров	Исправить ключ или форму его значения.
10	Различается внешний вид	Сохранить пару и выполнить визуальную локализацию правки.
13	Различается текст	Извлечь текст или открыть документы рядом для проверки содержания.
15	Разное число страниц	Проверить вставку, удаление или порядок листов.

Сценарий не должен использовать только конструкцию команда успешна или нет, если ему важно различать причины. Простая проверка через логическое отрицание объединит коды 1, 2, 10, 13 и 15, и ошибка пути станет выглядеть как регрессия документа. Надёжнее сначала сохранить значение в переменную, затем явно обработать ожидаемые классы.

comparepdf -ct -v=0 reference.pdf result.pdf
rc=$?
case "$rc" in
  0)  echo "PDF совпадает" ;;
  13) echo "Изменился текст"; exit 1 ;;
  15) echo "Изменилось число страниц"; exit 1 ;;
  *)  echo "Ошибка проверки, код $rc"; exit 2 ;;
esac

Для визуального теста ожидаемым кодом различия будет 10, а текстовый код 13 в этом запуске появиться не должен. Если один сценарий последовательно выполняет оба режима, сохраняйте результаты отдельно: первый запуск может подтвердить текст, второй — обнаружить изменение оформления. Итоговый статус тогда объясняет, какой критерий нарушен.

Подробность вывода в интерактивной работе

При ручной проверке удобно использовать -v=2: пользователь получает подтверждение совпадения и не задаётся вопросом, запускалась ли команда. В большом цикле этот уровень создаёт множество строк, поэтому обычно выбирают -v=0 и печатают собственную строку с именем пары и кодом. Значение -v=1 подходит для журнала, где успешные сравнения должны оставаться бесшумными, а отличия — появляться сразу.

Сообщение не заменяет код. При различном количестве страниц программа возвращает 15, но формулировка зависит от выбранного режима и может выглядеть как обычное текстовое или визуальное отличие. Скрипт, который ищет слова в сообщении, потеряет специальный смысл кода 15. Чтение `$?`, `returncode` или аналогичного свойства процесса надёжнее и не зависит от языка оболочки.

Количество страниц и проблема смещения

Проверка числа страниц выполняется до содержательного анализа. Если в эталоне один лист, а в новом файле два, программа сразу завершится с кодом 15. Это полезный быстрый контроль полноты, но он не отвечает, где появился лишний лист и совпадают ли остальные страницы. Для пакетной диагностики следует отдельно записывать число страниц обоих файлов, чтобы журнал сразу показывал масштаб структурного изменения.

Одинаковое число страниц не гарантирует правильного сопоставления. Если из начала удалена одна страница и в конец добавлена другая, количество останется прежним, но все промежуточные пары будут сдвинуты. ComparePDF не ищет наиболее похожие страницы и не умеет задавать диапазоны соответствия. Перед запуском такого набора нужно выделить сопоставимые страницы в отдельные PDF или воспользоваться программой, где можно вручную назначить пары.

Для отчётов с необязательными приложениями удобно разделить контроль на два уровня. Сначала проверять обязательную основную часть, формируемую с фиксированным количеством листов, затем отдельно проверять наличие и состав приложений. Так код 15 не скрывает успешное совпадение ключевого раздела и не превращает любое дополнительное вложение в неразборчивый общий отказ.

Подготовка файлов перед сравнением

Качество результата начинается до запуска. Оба документа должны полностью записаться на диск, быть доступны текущему пользователю и открываться без запроса пароля. В автоматическом процессе сравнение нельзя начинать одновременно с экспортом: частично записанный файл может не загрузиться или содержать неполную таблицу объектов. Безопасный вариант — создавать результат под временным именем, закрывать его, атомарно переименовывать и только затем запускать ComparePDF.

Проверяйте, что пути указывают на обычные файлы, а не на каталоги, символические ссылки с недоступной целью или нулевые заготовки. Размер сам по себе не является критерием совпадения: два логически одинаковых PDF могут иметь разные метаданные, сжатие и внутреннюю структуру. ComparePDF анализирует текст или отрисованный вид, поэтому отличие байтов не обязательно приводит к отличию результата, а совпадение размера ничего не доказывает.

Перед визуальной проверкой полезно убедиться, что в окружении доступны нужные шрифты. Если PDF не включает шрифт полностью, библиотека подберёт замену, и эталон, созданный на другом компьютере, может отрисоваться иначе. Наиболее стабильная схема — генерировать и сравнивать документы в одном образе системы, хранить шрифты как контролируемую зависимость и обновлять эталоны только после осознанного изменения окружения.

Проверка текстового слоя

Для цифрового PDF попробуйте выделить и скопировать несколько строк из каждого файла. Если порядок букв нарушен, символы заменяются квадратами или текст отсутствует, режим -ct будет отражать особенности внутренней кодировки, а не только читаемую надпись. В таких случаях сначала проверяют извлечение текста отдельной командой, затем решают, считать ли это дефектом документа или перейти к визуальному критерию.

В сканированном документе видимые слова часто находятся только внутри изображения. Результат распознавания может быть скрыт под картинкой и не совпадать с тем, что читает человек. ComparePDF обнаружит правку скрытого слоя даже при одинаковом скане, а без слоя может пропустить замену изображения в текстовом режиме. Для контроля сканов визуальный режим является обязательным, а текстовый полезен как дополнительная проверка качества распознавания.

Пароли, ограничения доступа и повреждённые PDF

Защищённый файл, который библиотека считает заблокированным, не сравнивается. В командной строке нет параметра для передачи пароля, поэтому документ нужно заранее открыть разрешённым средством и сохранить доступную для обработки копию, соблюдая правила организации. Не следует помещать пароль в имя файла, переменную команды или журнал: ComparePDF всё равно его не использует, а секрет может остаться в истории оболочки.

Сообщение о невозможности загрузки также появляется для несуществующего пути, отсутствия прав, некорректного PDF и некоторых ошибок парсера. Код 1 не различает эти причины детально. Диагностика начинается с проверки существования и размера, затем прав чтения, после чего файл открывают независимым валидатором или просмотрщиком. Если один просмотрщик показывает документ, это ещё не гарантирует, что Poppler сможет разобрать все его объекты.

Повреждённые перекрёстные таблицы и нестандартные конструкции иногда автоматически исправляются просмотрщиком при открытии. Сравнивать исходный дефектный файл с исправленной копией нежелательно: результат будет зависеть от восстановительной логики. Сначала нормализуйте оба документа одинаковым инструментом либо устраните проблему генератора, а затем применяйте ComparePDF к устойчивым выходным файлам.

Ошибки аргументов и путей

Если указан только один PDF, программа сообщает, что нужны два файла, и не начинает анализ. Та же логика срабатывает при лишнем позиционном аргументе. В циклах это часто случается из-за пустой переменной без кавычек или шаблона, раскрывшегося в несколько имён. Выводите сформированную команду в отладочном режиме и всегда заключайте переменные путей в двойные кавычки.

Имя, начинающееся с дефиса, оболочка или парсер может принять за параметр. Надёжнее использовать абсолютный путь, начинающийся с корня, либо предварять относительное имя компонентом `./`. В производственном наборе файлов полезно ограничить допустимые символы в именах, но это не отменяет правильного экранирования.

Не смешивайте стандартный вывод программы с собственным значением кода в одной переменной. Командная подстановка возвращает текст, но код нужно сохранить сразу после завершения процесса. Любая промежуточная команда, даже `echo`, перезаписывает `$?`. Сначала присвойте `rc=$?`, затем печатайте сообщения и выполняйте очистку.

Пакетная проверка каталога

ComparePDF обрабатывает только одну пару за запуск, поэтому сопоставление каталогов строится внешним циклом. Главная задача — правильно образовать пары. Совпадение только по порядку выдачи файлов ненадёжно: сортировка может различаться, а отсутствующий документ сдвинет все последующие элементы. Лучше использовать относительное имя как ключ и для каждого эталона искать файл с тем же путём в каталоге результата.

reference=/data/reference
build=/data/build
find "$reference" -type f -name "*.pdf" -print0 |
while IFS= read -r -d "" old; do
  rel=${old#"$reference"/}
  new="$build/$rel"
  if [ ! -f "$new" ]; then
    printf "MISSING %s\n" "$rel"
    continue
  fi
  comparepdf -ct -v=0 "$old" "$new"
  rc=$?
  printf "%s %s\n" "$rc" "$rel"
done

Отдельно проверяйте файлы, которые появились только в новом каталоге. Цикл по эталону обнаружит отсутствующие результаты, но не заметит лишние документы. Второй проход или построение двух отсортированных списков относительных путей решает эту задачу до содержательного сравнения. Таким образом структурная полнота набора и совпадение пар фиксируются разными проверками.

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

Параллельный запуск

Несколько независимых пар можно проверять параллельно, если хватает памяти и процессорного времени. Визуальный режим отрисовывает страницы и обычно тяжелее текстового, поэтому неконтролируемый запуск десятков процессов способен замедлить систему сильнее, чем последовательная обработка. Установите небольшое число рабочих процессов и измерьте время на типичных многостраничных документах.

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

Использование в непрерывной интеграции

В CI эталонные PDF хранят как тестовые данные, а новый файл создаётся во время сборки. После генерации запускают ComparePDF с тихим выводом, сохраняют код и помечают задание неуспешным только после копирования артефактов диагностики. Если завершить шаг немедленно, система может удалить временный каталог и оставить разработчика без пары, на которой воспроизводится расхождение.

Эталон должен меняться через осознанную процедуру. Автоматическая замена эталона новым файлом при любом отличии уничтожает смысл регрессионного теста. Разработчик сначала выясняет причину, подтверждает ожидаемую правку, просматривает документ и только затем обновляет контрольный файл вместе с изменением кода или шаблона.

Для стабильного визуального теста закрепляют образ системы, пакет шрифтов, локаль, часовой пояс и библиотеку отрисовки. Дата, имя пользователя и случайный идентификатор внутри видимого содержимого тоже делают результат нестабильным. Такие значения лучше подменять фиксированными тестовыми данными; удаление метаданных не поможет, если дата напечатана на странице.

set +e
comparepdf -ca -v=0 tests/reference.pdf build/result.pdf
rc=$?
set -e
cp build/result.pdf artifacts/result.pdf
cp tests/reference.pdf artifacts/reference.pdf
exit "$rc"

Пример намеренно отключает немедленный выход оболочки вокруг сравнения. При `set -e` ненулевой код различия может завершить шаг до копирования файлов. После сохранения пары возвращается исходный код, и система сборки получает корректный итог. Для различения ошибки инструмента и регрессии код можно преобразовать в разные статусы или сообщения.

Двухступенчатая проверка: текст, затем внешний вид

Во многих процессах полезно сначала запускать быстрый текстовый контроль, затем визуальный. Если текст изменился, причина уже относится к содержанию, и дорогое сравнение внешнего вида можно выполнить только для диагностики. Если текст совпал, но внешний вид отличается, круг поиска сужается до шрифтов, координат, изображений и параметров страницы.

1. Запустить -ct с -v=0 и сохранить код.
2. При коде 13 отметить содержательное расхождение и сохранить пару.
3. При коде 15 остановить проверку как структурное расхождение.
4. При коде 0 запустить -ca в том же окружении.
5. При коде 10 отметить изменение оформления; при коде 0 считать оба критерия выполненными.
6. Коды 1 и 2 всегда трактовать как неисправность процесса, а не как различие документа.

Такой порядок не означает, что текстовый режим всегда быстрее на любом PDF, но он даёт более содержательную классификацию. Для сканов без текста порядок можно поменять или отказаться от первого шага. Критерий должен соответствовать типу документа, а не применяться механически ко всем файлам организации.

Практические сценарии применения

Счета и платёжные документы

В эталоне фиксируют тестовые реквизиты, суммы и подписи. Текстовый режим быстро обнаруживает изменение числа, валюты или назначения платежа, тогда как перенос строки может остаться допустимым.

Если расположение полей строго задано формой, после успешного текста выполняют визуальную проверку. Динамическую дату и номер документа заменяют предсказуемыми тестовыми значениями, иначе каждое выполнение будет отличаться.

При ненулевом коде сохраняют оба PDF и извлечённый текст; это позволяет отделить изменение данных от проблемы кодировки шрифта.

Ежемесячные отчёты

Генератор запускают на фиксированном наборе данных, чтобы таблицы, итоги и подписи были воспроизводимы. ComparePDF проверяет, что изменение кода не повлияло на ожидаемый документ.

Текстовый режим полезен для числовых значений, визуальный — для ширины столбцов, переносов и диаграмм. Если диаграмма строится из растрового изображения, только визуальная проверка заметит её замену.

Нестабильный порядок строк в исходных данных нужно устранить до сравнения; иначе программа честно фиксирует перестановку, но тест не указывает причину.

Договоры из шаблонов

Для теста используют обезличенные фиксированные данные и одинаковый набор приложений. Текстовый код выявляет пропавший пункт, заменённую формулировку или неверный реквизит.

Визуальный код нужен для контроля разрывов страниц, положения подписи и нумерации. ComparePDF не подсветит конкретный пункт, поэтому проблемную пару передают юридическому редактору или средству подробного сравнения.

При вставке новой страницы код 15 возникает раньше содержательного анализа; структуру приложений проверяют отдельно.

Технические руководства

Сборка документации может менять оглавление, номера страниц, рисунки и листинги. Эталон создают для небольшой стабильной конфигурации, а не для постоянно меняющегося полного руководства.

Текстовый режим обнаруживает потерянный абзац или подпись, визуальный — сдвинутый рисунок и обрезанный код. Автоматические даты сборки исключают или фиксируют.

Если ожидаемо добавлен раздел, обновляют эталон только после просмотра всей новой сборки, поскольку программа остановилась на первом отличии.

Печатные формы

Для бланков важны координаты полей, размеры страницы и линии. Основным делают визуальный режим, а текстовый оставляют дополнительным контролем подписей.

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

После кода 10 страницы отрисовывают и накладывают внешним инструментом, чтобы определить направление сдвига.

Регрессия PDF-библиотеки

Набор эталонов включает простой текст, изображения, прозрачность, разные размеры страниц и встроенные шрифты. Каждая пара запускается отдельно, а журнал сохраняет код режима.

Совпадение текста при визуальном отличии часто указывает на изменение метрик, растеризации или геометрии. Различие обоих режимов может означать иное разбиение текстовых объектов либо настоящую правку содержания.

Нельзя автоматически признать новый результат правильным только потому, что библиотека была обновлена; эталоны пересматривают по одному.

OCR-процесс

После распознавания проверяют скрытый текстовый слой и вид исходного скана. Текстовый режим показывает изменение результата OCR, визуальный — изменение изображения страницы.

Если обработчик выравнивает, очищает фон или сжимает картинку, визуальное отличие ожидаемо и оценивается отдельно. Пустой текст на обеих страницах не является подтверждением равенства сканов.

Полезно хранить эталонный извлечённый текст, потому что ComparePDF сообщает только факт первого расхождения.

Миграция хранилища

После переноса или нормализации PDF байтовые контрольные суммы могут измениться, хотя страницы сохраняют содержание и вид. ComparePDF помогает проверить пользовательски значимые представления.

Сначала сравнивают количество страниц и текст, затем выборочно или полностью внешний вид. Метаданные, закладки, вложения и интерактивность этим методом не проверяются и требуют отдельных валидаторов.

Успех обоих режимов не доказывает сохранность всех структур PDF; он подтверждает только извлекаемый текст и отрисованные страницы.

Локализация

Для каждой языковой пары эталоном служит утверждённый PDF того же языка. Сравнение между разными языками бессмысленно, потому что текст закономерно отличается.

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

Порядок извлечения для сложной письменности следует проверить заранее; при нестабильности главным становится визуальный критерий.

Электронные формы

ComparePDF видит отрисованное состояние полей и доступный текст, но не сравнивает структуру виджетов, сценарии и правила проверки как отдельные сущности.

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

Пустое и заполненное поле даст ожидаемое различие; код не объяснит, какое поле изменилось.

Подписанные документы

Криптографическую действительность подписи ComparePDF не проверяет. Визуальное сравнение может заметить изменившийся штамп, а текстовое — видимую подпись, но статус сертификата требует отдельной проверки.

Переподписание часто меняет внутренние байты и метаданные без изменения страниц; это не мешает выбранным режимам совпасть.

Нельзя использовать нулевой код как доказательство подлинности или целостности электронной подписи.

Оптимизация размера

После сжатия PDF проверяют, сохранился ли текст и внешний вид. Текстовый режим выявляет потерю символов, визуальный — заметные изменения изображений и рендеринга.

Точное пиксельное равенство может быть слишком строгим для допустимого пережатия JPEG, поэтому при целевой оптимизации нужен инструмент с порогом качества или ручная оценка.

ComparePDF подходит как строгий фильтр: ноль подтверждает отсутствие обнаруженного изменения, а код 10 требует дальнейшего анализа, но не обязательно означает неприемлемое качество.

Экспорт из офисных документов

Фиксируют входной файл, набор шрифтов и параметры экспорта. Текстовый режим обнаруживает пропавшие символы и значения, визуальный — изменение пагинации и оформления.

Поля даты, номера страниц, автоматические ссылки и состояние принтера могут делать экспорт неповторяемым. Их стабилизируют до создания эталона.

Если изменился движок офисного пакета, массовое визуальное отличие может быть следствием метрик шрифтов, а не правки шаблона.

Генерация этикеток

Важны точные размеры листа, штрихкоды, подписи и координаты. Основным является визуальный режим, а данные под штрихкодом дополнительно контролируют текстом, если они присутствуют как символы.

ComparePDF не проверяет считываемость штрихкода, поэтому после совпадения страниц нужен тест декодирования.

Код 10 сообщает о любом пиксельном изменении, но не оценивает, нарушено ли технологическое поле или контраст.

Публикация каталогов

Каталог содержит текст, цены, фотографии и сложную верстку. На небольшом фиксированном наборе данных оба режима хорошо выявляют регрессию шаблона.

На полном каталоге ранняя остановка означает, что журнал не содержит списка всех изменённых товаров. Для массовой экспертной сверки нужен отчётный инструмент.

ComparePDF полезен как автоматический шлюз перед подробной проверкой: он быстро отбрасывает полностью совпавшие пары.

Научные графики

Текстовый режим проверяет подписи осей и числа, а визуальный — линии, маркеры и расположение легенды. При случайных данных генератор должен получать фиксированное зерно.

Различия сглаживания между графическими библиотеками способны дать код 10 без содержательной перемены.

Эталон и результат строят в одном контейнере; затем реальное изменение графика локализуют сравнением изображений.

Медицинские отчёты

Тестовые документы должны использовать синтетические данные. Текстовая проверка обнаруживает пропущенные показатели и единицы, визуальная — неверное расположение таблиц.

Нулевой код не является клинической валидацией и не проверяет смысл чисел; он лишь подтверждает совпадение с конкретным эталоном.

Доступ к проблемным парам ограничивают так же, как к другим чувствительным данным, а журналы не должны содержать полный текст пациента.

Государственные формы

Формы часто требуют фиксированного размера, положения полей и неизменных подписей. Визуальный режим выявляет сдвиг, текстовый — замену формулировки.

Если ведомство обновило бланк, старый эталон закономерно перестанет совпадать. Новый эталон утверждают после проверки требований, а не автоматически.

Наличие одинакового изображения не подтверждает корректность интерактивных полей или доступности документа.

Проверка резервной копии

После восстановления PDF можно сравнить с исходным документом не только по байтам, но и по извлекаемому тексту и отрисовке. Это полезно, если система хранения нормализует контейнер.

Однако вложенные файлы, комментарии, закладки и метаданные могут измениться незаметно для двух режимов.

Для полного контроля ComparePDF дополняют хешами исходных файлов и структурным анализом PDF.

Приёмка от подрядчика

Заказчик хранит утверждённый эталон и запускает автоматическую проверку полученного PDF. Ноль позволяет быстро принять технически совпавший файл, ненулевой код направляет пару на ручную экспертизу.

Критерий заранее прописывают: допустима ли смена оформления при том же тексте, или требуется точное визуальное совпадение.

Без согласованного критерия код 10 может вызвать спор из-за незначительной растеризации, а текстовый ноль — пропустить важный сдвиг макета.

Производительность и расход ресурсов

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

Для измерения производительности используйте документы, похожие на производственные, и разделяйте время генерации и сравнения. Кэш файловой системы и шрифтов влияет на повторные запуски. Если один огромный PDF регулярно проверяется целиком, можно дополнительно создавать тестовые фрагменты для быстрых проверок, но полный контроль оставлять отдельным этапом.

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

Что ComparePDF не проверяет

• Закладки, именованные назначения и структуру навигации, если они не влияют на отрисованную страницу или извлечённый текст.
• Вложения, мультимедиа, слои и комментарии как отдельные объекты.
• Корректность электронной подписи, сертификата и отметки времени.
• Соответствие PDF/A, PDF/X, требованиям доступности или корпоративному профилю.
• Сценарии JavaScript, действия кнопок и логику интерактивной формы.
• Порядок внутренних объектов, степень сжатия, метаданные и байтовую идентичность.
• Местоположение каждого различия и полный список изменённых страниц.

Эти ограничения не делают результат бесполезным; они задают его границы. ComparePDF отвечает на узкий вопрос о равенстве извлечённого текста или отрисованного вида двух последовательностей страниц. Для утверждений о стандарте, безопасности, подписи или полной структуре нужен отдельный тест, а нулевой код следует записывать именно как выполнение выбранного критерия.

Диагностика типичных результатов

Симптом	Вероятная причина	Что проверить
Код 13, страницы кажутся одинаковыми	Разный скрытый текст, порядок объектов или кодировка	Извлечь текст из каждой страницы и сравнить последовательность символов.
Код 10, текст совпадает	Изменились шрифт, координаты, изображение или отрисовка	Открыть страницы рядом и получить пиксельную карту отличий внешним средством.
Код 15	Добавлен, удалён или не сформирован лист	Сравнить число страниц и этапы сборки документа.
Код 1 для одного файла	Путь, права, пароль или повреждение	Проверить существование, чтение и открытие библиотекой PDF.
Код 2	Неверный ключ или форма значения	Сверить синтаксис --compare и --verbose.
Текстовый ноль для разных сканов	Нет извлекаемого текстового слоя	Перейти к -ca и проверить OCR отдельно.
Много визуальных отказов после обновления окружения	Изменился рендеринг или шрифты	Повторить в прежнем контейнере и сравнить зависимости.
В цикле пропущены файлы	Неверное образование пар	Сопоставлять относительные пути, проверять лишние и отсутствующие имена.

Начинать диагностику нужно с кода, затем с режима, и только потом с сообщения. Такая последовательность исключает две частые ошибки: принятие ошибки чтения за содержательную правку и попытку искать текстовую замену после визуального кода. Сохранённая команда должна быть частью отчёта об отказе, иначе воспроизведение будет зависеть от догадок.

Безопасность и конфиденциальность процесса

ComparePDF читает файлы, указанные в команде, и не требует отправлять их в удалённый кабинет. Это удобно для закрытых документов, но безопасность определяется всей средой: правами каталога, журналированием оболочки, местом хранения эталонов и диагностических копий. Не размещайте чувствительные имена и данные в общедоступных логах CI.

Запускайте программу с минимальными правами в отдельном рабочем каталоге. PDF является сложным форматом, поэтому входные файлы от недоверенной стороны лучше обрабатывать в контейнере или изолированной учётной записи с ограниченными ресурсами. Сам факт успешного сравнения не означает, что файл безопасен; антивирусная и структурная проверка решают другую задачу.

При сохранении проблемной пары задайте срок хранения и контроль доступа. Ненулевой код может возникнуть на документе с персональными или коммерческими данными, и автоматическое прикрепление обоих PDF к открытому заданию разработки создаст утечку. Для журнала часто достаточно относительного идентификатора, кода и защищённого пути к артефакту.

Сравнение ComparePDF с аналогами

Выбор аналога зависит от того, нужен ли только машинный ответ, подробная визуальная локализация или интерактивная работа специалиста. ComparePDF особенно силён в простом двоичном контроле двух файлов, но уступает инструментам, которые формируют отчёт, допускают порог пиксельного различия или позволяют сопоставлять диапазоны страниц.

Программа	Лучше подходит для	Главное ограничение
ComparePDF	Коротких автоматических проверок текста или внешнего вида по коду завершения	Не показывает место и состав правок.
DiffPDF	Ручного сравнения текста и оформления с просмотром страниц	Рабочий процесс ориентирован на интерактивное окно.
comparepdfcmd	Автоматизации с PDF-отчётом и подсветкой различий	Предназначен для Windows и распространяется коммерчески.
diff-pdf	Визуальной регрессии с созданием файла различий	Не заменяет содержательное сравнение извлечённого текста.
Adobe Acrobat Pro	Редакторской сверки с наглядным отчётом и переходом по изменениям	Требует платной профессиональной поставки и ручного процесса.
PDiff	Профессиональной интерактивной сверки документов и синхронного просмотра	Коммерческий продукт с более сложным рабочим процессом.

Для беззвучного теста в сценарии выбирайте ComparePDF: он легко встраивается в оболочку и различает классы результата кодами. Для поиска конкретной строки или области удобнее DiffPDF либо Acrobat Pro. Если автоматизация должна отдавать человеку готовый PDF с подсветкой, ближе comparepdfcmd или diff-pdf. PDiff уместен там, где оператор регулярно проводит подробную сверку и нужен развитый экран анализа, а не только пропускной тест.

Как выбрать режим для конкретного документа

1. Определите, что считается дефектом: изменившиеся символы, любое визуальное отклонение или оба события.
2. Проверьте наличие качественного текстового слоя и стабильность порядка извлечения.
3. Убедитесь, что страницы имеют одинаковую структуру и порядок; при вставках подготовьте сопоставимые фрагменты.
4. Для визуального критерия закрепите шрифты, библиотеку отрисовки и системное окружение.
5. Выберите уровень подробности: -v=2 для ручной проверки, -v=0 для сценария с собственной обработкой.
6. Явно обработайте коды 0, 1, 2, 10, 13 и 15, не объединяя ошибки запуска с различиями.
7. Сохраняйте проблемную пару до завершения задания и передавайте её инструменту локализации правок.
8. Дополните проверку валидатором, если важны подписи, стандарты, формы, вложения или доступность.

Если критерий невозможно сформулировать без слов примерно одинаково, точный визуальный режим, вероятно, окажется слишком строгим. В таком случае нужен инструмент с числовым порогом, масками областей или исключением динамических зон. ComparePDF не скрывает эту сложность настройками: он либо получает одинаковое представление, либо возвращает отличие.

Ответы на практические вопросы

Можно ли получить файл с подсветкой изменений?

Нет. ComparePDF выводит краткую строку и код, но не создаёт PDF, изображение или HTML с отмеченными областями. После ненулевого результата используйте отдельное средство визуального сравнения или отрисуйте страницы и постройте карту отличий.

Можно ли сравнить только выбранные страницы?

В командных параметрах нет диапазонов страниц и ручного сопоставления. Извлеките нужные листы в два временных PDF с одинаковым порядком и сравните получившуюся пару. При автоматизации фиксируйте правило извлечения, чтобы тест оставался воспроизводимым.

Можно ли сравнивать Word, изображения или другие форматы?

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

Почему код отличается, а сообщение выглядит одинаково?

Краткая фраза описывает выбранный режим, тогда как код 15 отдельно обозначает несовпадение количества страниц. Всегда считывайте код процесса; текст предназначен для человека и не содержит всей классификации.

Можно ли передать пароль?

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

Почему текст совпал, а страницы выглядят по-разному?

Режим -ct сравнивает извлечённую последовательность символов, а не шрифт, цвет, координаты и рисунки. Запустите -ca, если оформление входит в критерий.

Почему визуальный режим отказал после обновления системы?

Измениться могли Poppler, Qt, шрифты или параметры растеризации. Повторите тест в закреплённом окружении и сравните список зависимостей. Обновлять все эталоны без просмотра нельзя, потому что среди системных отличий может скрываться настоящая регрессия.

Как сравнить тысячу файлов?

Сформируйте пары по относительному пути, запускайте одну команду на пару, ограничьте параллелизм и сохраняйте код для каждого имени. Отдельно найдите отсутствующие и лишние документы. ComparePDF не обходит каталоги без внешнего цикла.

Подходит ли нулевой код для доказательства идентичности PDF?

Он доказывает только отсутствие различий в выбранном представлении при данном запуске. Внутренняя структура, метаданные, вложения, подписи и интерактивные элементы могут различаться. Для байтовой идентичности применяют хеш, для структурной — специализированный анализ.

Установка и проверка рабочей среды

В системах семейства Debian и Ubuntu ComparePDF поставляется как пакет с исполняемым файлом и зависимостями Qt и Poppler. После установки сначала вызовите справку и выполните контроль на двух копиях одного небольшого PDF. Такой тест одновременно подтверждает доступность команды, чтение формата, работу библиотек и правильное получение нулевого кода оболочкой. Проверять только строку с информацией о выпуске недостаточно: она не открывает PDF и не затрагивает движок сравнения.

comparepdf --help
cp sample.pdf sample-copy.pdf
comparepdf -ct -v=2 sample.pdf sample-copy.pdf
echo $?

Если оболочка сообщает, что команда не найдена, проверьте наличие исполняемого файла в каталогах PATH и установку пакета для архитектуры системы. Если команда запускается, но не может загрузить любой PDF, проверьте совместимость библиотек через менеджер пакетов, а не копируйте отдельный бинарник без зависимостей из другой системы. Qt обеспечивает базовую инфраструктуру приложения, Poppler отвечает за разбор, извлечение текста и отрисовку; неполный набор библиотек делает результат непредсказуемым или не позволяет запустить процесс.

В контейнере пакет добавляют на этапе сборки образа, а не скачивают при каждом тесте. Это делает зависимость явной и закрепляет одинаковое окружение для эталона и результата. После изменения базового образа выполняют контрольный набор документов обоими режимами: текст может остаться стабильным, а пиксельная отрисовка измениться из-за новых шрифтов или библиотек.

Права и рабочие каталоги

Процессу нужны права чтения обоих PDF и выполнения самой команды. Права записи требуются только вашей обвязке, если она копирует проблемные пары и создаёт журнал; ComparePDF не формирует выходной документ. Разделение прав полезно: каталог эталонов можно сделать доступным только для чтения, чтобы тестовый сценарий не смог случайно заменить утверждённые файлы.

Во временном каталоге избегайте одинаковых имён для параллельных заданий. Хотя программа читает два готовых файла и не создаёт промежуточных результатов, генератор PDF или скрипт копирования может перезаписать файл другой сборки. Создавайте отдельный каталог на идентификатор задания, а после сравнения удаляйте его только после успешной передачи диагностических материалов.

Вызов ComparePDF из Python

В Python используйте subprocess без передачи всей команды через shell. Список аргументов сохраняет пробелы в путях, не требует ручного экранирования и снижает риск выполнения постороннего текста из имени файла. Захватывать стандартный вывод удобно для журнала, но решение принимается по returncode. Тайм-аут задают на уровне процесса, особенно если входные PDF поступают из внешней системы и могут быть необычно сложными.

from pathlib import Path
import subprocess

def compare_text(reference: Path, result: Path) -> int:
    completed = subprocess.run(
        ['comparepdf', '-ct', '-v=0', str(reference), str(result)],
        stdout=subprocess.PIPE,
        stderr=subprocess.STDOUT,
        text=True,
        timeout=120,
        check=False,
    )
    return completed.returncode

Не используйте check=True, если коды 10, 13 и 15 являются ожидаемыми результатами проверки. В таком режиме Python сразу создаст исключение CalledProcessError, и вызывающий код потеряет удобную классификацию, если отдельно её не обработать. check=False позволяет сопоставить код с понятным состоянием и отличить расхождение от сбоя запуска.

Перед вызовом проверьте `is_file()` для обоих путей и сохраните их размеры. Эта предварительная проверка не заменяет чтение PDF, но выдаёт более понятную причину отсутствующего результата. После тайм-аута завершите процесс, сохраните пару и отметьте состояние как ошибку инфраструктуры; нельзя приравнивать зависание или принудительное завершение к обнаруженному различию.

RESULTS = {
    0: 'match',
    1: 'runtime_error',
    2: 'option_error',
    10: 'appearance_difference',
    13: 'text_difference',
    15: 'page_count_difference',
}
state = RESULTS.get(code, 'unexpected_exit')

Не полагайтесь на то, что неизвестный ненулевой код тоже означает PDF различаются. Он может появиться при аварийном завершении, сигнале операционной системы или изменении обвязки. Неизвестное значение следует поднимать как отдельную ошибку и сохранять весь доступный вывод.

Встраивание в Makefile и сборку документации

В Makefile команда сравнения обычно является проверочной целью, зависящей от уже созданного PDF. Важно помнить, что make прекращает рецепт при любом ненулевом коде. Это удобно для блокировки сборки, но перед завершением нужно скопировать файлы диагностики. Используйте отдельный сценарий или многострочный рецепт, который сохраняет код до выполнения дополнительных команд.

check-pdf: build/manual.pdf
	@set +e; \
	comparepdf -ct -v=0 tests/manual.pdf build/manual.pdf; \
	rc=$$?; \
	if [ $$rc -ne 0 ]; then \
	  mkdir -p artifacts; \
	  cp tests/manual.pdf artifacts/reference.pdf; \
	  cp build/manual.pdf artifacts/result.pdf; \
	fi; \
	exit $$rc

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

В сборке документации сравнивайте не весь постоянно меняющийся выпуск, а стабильные примеры, которые покрывают оглавление, таблицу, рисунок, колонтитул и длинный абзац. Один небольшой эталон с разнообразными элементами даёт более объяснимый отказ, чем сотни страниц с динамическими датами и ссылками. Полную публикацию можно проверять отдельно на структуру и валидность.

Проектирование хорошего набора эталонов

Эталонный набор должен представлять значимые особенности генератора, а не копировать все производственные документы. Для текстового режима включите латиницу, кириллицу, цифры, пунктуацию, переносы, таблицы и символы из используемых шрифтов. Для визуального режима добавьте векторную графику, растровое изображение, прозрачность, разные размеры страниц, поворот, линии малой толщины и элементы рядом с краем обрезки.

Каждый эталон снабжайте кратким описанием того, что он защищает. Когда тест падает, это описание помогает понять, почему нельзя просто заменить файл. Например, документ font-embedding.pdf контролирует встроенный шрифт и кириллицу, а page-boxes.pdf — размер и обрезку. Без назначения набор постепенно превращается в коллекцию непонятных файлов, которые обновляют оптом.

Добавляйте отрицательные пары, для которых заранее известен ожидаемый код. Копия эталона должна давать 0, замена одного слова — 13, сдвиг элемента при неизменном тексте — 10, добавленная страница — 15, защищённый файл — ошибку чтения. Такой самотест проверяет не только документы, но и правильность сценария, установку программы и обработку кодов.

Контрольная пара	Режим	Ожидаемый код	Проверяемое свойство
Файл и точная копия	text	0	Успешный путь и считывание кода.
Одно изменённое слово	text	13	Обнаружение содержательной правки.
Тот же текст с другим расположением	appearance	10	Обнаружение изменения макета.
Одна и две страницы	text или appearance	15	Ранний контроль структуры.
Доступный и защищённый файл	text	1	Отдельная обработка ошибки чтения.

Отрицательные примеры не должны попадать в обычный производственный отчёт как дефекты. Их запускают в отдельном самотесте и считают успешными, когда фактический код совпал с ожидаемым. Это особенно важно после обновления среды: нулевой тест показывает, что программа запускается, но только отрицательные пары подтверждают различение режимов и кодов.

Управление эталонами без случайного принятия правок

Эталон — часть тестовой спецификации. Его изменение должно проходить через тот же контроль, что и код: описание причины, просмотр получившегося PDF и подтверждение ответственным участником. В системе контроля файлов желательно хранить эталоны с механизмом, который не искажает бинарные данные и не заменяет их указателями без загрузки в рабочее окружение.

При осознанном изменении шаблона сначала создайте новый результат, получите ожидаемый отказ ComparePDF, затем проведите подробную визуальную и содержательную сверку. После утверждения замените эталон и повторите тест: он должен вернуть 0 в нужных режимах. Эта последовательность доказывает, что тест действительно видел изменение, а новый файл соответствует решению.

Не обновляйте эталоны командой, которая копирует все результаты сразу. Один неожиданный PDF может затеряться среди десятков ожидаемых изменений. Формируйте список пар с ненулевым кодом, классифицируйте каждую и принимайте отдельно. Для массовой осознанной переработки шаблона всё равно полезно сохранить старый и новый набор до завершения приёмки.

Ложные тревоги и пропущенные изменения

Ложная тревога визуального режима

Код 10 при приемлемом документе чаще всего связан с окружением или допустимой переработкой изображения. Проверьте встроенность шрифтов, одинаковую библиотеку рендеринга, размеры страниц и наличие динамических полей. Затем получите карту пикселей: если отличия равномерно проходят по краям всех букв, причина похожа на сглаживание; если сосредоточены в одной таблице, вероятнее реальная правка макета.

ComparePDF не позволяет исключить прямоугольник с датой или номером задания. Если динамическая область необходима, генерируйте тестовый документ с фиксированным значением либо предварительно создавайте нормализованные копии, где область закрыта одинаковым объектом. Нормализация должна быть детерминированной и применяться к обоим файлам одинаково, иначе она сама становится причиной расхождения.

Ложная тревога текстового режима

Код 13 при одинаковом видимом тексте требует анализа извлечения. Сравните результат `pdftotext` или аналогичного инструмента постранично, включая невидимые пробелы и управляющие символы. Разница может быть в порядке колонок, мягком переносе, неразрывном пробеле или представлении составного символа. Решите, является ли стабильный текстовый слой требованием доступности и поиска; если да, тревога оправдана, даже когда картинка совпадает.

Пропуск в текстовом режиме

Главный пропуск — изменение нетекстового объекта. Замена диаграммы, логотипа, подписи-картинки или цвета не меняет извлечённые символы. Второй случай — сканы без OCR, где обе страницы дают пустую строку. Поэтому текстовый ноль нельзя распространять на внешний вид; критерии следует формулировать раздельно и при необходимости выполнять -ca.

Пропуск при обоих режимах

Даже совпадение текста и отрисовки не проверяет невидимые структуры: вложение, закладку, тег доступности, сценарий формы, права доступа, подпись или метаданные. Если эти свойства важны, включите их в отдельный структурный тест. ComparePDF не должен становиться единственным валидатором только потому, что его результат удобно выражен одним кодом.

Сопоставление результатов двух режимов

Текст	Внешний вид	Практическая интерпретация
Совпадает	Совпадает	Выбранные пользовательские представления одинаковы; невидимые структуры всё ещё не проверены.
Различается	Совпадает	Вероятны скрытый текст, порядок извлечения, кодировка или невидимый слой.
Совпадает	Различается	Изменились оформление, изображения, геометрия, шрифт или рендеринг.
Различается	Различается	Есть содержательная правка либо изменение структуры текстовых объектов вместе с внешним видом.
Ошибка	Не запускался	Сначала устранить чтение, путь или параметры; сравнение не состоялось.
Разное число страниц	Разное число страниц	Структурное расхождение обнаружено до анализа содержимого.

Матрица помогает формировать сообщения, но не заменяет просмотр. Сочетание текст различается, внешний вид совпадает не всегда безобидно: скрытый слой влияет на поиск, копирование и программы чтения с экрана. Сочетание текст совпадает, внешний вид различается может быть как косметикой, так и критическим сдвигом подписи. Значимость определяется требованиями документа.

Для экономии времени внешний режим можно запускать только после текстового нуля, но тогда при коде 13 вы не узнаете, изменился ли также макет. Если отчёт нужен разработчику для быстрой диагностики, выполняйте оба режима независимо и сохраняйте оба кода. Цена дополнительного запуска оправдана, когда документы небольшие, а причина отказа должна быть понятна без повторения сборки.

Журналы, имена файлов и воспроизводимость

Строка журнала должна позволять повторить сравнение. Минимальный набор: идентификатор пары, относительные пути, режим, код, длительность и идентификатор окружения. Полные абсолютные пути часто содержат временные каталоги и не помогают на другом агенте, поэтому дополнительно сохраняют корень набора или команду с переменными.

2026-08-01T17:40:12Z	reports/invoice.pdf	text	13	0.42s	image=pdf-tests-42

Не включайте в журнал содержимое конфиденциального документа. Краткое сообщение ComparePDF само по себе не раскрывает текст, что удобно, но имена файлов могут содержать фамилию, номер договора или медицинский идентификатор. Присваивайте паре нейтральный тестовый ключ и храните соответствие в защищённой системе.

Для воспроизводимости запишите локаль и набор шрифтов, если используется appearance. Один и тот же контейнерный тег полезен только при неизменяемом образе; плавающий тег может указывать на другой набор пакетов. Лучше хранить точный идентификатор образа и обновлять его отдельным изменением с прогоном контрольного набора.

Сравнение документов, созданных разными программами

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

Визуальный режим в таком случае часто ближе к пользовательскому восприятию, но остаётся точным пиксельным тестом. Разные генераторы могут по-разному округлять координаты, строить кривые и встраивать изображения, создавая мелкие различия. Если цель — подтвердить функционально эквивалентный вид, понадобится инструмент с допуском; если цель — добиться строго одинакового вывода нового генератора, код 10 полезен как жёсткий критерий.

Не делайте вывод о качестве нового PDF только по тому, какой режим совпал. Новый генератор может улучшить теги доступности, изменить сжатие или исправить структуру без видимой правки. ComparePDF отвечает на ограниченный вопрос, а решение о миграции включает валидность, размер, скорость, доступность, подписи и требования отраслевого стандарта.

Особенности таблиц, колонок и сложного текста

В многостолбцовой странице порядок извлечения зависит от расположения текстовых блоков и решения Poppler. Небольшой сдвиг блока может изменить последовательность обхода, даже если все слова остались на странице. Код 13 в таком случае указывает на изменение машинного чтения, которое важно для копирования и индексации, но не обязательно означает замену слов.

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

Лигатуры, комбинируемые знаки и сложные письменности требуют отдельного эталона. Два визуально одинаковых слова могут иметь разную последовательность кодовых точек; обратная ситуация возникает, когда разные внутренние коды отображаются одним глифом. Прежде чем считать -ct содержательным критерием, проверьте, что извлечённая строка пригодна для поиска и сравнения именно на используемом языке.

Изображения, цвет и прозрачность

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

Небольшое изменение JPEG может затронуть множество пикселей и дать код 10, хотя при обычном масштабе оно почти не видно. ComparePDF не вычисляет perceptual similarity и не оценивает качество. Если процесс допускает повторное сжатие, строгий ноль подходит только как самый высокий стандарт; для практического допуска нужен количественный анализ изображения и порог, утверждённый для задачи.

Прозрачность и режимы наложения зависят от корректной отрисовки всех объектов. Если разные окружения дают разные результаты, сначала проверьте одинаковую сборку Poppler, затем наличие профилей и шрифтов. Не нормализуйте проблему простым обновлением эталона: различие может проявиться и у конечного пользователя или печатной системы.

Контроль времени выполнения и аварий

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

После принудительного завершения код оболочки может отражать сигнал, а не один из документированных кодов ComparePDF. Обвязка должна помечать его как timeout или crash, сохранять входные файлы и сведения о ресурсе. Нельзя преобразовывать любой код вне списка в 10 или 13: это скроет дефект инфраструктуры или уязвимость парсера.

Измеряйте пиковую память на самых сложных страницах, а не только среднее время. Визуальная отрисовка большого листа с высоким разрешением изображения может резко увеличить потребление. Ограничение числа параллельных процессов обычно эффективнее, чем общий большой лимит, потому что предотвращает одновременный пик нескольких сравнений.

Чек-лист перед вводом проверки в эксплуатацию

1. Подтвердить, что команда запускается и справка соответствует ожидаемым ключам.
2. Проверить положительную пару с кодом 0 и четыре отрицательных сценария с ожидаемыми кодами.
3. Выбрать text, appearance или последовательность обоих режимов для каждого типа документа.
4. Зафиксировать окружение рендеринга, шрифты и локаль для визуального теста.
5. Устранить динамические даты, случайные номера и нестабильный порядок данных.
6. Сформировать пары по относительным путям и отдельно обнаруживать лишние или отсутствующие файлы.
7. Сохранять код немедленно, не разбирать только текст сообщения.
8. Копировать проблемные документы до завершения шага и защищать их от лишнего доступа.
9. Установить тайм-аут и лимит параллелизма для больших или недоверенных PDF.
10. Описать процедуру утверждения нового эталона и запретить автоматическую массовую замену.
11. Добавить отдельные проверки для подписей, стандартов, форм, вложений и метаданных, если они значимы.
12. Периодически запускать самотест после изменения образа системы или зависимостей.

После выполнения чек-листа ComparePDF становится предсказуемым элементом контроля, а не случайной командой в конце сборки. Пользователь заранее знает, какой вид различия ловит каждый запуск, где окажется проблемная пара и как интерпретировать код. Именно эта дисциплина компенсирует отсутствие графического отчёта и настраиваемого порога.

Итоговый рабочий порядок

Надёжная проверка начинается с фиксированного эталона и чёткого критерия. Для смыслового содержимого запускают -ct, для макета и изображений — -ca, а для строгого процесса выполняют оба режима последовательно. Команда получает ровно два доступных PDF, уровень -v=0 оставляет журнал под контролем сценария, а код сохраняется немедленно после завершения.

Ноль позволяет продолжить процесс; 10, 13 и 15 обозначают разные виды расхождения; 1 и 2 требуют исправить сам запуск. Любой ненулевой результат сопровождают сохранённой парой, режимом и командой. Затем правку локализуют другим средством, поскольку ComparePDF намеренно не строит подробный отчёт и завершает работу после первого обнаруженного отличия.

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