PDF сохранился без ошибки, но знак не виден — начните с одного листа и непрозрачного красного прямоугольника в центре. Если такой overlay появляется, файл читается и проблема в геометрии или прозрачности исходного знака. Если не появляется, проверьте, какую страницу вы изменили и записал ли writer именно изменённый объект.
Stamp и watermark различаются положением в стеке. pypdf называет stamp слоем поверх документа, а watermark — фоном под ним. Плотная белая подложка исходной страницы полностью скроет underlay, хотя операция слияния прошла корректно. Для диагностической пробы используйте overlay, затем осознанно выберите требуемый слой.
Симптом указывает на конкретный слой PDF
| Что видно | Вероятная причина | Следующая проба |
|---|---|---|
| знак исчез везде | изменён не тот PageObject или underlay закрыт | яркий overlay на странице 1 |
| видна только часть | CropBox/MediaBox или смещение | вывести page boxes и bbox знака |
| знак повёрнут | rotation не перенесён в content | нормализовать rotation до merge |
| есть на первой странице | watermark page не повторяется | явный цикл по writer.pages |
| есть в одном viewer | ресурсы/прозрачность обработаны по-разному | отрендерить несколькими движками |
Проверяйте не только количество страниц. Запишите MediaBox, CropBox и rotation каждой уникальной группы листов. PDF может сочетать A4 portrait, landscape-вставки и страницы с ненулевым началом координат; один transform не обязан подходить всем.
Слой накладывается на страницу, а не на весь файл
В pypdf одностраничный watermark читают как PageObject и вызывают merge_page для каждой страницы writer. Параметр over=False помещает его под исходным content, over=True — сверху. QPDF использует те же понятия overlay и underlay и умеет повторять выбранную страницу на диапазоне выходных страниц.
watermark = PdfReader("watermark.pdf").pages[0]
writer = PdfWriter(clone_from="source.pdf")
for page in writer.pages:
if page.rotation != 0:
page.transfer_rotation_to_content()
page.merge_page(watermark, over=True)
writer.write("result.pdf")Это условный минимальный пример для актуального API pypdf. Для настоящего watermark обычно выбирают over=False, только если фон документа не перекрывает знак. Перед массовой обработкой протестируйте копию файла; документы с формами, подписями и аннотациями требуют отдельной приёмки.
Rotation и page boxes меняют систему координат
- Сравнить ширину и высоту CropBox у content и watermark page.
- Перенести rotation в content до merge, если библиотека это рекомендует.
- Вычислить scale и translation для каждой группы размеров.
- Не считать левый нижний угол равным нулю без чтения box coordinates.
- Проверить знак у края и в центре на portrait и landscape листах.
pypdf отдельно рекомендует transfer_rotation_to_content для неправильно повёрнутых stamps и watermarks. Эта операция меняет представление поворота, поэтому выполняйте её на рабочей копии страницы до расчёта transform. Если знак подготовлен в пикселях, сначала создайте PDF-страницу с известным физическим размером.
Прозрачность проверяется после геометрии
Нулевой alpha, режим смешивания и белый текст на светлом фоне визуально похожи на ошибку merge. Диагностический знак делайте полностью непрозрачным и контрастным. Когда координаты подтверждены, верните нужную opacity и проверьте печать: экранный viewer и принтер могут по-разному обрабатывать transparency.
Не растрируйте весь документ только ради watermark: это портит текстовый слой, доступность и поиск. Лучше сформировать векторный одностраничный stamp с встроенным шрифтом. Если шрифт не встроен или глифов нет, русская надпись может исчезнуть либо замениться квадратиками.
Приёмка рендерит, а не только открывает файл
- Проверить page count, отсутствие ошибок чтения и ожидаемый размер файла.
- Отрендерить первую, среднюю, последнюю и все уникальные по размеру страницы.
- Сравнить положение, opacity и читаемость с эталонным изображением.
- Открыть результат минимум в браузере и отдельном PDF viewer.
- Проверить печать, формы, ссылки и подписи, если они есть в исходнике.
Если исходник подписан цифровой подписью, любое изменение содержимого может повлиять на её валидность; такую политику согласуют до обработки. Для разбора подготовьте одну обезличенную проблемную страницу, watermark.pdf, версии pypdf/qpdf, page boxes и rotation. Полный конфиденциальный документ не нужен.