Техническая статья

PDF redaction и N-up stitching в Delphi с HotPDF

К вам приходит запрос: взять пакет уже отрендеренных выписок, закрасить номера счетов и вывести по две страницы на лист, чтобы сэкономить бумагу. Обе половины этой задачи сводятся к хирургии content stream в PDF, который создали не вы, поэтому здесь нет дружелюбного page canvas для рисования и нет font manager, на который можно опереться. Вы напрямую редактируете граф объектов загруженного документа, дописывая сырые операторы рисования в страницу, макет которой уже собрал другой инструмент. HotPDF открывает для этого ровно две точки входа, и более опасная из них выглядит как раз безобидной

HotPDF — нативный VCL PDF-компонент для Delphi и C++Builder, и его API загруженных документов включает методы, которые создают совершенно новый контент на странице, открытой с диска, а не собранной вами с нуля. Здесь речь о двух из них: RedactLoadedRect, который рисует непрозрачный прямоугольник поверх области, и StitchLoadedPage, который масштабирует одну страницу и рисует её на другой. Оба работают через запись операторов content stream из ISO 32000-1 §8.5 в поток /Contents страницы. Понимание того, что эти операторы делают — и, что не менее важно, чего не делают, — отличает рабочий инструмент от утечки данных

Добавление операторов в загруженную страницу

Когда вы строите страницу обычным API HotPDF, компонент сам владеет content stream и сериализует ваши вызовы TextOut и векторные вызовы за вас. Загруженная страница устроена иначе: её /Contents — уже существующий stream object, возможно разделяемый, возможно часть content array, и врезать туда свои байты нужно, не испортив то, что уже есть. Эту задачу безопасно решают три небольших помощника. NewIndirectStream выделяет свежий косвенный THPDFStreamObject с пустым буфером и записью /Length 0; ResolveLoadedStream спускается по косвенной ссылке до базового потока; а AppendLoadedStream дописывает сырые байты в конец потока и переписывает /Length, чтобы сохраняемый объект оставался корректно сформированным

Шаблон, которому следуют оба публичных метода, одинаков. Найти /Contents страницы, разрешить его в поток, а если пригодного потока нет, создать новый и привязать его. Затем дописать операторы. Поскольку новые байты помещаются в конец потока, модель художника гарантирует, что они будут нарисованы поверх всего, что вывел исходный макет. Вся механика прямоугольника для redaction держится именно на этом порядке, и по той же причине этот прямоугольник не является тем, чем его обычно считают

HotPDF: добавление операторов в загруженную страницу проходит три помощника — от нахождения потока Contents страницы через его разрешение или создание до добавления сырых байтов в конце, а модель художника гарантирует, что эти байты рисуются поверх всего, что нарисовала исходная компоновка
NewIndirectStream, ResolveLoadedStream и AppendLoadedStream вшивают свежие операторы в конец существующего потока /Contents, поэтому всё нарисованное ложится поверх исходной раскладки страницы, не переписывая ни байта

RedactLoadedRect: непрозрачная накладка, а не удаление

RedactLoadedRect принимает zero-based индекс страницы, четыре координаты в user space и три цветовых компонента в диапазоне 0-1:

var
  Pdf: THotPDF;
begin
  Pdf := THotPDF.Create(nil);
  try
    if Pdf.LoadFromFile('statement.pdf') > 0 then
    begin
      // Закрыть полосу с номерами счетов на странице 1 сплошным чёрным.
      // Координаты — это user space PDF: начало в левом нижнем углу, единицы — points.
      Pdf.RedactLoadedRect(0, 56, 690, 320, 706, 0, 0, 0);
      Pdf.SaveLoadedDocument('statement-covered.pdf');
    end;
  finally
    Pdf.Free;
  end;
end;

