К вам приходит запрос: взять пакет уже отрендеренных выписок, закрасить номера счетов и вывести по две страницы на лист, чтобы сэкономить бумагу. Обе половины этой задачи сводятся к хирургии 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 держится именно на этом порядке, и по той же причине этот прямоугольник не является тем, чем его обычно считают
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 требует удаления лежащих под этим объектов контента, а не рисования поверх них
Само имя метода говорит «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 всякий раз, когда вы программно изменяете документы
Где это подходит, а где нет
Оба метода являются инструментами 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