Artículo técnico

Representar páginas PDF a mapa de bits en Delphi con HotPDF

Una tira de miniaturas para un lote de facturas de proveedores parece correcta a simple vista: líneas de tabla en su sitio, logo nítido, columnas alineadas. Haz zoom sobre una y el nombre del cliente es una fila de cajas huecas, mientras la columna de totales guarda letras que no deletrean nada. Todas las facturas rotas usan la misma fuente, ABCDEF+Arial, y todas se leen bien en un visor PDF de escritorio en la misma máquina. El código de miniaturas tomó el nombre de fuente, soltó la etiqueta de subset de seis letras, pidió a Windows una Arial y le entregó los códigos de carácter crudos de la página. Esos códigos nunca fueron de Arial. Sacar un bitmap fiel de una página PDF exige dos cosas: ejecutar el flujo de contenido de la página como un programa, y dibujar el texto desde los contornos de glifo guardados en el archivo en lugar de desde las fuentes que la máquina de renderizado tenga instaladas

Una página PDF es algo que se ejecuta

ISO 32000-1 §8 describe una página como un flujo de contenido: operadores que cambian la matriz de transformación con cm, guardan y restauran el estado de gráficos con q y Q, construyen rutas, seleccionan fuentes con Tf, colocan glifos con Tj y pintan imágenes y formularios con Do. Nada en el archivo registra cómo es cualquier píxel. Para obtener un bitmap, algo tiene que ejecutar ese flujo contra una matriz de transformación actual, una pila de estados, una ruta de recorte y un par de espacios de color de relleno y trazo, y luego rasterizar lo que salga

El RenderLoadedPageToBitmap de HotPDF es ese intérprete. Recorre los operadores de una página cargada, mantiene la matriz y el estado de gráficos como los define la especificación, resuelve espacios de color, convierte rutas PDF en rutas GDI y toma los avances de glifo de la matriz /Widths de la fuente en lugar de GDI. Los image XObjects pasan por los mismos decodificadores que la biblioteca usa para extracción, así que cada filtro de imagen que HotPDF puede decodificar para extracción, incluidas las imágenes JPEG 2000 comprimidas con JPXDecode, aparece también en la página renderizada

Pipeline de renderizado de páginas de HotPDF: un intérprete de flujo de contenido PDF sigue la matriz de transformación, el estado de gráficos, los espacios de color, las rutas, los anchos de glifo y los contornos de glifos incrustados, y devuelve un TBitmap RGB de 24 bits propiedad del llamador
Cada operador actualiza la matriz, el estado de gráficos, el color, la ruta o el estado de texto que toca, y el resultado es un bitmap propiedad del llamador

Renderizar una página cargada a un TBitmap en Delphi

THotPDF.RenderLoadedPageToBitmap(PageIndex, DPI) toma un índice de página base cero y una resolución en puntos por pulgada, donde 72 DPI mapea una unidad PDF a un píxel, y devuelve un nuevo TBitmap RGB de 24 bits. Un índice fuera de rango o una página que no se puede construir devuelve nil en lugar de lanzar una excepción. Eso le va bien a un visor, que debe saltarse una página dañada y seguir con el resto. El bitmap pertenece al llamador

var
  Pdf: THotPDF;
  Bmp: TBitmap;
begin
  Pdf := THotPDF.Create(nil);
  try
    if Pdf.LoadFromFile('report.pdf') > 0 then
    begin
      Bmp := Pdf.RenderLoadedPageToBitmap(0, 144);  // primera página a 144 DPI
      if Bmp <> nil then
      try
        Image1.Picture.Assign(Bmp);
      finally
        Bmp.Free;  // el llamador es dueño del bitmap devuelto
      end;
    end;
  finally
    Pdf.Free;
  end;
end;

Las dimensiones en píxeles se derivan del área visible de la página. El renderizador toma la /CropBox recortada a la /MediaBox, como define la región visible ISO 32000-1 §14.11.2, usa la /MediaBox cuando no hay crop box utilizable, escala por DPI/72 y redondea hacia arriba. Una página US Letter sin crop box separado vuelve pues exactamente como 612×792 píxeles a 72 DPI. Una página A4 (595.28×841.89 puntos) a 96 DPI da 794×1123, porque 793.7 y 1122.5 redondean ambos hacia arriba. Una /Rotate de 90 o 270 intercambia ancho y alto, y el volteo del origen abajo-izquierda de PDF al arriba-izquierda de GDI ocurre dentro de la matriz de página, así que la imagen llega derecha sin posprocesado