Под капотом метод записывает в content stream три оператора: установку цвета заливки в DeviceRGB, r g b rg, путь прямоугольника, x y w h re, и заливку, f. Ширина и высота вычисляются как X2 - X1 и Y2 - Y1, поэтому вы передаете две противоположные точки, а метод сам вычисляет размеры. Передайте 0, 0, 0 для цвета и получите черную полосу. Передайте 1, 1, 1 для белой, совпадающей с белой страницей. Координаты принадлежат собственной user space загруженной страницы, то есть начало находится в левом нижнем углу, единицы измерения это points, и это также означает, что для точного размещения нужно знать /MediaBox страницы. GetLoadedPageBox вместе с pbMediaBox дает вам это

Прочитайте это дважды: закрашенный прямоугольник визуально закрывает контент, но не удаляет его. Текст, изображение или vector art под прямоугольником все еще присутствуют в PDF, все еще находятся в графе объектов, их по-прежнему может извлечь любой, кто скопирует страницу, запустит text extractor или просто удалит ваш прямоугольник из content stream. Это визуальная маскировка, а не redaction в юридическом или защитном смысле. Если вы скрываете действительно чувствительные данные, номера счетов, медицинские записи, личности, вообще что-либо регулируемое, закрывать это черным прямоугольником и отправлять файл означает готовить утечку данных, которая рано или поздно обнаружится. Настоящая redaction требует удаления лежащих под этим объектов контента, а не рисования поверх них

HotPDF: закрытый номер счёта переживает редактирование рисованием — просмотрщик показывает сплошную тёмную полосу над строкой счёта, но контентный поток всё ещё содержит строку ACCT, и любой извлекатель текста печатает её обратно без изменений
Операторы r g b rg, re и f лишь докладывают пиксели сверху — исходный текстовый объект остаётся живым в графе объектов, поэтому проход копирования и извлечения возвращает каждый символ, скрытый чёрной плашкой

Само имя метода говорит «Redact», и это полезное предупреждение о том, как результат будут неверно истолковывать, а не обещание того, что именно он удаляет. RedactLoadedRect по замыслу является примитивом визуальной redaction; redaction с удалением контента — другая операция, которая проходит по существующим операторам content stream и переписывает их. Поэтому безопасное правило узкое: используйте RedactLoadedRect для нечувствительной косметической маскировки — скрыть черновой watermark, очистить область перед скриншотом, перекрыть устаревший логотип на внутреннем proof. Как только то, что лежит под прямоугольником, стало бы важным в случае утечки, это неправильный инструмент, и верный ответ — пересобрать документ без этих данных или использовать настоящий pipeline удаления контента

StitchLoadedPage: масштабировать, сдвигать, рисовать

N-up impose является более дружелюбной задачей, потому что здесь ничего не скрывается, а только переставляется. StitchLoadedPage принимает индекс целевой страницы, индекс исходной страницы, смещение X/Y и коэффициент масштаба, затем рисует исходную страницу на целевой в указанной позиции и размере:

// Наложить страницу 2 (индекс 1) на страницу 1 (индекс 0),
// масштабированную до 70% и сдвинутую вправо-вверх.
Pdf.StitchLoadedPage(0, 1, 40, 380, 0.7);

// Удобный вариант 2-up: исходная страница на правой половине целевой.
Pdf.StitchLoadedPageSideBySide(0, 1);

Строка операторов, которую он дописывает, представляет собой стандартную последовательность transform-and-paint: q для сохранения графического состояния, матрицу cm со scale на диагонали и offset в слотах трансляции, /StitchSrc Do для вызова внешнего объекта и Q для восстановления состояния. Пара q/Q важна, она изолирует transform, чтобы stitched-страница не протекала своей системой координат во все, что будет дописано позже. Метод также блокирует очевидные ошибки, индексы вне диапазона, совпадение target и source, неположительный scale, который он зажимает к 1.0, и завершает работу тихо, без исключения, поэтому проверяйте входные данные, потому что безмолвный no-op выглядит точно так же, как успех

