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

FlattenLoadedPageRotation: выпрямляем поворот страницы PDF

Номер страницы, нарисованный в x = 560, y = 30 в пользовательском пространстве PDF (начало в левом нижнем углу), принадлежит правому нижнему углу страницы Letter. На сканированной ландшафтной странице, хранимой как портретный медиум, с /MediaBox [0 0 612 792] и /Rotate 90, тот же вызов рисования кладёт номер в 30 пунктах от левого края и в 52 пунктах над низом того, что видит читатель, причём цифры бегут прямиком вниз по полю. Штамповочный код сделал ровно то, что ему сказали. Он писал в систему координат, которую каждый просмотрщик поворачивает на четверть по часовой, прежде чем на неё взглянут

Сканеры и мобильные приложения захвата рождают такие страницы постоянно: выставить флаг поворота куда дешевле, чем перекодировать JPEG. Вьюверы чтут /Rotate, поэтому файл выглядит исправно ровно до тех пор, пока что-то не заработает в сыром user space: штамповочная процедура, шаг спуска полос, меряющий слоты по одному /MediaBox, печатный RIP со своим мнением об ориентации. Прочный фикс — выпрямить поворот: сдвинуть поворот в поток содержимого и выставить /Rotate в 0, чтобы сохранённая геометрия и показанная наконец совпали. Звучит как одна матрица. На практике это доходит до пяти page box, трёх сортов аннотационной геометрии, каждой ссылки, целящей в страницу, и дерева структуры, и у ISO 32000-1 для каждого своё правило

Куда /Rotate поворачивает страницу PDF?

/Rotate поворачивает страницу по часовой для показа и печати, кратно 90 градусам (ISO 32000-1 §7.7.3.3, Table 30). При 90 градусах левая грань медиума становится верхом, а верхняя грань — правой стороной, так что в y-down device space отображение — это X = (y - Bottom) * Scale и Y = (x - Left) * Scale. При 270 градусах верхом становится правая грань. Ключ вдобавок наследуемый: вместе с /Resources, /MediaBox и /CropBox он один из четырёх атрибутов страницы, которые может подать предок /Pages (§7.7.3.4), так что словарь страницы без собственного /Rotate всё равно может быть повёрнут. THotPDF.GetLoadedPageRotation идёт по цепочке /Parent, берёт первый встреченный /Rotate и нормализует его в 0–359, так что сохранённый -90 возвращается как 270

Направление — та часть, которая ломается незаметно. Матрица page-to-device с переставленными y-компонентами для 90 и 270 градусов вовсе не вращает страницу — она отражает её через диагональ, и детерминант меняет знак. Оба угла всё ещё выглядят повёрнутыми. Битмап имеет переставленные ширину и высоту, а отображение точки в вид и обратно возвращает стартовую позицию, так что проверки размеров и round-trip тесты проходят без жалоб. Что ловит ошибку — страница с асимметричным маркером в одном углу, отрендеренная и попиксельно сравнённая с независимым рендерером; проверка геометрии самой на себя здесь доказывает очень мало. В HotPDF FlattenLoadedPageRotation и RenderLoadedPageToBitmap делят одно clockwise-соглашение, так что угол, который рендерер рисует в левом верхнем углу повёрнутой страницы, после выпрямления остаётся в левом верхнем

Как HotPDF выпрямляет поворот страницы в Delphi: портретная страница, хранимая с /Rotate 90, показывается по часовой как ландшафтный вид 792 на 612, отображение в устройство X = (y - Bottom) * Scale, Y = (x - Left) * Scale двигает каждый угол, а перестановка y-компонент матрицы даёт отражение, которое ловит только сравнение угловых маркеров
Вьюверы поворачивают страницу по часовой для показа, тогда как байты остаются портретными — GetLoadedPageRotation сперва идёт по цепочке /Parent, потому что /Rotate один из четырёх наследуемых атрибутов страницы

Выпрямляем диапазон страниц с FlattenLoadedPageRotation

