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

Рефлоу содержимого PDF в адаптивный HTML в Delphi

Договор, экспортированный из текстового процессора с не поставленной галочкой «tagged PDF», на экране всё ещё выглядит структурированным: жирный заголовок кегля 24, нумерованные пункты, разлинованное расписание вознаграждения. Сконвертируйте его в перевёрстываемый HTML, и расписание вернётся настоящей <table>, а заголовок — <p> с в точности тем же статусом, что у сноски. Такой вывод корректен. ISO 32000-1 §14.8 даёт PDF ровно одно место, где можно сказать «этот прогон текста — заголовок», дерево структуры, и непомеченный файл его не имеет. Кегль и жирность — наборные решения, и конвертер, превращающий каждую крупную жирную строку в <h1>, повысит в ранге и выносные цитаты, и итоговые суммы таблиц, и название компании в шапке письма

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

Диаграмма конвейера reflow в PDFium Component в Delphi: GetStructuredText питает либо тегированное дерево структуры, либо порядок чтения компоновки в BuildReflowDocument и самодостаточный экспорт ToHtml
Каждый узел модели reflow прослеживается к тому же структурированному текстовому слою — объявлен ли его заголовок в дереве структуры или выведен из раскладки

Откуда берутся заголовки и списки

PDFium Component строит модель рефлоу вызовом TPdf.BuildReflowDocument, и тот метод берёт каждое слово, блок и семантическую подсказку из GetStructuredText — того же слоя структурированного текста, что разобран в статье о структурированных текстовых блоках и порядке чтения. За ним нет ни второго парсера, ни второго экстрактора текста. Для каждой страницы запрошенного диапазона он собирает блоки в порядке физической раскладки. GetStructuredText уже сопоставил каждый блок с тегированным содержимым страницы по перекрытию площади, а BuildReflowDocument копирует найденную роль на блок: H до H6 становятся заголовками со своим уровнем, LI, Lbl и LBody — элементами списка, Figure — рисунком, чей текст — альтернативное описание, а Caption — подписью

Следуют два следствия, и оба легко наблюдаемы. Порядок блоков всегда идёт за раскладкой страницы, даже в помеченном файле: теги решают, чем блок является, а геометрия — куда он идёт. И на странице без тегов каждый блок — абзац. Заголовки и списки никогда не угадываются по кеглю

Каждый узел несёт поле Source типа TPdfReadingOrderSource: rosStructure, когда роль пришла из дерева структуры, rosHeuristic — когда только из раскладки. Экспортированный HTML повторяет это атрибутами data-source="structure" или data-source="inferred" на каждом элементе, а документный TPdfReflowDocument.Source равен rosStructure, только когда каждая страница диапазона была помечена. Таблицы всегда rosHeuristic: они приходят из геометрического обнаружения, а не из тегов Table. Если нижестоящий шаг трактует заголовки как навигационные ориентиры, проверяйте сперва это поле: помеченный документ даёт ориентиры, выбранные автором

Плоский массив узлов вместо дерева объектов

TPdfReflowDocument.Nodes — дерево, сплющенное в прямом порядке обхода: один динамический массив записей TPdfReflowNode, каждая с ParentIndex и Depth. Узлы страниц сидят на глубине 0 с родителем -1. Абзацы, заголовки, рисунки, подписи, списки и таблицы висят на странице на глубине 1, элементы списка — на глубине 2 под своим списком, а ячейки таблиц доходят до глубины 3 под строкой. Соседние элементы списка делят один узел списка; любой другой блок или таблица между ними начинают новый список

Плоская раскладка — решение о переносимости. Рекурсивная запись, содержащая динамический массив самой себя, компилируется под Delphi, C++Builder и Free Pascal, но все трое обходятся с рекурсивными управляемыми типами по-разному за границей пакета или DLL. Плоский массив простых записей ведёт себя одинаково во всех трёх, и его можно прогнать через stream одним циклом for без рекурсии

uses
  SysUtils, PDFium;

var
  Pdf: TPdf;
  Options: TPdfReflowOptions;
  Doc: TPdfReflowDocument;
  Node: TPdfReflowNode;
  I: Integer;
begin
  Pdf := TPdf.Create(nil);
  try
    Pdf.FileName := 'contract.pdf';
    Pdf.LoadDocument;

    Options := TPdfReflowOptions.Default;   // все страницы, таблицы включены, CSS включён
    Doc := Pdf.BuildReflowDocument(Options);

    for I := 0 to High(Doc.Nodes) do
    begin
      Node := Doc.Nodes[I];
      case Node.Kind of
        prnkHeading:
          Writeln(Format('%sH%d [%s] %s', [StringOfChar(' ', Node.Depth * 2),
            Node.HeadingLevel,
            BoolToStr(Node.Source = rosStructure, True), Node.Text]));
        prnkTable:
          // на узле таблицы RowSpan/ColumnSpan держат число строк и колонок таблицы
          Writeln(Format('%stable %dx%d, page %d, confidence %.2f',
            [StringOfChar(' ', Node.Depth * 2), Node.RowSpan, Node.ColumnSpan,
             Node.PageNumber, Node.Confidence]));
      end;
    end;

    Writeln(Format('%d node(s), %d table(s), %d character(s), pages %d-%d',
      [Length(Doc.Nodes), Doc.TableCount, Doc.CharacterCount,
       Doc.FirstPage, Doc.LastPage]));
  finally
    Pdf.Free;
  end;