StitchLoadedPageSideBySide является тонкой удобной оберткой над общим методом. Он читает ширину media box целевой страницы, делит ее пополам и вызывает StitchLoadedPage с этой половиной ширины как X-offset и фиксированным scale 0.5, помещая исходную страницу в правую половину. Жестко заданное 0.5 предполагает, что у source и target одинаковая ширина. Если это не так, source не заполнит свою половину аккуратно, и вам понадобится общий StitchLoadedPage с scale, который вы вычислите сами из обоих media box

Как stitch ссылается на исходную страницу

Эта деталь — то, что стоит знать, прежде чем доверять результату в разных viewer. Классический N-up impose оборачивает контент исходной страницы в Form XObject — самодостаточный drawable object, который по ISO 32000-1 §8.10.1 обязан нести /Type /XObject, /Subtype /Form и собственную clipping box /BBox. StitchLoadedPage идёт более лёгким путём: он регистрирует сам словарь страницы-источника напрямую в /Resources /XObject целевой под именем StitchSrc, а затем рисует его через Do. Словарь страницы и Form XObject достаточно близки по модели содержимого — оба ссылаются на content stream и словарь ресурсов, — поэтому многие reader всё же отрисуют результат

Поскольку зарегистрированный объект не несёт маркера /Subtype /Form и собственной записи /BBox, строгий consumer имеет полное право проигнорировать Do или обрезать его не так, как вы ожидаете. Поэтому проверяйте сшитый вывод в тех viewer, которыми реально пользуются ваши клиенты, а не только в том, что стоит у вас, а для архивных PDF или файлов, чистых для строгих validator, накладывайте страницы через полноценную обёртку Form XObject выше по потоку. Та же дисциплина относится ко всему, что вы строите на загруженном графе объектов, — именно поэтому PDF preflight pass в Delphi заслуживает места в release pipeline всякий раз, когда вы программно изменяете документы

HotPDF: сшивка добавляет в целевую страницу q, матрицу cm с масштабом и смещением, вызов Do со StitchSrc и Q, а словарь ресурсов получает сам словарь страницы-источника — без подтипа Form и без BBox
Пара q/Q обрамляет одно преобразование cm и следующий за ним /StitchSrc Do, но поскольку зарегистрированный объект лишён /Subtype /Form и /BBox, сшитый вывод требует визуальной проверки в каждом зрителе, которым пользуются ваши клиенты

Где это подходит, а где нет

Оба метода являются инструментами content stream, поэтому ментальная модель здесь та же, что и для прямого рисования. Если вы уже строили страницы с нуля этим компонентом, vector и color operators за этими вызовами покажутся знакомыми по рисованию на canvas HotPDF в Delphi. Отличается лишь то, что здесь вы дописываете в поток, созданный кем-то другим, а не в поток, которым владеете сами. Держите в голове три границы:

  • Redaction является косметической. RedactLoadedRect закрашивает контент и никогда его не удаляет. Для всего чувствительного пересобирайте источник или используйте настоящее удаление контента, черный прямоугольник не является защитой
  • Проверяйте сшитые страницы в целевых viewer. Исходная страница ссылается напрямую, а не через Form XObject из §8.10.1 с /Subtype /Form и /BBox, поэтому подтверждайте рендеринг в целевых viewer и накладывайте страницы выше по потоку там, где требуется строгая валидация
  • Координаты живут в user space страницы. Начало в левом нижнем углу, единицы points, все определяется собственным media box страницы. Считывайте box через GetLoadedPageBox, прежде чем что-либо размещать, потому что загруженная страница может оказаться не того размера, который вы предполагали

Если использовать пару этих методов в указанных пределах, они покрывают реальный workflow: переставить страницы для печати, замаскировать неконфиденциальные области и записать результат обратно через SaveLoadedDocument — всё это без полного повторного рендеринга. API загруженных документов, включающий эти примитивы stitching и masking, поставляется в составе HotPDF Delphi Component для Delphi и C++Builder, рядом с его методами form field, annotation и FDF