HexaPDF помогает объединять и разделять PDF, переставлять и поворачивать страницы, уменьшать размер файлов, извлекать изображения и вложения, заполнять формы, устанавливать пароль, наносить штамп и проверять внутреннюю структуру документа. Основные операции выполняются командами merge, modify, split, optimize, images, files, form, watermark и inspect, поэтому один и тот же сценарий легко повторить для отдельного файла или целой папки.

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

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

Как устроена работа с командами

Главное окно HexaPDF — строка терминала, поэтому пользователь управляет не кнопками, а явно заданными аргументами. Общая форма вызова выглядит как hexapdf КОМАНДА [параметры] вход.pdf выход.pdf. Название команды определяет тип операции, параметры уточняют её поведение, а позиционные аргументы задают файлы. Такая схема делает результат воспроизводимым: команда сохраняется в журнале оболочки, её можно вставить в инструкцию для коллеги или положить в сценарий контроля качества.

Справка разделена на два уровня. Вызов hexapdf help показывает перечень действий, а hexapdf help merge, hexapdf help optimize или другая конкретная команда раскрывает её параметры. Длинные имена параметров предпочтительнее в автоматизации, потому что через несколько месяцев запись --prune-page-resources понятнее сокращённой формы. Названия команд и длинных параметров разрешено сокращать только до однозначного варианта; в рабочих сценариях это удобство лучше не использовать, чтобы новый параметр в будущей поставке не сделал сокращение неоднозначным.

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

Коды завершения и контроль результата

Успешное выполнение возвращает код 0, ошибка — код 1. Это простое правило позволяет строить надёжные цепочки: следующая команда запускается только после успешной предыдущей, а журнал сохраняет имя проблемного файла. В оболочках семейства Unix для этого применяют связку через &&, в PowerShell проверяют $LASTEXITCODE, а в системах непрерывной интеграции ненулевой код автоматически помечает этап как неуспешный. Важно проверять не только существование выходного файла: некоторые ошибки проявляются уже после создания неполного результата, поэтому в сценарии стоит дополнительно вызвать hexapdf info --check.

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

Установка и первый запуск

Для запуска команд требуется рабочий Ruby и менеджер пакетов RubyGems. Типовая установка выполняется командой gem install hexapdf, после чего hexapdf version подтверждает, что исполняемый файл найден. Если оболочка сообщает, что команда неизвестна, сначала проверяют ruby --version и gem env, затем каталог исполняемых файлов RubyGems в переменной PATH. На системах с несколькими Ruby важно устанавливать пакет тем же интерпретатором, которым будет выполняться команда; иначе gem окажется в другом наборе библиотек.

В окружениях, где зависимости фиксируются для проекта, HexaPDF добавляют в Gemfile и запускают через bundle exec hexapdf. Такой вызов использует именно тот набор gem-пакетов, который записан в lock-файле, и исключает незаметную подмену библиотек глобальными установками. Для серверной задачи полезно заранее прогреть установку, выполнить пробную обработку тестового PDF и сохранить версии Ruby, HexaPDF и зависимостей в журнале развертывания. Это облегчает повторение результата после обновления системы.

Утилита использует библиотеку cmdparse для разбора команд и geom2d для геометрических операций макета. При ошибке загрузки зависимости не следует копировать отдельные файлы вручную в каталог Ruby: корректнее повторить установку через RubyGems или Bundler и убедиться, что прокси и хранилище пакетов разрешают загрузку всех зависимостей. На Windows дополнительная причина — разные способы установки Ruby; путь из RubyInstaller и путь из среды разработки могут ссылаться на разные наборы gem-пакетов.

Проверочный сценарий после установки

1. Выполнить ruby --version и убедиться, что вызывается ожидаемый интерпретатор.
2. Выполнить hexapdf version и сохранить вывод вместе с журналом задачи.
3. Скопировать небольшой PDF в тестовую папку и вызвать hexapdf info --check sample.pdf.
4. Создать результат командой hexapdf optimize sample.pdf sample-optimized.pdf.
5. Сравнить число страниц, открытие и внешний вид обоих файлов.