El DPI es el único mando de escalado, y cubre los trabajos habituales. Miniaturas a 36 o 48 DPI son pequeñas y rápidas. Una vista previa de pantalla a 96 o 144 DPI coincide con la densidad típica de pantalla. Un export a 300 DPI da salida de calidad de imprenta, al precio de un bitmap de 2550×3300 por cada página Letter, unos 24 MiB cada uno a tres bytes por píxel

¿Por qué las fuentes sustituidas dibujan los glifos equivocados?

Glifos equivocados en un PDF renderizado significan casi siempre que el rasterizador metió una fuente instalada en lugar de la incrustada en el archivo. El atajo del ejemplo de las facturas es tentador porque muchas veces funciona: quitar el prefijo de subset de /BaseFont, pedir una fuente GDI por el nombre restante, dibujar la cadena. Para texto Arial o Times New Roman plano con codificación estándar, nadie se queja

Las fuentes subset lo rompen primero. Un subset puede llevar solo los cuarenta glifos que usa un documento, numerados en un orden privado de ese archivo, así que el código 1 puede ser «T» y el código 2 «h». Una fuente instalada no puede saberlo. Las codificaciones personalizadas, las fuentes de símbolos y de códigos de barras, y cualquier tipografía ausente de la máquina de renderizado fallan por la misma razón. E incluso cuando el sustituto tiene todos los caracteres, sus anchos de avance difieren de la cara incrustada, así que las líneas crecen o encogen y las columnas alineadas a la derecha dejan de alinearse

HotPDF: La sustitución por fuentes del sistema quita el prefijo de subset de ABCDEF+Arial y dibuja glifos equivocados, mientras el renderizado de glifos incrustados reproduce los contornos del FontFile para formas exactas
La sustitución solo sobrevive en caras comunes del sistema y falla exactamente en las fuentes subset que hicieron necesaria la incrustación

Dibujar texto desde el programa de fuente incrustado

HotPDF dibuja el texto desde los programas de fuentes guardados en el PDF. Cuando una fuente lleva un programa TrueType incrustado (/FontFile2) o un programa CFF (/FontFile3), cada glifo se delinea desde esos datos y se rellena como ruta GDI, con tamaño de fuente, matriz de texto y matriz de transformación actual compuestos en una sola transformación. Las fuentes subset, las codificaciones privadas y las caras que la máquina nunca ha visto salen con sus formas reales. Cómo un código de carácter llega a un glifo depende del tipo de fuente, y cada tipo tiene su propia trampa:

  • Contornos TrueType: los contornos vienen de las tablas glyf y loca. Los segmentos cuadráticos se elevan a las Béziers cúbicas que GDI dibuja, conversión que es exacta, se reconstruye el punto sobre la curva implícito entre dos puntos consecutivos fuera de la curva, y los glifos compuestos recursan en sus componentes con la transformación de cada componente aplicada
  • TrueType con claves CID: las fuentes Type0 sobre CIDFontType2 llegan a los IDs de glifo a través de /CIDToGIDMap, sea Identity (también el valor por defecto cuando falta la entrada) o un flujo de mapa explícito, y toman los avances de /W y /DW, así que el texto Identity-H de dos bytes avanza lo justo. Las CMaps CJK predefinidas y los flujos CMap incrustados descodifican los códigos de longitud variable antes de la consulta
  • Programas CFF: Type1C, CIDFontType0C y el CFF envuelto en un contenedor OpenType corren por un intérprete de charstrings Type 2 que maneja líneas, curvas, la familia flex, máscaras de hint y llamadas a subrutinas locales y globales con el sesgo de subrutina aplicado. Los programas con claves CID mapean cada código a través del charset de la fuente, lo que importa para subsets cuyo orden de glifos difiere del orden CID, y seleccionan el diccionario privado por glifo mediante FDArray y FDSelect
  • Fuentes TrueType simples: los códigos de un byte pasan por el cmap incrustado, probando primero las subtablas Unicode (3,1) y (3,10), luego la subtabla de símbolos (3,0) tanto directamente como en el espejo U+F000 que usan las fuentes de símbolos, y por último la tabla Macintosh (1,0) antigua

