PDFHummus — обзор возможностей, установки, форматов и актуального статуса PDF-Writer

PDFHummus — не настольный PDF-редактор и не программа для чтения документов, а встраиваемая C++-библиотека, которая в актуальном репозитории называется PDF-Writer (PDFHummus). Она предназначена для программного создания PDF, разбора существующих файлов, встраивания страниц и изображений, внесения изменений и работы с потоками. На 12 сентября 2026 года проект активен, а последним опубликованным выпуском является версия 4.9.0 от 29 мая 2026 года. Это важно отделять от HummusJS: старый Node.js-модуль с похожим названием прекратил поддержку ещё в 2019 году, тогда как C++-библиотека PDF-Writer продолжает развиваться.

Скачать PDFHummus

Безопасный источник PDFHummus — официальный репозиторий PDF-Writer и его раздел Releases. Текущий выпуск 4.9.0 распространяется как исходный код проекта; обычного пользовательского установщика с мастером установки для Windows или macOS у библиотеки нет. Для воспроизводимой сборки разумно выбирать конкретный тег релиза, а не случайное состояние ветки main. Это особенно существенно для серверных и корпоративных проектов, где версию зависимости нужно закреплять и обновлять контролируемо.

Официальный README описывает три основных способа подключения: CMake FetchContent, поиск уже установленного пакета через find_package и прямое включение исходников в собственный проект. В примере FetchContent в README по-прежнему указан тег v4.6.2; это пример синтаксиса, а не указание на актуальную версию. При новом внедрении следует сверять раздел Releases и сознательно закреплять выбранный современный тег, например 4.9.0 после проверки совместимости собственного приложения.

Что такое PDFHummus

PDFHummus, или PDF-Writer, — проект разработчика Gal Kahana и участников открытого репозитория. Его назначение — дать C++-приложению инструменты для низко- и среднеуровневой работы с PDF без запуска внешнего графического редактора. Библиотека умеет создавать страницы и объекты, рисовать контент, встраивать шрифты и изображения, копировать или объединять содержимое других PDF, разбирать структуру существующего документа и выполнять инкрементальные изменения.

Основные функции PDFHummus

Создание PDF и построение страниц

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

Текст, Unicode и шрифты

PDFHummus поддерживает Unicode-текст в UTF-8 и умеет встраивать распространённые типы шрифтов. В документации перечислены TrueType TTF, OpenType с CFF, Type 1 PFB/PFM, Mac DFont и коллекции TTC. Для типичного приложения это означает, что кириллица и другие символы не требуют сводить страницу к изображению: текст может оставаться текстом в PDF при корректном выборе шрифта и его наличии у приложения.

JPG, PNG, TIFF и страницы PDF

Из растровых источников библиотека умеет встраивать JPEG, PNG и TIFF. Для этих форматов предусмотрен ввод как из файлов, так и из пользовательских потоков; при потоковом вводе библиотеке нужен интерфейс с возможностью позиционирования.

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

Изменение существующих документов

Методика изменения построена на механизме incremental update из спецификации PDF. Библиотека может открыть существующий файл и дописать новые объекты и изменения, не переписывая всю исходную структуру с нуля. Есть вспомогательный PDFModifiedPage для сценариев вроде добавления штампа, текста или штрихкода поверх существующей страницы. Более глубокая правка требует понимания модели объектов PDF и явного копирования связанных сущностей.

Независимый парсер PDF

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

Потоки, буферы и сохранение состояния

Большинство файловых операций имеет потоковые варианты. Вывод PDF можно направить в реализацию IByteWriterWithPosition, а изображения и входные PDF — читать через поток с возможностью менять позицию. Это удобно, когда документ хранится в базе данных, объектном хранилище или памяти и нежелательно создавать временный файл. Для входных PDF, JPEG, TIFF и унифицированного PNG-интерфейса требуется random access к читающему потоку.

Шифрование PDF 2.0

Начиная с версии 4.7.0 библиотека поддерживает шифрование PDF 2.0: может создавать зашифрованные документы, разбирать и расшифровывать их при наличии пароля, а также изменять зашифрованный PDF 2.0 с сохранением метода шифрования. Для этой функции требуется OpenSSL. Он не входит в комплект проекта как bundled-зависимость, поэтому сборочная среда должна предоставить совместимую установку OpenSSL.

Интерфейс и удобство использования

API вместо рабочего окна

У PDFHummus нет панели инструментов, списка миниатюр страниц, меню «Файл» и других зон настольного редактора. Его интерфейс — C++-классы, заголовочные файлы и методы. Основной уровень PDFWriter управляет созданием и изменением документа, а более низкие контексты дают доступ к объектам PDF и сериализации. Поэтому удобство продукта следует оценивать не по визуальной навигации, а по тому, насколько его API соответствует архитектуре приложения и квалификации команды.

