Artículo técnico

Extraer imágenes de un PDF cargado en Delphi: HotPDF

Tienes un PDF en el disco, un cliente lo ha escaneado desde una pila de facturas y tu trabajo consiste en sacar de nuevo las imágenes de las páginas como mapas de bits para una pasada de OCR. Cargas el archivo, localizas los objetos XObject de imagen y entonces descubres la parte que nadie te advierte: los bytes de esos flujos no son píxeles. Son un codestream JPEG, o un blob JPEG 2000 comprimido por wavelets, o una pasada de fax Grupo 4, o un raster indexado detrás de una paleta detrás de un filtro Flate. El objeto de imagen conoce su ancho y alto, pero las muestras reales están selladas dentro del filtro que haya elegido el productor. Obtener un TBitmap utilizable significa deshacer ese filtro, y PDF te da más o menos ocho maneras distintas de sellar esos bytes

Ese hueco es justo el que rellena ExtractLoadedImage en HotPDF, el componente PDF VCL nativo para Delphi y C++Builder. Enumera los XObject de imagen de un documento que has cargado, informa de qué es cada uno y decodifica los que puede de vuelta a un mapa de bits de 24 bits. Lo interesante no es la superficie de la API, que son tres métodos, sino por qué tiene que existir una ruta de decodificación separada y qué filtros convierte de nuevo en píxeles

Por qué las imágenes cargadas no están ya decodificadas

El cargador de HotPDF se basa en la fidelidad de paso directo. Cuando llamas a LoadFromFile, los flujos de imagen se conservan exactamente tal como aparecen en el archivo de origen: el filtro original, los bytes comprimidos originales y el diccionario original. Eso es deliberado. El propósito de cargar un documento suele ser copiar páginas, fusionar archivos, estamparlos, cambiarles permisos y escribirlos de nuevo, y para todo eso lo más barato y seguro es dejar intacto cada flujo de imagen. Decodificar todas las imágenes a un raster al cargar consumiría memoria y CPU en trabajo que la mayoría de los llamadores nunca necesita, y volver a codificar al guardar degradaría imágenes que deberían haberse copiado literalmente

La consecuencia es que el grafo de objetos cargado no lleva píxeles. Un XObject de imagen cuyo /Filter es /DCTDecode contiene bytes JPEG; HotPDF nunca ejecutó un decodificador JPEG sobre él, porque nada en la ruta de copia y reescritura lo necesitaba. Así que cuando realmente quieres píxeles, la API de extracción tiene que hacer ella misma la decodificación, desde cero, para el filtro concreto que use esa imagen. Es la misma razón por la que los códecs de la parte de codificación son independientes del cargador: el artículo sobre añadir imágenes JPEG 2000 a PDFs en Delphi describe cómo el motor JPX se acopla a la parte de creación, y la API de extracción conecta ese mismo motor en la ruta de lectura

La API de tres métodos

La superficie es pequeña. GetLoadedImageCount devuelve cuántos XObject de imagen contiene el documento cargado. GetLoadedImageInfo rellena un registro descriptor para uno de ellos por índice. ExtractLoadedImage devuelve el mapa de bits decodificado, o nil cuando no puede decodificar esa imagen. La enumeración se basa en índices y es estable para una carga dada: internamente recorre la tabla de objetos indirectos y recopila todos los flujos cuyo /Subtype resuelve a /Image, de modo que el índice que pasas a GetLoadedImageInfo es el mismo que pasas a ExtractLoadedImage