Dos reglas se sientan encima de eso. El diccionario /Encoding de una fuente simple se resuelve en el orden que prescribe ISO 32000-1 §9.6.6: /Differences anula la codificación base, que anula el mapeo integrado del programa. Las cadenas de herramientas derivadas de TeX y de PostScript se apoyan mucho en esto, así que equivocar el orden revuelve exactamente el texto matemático y simbólico donde un glifo equivocado es más difícil de ver. Las fuentes Type3, cuyos glifos son pequeños flujos de contenido propios, se reproducen por el mismo intérprete con matriz de fuente, tamaño de fuente y matriz de texto compuestos; los /Widths en espacio de glifo pasan por /FontMatrix como exige §9.6.5, y un procedimiento de glifo que declara una caja delimitadora d1 se recorta a ella, así que un glifo de código de barras malformado no puede pintar fuera de su celda

Cuando un solo código no se puede mapear, porque el programa está dañado o el subset carece de ese glifo, ese carácter se dibuja con la fuente instalada del mismo nombre y el resto de la secuencia sigue usando los contornos incrustados. Soltar la secuencia entera escondería el problema; una letra extraña es más fácil de notar. Las fuentes sin programa incrustado utilizable siguen la ruta de fuente instalada descrita en renderizar fuentes no incrustadas con caras del sistema

¿Cómo mantienes rápidos los renderizados repetidos?

Para cualquier cosa interactiva, llama a RenderLoadedPageToBitmapCached en lugar del método plano. Mantiene las páginas recién renderizadas en una caché más-recientemente-usada con clave de índice de página, DPI y los ajustes de render vigentes (intent de color, vista previa de overprint, política de fallback y qué capas de contenido opcional están visibles), y un acierto devuelve una copia nueva propiedad del llamador sin interpretar el flujo de contenido otra vez. Alternar entre dos páginas, o un cambio de tamaño que vuelve a pedir la misma página al mismo DPI, acierta en la caché cada vez. Para un export de un solo uso que visita cada página una vez, el RenderLoadedPageToBitmap plano es la mejor llamada, porque la variante en caché copia cada bitmap que devuelve y conservaría páginas que nadie volverá a pedir

HotPDF: Flujo de la caché MRU de páginas renderizadas: un acierto devuelve una copia fresca del TBitmap sin reinterpretar la página, un fallo renderiza y almacena hasta RenderCacheCapacity páginas
Un acierto de caché se salta el flujo de contenido por completo, mientras la invalidación y el presupuesto de memoria mantienen los renderizados repetidos correctos y seguros
// Tira de miniaturas: la primera pasada renderiza, volver a bajar acierta la caché
Pdf.RenderCacheCapacity := 32;   // límite de entradas; por defecto es 8
for I := 0 to Pdf.LoadedPageCount - 1 do
begin
  Bmp := Pdf.RenderLoadedPageToBitmapCached(I, 48);
  if Bmp <> nil then
  try
    ThumbList.AddThumbnail(I, Bmp);  // tu propio código de UI
  finally
    Bmp.Free;
  end;
end;

// ¿Cachear también páginas a 300 DPI? Dale al cache raster un presupuesto de bytes mayor
// (Policy: THPDFCacheAdmissionPolicy)
if Pdf.GetCacheAdmissionPolicy(clkRaster, Policy) then
begin
  Policy.MaxTotalBytes := Int64(512) * 1024 * 1024;
  Pdf.SetCacheAdmissionPolicy(clkRaster, Policy);
end;

// Tras cambiar el contenido de página directamente:
Pdf.InvalidateRenderedPageCache;  // el siguiente render refleja la edición

RenderCacheCapacity es solo uno de los dos límites. El cache raster también tiene un presupuesto de bytes, 128 MiB por defecto, con un techo de 64 MiB por entrada, y cuenta cuatro bytes por píxel al presupuestar. Supón un visor que cachea páginas Letter a 300 DPI: cada entrada cuenta como unos 32 MiB, así que solo caben tres, diga lo que diga RenderCacheCapacity. A 48 DPI la misma página cuenta como unos 0.82 MiB, y hasta 32 miniaturas del bucle de arriba permanecen residentes en menos de 27 MiB. Cuando la caché está llena, una página pedida una vez puede no desplazar a una pedida a menudo; se renderiza y se devuelve igualmente, solo que no se guarda. Si un visor pasa páginas en un orden predecible, PrefetchLoadedPages llena la misma caché en un hilo de trabajo por delante del usuario

