Artículo técnico

Renderiza páginas PDF a monocromo de 1 bit en Delphi

Un gateway de fax no quiere tu renderizado de página en 24 bits. Tampoco lo quiere el flujo de archivo que guarda un millón de facturas con aspecto de escaneo, ni el front-end de OCR que umbraliza todo a blanco y negro antes de buscar una sola letra. Los tres quieren lo mismo: un bitmap limpio de 1 bit, un bit por píxel, donde cada punto sea tinta o papel. Si les das un BMP a color, descartarán igual 23 bits por píxel, por lo general con un tramado peor que el que habrías podido hacer tú mismo. La pregunta interesante es dónde debe ocurrir esa conversión descendente, y la respuesta en PDF Library for Delphi termina diciendo algo útil sobre cómo extender un renderizador que preferirías no reescribir

PDF Library for Delphi es una biblioteca nativa de PDF en Object Pascal para Delphi y C++Builder. Su núcleo de renderizado rasteriza una página a un bitmap y puede emitir BMP, PNG, JPEG, WMF y algunos otros formatos. Devolver un verdadero bitmap monocromo y renderizar solo una parte de una página está disponible desde v3.83.0, y ambas cosas se construyeron como capas de conveniencia delgadas sobre el renderizador existente, no como cambios al rasterizador en sí. Esa restricción es toda la historia

Por qué convertir después de renderizar, no dentro del renderizador

La forma obvia de producir una imagen de 1 bit es decirle al rasterizador que dibuje en 1 bit. También es la forma de romper todo lo demás. El bitmap interno del renderizador se crea con un PixelFormat := pf24bit codificado de forma fija en el constructor PDFlibRenderer, y esa superficie de 24 bits se comparte por todas las rutas de renderizado: exportación PNG, la vista previa en contexto de dispositivo, salida JPEG, todo. Si lo cambias a pf1bit en el origen, no agregas una función monocroma, degradas la fidelidad de color para todos los consumidores de la biblioteca y te inscribes para depurar una docena de regresiones aguas abajo

Así que RenderPageToMonochromeFile toma la ruta opuesta. Renderiza la página de forma normal, en un BMP temporal de 24 bits, y solo después la reduce a 1 bit como paso de posprocesamiento. El renderizador no se toca. El comportamiento monocromo vive por completo en el método de conveniencia, lo que significa que no puede afectar a nadie que no lo invoque. Este es el tipo de intercambio que vale la pena nombrar explícitamente: un posprocesamiento paga una asignación extra de bitmap y un archivo temporal, y a cambio mantiene completamente fuera de alcance un núcleo que sostiene todo. Para una función que existe para atender casos límite de fax y archivo, ese es el lado correcto de la balanza

Pipeline de PDF Library for Delphi que muestra una página PDF renderizada a un BMP temporal de 24 bits, colapsada por un blit GDI HALFTONE en un mapa de bits monocromático de 1 bit, y consumida por flujos de trabajo de fax, archivo y OCR
Los nuevos métodos renderizan primero una página a todo color y luego down-convierten el raster terminado fuera del renderizador. Las pasarelas de fax, los almacenes de archivo y los front-ends de OCR reciben un mapa de bits pf1bit auténtico
var
  Pdf: TPDFlib;
begin
  Pdf := TPDFlib.Create;
  try
    Pdf.LoadFromFile('invoice.pdf');
    // 200 DPI es la resolución clásica de fax Group 4; el índice de página está basado en 1
    Pdf.RenderPageToMonochromeFile(200, 1, 'invoice-page1.bmp');
  finally
    Pdf.Free;
  end;
end;

Cómo sucede de verdad la reducción a 1 bit

La conversión descendente se apoya en GDI en lugar de un bucle de umbral hecho a mano, y esa elección importa para la calidad de salida. Dentro del método, el BMP temporal de 24 bits se carga en un TBitmap, se crea un segundo TBitmap con PixelFormat := pf1bit en las mismas dimensiones, y los píxeles pasan con un solo blit:

