Artículo técnico

Reajustar contenido PDF a HTML adaptable en Delphi

Un contrato exportado desde un procesador de textos con la casilla «tagged PDF» sin marcar sigue pareciendo estructurado en pantalla: un título en negrita de 24 puntos, cláusulas numeradas, un cuadro de tarifas con líneas. Conviértalo en HTML reflowable y el cuadro de tarifas vuelve como una <table> propiamente dicha, mientras que el título es un <p> con exactamente la misma categoría que una nota al pie. Esa salida es correcta. ISO 32000-1 §14.8 da a un PDF un único sitio para decir «esta tirada de texto es un título», el árbol de estructura, y un archivo sin etiquetas no lo tiene. El tamaño de fuente y la negrita son decisiones de maquetación, y un convertidor que convierta cada línea grande y en negrita en un <h1> también ascenderá citas destacadas, totales de tablas y el nombre de la empresa en el membrete

La pregunta que vale la pena hacer a cualquier pipeline de PDF a HTML es, entonces, de dónde salió cada título, cada item de lista y cada tabla de su salida, y hasta dónde puede fiarse de cada uno un layout de móvil, un lector de pantalla o un indexador de búsqueda. Títulos y tablas dan respuestas distintas. El paso de exportación añade sus propias decisiones sobre saltos de línea, codificación de caracteres y memoria

Diagrama del pipeline de reflow de PDFium Component en Delphi, donde GetStructuredText alimenta un árbol de estructura etiquetado o un orden de lectura por layout hacia BuildReflowDocument y una exportación ToHtml autosuficiente
Cada nodo del modelo de reflow se remonta a la misma capa de texto estructurado, tanto si su rol lo declaró el árbol de estructura como si el bloque cayó al orden de layout plano

De dónde salen los títulos y las listas

PDFium Component construye el modelo de reflow con TPdf.BuildReflowDocument, y ese método toma cada palabra, bloque y pista semántica de GetStructuredText, la misma capa de texto estructurado descrita en bloques de texto estructurado y orden de lectura. No hay un segundo parser ni un segundo extractor de texto detrás. Para cada página del rango pedido recoge los bloques en orden de layout físico. GetStructuredText ya ha emparejado cada bloque con el contenido etiquetado de la página por área de solape, y BuildReflowDocument copia el rol que encontró sobre el bloque: H a H6 se vuelven títulos con su nivel, LI, Lbl y LBody se vuelven items de lista, Figure se vuelve una figura cuyo texto es la descripción alternativa, y Caption se vuelve un caption

Se siguen dos consecuencias, y ambas son fáciles de observar. El orden de los bloques siempre sigue el layout de la página, incluso en un archivo etiquetado, así que las etiquetas deciden qué es un bloque y la geometría decide dónde va. Y en una página sin etiquetas cada bloque es un párrafo. Los títulos y las listas jamás se adivinan por el tamaño de fuente

Cada nodo lleva un campo Source de tipo TPdfReadingOrderSource: rosStructure cuando el rol vino del árbol de estructura, rosHeuristic cuando vino solo del layout. El HTML exportado lo repite como data-source="structure" o data-source="inferred" en cada elemento, y el TPdfReflowDocument.Source a nivel de documento es rosStructure solo cuando todas las páginas del rango estaban etiquetadas. Las tablas son siempre rosHeuristic, porque vienen de detección geométrica y no de etiquetas Table. Si un paso posterior trata los títulos como hitos de navegación, compruebe ese campo primero; un documento etiquetado le da hitos que el autor eligió

Un array plano de nodos en lugar de un árbol de objetos

TPdfReflowDocument.Nodes es un árbol aplanado en preorden: un único array dinámico de registros TPdfReflowNode, cada uno con un ParentIndex y un Depth. Los nodos de página se sientan a profundidad 0 con índice de padre -1. Párrafos, títulos, figuras, captions, listas y tablas cuelgan de la página a profundidad 1, los items de lista se sientan a profundidad 2 bajo su lista, y las celdas de tabla llegan a profundidad 3 bajo una fila. Los items de lista consecutivos comparten un nodo de lista; cualquier otro bloque o una tabla entre ellos arranca una lista nueva

La disposición plana es una decisión de portabilidad. Un registro recursivo que contiene un array dinámico de sí mismo compila en Delphi, C++Builder y Free Pascal, pero los tres manejan los tipos gestionados recursivos de forma distinta a través de una frontera de paquete o DLL. Un array plano de registros llanos se comporta igual en los tres, y se puede volcar en streaming con un único bucle for y sin recursión

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;   // todas las páginas, tablas activadas, CSS activado
    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:
          // en un nodo de tabla RowSpan/ColumnSpan guardan los recuentos de filas y columnas de la tabla
          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;

Sobre el contrato sin etiquetas de la apertura, ese bucle no imprime ni una línea H y una línea de tabla por cada cuadro de tarifas detectado. Ejecútelo sobre una copia etiquetada del mismo documento y los títulos aparecen con True al lado. FirstPage y LastPage en las opciones toman 0 por defecto, que significa la primera y la última página del documento; un rango fuera del recuento de páginas lanza EPdfError antes de leer cualquier página