Диагностика и контроль ошибок

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

Поддерживаемые форматы и совместимость

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

PDFHummus не заявлен как универсальный импортёр DOCX, XLSX, EPUB или изображений произвольного формата. Если исходные данные приходят из офисных документов, их следует преобразовывать другим компонентом либо формировать PDF напрямую из структурированных данных. Для пользовательской конвертации без программирования уместнее готовые инструменты вроде PDF24 Creator.

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

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

Парсер специально не загружает все объекты документа сразу: он читает служебные таблицы и список страниц, а отдельные объекты извлекаются по запросу. Это делает библиотеку пригодной для обработки крупных файлов без обязательного удержания полной объектной модели в памяти. Для очень больших создаваемых документов с версии 4.6.8 можно использовать xref streams PDF 1.5 и новее; разработчик прямо связывает эту возможность с обходом ограничения традиционной xref-таблицы для файлов больше 10 ГБ.

История последних выпусков показывает, что стабильность зависит от обновлений. Версия 4.8.0 принесла переработку внутреннего ByteList ради производительности, но вызвала ошибки libc++ в части окружений; 4.8.1 через несколько дней заменила проблемное решение на сочетание vector и собственной оптимизации малых объектов. Версия 4.9.0 затем сосредоточилась на проверках памяти, границ, циклов и декодеров. Для production-систем это аргумент закреплять версию, запускать собственный набор документов на обновлении и не пропускать security-релизы.

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

Лицензирование и версии

PDF-Writer распространяется по Apache License 2.0. Это открытая разрешительная лицензия, допускающая использование библиотеки в коммерческом и закрытом программном обеспечении при соблюдении условий лицензии и уведомлений. У проекта нет отдельной платной редакции, ограниченного бесплатного режима или пробного периода: исходный код доступен полностью, а функциональность не разблокируется покупкой ключа.

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

Системные требования

Windows

Официальный README называет Visual Studio компилятором для Windows и требует CMake. Точная минимальная версия Windows или Visual Studio в текущем README не зафиксирована, поэтому при внедрении лучше опираться на собственную поддерживаемую матрицу toolchain и запускать тесты проекта в целевой конфигурации. Для PDF 2.0 encryption требуется внешняя установка OpenSSL, если функция не отключена.

Linux и macOS

Для Linux и macOS указаны GCC или Clang и CMake. Большая часть зависимостей может собираться из включённых в репозиторий исходников, поскольку USE_BUNDLED по умолчанию включён. Команда, предпочитающая системные библиотеки и централизованные обновления пакетов, может отключить bundled-режим или разрешить fallback на встроенные копии. Такой выбор влияет на воспроизводимость сборки и ответственность за обновление зависимостей.

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

Стандартный состав проекта включает FreeType, LibAesgm, LibJpeg, LibPng, LibTiff и Zlib; OpenSSL не bundled. Поддержку DCT/JPEG, TIFF, PNG и PDF 2.0 encryption можно исключить отдельными CMake-параметрами, что уменьшает набор зависимостей ценой соответствующих возможностей. В README также есть отдельная ссылка на руководство сборки для iOS, но PDFHummus не следует из этого считать готовым мобильным приложением: это по-прежнему библиотека, которую разработчик интегрирует в свой продукт.

Преимущества и недостатки PDFHummus

Плюсы и минусы

Открытая Apache 2.0. Нет подписки, платной разблокировки API или обязательного облака.

Создание и разбор в одном проекте. Библиотека сочетает генератор, парсер, копирование страниц и инкрементальные изменения.

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

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

Работа с крупными документами. Ленивое чтение объектов снижает необходимость держать весь PDF в памяти, а xref streams позволяют создавать очень большие файлы.

Актуальная работа над безопасностью. Выпуск 4.9.0 включает большой набор исправлений и развивает fuzzing и sanitizer-инструменты.

Минусы

Нет GUI. Для конечного пользователя PDFHummus сам по себе ничего не открывает и не редактирует на экране.

Высокий порог для сложных изменений. Работа с внутренними объектами PDF требует понимания спецификации и связей ресурсов.

Нет создания linearized PDF. Библиотека умеет читать такой вход, но Fast Web View на выходе специально не реализован.

Нет подтверждённого универсального OCR или рендерера. Скан в текст и превращение страниц в пиксельные превью требуют другого компонента.

OpenSSL добавляет внешнюю зависимость. Она обязательна для PDF 2.0 encryption и не поставляется bundled.