PDF Library for Delphi: detalle del colapso GDI que compara un stretch blit HALFTONE que difumina los grises en patrones de puntos frente al umbral predeterminado BLACKONWHITE de bloques
Dentro de RenderPageToMonochromeFile un solo StretchBlt mueve cada píxel a una superficie pf1bit de tamaño idéntico. Con HALFTONE activo, los grises se convierten en patrones de puntos de tinta tramados en lugar de las formas en bloques que produce el umbral predeterminado
// dentro de RenderPageToMonochromeFile, después de cargar el ColorBmp de 24 bits
MonoBmp.PixelFormat := pf1bit;
MonoBmp.Width  := ColorBmp.Width;
MonoBmp.Height := ColorBmp.Height;
// HALFTONE le dice a GDI que tramee el origen de 24 bits hasta 1 bit
SetStretchBltMode(MonoBmp.Canvas.Handle, HALFTONE);
StretchBlt(MonoBmp.Canvas.Handle, 0, 0, MonoBmp.Width, MonoBmp.Height,
  ColorBmp.Canvas.Handle, 0, 0, ColorBmp.Width, ColorBmp.Height, SRCCOPY);
MonoBmp.SaveToFile('out.bmp');

El truco está en SetStretchBltMode con HALFTONE. Aunque el origen y el destino tienen el mismo tamaño, así que no ocurre ningún escalado, el modo de stretch sigue determinando cómo GDI asigna colores a la paleta de 1 bit. HALFTONE hace que aplique tramado halftone, convirtiendo las zonas grises y los bordes de texto con antialiasing en patrones de puntos negros y blancos en lugar de un corte duro hacia el color más cercano de los dos. Si quitas la llamada al modo, o usas el valor predeterminado BLACKONWHITE, el contenido en escala de grises se posteriza en formas en bloques umbralizadas. Para salida de documentos escaneados y preprocesamiento de OCR, el resultado con tramado es casi siempre lo que quieres

Un detalle no negociable y fácil de hacer mal: el renderizado temporal debe ser un BMP. RenderPageToMonochromeFile llama al renderizador general con un código de opciones de 0, que es BMP. El argumento de opciones en RenderPageToFile es una pequeña enumeración entera, y los valores no son intercambiables para este propósito: 0 es BMP, 1 JPEG, 2 WMF, 3 EMF, 5 PNG, y así sucesivamente. Luego el convertidor descendente hace TBitmap.LoadFromStream sobre el archivo temporal. Si le pasas un WMF, usando 2, esa carga arroja "Bitmap image is not valid", porque un Windows Metafile es un flujo de registros vectoriales, no un DIB. La conversión monocroma es una operación raster de punta a punta, así que el intermedio tiene que ser un formato raster

Renderizar solo una subregión de una página

El segundo método, RenderPageRegionToFile, renderiza solo un rectángulo de la página en lugar de la página completa. Los casos de uso son familiares en cuanto construyes cualquier visor de documentos: recortar un bloque de firma de un contrato, generar un mosaico para un mapa ampliado de un plano grande, o tomar una región estampada para una miniatura sin pagar el costo de rasterizar toda la página a alto DPI. La firma es sencilla:

PDF Library for Delphi: renderizado de recorte de región en puntos PDF: un rectángulo de 72,72,180,72 en una página PDF renderizada a resolución completa se convierte en un mapa de bits de 375 por 150 píxeles a 150 DPI porque el clip recorta en lugar de escalar
RenderPageRegionToFile recorta una ventana medida en puntos PDF de un render de resolución completa. El mapa de bits de salida se dimensiona a partir de width y height por DPI entre 72, nunca de una página completa reducida
// Clip es "Left,Top,Width,Height" en puntos PDF (72 pt = 1 pulgada)
// Aquí: una caja de 2.5in x 1in, a una pulgada desde la esquina superior izquierda de la página
Pdf.RenderPageRegionToFile(150, 1, '72,72,180,72', 'sig-block.bmp');

La cadena de recorte son cuatro double separados por comas en puntos de PDF, analizados manualmente dentro del método para evitar las particularidades de la configuración regional y de DelimitedText. A partir del ancho y el alto, el método calcula el tamaño del bitmap de salida como Round(Width * DPI / 72) por Round(Height * DPI / 72), reserva un bitmap pf24bit en memoria exactamente de ese tamaño y renderiza en su contexto de dispositivo a través de RenderPageToDCClip. El archivo resultante contiene solo el rectángulo recortado, dimensionado según la región y no según la página completa