end;

На непомеченном договоре из вступления тот цикл не напечатает ни одной строки H и по одной строке таблицы на каждое найденное расписание вознаграждения. Прогоните его на помеченной копии того же документа — и заголовки появятся с True рядом. FirstPage и LastPage в опциях по умолчанию 0, что значит первую и последнюю страницу документа; диапазон за пределами числа страниц бросает EPdfError прежде, чем будет прочитана хоть одна страница

Почему текст таблиц не появляется дважды?

Обнаружение таблиц идёт на каждой странице после сбора структурированного текста, а значит слова внутри таблицы существуют дважды: раз как текстовые блоки, раз как ячейки. Выдать и то и другое — и каждая таблица в HTML будет сопровождена собственным содержимым снова, уже россыпью абзацев, — ровно то, что выдаёт наивное слияние «добавим таблицы к тексту»

Модель решает это геометрически. Текстовый блок, чей bounding box лежит хотя бы наполовину внутри границ найденной таблицы, выбрасывается, а его место занимает узел таблицы. Затем таблицы чередуются с оставшимися блоками по вертикальной позиции (выше на странице — раньше, с направлением слева направо как тай-брейком, когда верхние края расходятся меньше чем на полпункта), так что таблица ложится между абзацем над ней и абзацем под ней вместо присоединения в конец страницы

Диаграмма геометрического правила обнаружения таблиц в PDFium Component для reflow в Delphi: таблица, покрывающая более половины текстового блока, замещает его, так что текст ячеек никогда не появляется дважды
Когда обнаруженная таблица накрывает больше половины текстового блока, узел таблицы заменяет блок, чтобы текст ячеек появился ровно один раз

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

Найденные таблицы вдобавок несут достоверность, и две стратегии обнаружения попадают в разные полосы. Таблица, найденная по линейкам, набирает от 0.88 до 1.0 в зависимости от того, сколько ячеек держат текст. Таблица, выведенная чисто из выравнивания пробелами, — от 0.58 до 0.88. Узел таблицы держит тот балл в Confidence, каждая ячейка повторяет его, а HTML пишет его атрибутом data-confidence на элементе <table>. Таблицы ниже TableOptions.MinConfidence (по умолчанию 0.5) не создаются вовсе, а когда таблица отвергнута, её слова просто остаются в модели обычными абзацами

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

Options := TPdfReflowOptions.Default;
Options.DetectTables := True;
Options.TableOptions.DetectWhitespaceTables := False; // только таблицы с линейками
Options.TableOptions.MinConfidence := 0.9;            // отбрасываем и разреженные сетки
Options.TableOptions.MaxTables := 200;                // потолок на весь документ
Options.TableOptions.MaxCells := 50000;               // потолок на весь документ

Doc := Pdf.BuildReflowDocument(Options);
if Doc.TableCount = 0 then
  Writeln('No ruled tables; all page text is emitted as paragraphs');

Внутри сборки рефлоу MaxTables и MaxCells считаются по всему диапазону страниц, а не на страницу, так что выписка на 300 страниц с разлинованной таблицей на каждой требует MaxTables не меньше 300, иначе сборка остановится с EPdfError на первой таблице за лимитом. Дефолты — 1000 таблиц и 100000 ячеек

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

Экспортируем HTML, которому ничего не нужно

TPdfReflowDocument.ToHtml обходит уже построенную модель и больше никогда не трогает PDFium, поэтому двойной экспорт той же модели даёт ту же строку. Со взведённым FullDocument (дефолт) результат — полная страница: doctype, <meta charset="utf-8">, мета-тег viewport, <title> из записи Title документа (или «PDF document», когда та пуста) и атрибут lang из языка документа. Без FullDocument вы получаете единственный фрагмент <div class="pdf-reflow"> для вставки в свой шаблон

Опциональная таблица стилей из IncludeCss — один встроенный блок <style>: читательская колонка в 72rem, каждая страница PDF белой карточкой при включённом IncludePageSections, схлопнутые рамки таблиц и media query ниже 40rem, снимающий поля карточки и ужимающий текст таблиц. Ни скрипта, ни веб-шрифта, ни внешнего URL — именно это позволяет файлу жить внутри письма, справочника в духе CHM или песочницы браузерного контрола. Уровни заголовков вне 1–6 пишутся как h2, ячейки шапки становятся th, а ячейки с RowSpan или ColumnSpan выше 1 получают rowspan и colspan. Включение IncludeGeometry добавляет data-left, data-top, data-right и data-bottom в пунктах PDF — удобно для подсветки поискового попадания обратно на отрисованной странице