Проверка PDF командой info

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

Параметр --check заставляет парсер пройти по структуре и объектам, а не ограничиваться чтением заголовка. HexaPDF умеет исправлять часть восстанавливаемых несоответствий при разборе, поэтому сообщение о коррекции нужно фиксировать как свойство исходника. Практичная схема такова: сначала проверяется оригинал, затем выполняется операция, после чего проверяется результат. Если предупреждение исчезло, это может означать нормализацию структуры; если появилось новое, операцию повторяют на копии с более консервативными настройками.

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

Что делать с повреждённым входным файлом

Если info --check завершается ошибкой, первым делом сохраняют неизменную копию и полный вывод с повышенной подробностью. Затем проверяют, открывается ли файл в просмотрщике и способен ли тот сохранить его под новым именем. Повторное сохранение иногда строит корректную таблицу перекрёстных ссылок, но может удалить нестандартные данные, поэтому такой путь применяют только к копии. Альтернативный подход — открыть файл библиотечным API HexaPDF в режиме, допускающем исправление, и записать диагностические сведения об объектах, на которых остановился парсер.

Выбор, перестановка и поворот страниц

Страница задаётся не только одним номером. Спецификация поддерживает списки через запятую, диапазоны, обратный порядок, шаг и отсчёт от конца. Запись 1-4,8 выбирает первые четыре страницы и восьмую; 10-6 располагает страницы в обратном порядке; 1-20/2 берёт каждую вторую. Символ e обозначает последнюю страницу, а форма rN — страницу, отсчитанную от конца. Такая запись удобна, когда длина входного документа заранее неизвестна.

Суффиксы поворота прикрепляются к выбранной странице или диапазону. Буква r означает поворот вправо, l — влево, d — на 180 градусов, n оставляет ориентацию без дополнительного поворота. Поворот в PDF обычно меняет атрибут страницы, а не пересчитывает координаты каждого элемента. Большинство просмотрщиков учитывает его правильно, но приложения, которые игнорируют Rotate или анализируют координаты без нормализации, могут потребовать физического преобразования содержимого через API.

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

Практические шаблоны выбора

Задача	Спецификация	Результат
Оставить первые пять страниц	1-5	Страницы 1, 2, 3, 4 и 5
Удалить титульный лист	2-e	Все страницы со второй до последней
Развернуть весь документ	e-1	Полностью обратный порядок
Выбрать нечётные	1-e/2	Каждая вторая страница, начиная с первой
Последние три страницы	r3-e	Диапазон от третьей с конца до последней
Повернуть одну страницу	7r	Седьмая страница с поворотом вправо

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

Объединение документов

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

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

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

Формы, закладки и наследуемые ресурсы

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

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

Разделение PDF

Без дополнительных параметров split создаёт отдельный файл для каждой страницы. Имя результата задаётся шаблоном с числовым заполнителем в стиле printf, например page-%03d.pdf. Три цифры обеспечивают правильную сортировку до 999 страниц: page-001, page-002 и так далее. Если оставить непредсказуемое число разрядов, файловые менеджеры могут расположить page-10 раньше page-2.

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

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

Надёжное именование результатов

В автоматизации имя должно исключать коллизии. Хорошая схема включает базовое имя источника, порядковый номер и при необходимости контрольный идентификатор задания. Нельзя помещать все результаты разных входов в один каталог с шаблоном page-%d.pdf: второй документ перезапишет первый при разрешённом force или остановит процесс без него. Каталог для каждого входа либо уникальный префикс устраняют эту проблему.

Оптимизация размера и структуры

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

Для объектных потоков, xref-потоков и обычных потоков доступны режимы generate, delete и preserve. Preserve сохраняет подход исходника, generate переводит структуру на современное представление, delete возвращает более традиционную форму. Если PDF предназначен для неизвестного оборудования, например старого контроллера печати, сначала тестируют preserve. Если цель — минимальный размер и используются современные просмотрщики, generate обычно предпочтительнее.