Некоторые семантические объекты при копировании требуют ручной работы. Аннотации и дополнительные ссылки нельзя считать автоматически перенесёнными во всех сценариях.

Карта критических зависимостей

Паспорт обратимости операций

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

Хронология развития и поддержки

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

С Sumatra PDF сравнение возможно только по месту в цепочке документов. Sumatra PDF — готовый Windows-просмотрщик, а PDFHummus — библиотека без GUI. Их можно использовать вместе: сервер или настольное приложение создаёт PDF через PDFHummus, а пользователь открывает результат в Sumatra PDF. Если нужен именно визуальный редактор, логичнее смотреть на PDF-XChange Editor или Adobe Acrobat Pro; это другой класс продуктов.

Инструкция по установке

Получение исходников и выбор версии

1. Откройте официальный репозиторий PDF-Writer и раздел Releases, а не страницу HummusJS.

2. Выберите стабильный тег, совместимый с вашим проектом. На дату обзора последний релиз — 4.9.0.

3. Сохраните номер тега в файле зависимостей или CMake-конфигурации, чтобы сборка не менялась неожиданно при обновлении ветки main.

4. Если в проекте обрабатываются внешние PDF, просмотрите release notes между старой и новой версией, особенно security-исправления.

Сборка на Windows

1. Подготовьте Visual Studio с C++ toolchain и установите CMake.

2. Если требуется PDF 2.0 encryption, установите OpenSSL так, чтобы CMake мог найти библиотеку. Если функция не нужна, предусмотрите PDFHUMMUS_NO_OPENSSL=TRUE.

3. Создайте отдельный каталог build рядом с исходниками и выполните конфигурацию CMake для проекта.

4. Соберите конфигурацию Release командой CMake build. Затем запустите ctest для тестового набора PDFWriter.

5. При необходимости выполните CMake install в отдельный prefix и подключите экспортированную цель PDFHummus::PDFWriter к приложению.

Сборка на Linux и macOS

1. Установите GCC или Clang и CMake. Для шифрования PDF 2.0 отдельно предоставьте OpenSSL.

2. Определите политику зависимостей: USE_BUNDLED=TRUE подходит для встроенных копий, а системные библиотеки можно выбрать отключением bundled-режима.

3. В каталоге build выполните конфигурацию CMake, затем сборку Release.

4. Запустите ctest до подключения библиотеки к основному приложению. Это отделяет проблемы toolchain и зависимостей от ошибок собственного кода.

5. Установите библиотеку в выбранный prefix либо подключите её через FetchContent/find_package согласно структуре проекта.

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

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

Обновление и безопасное удаление

PDFHummus обычно не регистрируется в системе как настольное приложение. Поэтому «удаление» зависит от способа интеграции: при FetchContent удаляется ссылка на зависимость и очищается build-каталог; при CMake install следует удалить файлы из того prefix, который контролируется вашим проектом или пакетным менеджером; при копировании исходников — убрать их из дерева проекта и сборочной конфигурации. Перед этим нужно убедиться, что ни одна цель больше не линкуется с PDFWriter.

Практические кейсы

Генерация счёта или отчёта из данных

Цель. Сформировать PDF без офисного шаблона и внешнего приложения. Подготовка. Определите размеры страниц, доступные шрифты, набор изображений и правила переноса строк. Шаги. Создайте PDFWriter, откройте новый документ, добавляйте страницы, выводите текст UTF-8 и изображения, завершите PDF и проверяйте статус каждой операции. Контроль. Откройте результат в независимом просмотрщике, проверьте количество страниц, копирование текста и наличие встроенных шрифтов. Ограничение. Сложную табличную или потоковую верстку приложение рассчитывает само; PDFHummus не заменяет HTML/CSS layout engine.

Добавление штампа к существующему PDF

Цель. Нанести идентификатор заказа, штрихкод или служебную надпись поверх готовой страницы. Подготовка. Сохраните неизменённый оригинал и определите координаты с учётом MediaBox/CropBox и поворота страницы. Шаги. Откройте документ в режиме изменения, получите PDFModifiedPage, добавьте новый контент и завершите incremental update в отдельный выходной файл. Контроль. Сравните число страниц и визуально проверьте несколько вариантов ориентации. Ограничение. Инкрементальная правка не является санитарным удалением старых данных и не даёт пользовательской истории Undo.

Сборка документа из страниц нескольких PDF

