Artículo técnico

Incrustar imágenes AVIF, HEIF y JPEG XL en PDF desde Delphi

Una foto HEIC de un teléfono entra en un informe generado con Delphi, el PDF se ve bien en pantalla, y la página impresa vuelve con rojos desplazados y un logo recortado sentado sobre una caja sólida. La foto se decodificó por un bitmap de la plataforma en su camino hacia dentro; cárguela con AddModernImageFromFile en PDF Library for Delphi en cambio, y las imágenes AVIF, HEIF y JPEG XL conservan el alfa, el perfil ICC y los canales de 16 bits por defecto

Estos formatos llegaron a los flujos de documentos mayormente por los teléfonos. Los iPhones guardan HEIC por defecto desde hace años, los dispositivos Android producen AVIF, y JPEG XL está apareciendo en pipelines de archivado y fotografía. Un generador de informes diseñado alrededor de JPEG y PNG tiene dos opciones cuando llega uno: rechazar el archivo, o abrirlo por el decodificador que ofrezca el sistema operativo y aceptar un bitmap aplanado de 8 bits. Este artículo cubre una tercera ruta, donde la biblioteca reconoce el formato por sí misma, lo decodifica por un codec que usted elige e incrusta el resultado con su profundidad y datos de color intactos

¿Qué pierde un round trip por bitmap?

Una conversión por bitmap de la plataforma pierde tres cosas en un solo paso: la transparencia, el perfil de color incrustado y cualquier profundidad de canal por encima de 8 bits. Cada una tiene un flujo de trabajo que depende de ella. El alfa importa para logos y recortes de producto colocados sobre contenido de página. El perfil ICC importa para cualquier cosa que se imprima o se iguale en color contra una referencia, porque sin él el visor asume sRGB y una imagen de cámara de gama amplia se reinterpreta. Y los canales de 16 bits importan en imágenes médicas, científicas y de inspección, donde cuantizar a 8 bits borra justo las gradaciones para las que la imagen se capturó

Nada de esto produce un error. La página se renderiza, la foto es reconocible, y el problema espera a que alguien compare una impresión contra el original. Por eso tratamos la preservación como el valor por defecto y no como algo que los llamadores activan: AddModernImageFromFile, AddModernImageFromStream y AddModernImageFromString toman todos un parámetro Options que vale 8 por defecto, y la opción 8 es el ajuste que lleva alfa, ICC y muestras de 16 bits juntos al objeto de imagen PDF

Diagrama de PDF Library for Delphi comparando una conversión por bitmap de la plataforma que tira el alfa, el perfil ICC y los canales de 16 bits contra la ruta de imagen moderna que lleva los tres al objeto de imagen PDF
Una decodificación por bitmap genérica aplana en silencio la transparencia y cuantiza los canales antes de que la página se renderice

Una imagen de 16 bits también cambia el archivo que produce. PDF Library for Delphi eleva el documento a por lo menos PDF 1.5 cuando una imagen lleva muestras de 16 bits, ya que esa es la versión donde 16 bits por componente se volvieron válidos para image XObjects. Si un sistema posterior insiste en PDF 1.4, ese requisito y fotografías de 16 bits no pueden cumplirse ambos, y es mejor descubrirlo en tiempo de diseño

Agregar una foto de teléfono a una página

Las llamadas de imagen moderna devuelven un ID de imagen mayor que cero en caso de éxito y 0 en caso de fallo, y el ID luego va a DrawImageAndRelease o al par habitual SelectImage / DrawImage. El boceto de abajo incluye el único respaldo que las subidas reales de teléfono necesitan, que se explica justo después:

uses
  PDFlibrary;

var
  Lib: TPDFlib;
  ImageID: Integer;
begin
  Lib := TPDFlib.Create;
  try
    Lib.NewDocument;
    Lib.SetPageSize('A4');      // NewDocument ya creó la página 1
    Lib.SetOrigin(1);           // medir Top desde el borde superior

    // Options es 8 por defecto: alfa, perfil ICC y canales de 16 bits
    ImageID := Lib.AddModernImageFromFile('uploads\pump-housing.heic');

    // La extensión dice HEIC, pero los bytes pueden ser un JPEG ordinario
    if ImageID = 0 then
      ImageID := Lib.AddImageFromFile('uploads\pump-housing.heic', 0);

    if ImageID > 0 then
      Lib.DrawImageAndRelease(ImageID, 40, 40, 515, 340)
    else
      Lib.DrawText(40, 40, 'Photo could not be decoded');

    Lib.SaveToFile('inspection-report.pdf');
  finally
    Lib.Free;
  end;
end;

El respaldo existe porque los nombres de archivo mienten. Las hojas para compartir, las apps de mensajería y los formularios de subida convierten HEIC a JPEG en el camino de salida mientras conservan el nombre original, o renombran archivos a lo que el formulario receptor espere. AddModernImageFromFile jamás mira la extensión. Inspecciona los primeros bytes, y si no son AVIF, HEIF o JPEG XL devuelve 0 sin tocar el decodificador. Un JPEG con sufijo .heic por tanto falla en la llamada moderna y triunfa por el AddImageFromFile general, que husmea el contenido de la misma manera y maneja JPEG, PNG, TIFF y los demás formatos clásicos