Параметр --compress-pages разбирает и заново сжимает потоки содержимого страниц. Операция может быть заметно медленнее, а выигрыш часто невелик, если исходный генератор уже применил Flate. Её включают после измерения, а не по умолчанию. Параметр --prune-page-resources анализирует, какие ресурсы страницы действительно используются, и способен существенно уменьшить файлы, собранные повторным импортом страниц. Цена — дополнительный разбор содержимого и риск столкнуться с нестандартными операторами в повреждённом PDF.

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

Как оценивать результат оптимизации

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

Настройка	Когда применять	Что проверить
compact	Почти всегда для копии с ревизиями	Подписи и историю изменений
object streams: generate	Современные просмотрщики, нужен меньший размер	Старые принтеры и импортёры
xref streams: generate	Современный структурный формат	Совместимость целевой системы
compress pages	Большие несжатые потоки содержимого	Время обработки и визуальную идентичность
prune page resources	Файлы после многократного импорта страниц	Редкие ресурсы и прозрачность
optimize fonts	Статические документы	Редактирование полей и набор символов

Извлечение изображений

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

Извлечение выполняется по индексам. Формат результата зависит от внутреннего представления: JPEG можно сохранить без повторного сжатия, PNG используется для совместимых растровых данных, JPEG 2000 получает соответствующее расширение. Нельзя ожидать, что каждый визуальный элемент страницы станет отдельной картинкой. Векторная схема, текст, маски, узоры и Form XObject не являются обычным растром; для них нужен рендеринг страницы или анализ содержимого.

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

Почему извлечённое изображение выглядит иначе

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

Вложения внутри PDF

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

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

Удаление или замена вложений требует явной проверки конфиденциальности. Визуально документ может не содержать чувствительных данных, но вложенный CSV, старая редакция договора или исходное изображение остаются внутри. Перед публикацией запускают files, проверяют аннотации-файлы и при необходимости анализируют объектную структуру. Простая печать в PDF часто удаляет вложения, но одновременно уничтожает закладки, формы, метаданные и доступность, поэтому контролируемое удаление предпочтительнее.

Диагностика шрифтов

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

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

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

Проверка проблемы с символами

1. Найти страницу и шрифтовой ресурс командой fonts.
2. Проверить встраивание и тип кодировки.
3. Сравнить отображение в двух независимых просмотрщиках.
4. Проверить извлечение текста и наличие ожидаемых Unicode-символов.
5. Если проблема появилась после оптимизации, повторить её без изменения шрифтов.

Заполнение и уплощение форм

Команда form выводит дерево полей AcroForm. Обычный режим показывает имена и значения, подробный — тип поля, виджеты, возможные варианты выбора, страницы и координаты. Имена могут быть иерархическими, например customer.address.city. Для заполнения важен полный путь: сокращённое имя способно совпасть у нескольких полей или обратиться не к тому узлу.

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

После установки значения HexaPDF формирует внешний вид виджета, чтобы текст был виден без участия просмотрщика. Параметр viewer override заставляет программу чтения пересоздать отображение, но разные приложения делают это неодинаково. Для предсказуемого обмена лучше использовать сгенерированные appearances и проверить результат в Adobe Reader, браузере и целевой системе документооборота.

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

Ограничение XFA

Команда ориентирована на AcroForm. XFA использует XML-шаблон и модель отображения, которую многие современные библиотеки и просмотрщики поддерживают частично. При обнаружении XFA HexaPDF предупреждает, что результат может быть неверным. Такой документ нельзя без проверки прогонять через обычное заполнение или оптимизацию: сначала определяют, существует ли параллельная AcroForm-разметка, затем тестируют поля в Adobe Reader. Если бизнес-процесс зависит от динамического XFA, требуется специализированное решение или предварительное преобразование формы.

Пароли, шифрование и разрешения

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

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

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

Снятие шифрования

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

Водяные знаки и штампы

Команда watermark использует страницу другого PDF как накладываемый объект. В режиме background она помещается под существующим содержимым, в режиме stamp — поверх. Файл водяного знака может содержать одну или несколько страниц; при необходимости последняя страница повторяется либо используются все страницы по заданному правилу. Такой подход сохраняет векторный текст и графику лучше, чем предварительное превращение знака в растр.