Cargar un documento nuevo limpia la caché. Varias de las llamadas de edición de páginas de la propia biblioteca, como FlattenLoadedFormFields, sueltan por sí solas las páginas afectadas; tras cualquier cambio que hagas tú directamente sobre objetos de página o flujos de contenido, llama a InvalidateRenderedPageCache, porque la caché no puede saber que los bytes detrás de una página cambiaron. Debajo hay un segundo almacén para image XObjects descodificados, acotado por ImageCacheMaxBytes (32 MiB por defecto), así que un logo o membrete repetido en cada página se descodifica una vez por carga de documento en lugar de una por operador Do. InvalidateRenderedPageCache limpia también ese. Si las miniaturas deben sobrevivir a un reinicio de la aplicación, la capa de disco del cache de render cubre ese caso

Averiguar cuándo una página fue aproximada

La mayoría de las páginas nunca tocan un fallback, porque el renderizador cubre mucho más que texto e imágenes. Los espacios de color CalGray, CalRGB, Lab y basados en ICC se convierten con el intent de renderizado vigente, que RenderColourIntent puede sobrescribir, y ConfigureRenderICCWorkflow toma perfiles ICC de prueba y de salida para soft-proofing. Las paletas Indexed, los tintes Separation y DeviceN y las consultas de color de funciones Type 0 muestreadas están cubiertas. Los sombreados basados en funciones, axiales, radiales y de malla se renderizan tanto por el operador sh como por patrones de sombreado, y los grupos de transparencia, los grupos knockout y las máscaras suaves de alfa o luminosidad se componen con sus modos de fusión, como se describe en grupos de modos de fusión y máscaras de luminosidad

Los archivos reales todavía contienen cosas que no se pueden dibujar exactamente: un recurso que la página nombra pero nunca define, una imagen cuyos datos no se descodifican, un Form XObject que se pinta a sí mismo. RenderFallbackPolicy decide qué pasa entonces. El valor por defecto, rfpIgnore, dibuja la aproximación más cercana y sigue. rfpReport hace lo mismo pero registra un diagnóstico por cada fallback, hasta RenderFallbackDiagnosticLimit entradas (256 por defecto). rfpStrict lanza una excepción en lugar de devolver un bitmap aproximado. El anidamiento de formularios se detiene en 32 niveles y un formulario que se refiere a sí mismo se salta, así que un archivo roto u hostil no puede recursar sin límite

// rfpReport y THPDFRenderFallbackDiagnostics se declaran en HPDFPageRenderer
var
  Diags: THPDFRenderFallbackDiagnostics;
  J: Integer;
begin
  Pdf.RenderFallbackPolicy := rfpReport;
  Bmp := Pdf.RenderLoadedPageToBitmap(PageIndex, 150);
  try
    Diags := Pdf.GetLastRenderFallbackDiagnostics;
    for J := 0 to High(Diags) do
      Log.Add(Format('page %d: %s %s - %s', [PageIndex + 1,
        string(Diags[J].OperatorName), string(Diags[J].ObjectName),
        string(Diags[J].Reason)]));
    if Pdf.LastRenderFallbackDroppedCount > 0 then
      Log.Add(Format('%d more fallbacks not recorded',
        [Pdf.LastRenderFallbackDroppedCount]));
  finally
    Bmp.Free;  // Free es seguro con nil
  end;
end;

Ejecuta las compilaciones de QA y de ingesta con rfpReport. El bitmap es idéntico al que produce rfpIgnore, y el log muestra qué páginas fueron aproximadas y por qué, antes de que un cliente informe de que la página 14 se ve rara. Reserva rfpStrict para la conversión de archivo, donde una página silenciosamente aproximada es peor que una fallida. Un acierto de caché restaura los diagnósticos registrados cuando esa página se renderizó por primera vez, así que GetLastRenderFallbackDiagnostics da la misma respuesta haya o no trabajado la variante en caché

RenderLoadedPageToBitmap, la variante en caché y la ruta de texto por glifos incrustados forman parte del HotPDF Delphi Component, una biblioteca VCL nativa para Delphi y C++Builder sin DLL externas, que además crea, edita y extrae texto de los mismos documentos cargados que renderizas