¿Por qué el texto de las tablas no aparece dos veces?

La detección de tablas corre sobre cada página después de recoger el texto estructurado, lo que significa que las palabras dentro de una tabla existen dos veces: una como bloques de texto y otra como celdas. Emitir ambas hace que cada tabla del HTML vaya seguida de nuevo por su propio contenido en forma de párrafos sueltos, que es exactamente lo que produce una fusión ingenua de «añadir las tablas al texto»

El modelo lo resuelve geométricamente. Un bloque de texto cuyo bounding box queda al menos la mitad dentro de los límites de una tabla detectada se descarta, y el nodo de tabla toma su lugar. Las tablas se entrelazan entonces con los bloques restantes por posición vertical (primero las más altas en la página, con izquierda a derecha como desempate cuando los bordes superiores están a menos de medio punto), así que una tabla aterriza entre el párrafo de arriba y el de abajo en lugar de añadirse al final de la página

Diagrama de la regla geométrica en la detección de tablas de PDFium Component para el reflow en Delphi, donde una tabla que cubre al menos la mitad de un bloque de texto lo sustituye para que el texto de las celdas no aparezca nunca dos veces
Cuando una tabla detectada cubre al menos la mitad de un bloque de texto, el nodo de tabla sustituye al bloque para que el texto de las celdas aparezca exactamente una vez

El umbral de media área tiene un borde visible. Un bloque que cabalga sobre el borde de la tabla y se sienta mayormente fuera sobrevive intacto, así que una línea de texto puede aparecer ocasionalmente tanto en la última fila como en el párrafo que sigue. Es el lado correcto donde equivocarse. Un umbral lo bastante bajo para eliminar cada bloque solapado también borraría texto de cuerpo que solo roza el bounding box de una tabla, y una línea duplicada es mucho más fácil de notar y perdonar que una frase que falta

Las tablas detectadas llevan además una confianza, y las dos estrategias de detección aterrizan en bandas distintas. Una tabla hallada a partir de líneas de retícula puntúa entre 0.88 y 1.0, según cuántas de sus celdas llevan texto. Una tabla inferida puramente de la alineación de espacios en blanco puntúa entre 0.58 y 0.88. El Confidence del nodo de tabla guarda esa puntuación, cada nodo de celda la repite, y el HTML la escribe como data-confidence en el elemento <table>. Las tablas por debajo de TableOptions.MinConfidence (0.5 por defecto) jamás se crean, y cuando se rechaza una tabla sus palabras simplemente se quedan en el modelo como párrafos ordinarios

Para un índice de búsqueda o una vista de lectura móvil, una tabla equivocada cuesta poco y una bien detectada es una gran mejora, así que deje los defaults. Para conversión de archivo, donde una retícula inventada alrededor de un bloque de dirección a dos columnas es peor que ninguna retícula, restrinja la detección a tablas con líneas:

Options := TPdfReflowOptions.Default;
Options.DetectTables := True;
Options.TableOptions.DetectWhitespaceTables := False; // solo tablas con líneas de retícula
Options.TableOptions.MinConfidence := 0.9;            // suelta también retículas con líneas poco densas
Options.TableOptions.MaxTables := 200;                // techo de todo el documento
Options.TableOptions.MaxCells := 50000;               // techo de todo el documento

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

Dentro de una construcción de reflow, MaxTables y MaxCells se cuentan por todo el rango de páginas, no por página, así que un extracto de 300 páginas con una tabla con líneas en cada una necesita un MaxTables de al menos 300 o la construcción se detiene con EPdfError en la primera tabla que pase del límite. Los defaults son 1.000 tablas y 100.000 celdas

Para el lado de la detección en sí, incluidos los rectángulos rellenos finos dibujados como bordes y la continuación entre páginas, vea detección y extracción de tablas

Exportar un HTML que no necesita nada más

TPdfReflowDocument.ToHtml recorre el modelo ya construido y no vuelve a tocar PDFium, así que exportar el mismo modelo dos veces produce la misma cadena. Con FullDocument activado (el default) el resultado es una página completa: doctype, <meta charset="utf-8">, una meta etiqueta viewport, un <title> tomado de la entrada Title del documento (o «PDF document» cuando está vacía) y un atributo lang con el idioma del documento. Con FullDocument apagado obtiene un único fragmento <div class="pdf-reflow"> para soltar en su propia plantilla