Размер и система координат страницы источника имеют значение. Если знак создан для A4, а целевой документ содержит Letter и нестандартные обрезки, положение может отличаться. Надёжный шаблон формируют с прозрачным фоном, корректным MediaBox и CropBox, а затем тестируют на портретной и альбомной странице. Для диагонального текста проще заранее создать одну страницу нужного размера через API HexaPDF, чем пытаться компенсировать геометрию после наложения.

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

Создание PDF из изображений

Команда image2pdf принимает JPEG, PNG и страницы PDF, размещая каждый вход на отдельной странице результата. Автоматический размер страницы соответствует изображению, а готовые варианты позволяют выбрать A4 или альбомный A4. Масштабирование fit вписывает картинку в доступную область, минимальное PPI ограничивает чрезмерное увеличение, а поля задаются одним числом либо четырьмя значениями по сторонам.

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

Минимальное PPI защищает от неразумного растягивания маленького изображения на большую страницу. Например, картинка 600×800 пикселей на полном A4 будет выглядеть заметно хуже скана 2480×3508. Для архивного сканирования исходное разрешение и компрессию выбирают до сборки PDF; image2pdf размещает изображения, но не выполняет OCR и не превращает пиксели в searchable text.

После сборки можно сразу применить структурную оптимизацию и шифрование, однако удобнее сначала проверить порядок, ориентацию и поля на незашифрованной копии. Ошибка в сортировке имён часто приводит к последовательности 1, 10, 11, 2. Нулевое дополнение или естественная сортировка входов устраняют проблему.

Анализ внутренней структуры

Команда inspect предназначена для ситуаций, когда обычной информации недостаточно. Она открывает интерактивную оболочку или выполняет одно действие и завершает работу. Доступны просмотр объекта, рекурсивное раскрытие ссылок, декодированный и сырой поток, каталог, трейлер, таблица ссылок, дерево страниц, содержимое страницы, ревизии и поиск. Вывод использует синтаксис PDF, поэтому имена начинаются с косой черты, строки и массивы отличаются от Ruby-объектов, а косвенная ссылка выглядит как 12 0 R.

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

Команда page-stream показывает операции рисования страницы в декодированном виде. Она полезна, когда элемент виден, но не находится как обычный текст, или когда требуется понять, какой ресурс используется. Формы XObject могут содержать собственные потоки, и одного уровня страницы недостаточно. Рекурсивный анализ идёт от ресурсов страницы к формам, изображениям, шрифтам и графическим состояниям.

Безопасность при просмотре потоков

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

Статистика занимаемого места

Команда usage оценивает, сколько места занимают категории PDF-объектов. Это нижняя граница: синтаксические разделители, комментарии и таблицы ссылок не всегда полностью распределяются по категориям. Тем не менее отчёт быстро показывает, что доминирует — изображения, шрифты, потоки содержимого, вложения или накопленные объекты.

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

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

Пакетная обработка

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

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

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

Идемпотентность и повторный запуск

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

Работа через Ruby API

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

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

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

Когда API предпочтительнее команды

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

Форматы и совместимость

Основным входом и выходом является PDF. Для команды image2pdf дополнительно используются JPEG и PNG, а PDF-страница может выступать как изображение-источник. Команда images сохраняет поддерживаемые растровые ресурсы в JPEG, PNG или JPEG 2000 в зависимости от внутреннего кодирования. Вложения могут иметь любой формат, но HexaPDF рассматривает их как данные и не преобразует содержимое.

Библиотека поддерживает современные конструкции PDF, включая объектные потоки, xref-потоки, AES-шифрование, интерактивные формы AcroForm, аннотации, слои, цифровые подписи и PDF/A-инструменты. Поддержка конструкции не означает одинаковое отображение во всех просмотрщиках. PDF остаётся сложным стандартом с реализациями разного качества; итоговый контроль строят на фактическом наборе устройств и программ получателя.