PreserveLineBreaks заслуживает обдуманного выбора. Разрыв строки внутри PDF-абзаца сделан под одну фиксированную ширину колонки; утащите его на экран в 360 пикселей, и каждая строка завернётся дважды — та самая рваная кромка, ради устранения которой существует рефлоу. Для прозы держите выключенным (дефолт). Включайте для документов, где разрыв несёт смысл, — адресов, стихов, листингов кода, — и тогда вместо пробела пишется <br>

Для длинного документа сборка всей страницы в одну WString с последующим кодированием удваивает пик памяти. WriteHtml вместо этого транслирует ту же разметку в TPdfReportWriter, пишущий ASCII с каждым не-ASCII символом в виде числовой символьной ссылки, так что байты валидны независимо от того, как угадает кодировку принимающая сторона:

uses
  Classes, SysUtils, PDFium, FPdfAsync, FPdfReport;

procedure ExportReflowHtml(Pdf: TPdf; const FileName: string;
  const Token: IPdfCancellationToken);
var
  Options: TPdfReflowOptions;
  Doc: TPdfReflowDocument;
  Limits: TPdfReportLimits;
  Stream: TFileStream;
  Writer: TPdfReportWriter;
begin
  Options := TPdfReflowOptions.Default;
  Options.MaxNodes := 500000;
  Options.MaxCharacters := 20000000;
  Doc := Pdf.BuildReflowDocument(Options, Token);   // состояние страницы восстанавливается после

  Limits := TPdfReportLimits.Default;
  Limits.MaxCharacters := 64 * 1024 * 1024;  // потолок байтов вывода, максимум 64 МиБ
  Limits.MaxItems := Options.MaxNodes;       // один элемент на узел, максимум 1048576

  Stream := TFileStream.Create(FileName, fmCreate);
  try
    Writer := TPdfReportWriter.Create(Limits, Stream);  // stream остаётся у вызывающего
    try
      Doc.WriteHtml(Writer);
    finally
      Writer.Free;
    end;
  finally
    Stream.Free;
  end;
end;

WriteHtml проверяет больше, чем ToHtml. Он отказывает модели с числом узлов выше Options.MaxNodes, следит за Options.MaxCharacters на записываемом тексте, ограничивает вложенность аргументом MaxDepth (по умолчанию 64) и проверяет, что каждый ParentIndex указывает на более ранний узел. Последняя проверка важна, если ваш код фильтрует или переписывает Nodes перед экспортом: правленый массив с родителем вперёд по массиву бросит EPdfReportLimit вместо разметки с непарными тегами

Бюджеты, отмена и состояние страницы

PDF — недоверенный вход, и кривой или враждебный файл может объявить тысячи страниц мелкого текста. BuildReflowDocument сверяет бюджеты символов, узлов, таблиц и ячеек перед добавлением каждого узла, так что файл, за них вышедший, останавливается с EPdfError и сообщением, называющим бюджет («Reflow node budget exceeded», например), пока потребление памяти ещё ограничено. И MaxCharacters, и MaxNodes обязаны быть положительными; дефолты — 10 000 000 символов и 1 000 000 узлов

Опциональный IPdfCancellationToken проверяется перед каждой страницей, между блоками, перед каждой таблицей и перед каждой строкой таблицы. Передайте Token источника TPdfCancellationTokenSource, принадлежащего вашей форме, позовите Cancel из обработчика кнопки, и сборка бросит EPdfOperationCancelled на ближайшей из тех контрольных точек. Ловите его отдельно от EPdfError, чтобы пользовательская отмена не попала в журнал как сломанный файл. Каким бы исключением сборка ни кончилась, частичного результата не возвращается; если сбой случился позже внутри WriteHtml, файл назначения держит усечённую страницу, так что удаляйте его в собственном обработчике исключений

Состояние страницы — та деталь, на которую опирается GUI-код. Сборка посещает каждую страницу диапазона сдвигая PageNumber, а try/finally возвращает страницу вызывающего на место и при успехе, и при отказе по бюджету, и при отмене. Просмотрщик, запустивший экспорт, пока пользователь читает страницу 340, обнаружит её текущей и после возврата экспорта

Куда рефлоу встаёт

Вывод рефлоу хорош как вход для поискового индексирования, доступных читательских видов, показа на телефоне и миграции содержимого в CMS. Он нарочно выбрасывает абсолютное позиционирование, точные шрифты, векторную графику и геометрию страниц — за вычетом опциональных координат data-*. Когда задаче нужно, чтобы страница выглядела одинаково, рендерьте; когда нужно, чтобы слова читались где-то ещё, перевёрстывайте

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

Рефлоу, структурированный текст, извлечение таблиц и рендеринг работают с одним и тем же объектом TPdf в Delphi, C++Builder и Lazarus; записи опций, исключения и репорт-райтер задокументированы на странице продукта PDFium Component для Delphi