Цель. Составить единый пакет из титульного листа и выбранных страниц исходных документов. Подготовка. Зафиксируйте порядок источников и диапазоны страниц. Шаги. Создайте новый PDF, для каждого источника создайте контекст копирования и переносите требуемые страницы; один и тот же контекст используйте повторно, если из файла копируется несколько диапазонов. Контроль. Проверьте порядок, размеры страниц, ссылки и аннотации, если они критичны. Ограничение. Не все дополнительные связанные объекты гарантированно копируются автоматически; сложные формы и аннотации требуют отдельной проверки.

PDF напрямую в память или хранилище

Цель. Избежать временного файла на диске в веб-сервисе. Подготовка. Реализуйте IByteWriterWithPosition для буфера или адаптера к целевому хранилищу. Шаги. Запустите StartPDFForStream, сформируйте страницы и завершите документ EndPDFForStream. Контроль. После завершения проверьте размер буфера и разберите полученные байты PDF-парсером перед выдачей клиенту. Ограничение. Откат уже переданных байтов зависит от вашей реализации потока, поэтому до успешного завершения лучше не объявлять объект готовым.

Контроль перед сохранением и передачей

Проверить все коды возврата и не публиковать файл после ошибки генерации.

Убедиться, что EndPDF или EndPDFForStream завершился успешно.

Повторно открыть итог парсером и сверить ожидаемое число страниц.

Проверить документ в независимом просмотрщике, например Sumatra PDF; для интерактивной проверки аннотаций можно использовать Okular.

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

При копировании страниц отдельно проверить аннотации, формы и ссылки, если они важны.

Для чувствительных документов не считать incremental deletion гарантированным стиранием прежнего содержимого.

Зафиксировать версию PDFHummus и зависимости в метаданных сборки или журнале задания.

Если задача — только разделить или склеить PDF вручную без разработки, API-библиотека будет избыточной: проще использовать PDFsam Basic. PDFHummus оправдан, когда сценарий является частью автоматизированного приложения и должен повторяться без участия оператора.

Реестр проверяемых утверждений

Часто задаваемые вопросы

PDFHummus — это программа для чтения PDF?

Нет. Это C++-библиотека без собственного графического просмотрщика. Для чтения пользователем нужен отдельный viewer, например Sumatra PDF, а PDFHummus используется внутри программы для генерации, анализа или изменения файла.

Нужно ли отправлять документы в облако?

Нет. Основной PDF-Writer работает локально как код внутри приложения. Отдельный PDFHummus Services — другой продукт; его существование не делает облако обязательным для C++-библиотеки.

Есть ли OCR для сканов?

Подтверждённого OCR-движка в PDFHummus нет. Он может встраивать изображения, но распознавание текста на скане требует отдельного OCR-компонента.

Можно ли получить Fast Web View?

PDFHummus способен разбирать linearized PDF на входе, но генерация linearized PDF на выходе официально не реализована, поскольку противоречит однопроходной архитектуре записи. Если Fast Web View обязателен, после генерации потребуется инструмент с linearization, например QPDF.

HummusJS и PDFHummus — одно и то же?

Нет. HummusJS — Node.js-обёртка вокруг PDFHummus/PDF-Writer, поддержку которой автор прекратил в 2019 году. Основной C++-репозиторий PDF-Writer продолжает выпускаться. Для Node.js следует отдельно оценивать поддерживаемые обёртки, а не подключать архивный HummusJS только из-за знакомого имени.

Можно ли редактировать текст существующего PDF как в Word?

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

Есть ли цифровая подпись PAdES?

В актуальном официальном описании PDFHummus такая возможность не представлена как штатная высокоуровневая функция. Если электронная подпись — обязательное требование, стоит рассмотреть библиотеку с явно заявленной поддержкой подписи, например PoDoFo, и отдельно проверить нужный профиль и нормативные требования.

Насколько безопасно обрабатывать неизвестные PDF?

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

Вывод

PDFHummus подходит разработчикам C++-систем, которым нужен локальный, бесплатный и встраиваемый механизм создания PDF, работы со страницами и изображениями, программного разбора и контролируемых изменений. Особенно органично библиотека выглядит в сервисах генерации документов и приложениях, где уже есть собственный интерфейс и бизнес-логика, а PDF требуется получать непосредственно из кода или потока.

Продукт менее удачен, если задача состоит в ручном редактировании документов, OCR, готовом рендеринге страниц, создании Fast Web View или работе конечного пользователя без программирования. В таких случаях лучше выбрать профильный GUI-редактор, OCR-продукт или библиотеку с нужной специализированной функцией. QPDF сильнее в структурных преобразованиях и linearization, PDFBox — в широком Java-наборе функций, PoDoFo стоит проверить при требованиях к подписи и современному C++17 API, а Sumatra PDF решает совсем другую задачу — удобный просмотр готового документа.