THotPDF.FlattenLoadedPageRotation(PageRange, Info) обрабатывает каждую страницу из PageRange, чей эффективный поворот равен 90, 180 или 270, и возвращает число выпрямленных страниц. Пустой PageRange значит весь документ; иначе строка использует синтаксис с единицы '1-3,7', а номер страницы за концом бросает исключение вместо тихого выпадения из диапазона. Исходные потоки содержимого остаются байт в байт как были. Метод ставит новый поток с q и поворотом cm в начало /Contents, поток с Q — в конец, а затем вписывает /Rotate 0 в сам словарь страницы

Действующий /RotateПрефиксный потокНовый MediaBox
90q 0 -1 1 0 -Bottom Width+Left cm[0 0 Height Width]
180q -1 0 0 -1 Width+Left Height+Bottom cm[0 0 Width Height]
270q 0 1 -1 0 Height+Bottom -Left cm[0 0 Height Width]

Явный ноль значит больше, чем кажется. Удалить ключ /Rotate казалось бы аккуратнее, и это ломает каждую страницу, чья девяностка пришла с узла /Pages: страница снова унаследует поворот, и вьювер развернёт уже прямое содержимое. /Rotate 0 на словаре страницы блокирует то наследование, что делает его единственным безопасным значением для записи

var
  Pdf: THotPDF;
  Info: THPDFRotationFlattenInfo;
  Flattened: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    if Pdf.LoadFromFile('scanned-batch.pdf') > 0 then
    begin
      // '' = все страницы; страницы уже на 0 градусов считаются, но не трогаются
      Flattened := Pdf.FlattenLoadedPageRotation('', Info);
      Writeln(Format('Scanned %d, flattened %d pages',
        [Info.ScannedPageCount, Info.FlattenedPageCount]));
      Writeln(Format('Turned %d annotations, %d destinations, %d tagged geometry entries',
        [Info.TransformedAnnotationCount, Info.TransformedDestinationCount,
         Info.TransformedStructureGeometryCount]));
      if Flattened > 0 then
        Pdf.SaveLoadedDocument('scanned-batch-upright.pdf');
    end;
  finally
    Pdf.Free;
  end;
end;

Запись THPDFRotationFlattenInfo стоит залогировать, а не выбросить. ScannedPageCount — число страниц в диапазоне, FlattenedPageCount совпадает с возвращаемым значением, а три счётчика Transformed... показывают, указывали ли ссылки, закладки или помеченная геометрия на повёрнутые страницы. Ноль destination по всему сканер-пакету — норма, ведь сканеры редко пишут ссылки вовсе. А вот файл PDF/UA с тегами, отчитавшийся нулевой структурной геометрией, когда вы знаете, что он несёт bounding box фигур, — тот самый, что надо открыть руками

Прочитайте каждый page box, прежде чем писать хоть один

Выпрямление переписывает только боксы, которые у страницы уже есть, и читает их все прежде записи первого. Порядок важен из-за цепочки дефолтов в §14.11.2: GetLoadedPageBox(PageIndex, pbCropBox, ...) возвращает MediaBox, когда у страницы нет /CropBox, а /BleedBox, /TrimBox и /ArtBox откатываются к CropBox. Цикл, читающий, поворачивающий и пишущий по одному боксу за раз, идёт прямиком в эту цепочку. Он поворачивает MediaBox и сохраняет его, читает «CropBox», получает обратно свежеповернутый MediaBox, поворачивает его второй раз и пишет CropBox, которого у страницы никогда не было. На странице Letter второй поворот даёт [0 -180 612 612], и, обрезанный новым MediaBox, видимый участок страницы сжимается до квадрата 612 × 612

Наследование делит пять боксов на две группы. MediaBox и CropBox ищутся по цепочке /Parent, тогда как BleedBox, TrimBox и ArtBox засчитываются, только когда сидят на самом словаре страницы. FlattenLoadedPageRotation следует тому же разделу, решая, какие боксы существуют: унаследованный CropBox поворачивается и пишется на страницу, а бродячий /TrimBox на узле /Pages считается отсутствующим и вниз не копируется

procedure DumpPageGeometry(Pdf: THotPDF; PageIndex: Integer);
var
  L, B, R, T: Single;
