PDFCompare Local

Локальное сравнение двух ревизий PDF (чертежи, схемы, спецификации) с наглядным HTML-отчётом. Windows, без облака — файлы не покидают ваш компьютер.

Current release: v0.1.24

Возможности

• Визуальный HTML-отчёт — матрица изменений по всем листам, постраничный просмотр OLD / NEW / DIFF и слайдер-сравнение со шторкой.
• Метрики для чертежей — процент изменений от нарисованного контента (FG %), площадь изменений в мм², число зон; классификация «мелкие / средние / крупные».
• Сопоставление листов между ревизиями: добавленные, удалённые и изменённые листы находятся даже при сдвиге нумерации.
• Исключаемые зоны — штампы, рамки и подписи можно вырезать из сравнения: визуальным редактором (мм-сетка, форматы A4–A0 в обеих ориентациях, привязка к углам) или текстом в поле. Зоны задаются в миллиметрах от угла листа, поэтому одна настройка штампа работает на всех форматах.
• Перегенерация — пересчёт отдельных листов с другим DPI / строгостью без полного повторного прогона.
• MCP-сервер для AI-агентов (Cursor, Claude Code, VS Code) — те же операции через инструменты агента.
• Автообновление — приложение само находит новый релиз, скачивает инсталлятор и обновляется.

Установка

Вариант	Кому подходит
Инсталлятор — рекомендуется	Ставится в профиль пользователя (без прав администратора), создаёт ярлыки, удаляется штатно, обновляется в один клик из самого приложения
Portable EXE	Один файл без установки; для обновления скачайте новый EXE
Portable ZIP + Python 3.12	Запуск из исходников: scripts/setup.ps1, затем scripts/run.ps1

Python для инсталлятора и EXE не нужен.

Быстрый старт

1. Перетащите два PDF прямо в окно (или выберите кнопками): старая ревизия — слева, новая — справа.
2. Если на листах есть штамп или рамка, которые не нужно сравнивать, — «Исключить области» → «Выбрать…» и обведите зону на превью.
3. Нажмите «Сравнить» (или Enter) и откройте готовый HTML-отчёт.

Не уверены, с чего начать — кнопка «?» в шапке (или F1) открывает краткую справку: что делать по шагам и что значат цифры в отчёте. У всех параметров есть подсказки при наведении.

Интерфейс

№	Зона	Что делает
1	Карточки файлов	Старая и новая ревизии PDF; кнопка между карточками меняет их местами
2	Зона перетаскивания	Бросьте два PDF сразу — они автоматически разложатся в «Старый» и «Новый»
3	Папка отчёта	Путь папки, которую создаст запуск. «Сгенерировать имя» соберёт имя из имён обоих PDF (общая часть + ревизии); если указать существующую папку, имя внутри неё подберётся само
4	Точность	DPI рендера (выше — точнее, но медленнее) и допуск штриха в px (гасит шум тонких линий и сглаживания)
5	Строгость	strict ловит больше мелких отличий, loose игнорирует мелкий дребезг, normal — баланс
6	Исключаемые зоны	Текстовое поле + кнопка визуального редактора зон (см. раздел ниже)
7	Эксперименты	Объединение соседних рамок изменений (gap в мм) и сохранение отладочных изображений
8	Запуск и действия	«Сравнить», подстановка из истории, открытие отчёта/папки; ниже — статус, таймер и прогресс
9	Вкладки	«История» запусков и «Перегенерация» отдельных листов с новыми настройками
10	Язык, справка и обновления	Переключатель RU/EN, «?» (справка, F1) и ручная проверка обновлений (↻)

Наведите курсор на любой параметр — всплывёт подсказка, что он делает:

Исключаемые зоны (штампы, рамки, подписи)

Визуальный редактор

Кнопка «Выбрать…» открывает окно с листом и вертикальной панелью настроек — формат, ориентация, сетка, привязка и единицы видны сразу, без выпадающих списков.

Зоны физические — в миллиметрах от угла листа. Это главное: штамп 185×55 мм с привязкой ↘ (низ-право) остаётся ровно 185×55 мм и на A4, и на A3, и на A0, в обеих ориентациях. Одна настройка — все форматы; отдельные наборы зон под каждый лист не нужны. (Зона в процентах так не умеет: 185 мм — это 62% ширины A4, но лишь 16% ширины A0, поэтому та же процентная рамка накрыла бы на A0 741×220 мм. Режим «проценты» остался для зон, которые должны тянуться вместе с листом.)

• Лист всегда чистый — сам чертёж не показывается. Зоны задаются размером от угла, поэтому картинка под ними только мешает. На листе есть рамка чертежа и пунктирный ориентир штампа 185×55 мм в правом нижнем углу;
• формат документа определяется автоматически и подставляется как выбранный (для нестандартного листа — ближайший, а реальный размер подписан рядом: «Документ: 305×430 мм»);
• формат A4–A0 и ориентация (вертикальный/горизонтальный): переключение меняет только лист — зоны остаются теми же. Это и есть способ проверить глазами, куда лягут ваши зоны на другом формате, до запуска сравнения;
• сетка 5–50 мм, живая подпись размера при рисовании; зоны можно двигать, растягивать за 8 маркеров и удалять (Del);
• список областей рядом с листом: номер, размер, привязка, удаление;
• существующие значения поля открываются как редактируемые рамки.