¿Por qué no mandar todo por AddImageFromFile? También reconoce los formatos modernos, pero las llamadas modernas hacen explícita la intención y suministran la opción 8 cuando usted no pasa nada, así que preferimos verlas en el sitio de la llamada siempre que se espere que la entrada sea una foto de teléfono

¿Cómo distingue la biblioteca AVIF de HEIC?

PDF Library for Delphi decide el formato desde una lectura de encabezado acotada de a lo más 4096 bytes y luego devuelve la posición del stream del llamador a donde estaba. JPEG XL es el caso fácil: un codestream crudo empieza con FF 0A, y la forma de contenedor empieza con una caja de firma fija de 12 bytes. AVIF y HEIF son más difíciles, porque ambos viven en el formato ISO base media file, la misma estructura de cajas que MP4, y difieren solo en las marcas listadas dentro de la caja ftyp

La trampa es que las listas de marcas se traslapan. Un archivo AVIF normalmente lista mif1 entre sus marcas compatibles, porque AVIF está construido sobre el mismo perfil de archivo de imagen que HEIF. Un detector que devuelve HEIF en el momento en que ve mif1 etiquetará mal una gran parte de los archivos AVIF reales. La biblioteca por tanto escanea primero toda la lista de marcas y deja que avif o avis le ganen a la familia HEIF (heic, heix, hevc, hevx, heim, heis, mif1, msf1)

Diagrama de la compuerta de detección por magic number acotada que confirma AVIF, HEIF y JPEG XL antes de que se elija un backend de decodificación desde una ruta explícita, variables de entorno, el directorio del ejecutable o un callback Delphi registrado
La detección corre sobre una lectura de encabezado acotada, así que un ejecutable renombrado jamás llega al codec

Correr la detección antes de la decodificación también es una propiedad de seguridad. Una entrada desconocida o disfrazada jamás llega al codec externo, así que un ejecutable renombrado o una subida mal formada se despacha con unas docenas de comparaciones de bytes en lugar de con un decodificador de imágenes grande que tendría que parsearlo

Dónde ocurre la decodificación

PDF Library for Delphi no compila dentro de sí un codec AVIF, HEIF o JPEG XL. Esos codecs son grandes, cambian a menudo, y una aplicación que jamás ve una foto de teléfono no debería pagar por ellos. El backend predeterminado carga un módulo MagickWand de ImageMagick en el propio proceso en el primer uso y lo busca en un orden fijo: el archivo o directorio establecido con SetModernImageCodecLibrary, luego la variable de entorno PDFLIB_MODERN_IMAGE_CODEC, luego el directorio del ejecutable, luego la ruta de búsqueda normal del sistema. En Windows prueba CORE_RL_MagickWand_.dll, MagickWand-7.Q16HDRI-10.dll y MagickWand-7.Q16-10.dll en cada ubicación

Se siguen dos consecuencias prácticas. Distribuya una build Q16 del codec, porque una build de quantum de 8 bits no puede entregar muestras de 16 bits pase lo que pase con la opción que usted pase. Y si el directorio del codec contiene una subcarpeta modules\coders, la biblioteca rellena MAGICK_HOME, MAGICK_CONFIGURE_PATH y MAGICK_CODER_MODULE_PATH por usted, pero solo aquellas variables que el proceso anfitrión aún no haya establecido. Una aplicación con su propia distribución en tiempo de ejecución conserva la suya

Nuestra recomendación es fijar la ruta explícitamente y no depender de la ruta de búsqueda del sistema. Una máquina que por casualidad tenga otro ImageMagick en el PATH decidirá de otro modo qué codec usa su generador de informes, y ese es el tipo de diferencia que solo aparece en el servidor de un cliente

Las aplicaciones que ya distribuyen un decodificador, o que no tienen permitido cargar un módulo externo, registran en cambio un callback. El callback es una función plana que lee el stream de origen, escribe bytes PNG al stream de salida y honra la bandera de orientación. El registro es de todo el proceso y está protegido por un lock, así que hágalo una vez al arrancar en lugar de por documento:

uses
  Classes, PDFlibModernImage,
  AppCodec;  // su propia unidad que envuelve el codec que ya distribuye

function MyModernDecoder(InStream, OutPNG: TStream;
  ImageFormat: TPDFlibModernImageFormat;
  ApplyOrientation: Boolean): Boolean;
begin
  // InStream está posicionado en 0, OutPNG está vacío
  Result := (ImageFormat <> mifUnknown) and
    AppDecodeToPNG(InStream, OutPNG, ApplyOrientation);
end;

initialization
  RegisterModernImageDecoderBackend(MyModernDecoder);

finalization
  ClearModernImageDecoderBackend;  // de vuelta al backend MagickWand