Diagrama del flujo de trabajo de ExtractLoadedImage de HotPDF mostrando GetLoadedImageCount, GetLoadedImageInfo llenando THPDFLoadedImageInfo, y ExtractLoadedImage devolviendo un TBitmap propiedad del llamador en Delphi
La enumeración es estable en índices, el indicador Decodable es una precondición y no una pista, y el TBitmap devuelto pertenece a quien llama
var
  Pdf: THotPDF;
  Info: THPDFLoadedImageInfo;
  Bmp: TBitmap;
  I, Count: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    if Pdf.LoadFromFile('scanned-invoices.pdf', '') <= 0 then
      Exit;
    Count := Pdf.GetLoadedImageCount;
    for I := 0 to Count - 1 do
    begin
      if not Pdf.GetLoadedImageInfo(I, Info) then
        Continue;
      if not Info.Decodable then
        Continue;                       // filtro o espacio de color no admitido
      Bmp := Pdf.ExtractLoadedImage(I);
      if Bmp <> nil then
      try
        Bmp.SaveToFile(Format('img_%d.bmp', [I]));
      finally
        Bmp.Free;                       // el llamador es propietario del mapa de bits
      end;
    end;
  finally
    Pdf.Free;
  end;
end;

Dos detalles del contrato importan aquí. Primero, el TBitmap devuelto es tuyo y debes liberarlo; el documento no lo cachea ni lo posee. Segundo, comprueba Decodable antes de llamar y comprueba el resultado frente a nil después. El método no lanza una excepción con un filtro no compatible, devuelve nil, y un nil silencioso en un bucle por lotes es exactamente el tipo de cosa que se traga una página de un trabajo de mil páginas sin que nadie lo note

Leer el descriptor antes de decodificar

THPDFLoadedImageInfo te dice qué es una imagen sin comprometerse con una decodificación completa. Sus campos salen directamente del diccionario de la imagen: Width y Height en muestras, BitsPerComponent, ColorComponents y ColorSpace que describen la interpretación tras la decodificación (1 para gris, 3 para RGB, 4 para CMYK), Filter como la compresión nombrada, IsImageMask para máscaras de esténcil, ObjectNumber para el objeto indirecto subyacente y Decodable

Esa última bandera es la honesta. Decodable es True solo cuando la compilación en ejecución puede convertir de verdad esa combinación concreta de filtro y espacio de color en un mapa de bits. Codifica la matriz real de compatibilidad, no un deseo: una imagen cuyo Filter la compilación actual no entiende informa Decodable = False, y puedes ramificar a partir de ahí para registrar, omitir o recurrir a extraer tú mismo el flujo bruto. Trátalo como una precondición, no como una pista

// Clasifica cada imagen antes de comprometerse con una decodificación.
var
  Pdf: THotPDF;
  Info: THPDFLoadedImageInfo;
  I: Integer;
begin
  // ... Pdf cargado ...
  for I := 0 to Pdf.GetLoadedImageCount - 1 do
  begin
    if not Pdf.GetLoadedImageInfo(I, Info) then
      Continue;
    if Info.Decodable then
      // ExtractLoadedImage(I) devolverá un TBitmap
    else
      // filtro o espacio de color no admitido: registra el objeto y se lo salta
      Writeln(Format('Image %d obj %d: %dx%d %s/%s not decodable',
        [I, Info.ObjectNumber, Info.Width, Info.Height,
         String(Info.Filter), String(Info.ColorSpace)]));
  end;
end;

Un detalle de implementación muerde a quien construye registros descriptor a mano. THPDFLoadedImageInfo contiene dos campos AnsiString, Filter y ColorSpace. Son tipos administrados con recuento de referencias, así que el reflejo de poner a cero un registro con FillChar(Info, SizeOf(Info), 0) no vale aquí: sobrescribe la referencia de la cadena sin decrementarla, lo que provoca fugas o corrupción. HotPDF inicializa el registro campo por campo precisamente por eso, y si alguna vez copias este patrón en tu propio código, haz lo mismo

Un despachador, ocho rutas de filtro