Для текста поддерживаются стандартные PDF-шрифты и TrueType, а корректный Unicode зависит от выбранной гарнитуры, формирования подмножества и таблиц сопоставления. Новые возможности сложного формирования текста могут использовать движок HarfBuzz через соответствующую настройку API. При создании многоязычного документа следует проверять лигатуры, направление письма, составные знаки и fallback-шрифты, а не ограничиваться латиницей в тестовом примере.

Чего не следует ожидать

HexaPDF не выполняет OCR сканов, не преобразует произвольный HTML и CSS в полиграфически точный PDF и не предоставляет визуальное редактирование абзацев как в текстовом процессоре. Команды manipulations работают со страницами, объектами, ресурсами, формами и защитой; изменение одной фразы в сложном существующем макете требует разбора потоков содержимого и шрифтов и обычно не сводится к поиску и замене строки.

Ошибки и способы устранения

Симптом	Вероятная причина	Действие
Команда не найдена	Каталог RubyGems отсутствует в PATH	Проверить gem env и запуск через bundle exec
Gem загружается не тем Ruby	Несколько интерпретаторов	Сравнить which ruby, which gem и пути gem env
Файл требует пароль	Вход зашифрован	Передать разрешённый пароль и не писать его в общий журнал
После оптимизации поле пусто	Нарушен appearance или удалены данные шрифта	Повторить без оптимизации шрифтов, проверить form
XFA отображается неверно	Форма не AcroForm	Использовать специализированный процесс и тест в Adobe Reader
Результат больше исходника	Ресурсы повторились или исходник уже сжат	Сравнить usage, включить compact и измерить
Старое устройство не открывает файл	Объектные/xref-потоки или AES-256	Использовать preserve/delete и совместимое шифрование
Водяной знак не виден	Он под непрозрачным фоном	Использовать stamp или изменить шаблон
Извлечённое изображение без прозрачности	Маска хранится отдельно	Проверить тип, мягкую маску и цветовое пространство
Пакет перезаписывает файлы	Неуникальный шаблон выхода	Разнести каталоги или включить имя источника

Ошибка чтения объекта или таблицы ссылок

Сначала запускают info --check с подробным выводом и фиксируют номер объекта. Затем inspect показывает трейлер, xref и проблемную ссылку. Если файл открывается в просмотрщике, сохранение копии иногда восстанавливает таблицу, но это изменение нужно считать отдельной конвертацией. При массовом потоке повреждённые входы помещают в карантин, а не пытаются бесконечно исправлять в общем процессе.

Неожиданное изменение внешнего вида

Отключают дополнительные оптимизации и повторяют только базовую запись. Если проблема исчезла, параметры включают по одному: object streams влияют на структуру, compress-pages — на содержимое, prune-page-resources — на набор ресурсов, optimize-fonts — на шрифты. Такой бинарный поиск быстрее случайной смены всех настроек. Страницы сравнивают после рендеринга одинаковым движком, а затем подтверждают в целевом просмотрщике.

Высокое потребление памяти или времени

Большие изображения, глубокие объектные графы и рекомпрессия страниц требуют ресурсов. Для начала измеряют info и usage, отключают compress-pages и pruning, обрабатывают один файл и наблюдают пик памяти. Если задача состоит только в перестановке страниц, не нужно одновременно включать все оптимизации. В серверном процессе задают ограничение времени, отдельный рабочий каталог и очередь с контролируемым параллелизмом.

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

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

Программа	Лучше подходит для	Главное ограничение
HexaPDF	Ruby-сценариев, пакетной обработки, создания и анализа PDF	Нет графического редактора
PDF Commander	Визуальной ручной правки страниц, текста и изображений	Не предназначен для Ruby-автоматизации
qpdf	Надёжных структурных преобразований, шифрования и проверки из CLI	Не является редактором содержимого страниц
pdfcpu	CLI и Go API для проверки, оптимизации и преобразований	Нет визуальной правки макета
Prawn	Создания новых PDF средствами Ruby	Не читает и не изменяет существующие PDF как полная библиотека
PDFtk	Простого объединения, разделения, штампов и форм	Меньше средств глубокой объектной диагностики