La hoja de estilo opcional de IncludeCss es un único bloque <style> inline: una columna de lectura de 72rem, cada página PDF como una tarjeta blanca cuando IncludePageSections está activo, bordes de tabla colapsados y una media query por debajo de 40rem que quita el padding de la tarjeta y encoge el texto de las tablas. No hay script, ni webfont, ni URL externa, que es lo que deja al archivo sentarse dentro de un correo, un visor de ayuda estilo CHM o un control de navegador en sandbox. Los niveles de título fuera de 1 a 6 se escriben como h2, las celdas de cabecera se vuelven th, y las celdas con RowSpan o ColumnSpan por encima de 1 reciben rowspan y colspan. Activar IncludeGeometry añade data-left, data-top, data-right y data-bottom en puntos PDF, lo que viene bien para resaltar un resultado de búsqueda de vuelta sobre la página renderizada

PreserveLineBreaks merece una elección deliberada. Un salto de línea dentro de un párrafo PDF se hizo para una anchura de columna fija; mantenerlo en una pantalla de 360 píxeles hace que cada línea se parta dos veces, el patrón desigual que el reflow existe para eliminar. Déjelo apagado (el default) para prosa. Actívelo para documentos donde el salto lleva significado, como direcciones, verso o listados de código, y escribe <br> en lugar de un espacio

Para un documento largo, construir la página entera como un WString y codificarla después duplica el pico de memoria. WriteHtml vierte el mismo marcado en un TPdfReportWriter en su lugar, escribiendo ASCII con cada carácter no ASCII como character reference numérica, así que los bytes son válidos sin importar cómo adivine la codificación el lado receptor:

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);   // el estado de página se restaura después

  Limits := TPdfReportLimits.Default;
  Limits.MaxCharacters := 64 * 1024 * 1024;  // techo de bytes de salida, máximo 64 MiB
  Limits.MaxItems := Options.MaxNodes;       // un item por nodo, máximo 1048576

  Stream := TFileStream.Create(FileName, fmCreate);
  try
    Writer := TPdfReportWriter.Create(Limits, Stream);  // el stream sigue siendo propiedad del llamador
    try
      Doc.WriteHtml(Writer);
    finally
      Writer.Free;
    end;
  finally
    Stream.Free;
  end;
end;

WriteHtml comprueba más cosas que ToHtml. Rechaza un modelo con más nodos que Options.MaxNodes, hace cumplir Options.MaxCharacters sobre el texto que escribe, limita el anidamiento al argumento MaxDepth (64 por defecto) y verifica que cada ParentIndex apunte a un nodo anterior. Esa última comprobación importa si su código filtra o reescribe Nodes antes de exportar: un array editado con un índice de padre hacia delante lanza EPdfReportLimit en lugar de producir marcado con etiquetas descuadradas

Presupuestos, cancelación y la página actual

Un PDF es entrada no confiable, y un archivo malformado u hostil puede declarar miles de páginas de texto minúsculo. BuildReflowDocument consulta los presupuestos de caracteres, nodos, tablas y celdas antes de añadir cada nodo, así que un archivo que los excede se detiene con EPdfError y un mensaje que nombra el presupuesto («Reflow node budget exceeded», por ejemplo) mientras el uso de memoria sigue acotado. MaxCharacters y MaxNodes deben ser positivos; los defaults son 10.000.000 de caracteres y 1.000.000 de nodos

El IPdfCancellationToken opcional se consulta antes de cada página, entre bloques, antes de cada tabla y antes de cada fila de tabla. Pase el Token de un TPdfCancellationTokenSource propiedad de su formulario, llame a Cancel desde el handler del botón, y la construcción lanza EPdfOperationCancelled en el siguiente de esos puntos de control. Capúrela aparte de EPdfError para que el cancel de un usuario no quede registrado como archivo roto. Con la excepción que termine la construcción, no se devuelve nada parcial; si el fallo ocurre luego dentro de WriteHtml, el archivo destino guarda una página truncada, así que bórrelo en su propio handler de excepciones

El estado de página es el detalle del que depende el código GUI. La construcción visita cada página del rango moviendo PageNumber, y un try/finally devuelve al llamador su página tanto en el éxito como en un fallo de presupuesto o en una cancelación. Un visor que arranca una exportación mientras el usuario lee la página 340 sigue en la página 340 cuando la exportación vuelve

Dónde encaja el reflow

La salida del reflow funciona bien como entrada para indexación de búsqueda, vistas de lectura accesibles, pantalla de móvil y migración de contenido hacia un CMS. Suelta deliberadamente el posicionamiento absoluto, las fuentes exactas, el arte vectorial y la geometría de página, aparte de las coordenadas data-* opcionales. Cuando un trabajo necesita que la página se vea idéntica, renderícela; cuando necesita que las palabras se lean en otro sitio, reflújela

Como los títulos y las listas vienen solo de las etiquetas, la calidad del HTML sigue la calidad del etiquetado de origen. Los documentos que pasan las comprobaciones de validación del árbol de estructura PDF/UA producen modelos con jerarquía de títulos real, y el mismo contenido etiquetado dirige las funciones de lectura de construir un lector accesible

Reflow, texto estructurado, extracción de tablas y renderizado corren todos contra el mismo objeto TPdf en Delphi, C++Builder y Lazarus; los registros de opciones, las excepciones y el report writer están documentados en la página del producto PDFium Component para Delphi