La razón de que la extracción necesite un despachador es que PDF no tiene un formato de imagen: tiene filtros, y el §8.9.5 de ISO 32000-1 permite que un XObject de imagen nombre cualquiera de ellos en /Filter, con la interpretación de las muestras regida aparte por /ColorSpace, /BitsPerComponent y un array /Decode opcional. ExtractLoadedImage lee el nombre del filtro y deriva cada caso a un decodificador dedicado. El conjunto admitido cubre ocho rutas distintas

  • Rasteres brutos (FlateDecode, LZWDecode o sin filtro) en DeviceRGB o DeviceGray de 8 bits. Los bytes se expanden a un raster empaquetado y la única transformación es un intercambio de canales, que se explica más abajo
  • DCTDecode (JPEG). El codestream se entrega a TJPEGImage de la VCL, que resuelve la geometría y el color, y el resultado se asigna a un mapa de bits de 24 bits
  • JPXDecode (JPEG 2000). Se decodifica a través del backend OpenJPEG, el mismo motor descrito en el artículo de JPEG 2000, con componentes de alta profundidad de bits remuestreados a 8 bits
  • Color indexado. La paleta se lee del array [/Indexed base hival lookup] y cada muestra se expande a color verdadero a través de la tabla de búsqueda
  • DeviceCMYK. Las muestras de cuatro canales se convierten a RGB con la fórmula estándar de tinta sobre blanco
  • DeviceGray e Indexed por debajo de 8 bits a 1, 2 o 4 bits por componente, desempaquetados muestra a muestra y escalados al rango 0–255
  • CCITTFaxDecode, los filtros de fax Grupo 3 y Grupo 4, decodificados por un backend T.4/T.6 dedicado
  • JBIG2Decode, el filtro monocromo de alta compresión, decodificado mediante el backend JBIG2 registrado que el artículo sobre compresión JBIG2 nativa cubre desde el lado de la codificación

Todo termina en el mismo sitio: un mapa de bits BGR de 24 bits, porque eso es lo que almacena nativamente un TBitmap de la VCL y lo que espera cualquier consumidor aguas abajo

Diagrama de HotPDF de las ocho rutas de filtros de decodificación de imágenes PDF, FlateDecode LZWDecode DCTDecode JPXDecode Indexed DeviceCMYK CCITTFaxDecode y JBIG2Decode, convergiendo en un único TBitmap BGR de 24 bits
Las ocho vías de decodificación comparten un único dispatcher y convergen en el mismo formato nativo de mapa de bits VCL

Las transformaciones que cambian píxeles sin avisar

Dos de estas rutas implican una transformación que es fácil hacer mal de forma sutil, y merece la pena entenderla aunque nunca toques el decodificador tú mismo. La primera es el intercambio del orden de color. Un raster PDF DeviceRGB almacena las muestras en orden rojo-verde-azul, con la fila superior primero. Un scanline de 24 bits de la VCL las almacena en orden azul-verde-rojo. Así que decodificar una imagen RGB normal no es un memcpy; el primer y el tercer byte de cada píxel se intercambian al entrar en el scanline. Si lo haces al revés, los rojos y los azules se intercambian, lo que parece bien en una imagen de prueba en escala de grises y fatal en una imagen en color. El orden de las filas, por cierto, se mapea directamente: los raster descendentes de PDF se alinean con ScanLine[0] de la VCL como fila visual superior, así que no hace falta voltear verticalmente

La segunda es CMYK. Las imágenes PDF DeviceCMYK llevan cuatro tintas, y la conversión a RGB es un cálculo por canal, no una tabla: cada canal de salida es (255 - ink) * (255 - K) / 255. Esto es una aproximación de dispositivo, no una conversión gestionada por color a través de un perfil ICC, así que el resultado es suficiente para mostrar y volver a rasterizar, pero no es la ruta adecuada si necesitas un color exacto para impresión. Si tu flujo de trabajo exige fidelidad, trata el mapa de bits extraído como una vista previa y conserva el flujo CMYK original para la cadena gestionada por color