Для пользователя, который хочет открыть документ и мышью исправить надпись, практичнее PDF Commander. Для конвейера на Ruby, где нужны создание, формы, объектный анализ и собственная логика, выбирают HexaPDF. qpdf удобен как зрелый инструмент структурного переписывания и шифрования, pdfcpu — когда основной стек построен на Go, Prawn — когда требуется только генерация новых документов, а PDFtk остаётся понятным вариантом для ограниченного набора классических команд.

Практические рабочие процессы

Сборка отчёта из нескольких частей

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

Подготовка сканов к отправке

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

Публикация формы как неизменяемого документа

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

Архивная нормализация

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

Диагностика подозрительно большого файла

Usage определяет доминирующую категорию. Images показывает крупные растры, fonts — гарнитуры, files — вложения, inspect revisions — накопленную историю. После этого выбирают точечную меру: compact для ревизий, удаление вложения, корректное подмножество шрифта, pruning ресурсов или контролируемую перекодировку изображений. Такой порядок сохраняет качество лучше, чем слепая агрессивная компрессия.

Ограничения, которые важно учитывать

Отсутствие графического редактора означает, что HexaPDF не показывает страницу с рамками выделения и не предлагает визуально перетаскивать объекты. Для стандартных команд это компенсируется точным синтаксисом, но ручное исправление макета быстрее выполнить в PDF Commander или другом визуальном редакторе. API позволяет менять содержимое, однако разработчику нужно понимать систему координат, ресурсы и операторы PDF.

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

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

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

Дополнительные рецепты контроля качества

Контроль страниц после объединения

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

Безопасная замена исходника

Записывайте результат во временное имя в том же файловом разделе, запускайте info --check и только после успеха выполняйте атомарное переименование. Не используйте force как замену транзакции: при нехватке места или аварии процесса файл, записываемый поверх, может стать неполным.

Проверка вложений перед публикацией

Сопоставьте вывод files с разрешённым списком имён и MIME-типов. Извлеките вложения в карантин, рассчитайте хеши и проверьте антивирусом. Удалите старые редакции и исходные таблицы, если они не должны входить в публикуемый пакет.

Форма с новыми символами

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

Совместимость шифрования

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

Сравнение рендеринга

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

Измерение оптимизации

Запишите размер, длительность и параметры каждого варианта: базовый optimize, compress-pages и pruning. Выберите самый простой вариант, который даёт достаточный выигрыш и проходит тесты. Однократный лучший результат на одном PDF нельзя переносить на весь архив без выборки разных типов документов.

Работа с подписями

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

Карантин для ошибок

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

Оценка ресурсов страницы

Если pruning даёт неожиданное изменение, inspect page-stream помогает увидеть фактические имена ресурсов. Проверьте Form XObject и шаблоны, которые вызываются косвенно. Ресурс, не упомянутый прямо в основном потоке страницы, может быть нужен вложенной форме.

Печать после поворота

Некоторые драйверы ориентируются на MediaBox и Rotate по-разному. После команды modify напечатайте тестовую страницу на целевом устройстве или в виртуальный PostScript/PDF-принтер. Это особенно важно для смешанных портретных и альбомных приложений.

Ограничение журналов

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

Точная проверка отдельных типов объектов

Для изображений сверяйте не только ширину и высоту, но и ColorSpace, BitsPerComponent, Decode и наличие SMask. Для шрифтов сопоставляйте BaseFont, Encoding, ToUnicode и FontDescriptor. Для страницы проверяйте MediaBox, CropBox, Rotate, Resources, Contents и Annots. Такой чек-лист позволяет локализовать изменение, когда визуальный тест обнаружил отличие, но общая структура выглядит корректной.

При сравнении метаданных различайте словарь Info и XMP-пакет. Они могут содержать разные заголовки, авторов и даты. Переписывание способно синхронизировать или изменить одну из копий. Если downstream-система индексирует XMP, проверка только свойства Title из Info недостаточна.

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