Cuando una imagen se agrega a un documento, la biblioteca siempre pide que la orientación se aplique. Las cámaras de teléfono guardan rutinariamente la imagen del sensor de lado y registran la rotación prevista como metadatos, así que un callback que ignora ApplyOrientation produce fotos verticales tiradas de costado. Un backend casero se equivoca fácilmente aquí, y el error es fácil de perder cuando las imágenes de prueba se tomaron todas en horizontal

¿Por qué decodificar a PNG en memoria?

El backend convierte la imagen decodificada en un PNG en memoria y alimenta ese PNG por la ruta de incrustación PNG existente. Parece un rodeo comparado con entregar un buffer de píxeles crudo, y sin embargo es la opción correcta más barata. PNG puede expresar todo lo que tiene que sobrevivir (alfa, tipo de color, 8 o 16 bits por muestra y un perfil ICC incrustado) y PDF Library for Delphi ya tiene una ruta madura de PNG a objeto de imagen PDF con los filtros correctos, la soft mask y el espacio de color. Los formatos modernos heredan ese trabajo en lugar de recibir una implementación paralela con sus propios bugs por encontrar. La salida del decodificador se normaliza a 16 bits cuando el origen tiene más de 8 bits por canal y a 8 bits en los demás casos

No se escriben archivos temporales, así que no hay nada que limpiar tras un crash. Un detalle necesitó manejo explícito. Durante el desarrollo encontramos que el codec podía tirar el perfil ICC al cambiar la imagen en memoria a PNG, lo que habría reintroducido exactamente el desplazamiento de color que esta ruta existe para prevenir. El backend ahora lee el perfil de origen antes del cambio de formato, lo comprime con Flate, lo escribe en un chunk iCCP válido con CRC recalculado y elimina cualquier chunk sRGB que lo contradiga. En una corrida Win64 sobre un AVIF real, la salida conservó RGBA de 16 bits con alfa de 16 bits, y el perfil extraído del PDF fue de 60.960 bytes con un SHA-256 idéntico al perfil de origen

Diagrama de PDF Library for Delphi del puente PNG en memoria que captura el perfil ICC de origen antes del cambio de formato, lo reconstruye como un chunk iCCP comprimido, tira el chunk sRGB conflictivo y reutiliza la ruta probada de incrustación PNG a PDF
Tomar una instantánea del perfil ICC antes del cambio de formato mantiene la copia incrustada idéntica byte a byte a la de origen

Verificar el codec al arrancar

Sondee el codec cuando la aplicación arranca, antes de que llegue la primera fotografía. ModernImageCodecAvailable devuelve 1 cuando hay un callback registrado o un módulo MagickWand cargable, y SetModernImageCodecLibrary apunta el cargador a un archivo o directorio específico:

procedure CheckModernImageSupport(Lib: TPDFlib);
var
  CodecDir: string;
begin
  CodecDir := ExtractFilePath(ParamStr(0)) + 'codecs';

  // Devuelve 0 una vez que un módulo codec ya está cargado en este proceso
  if Lib.SetModernImageCodecLibrary(CodecDir) = 0 then
    Log('Codec already loaded, path change ignored');

  if Lib.ModernImageCodecAvailable = 0 then
    Log('No AVIF/HEIF/JPEG XL decoder in ' + CodecDir +
      ' - phone photos will be rejected');
end;

Dos comportamientos valen conocer antes de conectar esto a un instalador o a un servicio. Una carga fallida se recuerda, así que la biblioteca no vuelve a buscar en el disco por cada imagen. Si su servicio sondea antes de que el instalador haya terminado de copiar la carpeta del codec, sigue reportando el codec como no disponible hasta que se llame de nuevo a SetModernImageCodecLibrary, lo que limpia esa falla recordada. Lo contrario también vale: una vez que un módulo se cargó, SetModernImageCodecLibrary devuelve 0 y la ruta queda como está por la vida del proceso, porque descargar un codec nativo bajo conversiones en marcha no es algo que queramos hacer implícitamente

Vigile también el tamaño de la salida. Una foto RGBA de 16 bits con su perfil es un objeto de imagen grande, y un informe con cuarenta de ellas se pone pesado rápido. Para documentos que solo se leerán en pantalla, el re-muestreo hacia abajo antes de incrustar es el intercambio correcto, y las palancas generales de tamaño están cubiertas en optimización del tamaño de archivo PDF. La política de color también merece una decisión deliberada. Conservar cada perfil de origen es lo correcto para trabajo de archivado e impresión, mientras que convertir todo a un espacio único de documento conviene a un conjunto de fotografías de teléfonos distintos que deben verse consistentes lado a lado; esa ruta se describe en recolorear un documento a otro espacio de color. Para confirmar lo que realmente aterrizó en el archivo, la ruta de inspección en extracción de texto, imágenes y fuentes reporta los objetos de imagen que un documento lleva

La entrada AVIF, HEIF y JPEG XL vive junto a la entrada PNG, JPEG, TIFF y WebP, la conversión de espacios de color y la optimización de imágenes en la misma biblioteca para Delphi, C++Builder y Free Pascal. Las licencias, el soporte de plataformas y la referencia completa de la API están en la página del producto PDF Library for Delphi