begin
  Writeln('Effective /Rotate: ', Pdf.GetLoadedPageRotation(PageIndex));
  if Pdf.GetLoadedPageBox(PageIndex, pbMediaBox, L, B, R, T) then
    Writeln(Format('MediaBox [%g %g %g %g]', [L, B, R, T]));
  // True даже без ключа /TrimBox: значение откатывается к CropBox, затем MediaBox
  if Pdf.GetLoadedPageBox(PageIndex, pbTrimBox, L, B, R, T) then
    Writeln(Format('TrimBox  [%g %g %g %g]', [L, B, R, T]));
  // Предустановка Letter; GetLoadedPageVisibleBox при неудаче не трогает выходы
  L := 0; B := 0; R := 612; T := 792;
  Pdf.GetLoadedPageVisibleBox(PageIndex, L, B, R, T);
  Writeln(Format('Visible  [%g %g %g %g]', [L, B, R, T]));
end;

Прогоните этот хелпер до и после выпрямления. Для страницы на 90 градусов с MediaBox [0 0 612 792] выпрямленный MediaBox читается как [0 0 792 612]. Каждый переписанный бокс проходит тот же поворот по часовой относительно исходного начала MediaBox, поэтому новый MediaBox всегда стартует из 0,0, а TrimBox [18 18 594 774] становится [18 18 774 594] — по-прежнему 18 пунктов от каждого края ландшафтной страницы

GetLoadedPageVisibleBox возвращает область, которую показывает вьювер и печатает принтер: CropBox, обрезанный до MediaBox и нормализованный так, что Left меньше Right, а Bottom меньше Top. Рендерер страниц и SVG-экспорт меряют вывод по тому же боксу. Коду, которому нужен размер, реально видимый человеку, следует звать GetLoadedPageVisibleBox: чтение /MediaBox для этой цели даёт неверный ответ на любой странице с CropBox

Почему HotPDF читает каждый бокс страницы до записи любого при FlattenLoadedPageRotation: BleedBox, TrimBox и ArtBox дефолтят к CropBox, который сам откатывается к MediaBox, поэтому поворот боксов по одному заставлял CropBox прочитать уже переписанный MediaBox, и второй поворот писал бокс, которого у страницы не было, обрезая ландшафтную страницу до квадрата
Цепочка дефолтов значит, что вывод одного бокса — вход другого: сперва прочитайте всё, трансформируйте от исходного начала MediaBox, потом пишите

Почему аннотации ломаются, если повернуть только /Rect?

Аннотации ломаются, потому что appearance-поток никогда не рисуется прямиком в /Rect. По §12.5.5 вьювер сперва трансформирует /BBox формы её /Matrix, затем масштабирует и транслирует ограничивающую рамку результата в /Rect. Поверните только /Rect — и штамп 200 × 40 будет втиснут в слот 40 × 200, где его никто не прочтёт. Потому FlattenLoadedPageRotation домножает справа clockwise-поворот страницы на каждый appearance-/Matrix (при 90 градусах — [0 -1 1 0 0 0] в соглашении вектор-строк) по всем appearance /N, /R и /D и каждому состоянию внутри них. Один appearance-поток может обслуживать несколько аннотаций или состояний, поэтому каждый поток поворачивается ровно один раз за вызов; поток, разделяемый страницами с разными поворотами, берёт поворот первой страницы, которая до него добралась

Два правила поменьше удерживают поля форм и стикеры на местах. Запись /MK /R виджета (§12.5.6.19) — угол против часовой, поэтому clockwise-угол страницы из него вычитается по модулю 360. Оставите как есть — следующая регенерация appearance нарисует текст поля не в ту сторону. Аннотации с флагом NoRotate (позиция бита 5, значение 16, §12.5.3) остаются прямыми на повёрнутой странице и вращаются вокруг верхнего левого угла своего /Rect; для них метод сохраняет ширину, высоту и прямой вид, двигая лишь этот угол туда, куда его ставит поворот

Дальше словарей аннотаций тот же вызов поворачивает /QuadPoints, /Vertices, /L и /InkList. Он переписывает явные destination, называющие страницу: точки /XYZ и прямоугольники /FitR прогоняются через поворот, а при 90 или 270 градусах /FitH и /FitBH становятся /FitV и /FitBV, и наоборот (§12.3.2.2). Он также трансформирует помеченную геометрию вроде записей /BBox атрибутов у структурных элементов, чей /Pg — эта страница