Текстом в поле

Формат	Пример	Когда удобно
Проценты x,y,w,h через ;	70,80,30,20	Быстрая зона от верхнего-левого угла
JSON: мм + якорь	[{"x":10,"y":10,"w":185,"h":55,"unit":"mm","anchor":"bottom_right"}]	Штамп 185×55 мм в 10 мм от правого-нижнего угла — работает на любом формате листа
JSON: проценты	[{"x":0,"y":90,"w":100,"h":10}]	Нижняя полоса на всю ширину

unit: percent (по умолчанию) / mm / px. anchor: top_left (по умолчанию) / top_right / bottom_left / bottom_right. Те же форматы принимают CLI (--exclude-region) и MCP-инструменты.

Отчёт

• Матрица изменений — все листы с бейджами статуса и метрикой FG % (доля изменённого от нарисованного контента).
• Просмотр листа — OLD / NEW / DIFF с подсветкой зон изменений.
• Слайдер — шторка OLD↔NEW с пришпиленной панелью навигации по листам, масштабированием и настройкой рамок изменений.

Скриншоты показывают интерфейс; содержимое чертежей может быть размыто.

Обновления

Приложение раз в час проверяет GitHub Releases. Когда выходит новая версия, установленное через инсталлятор приложение предлагает «Скачать и установить сейчас» — скачивает инсталлятор, тихо обновляется и перезапускается само. Portable EXE открывает страницу загрузки. Кнопка ↻ в шапке — проверить вручную.

CLI

python compare_pdfs.py --old old.pdf --new new.pdf --out-dir runs --run-name My_Comparison
python compare_pdfs.py --old old.pdf --new new.pdf --exclude-region "70,80,30,20" --diff-strictness loose
python compare_pdfs.py --old old.pdf --new new.pdf --bbox-merge-gap-mm 5 --keep-debug-images

Основные флаги: --dpi, --stroke-tol, --diff-strictness (strict/normal/loose), --exclude-region (повторяемый, проценты X,Y,W,H или JSON), --bbox-merge-gap-mm / --bbox-merge-max-area-ratio (эксперимент), --keep-debug-images, --workers, --lang, --run-name.

AI Agent Setup (MCP)

Вставьте в вашего локального агента:

Прочитай https://raw.githubusercontent.com/mikhalchankasm/AutoPDFCompare/master/docs/SETUP_PROMPT.md и выполни инструкцию по подключению PDFCompare MCP. Используй stdio transport, имя сервера pdfcompare.

Обновление MCP

MCP-сервер — отдельная от приложения установка: агент клонирует репозиторий в %LOCALAPPDATA%\PDFCompareMCP\AutoPDFCompare и запускает сервер из исходников. Инсталлятор и автообновление приложения заменяют только PDFCompareLocal.exe и MCP не трогают.

По умолчанию сервер обновляется сам: при каждом старте (то есть при перезапуске MCP-клиента) бутстрап подтягивает origin/master и доустанавливает зависимости, если они изменились. Обновление пропускается, если checkout не на master или в нём есть локальные правки — об этом пишется в .pdfcompare_mcp/bootstrap.log.

• Спросить у агента, актуальна ли версия: инструмент check_pdfcompare_update (покажет версию, коммит, на сколько отстал от master и что мешает обновиться).
• Отключить автообновление: -NoAutoUpdate у scripts/run_mcp_bootstrap.ps1 или PDFCOMPARE_MCP_AUTO_UPDATE=0 в окружении сервера.
• Обновить вручную:

git -C "$env:LOCALAPPDATA\PDFCompareMCP\AutoPDFCompare" pull --ff-only origin master

Важно: MCP-кнопки запускают локальную PowerShell-команду и код из этого репозитория. Используйте их, только если доверяете репозиторию и агенту.

Агенту доступны те же операции, что и в GUI: подготовка и запуск сравнения, статус/отмена, перегенерация листов, список прошлых прогонов и визуальный выбор исключаемых зон (pick_pdf_exclude_region). Подробности: docs/LOCAL_AGENT_MCP.md.

Документация

• MCP: установка и инструменты — docs/LOCAL_AGENT_MCP.md
• Готовые промпты для агентов — docs/AGENT_PROMPTS.md
• Skill-гайд для агентов — docs/PDFCOMPARE_AGENT_SKILL.md
• История изменений — CHANGELOG.md
• Процесс релиза — docs/RELEASE_PROCESS.md
• Промпт для ревью репозитория — docs/REVIEW_PROMPT.md

License

MIT. Обратите внимание: зависимость PyMuPDF распространяется под AGPL-3.0 (или коммерческой лицензией Artifex) — при использовании и распространении сборок ограничения PyMuPDF наследуются независимо от лицензии этого репозитория.