La ruta Indexed oculta su propia trampa de análisis. La paleta en un espacio de color /Indexed puede almacenarse como una cadena literal o como una cadena hexadecimal, y HotPDF almacena el valor de una cadena hex como el texto hexadecimal, no como los bytes decodificados. Así que cuando la paleta es una cadena hex, la tabla de búsqueda tiene que pasar primero por una decodificación de hex a bytes; una cadena literal ya son bytes en bruto. Si pasas por alto esa rama, una imagen indexada de cuatro colores sale hecha un desastre, porque cada entrada de la paleta se está leyendo con el límite de byte equivocado

Cadenas de filtros: el último filtro es el propio de la imagen

Un único nombre de /Filter es el caso fácil. PDF también permite una cadena de filtros, donde el flujo ha pasado por varios en secuencia, listados en orden dentro de un array /Filter como [/ASCII85Decode /FlateDecode] o [/ASCIIHexDecode /DCTDecode] (ISO 32000-1 §7.4). La semántica es precisa: los filtros se aplican de izquierda a derecha al codificar, así que al decodificar los deshaces de derecha a izquierda, y el último filtro del array es el que define realmente el formato de imagen. Los filtros iniciales no son más que codificaciones de transporte envueltas alrededor

El extractor maneja esto pelando capas. Antes de que se ejecute cualquier decodificador de imagen, se aplica cada filtro de la cadena excepto el último para producir la entrada que espera el filtro final, y solo entonces se despacha sobre ese último filtro. Así, [/ASCII85Decode /DCTDecode] primero deshace ASCII85 del flujo y luego envía el resultado por la ruta JPEG; [/FlateDecode] envuelto sobre un raster bruto lo expande y luego ejecuta la ruta raster. Esto es lo que permite que los ocho decodificadores sigan siendo simples. Ninguno tiene que saber nada de envoltorios ASCII85 o hex de transporte, porque cuando el decodificador ve los bytes, los envoltorios ya han desaparecido. También significa que una cadena cuyo filtro final no está soportado falla limpiamente en el paso de despacho y no a medias

HotPDF: Anatomía de la cadena de filtros PDF mostrando ASCIIHexDecode y DCTDecode aplicados de izquierda a derecha al codificar y pelados de derecha a izquierda al decodificar antes de despachar sobre el filtro final
Los envoltorios de transporte se retiran en orden inverso de codificación, y solo el último filtro decide qué decodificador se ejecuta

Qué devuelve y cuándo usar el flujo bruto

Lo que obtienes es la imagen base tal como la decodifica su propio flujo, no un resultado compuesto con la máscara blanda aplicada. Los componentes JPEG 2000 de más de 8 bits se remuestrean a 8, lo que sirve para visualización y OCR, y una máscara de imagen, una plantilla de 1 bit sin color propio, queda señalada por IsImageMask para que la trates como una plantilla y no como una foto. Una imagen cuyo filtro final o espacio de color se sale del conjunto anterior devuelve nil, y por eso la comprobación Decodable pertenece a todos los bucles

Cuando necesitas alfa, profundidad de color completa o salida con gestión de color, el flujo bruto sigue estando ahí mismo en el grafo de objetos cargado, filtro incluido, y puedes sacarlo byte a byte y entregárselo a un códec especializado tuyo. Ese es el recurso de reserva que el diseño de paso directo conserva a propósito: los bytes originales nunca se descartan, así que el peor caso es que los decodifiques tú mismo, no que los datos hayan desaparecido. Para la mayoría de los trabajos reales, aun así, los ocho filtros admitidos cubren lo que realmente emiten escáneres, suites ofimáticas y motores de informes, y un bucle sobre GetLoadedImageCount con la comprobación Decodable convierte un PDF cargado en una carpeta de mapas de bits en unas pocas líneas

La API de extracción de imágenes cargadas, junto con el conjunto completo de filtros de decodificación descritos aquí, se distribuye en el HotPDF Delphi Component para Delphi y C++Builder