Дерево структуры — то место, где прямолинейный обход ломается неприятным образом. /Pg структурного элемента указывает назад на объект страницы, поэтому сканер, таскающий «это принадлежит странице» вниз по каждому ключу, зайдёт по /Pg в страницу, затем в /Annots — поворачивая прямоугольники аннотаций второй раз — и в Form XObject, чей /BBox живёт в пространстве формы и уже покрыт внешним cm. Ход по /P поднимается к корню дерева и затягивает элементы с других страниц. Сработает ли что-то из этого, зависит от того, в каком порядке случайно обойдут объекты; когда /Pages стоит в каталоге раньше /StructTreeRoot, страница обычно достигается первой, и ущерб остаётся скрытым, так что обычные тестовые файлы могут проходить. FlattenLoadedPageRotation несёт контекст страницы только через /K (детей) и /A (атрибуты), а ребёнок с собственным /Pg на другой странице оставляется той странице

Почему аннотации ломаются, когда страницу HotPDF выпрямляют поворотом одного /Rect: штамп 200 на 40 масштабируется в слот 40 на 200 и становится нечитаемым, поэтому FlattenLoadedPageRotation домножает clockwise-поворот на каждый appearance /Matrix по /N, /R и /D, поправляет идущий против часовой /MK /R и вращает NoRotate-аннотации вокруг их верхнего левого угла
Вьювер втискивает трансформированный BBox appearance в /Rect, поэтому сам поток обязан повернуться — один проход на разделяемый appearance, ровно один раз за вызов

Проверяем результат, прежде чем отправлять партию

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

  • Страницы с эффективным поворотом уже 0 или с отсутствующим MediaBox либо нулевой шириной или высотой пропускаются без исключения, так что сверяйте возвращаемое значение с ожидаемым числом изменений
  • Form XObject, на которые ссылаются ресурсы страницы, хранят собственные /BBox и /Matrix, потому что внешний cm уже поворачивает всё, что они рисуют
  • Destination находятся обходом каждого косвенного объекта по разу на каждую выпрямленную страницу; на большом файле с сотнями повёрнутых страниц закладывайте бюджет на этот обход для каждой
  • RenderLoadedPageToBitmap рисует потоки содержимого страницы и оставляет аннотации в стороне, так что визуальная проверка повернутых штампов требует сперва FlattenLoadedAnnotations на черновой копии документа

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

// Только черновая копия: FlattenLoadedAnnotations запекает аннотации
// в содержимое страницы и удаляет их со страницы
Pdf.FlattenLoadedAnnotations('1');              // диапазон страниц с единицы
Before := Pdf.RenderLoadedPageToBitmap(0, 96);  // индекс страницы с нуля
if Before = nil then
  raise Exception.Create('Page 1 did not render');
try
  Pdf.FlattenLoadedPageRotation('1', Info);
  After := Pdf.RenderLoadedPageToBitmap(0, 96);
  if After = nil then
    raise Exception.Create('Flattened page 1 did not render');
  try
    // Ваши собственные проверки, а не вызовы библиотеки: размеры обязаны совпасть...
    Assert((Before.Width = After.Width) and (Before.Height = After.Height));
    // ...как и пиксели метки в левом верхнем углу
    Assert(Before.Canvas.Pixels[8, 8] = After.Canvas.Pixels[8, 8]);
  finally
    After.Free;
  end;
finally
  Before.Free;
end;

Если у штампов на ваших повёрнутых страницах ещё нет appearance-потоков, шаг их создания разбирает статья о синтезе appearance аннотаций перед выпрямлением. Рендерер за угловым сравнением описан в статье о рендеринге загруженной страницы PDF в битмап, а редакция со стиранием и N-up сшивка на загруженных PDF держатся той же идеи добавления потоков в /Contents без перекодирования исходных. FlattenLoadedPageRotation, GetLoadedPageBox и GetLoadedPageVisibleBox поставляются с HotPDF для Delphi и C++Builder — подробности на странице компонента HotPDF Delphi PDF