Аннотации имеют собственные прямоугольники, внешние представления и действия. Уплощение должно переносить appearance, а удаление — не оставлять недоступные действия. Ссылки GoTo и именованные назначения проверяют после перестановки страниц, потому что визуально документ может быть цел, а навигация вести в неверный раздел.

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

Параметры записи и сохранения

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

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

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

Строгий и исправляющий разбор

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

Управление аннотациями

Команда modify умеет удалять или уплощать аннотации. Удаление исключает объект и его визуальное представление, а уплощение переносит appearance на страницу, после чего аннотация перестаёт быть интерактивной. Разница важна для штампов и комментариев: удаление уничтожает видимый знак, уплощение сохраняет его в печатном виде. Если appearance отсутствует или рассчитан нестандартно, уплощение может дать пустое место, поэтому аннотации сначала инвентаризируют через API или inspect.

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

После перестановки страниц внутренние переходы должны вести к тем же смысловым разделам. Ссылки GoTo могут ссылаться на объект страницы, поэтому импорт обычно сохраняет направление, но именованные назначения и сценарии документа требуют проверки. Создайте список кликабельных элементов на тестовых страницах и пройдите его после merge или modify, особенно если часть страниц была удалена.

Тонкости команды image2pdf

Размер страницы auto строится из размеров изображения и выбранной плотности. Если плотность отсутствует или интерпретируется иначе, физический размер может оказаться неожиданным. Фиксированный A4 даёт предсказуемую бумагу, а fit масштабирует изображение в рамку с учётом полей. Минимальное PPI запрещает увеличение ниже установленной детализации и тем самым предотвращает слишком размытый результат.

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

Входной PDF в image2pdf рассматривается как графический объект страницы. Это удобно для унификации размеров и размещения нескольких готовых страниц, но может изменить навигационные структуры и интерактивность: импортированная страница становится визуальным содержимым нового документа, а не полным клоном всех свойств. Если нужно сохранить закладки, поля и аннотации, применяют merge или более точный API.

Поиск объектов и данных

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

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

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

Метаданные и навигация через API

Словарь Info хранит простые поля вроде Title, Author и Subject, а XMP представляет расширяемый XML-пакет. Документ может содержать оба набора и противоречащие значения. Перед публикацией выбирают главный набор, синхронизируют его и удаляют нежелательные пользовательские свойства. Даты PDF имеют собственный формат и часовой пояс; строку нельзя формировать произвольным локализованным текстом.

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

Метки страниц позволяют отображать римские цифры для введения и арабские для основной части, хотя физические позиции остаются последовательными. Командная спецификация страниц использует физические номера; API может читать и строить дерево меток. В инструкции для пользователя нужно явно различать надпись в интерфейсе просмотрщика и позицию, передаваемую в modify или merge.

Создание содержимого средствами Canvas

Canvas предоставляет операции перемещения, линий, кривых Безье, прямоугольников, дуг, заливки, обводки, отсечения, текста, изображений и Form XObject. Графическое состояние включает матрицу трансформации, цвета, ширину линии, прозрачность и параметры текста. Изменение сохраняется до восстановления состояния, поэтому блок save/restore предотвращает случайное влияние одной фигуры на следующую.

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

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

Текст и сложный макет

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

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

Fallback-шрифты нужны, когда основная гарнитура не содержит символ. Без них редкий знак превращается в отсутствующий глиф. Для многоязычного текста тестовый набор должен включать реальные письменности, диакритику, математические знаки и emoji, которые планируется поддерживать. Наличие файла шрифта ещё не гарантирует правильное формирование сложных письменностей; для них требуется shaping.

Цифровые подписи в программном сценарии

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

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

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

Как построить надёжный процесс

Начинайте с минимальной команды, которая решает одну задачу. Сохраните оригинал, выполните info --check, запишите новый файл и повторите проверку. Затем добавляйте оптимизацию, форму, шифрование или водяной знак отдельными этапами. Такой конвейер легче диагностировать: известно, после какого шага изменилось содержимое или появилась несовместимость.

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

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

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