Cómo llega el rectángulo de Clip al device context

La ruta de región se apoya en RenderPageToDCClip y su parámetro Clip, que la llamada entrega hacia abajo a TPDFPageTree.RenderPageToDC. La trampa en una API en capas como esta es un parámetro que se acepta arriba y se pierde en algún punto del camino: quien llama pasa el rectángulo que quiera y recibe en silencio la página completa de vuelta, y según el layout nadie lo nota

RenderPageToDC analiza el mismo rectángulo de puntos "Left,Top,Width,Height" y lo aplica como una región real de recorte GDI en el contexto de dispositivo de destino antes de que el renderizador dibuje. La conversión de puntos a píxeles de dispositivo es el factor de escala usual DPI / 72, aplicado a los cuatro bordes. La secuencia alrededor del renderizado es el baile estándar de guardar, recortar y restaurar:

// dentro de TPDFPageTree.RenderPageToDC, cuando Clip no está vacío
ScaleFactor := DPI / 72;
SaveDC(TargetDC);
IntersectClipRect(TargetDC,
  Round(ClipLeft * ScaleFactor),
  Round(ClipTop * ScaleFactor),
  Round((ClipLeft + ClipWidth) * ScaleFactor),
  Round((ClipTop + ClipHeight) * ScaleFactor));
// ... el renderizador dibuja la página aquí ...
// en el bloque finally:
RestoreDC(TargetDC, -1);

El par SaveDC / RestoreDC(-1) es lo que permite llamarlo repetidamente con seguridad: la región de recorte se apila en el estado del DC, la página se dibuja y el recorte original se restaura sin importar cómo termine el renderizado. RestoreDC(TargetDC, -1) restaura el estado guardado más reciente, que es el idiom estándar para equilibrar guardar y restaurar. Si omites la restauración, un consumidor que reutilice el mismo DC para un render de página completa posterior encontraría, sin explicación, que quedó recortado a la última región. RenderPageRegionToFile obtiene el mismo comportamiento gratis, ya que pasa exactamente por esta ruta

Un punto de comportamiento que conviene internalizar: el recorte corta, no escala. La página sigue rasterizándose al DPI que pediste, en su posición normal, y la región de recorte simplemente descarta todo lo que queda fuera del rectángulo. No estás acercando la región para que llene la salida; estás cortando una ventana de la renderización a resolución completa. Si quieres ampliar una región, sube el DPI. Las coordenadas del rectángulo se interpretan en espacio de dispositivo después de la conversión de puntos a píxeles, medidas desde la esquina superior izquierda de la superficie renderizada, así que planifica Left y Top desde la parte superior de la página hacia abajo. Para una revisión más profunda de cómo PDF Library for Delphi maneja un contexto de dispositivo para salida en pantalla, el artículo complementario sobre vista previa de impresión y salida con contexto de dispositivo recorre la misma tubería DC desde el lado de la visualización

Formato de salida: un BMP de 1 bit sin compresión

RenderPageToMonochromeFile produce un BMP pf1bit sin compresión: el formato de píxel correcto, con tramado y listo para usar. La mayoría de las cadenas de fax, archivo u OCR lo ingerirán sin problema o lo convertirán ellas mismas a TIFF CCITT Group 4 con un paso posterior, así que si su flujo de fax o su archivo TIFF espera G4, planifique esa etapa de compresión en su propio pipeline

Ambos métodos son deliberadamente pequeños, y esa es la lección de diseño que vale la pena llevarse de esta página: una API de conveniencia que se apoya sobre un renderizador puede sumar capacidad real, salida monocroma, recorte por región, sin meterse en el rasterizador y desestabilizar a los demás consumidores. Cuando necesites elegir entre motores de renderizado para la rasterización subyacente, el panorama general de renderizado PDF con varios motores en Delphi cubre los compromisos en profundidad. Para ver la superficie completa de renderizado y el resto de la API, la página del producto PDF Library for Delphi Delphi PDF Library ofrece la imagen completa