Te llega una solicitud: tomar un lote de estados ya renderizados, tapar los números de cuenta y entregar dos páginas por hoja para ahorrar papel. Ambas mitades de esa tarea son cirugía sobre el flujo de contenido de un PDF que no creaste, así que no hay un lienzo de página amable para dibujar ni un administrador de fuentes al que recurrir. Estás editando directamente el grafo de objetos de un documento cargado y agregando operadores de dibujo en bruto a una página que otra herramienta ya maquetó. HotPDF expone exactamente dos puntos de entrada para esto, y el más peligroso de los dos es el que parece inocente
HotPDF es un componente PDF VCL nativo para Delphi y C++Builder, y su API de documentos cargados incluye métodos que crean contenido nuevo sobre una página que abriste desde disco en lugar de una que construiste desde cero. Dos de ellos son el tema de este artículo: RedactLoadedRect, que pinta un rectángulo opaco sobre una región, y StitchLoadedPage, que escala una página y la dibuja sobre otra. Ambos funcionan escribiendo operadores de flujo de contenido de ISO 32000-1 §8.5 en el flujo /Contents de la página. Entender qué hacen esos operadores, y en igual medida qué no hacen, es la diferencia entre una herramienta que funciona y una fuga de datos
Agregar operadores a una página cargada
Cuando construyes una página con la API normal de HotPDF, el componente controla el flujo de contenido y serializa por ti tus llamadas a TextOut y a vectores. Una página cargada es distinta: su /Contents es un objeto de flujo existente, quizá compartido, quizá parte de un arreglo de contenido, y tienes que injertar en él sin corromper lo que ya está. Tres pequeños auxiliares vuelven eso seguro. NewIndirectStream asigna un THPDFStreamObject indirecto nuevo, con un búfer vacío y una entrada /Length 0; ResolveLoadedStream sigue una referencia indirecta hasta el flujo subyacente; y AppendLoadedStream escribe bytes en bruto al final del flujo y reescribe /Length para que el objeto guardado siga bien formado
El patrón que siguen ambos métodos públicos es el mismo. Busca el /Contents de la página, resuélvelo a un flujo y, si no hay un flujo utilizable, crea uno y adjúntalo. Después agrega los operadores. Como los bytes nuevos van al final del flujo, el modelo del pintor garantiza que se rendericen por encima de todo lo que dibujó el diseño original. Ese orden es todo el mecanismo detrás del rectángulo de redacción, y también la razón por la que ese rectángulo no es lo que la mayoría supone
RedactLoadedRect: un cubrimiento opaco, no una eliminación
RedactLoadedRect toma un índice de página basado en cero, cuatro coordenadas en el espacio de usuario y tres componentes de color en el rango de 0 a 1:
var
Pdf: THotPDF;
begin
Pdf := THotPDF.Create(nil);
try
if Pdf.LoadFromFile('statement.pdf') > 0 then
begin
// Cubre la franja del número de cuenta en la página 1 con negro sólido.
// Las coordenadas están en el espacio de usuario de PDF: origen abajo-izquierda, en puntos.
Pdf.RedactLoadedRect(0, 56, 690, 320, 706, 0, 0, 0);
Pdf.SaveLoadedDocument('statement-covered.pdf');
end;
finally
Pdf.Free;
end;
end;
Por debajo, el método emite tres operadores en el flujo de contenido: una asignación de color de relleno en DeviceRGB (r g b rg), una ruta de rectángulo (x y w h re) y un relleno (f). El ancho y el alto se derivan como X2 - X1 y Y2 - Y1, así que pasas dos esquinas opuestas y dejas que el método calcule la extensión. Pasa 0, 0, 0 como color y obtienes una franja negra; pasa 1, 1, 1 para una blanca que combine con una página blanca. Las coordenadas usan el propio espacio de usuario de la página cargada, lo que significa que el origen está en la esquina inferior izquierda y las unidades son puntos, y también significa que necesitas el /MediaBox de la página para ubicar cualquier cosa con precisión; GetLoadedPageBox con pbMediaBox te da eso
Léelo dos veces: un rectángulo relleno cubre el contenido de forma visual, pero no lo elimina. El texto, la imagen o el arte vectorial que queda debajo del rectángulo sigue presente en el PDF, sigue en el grafo de objetos y sigue siendo extraíble por cualquiera que copie la página, ejecute un extractor de texto o simplemente borre tu rectángulo del flujo de contenido. Esto es enmascaramiento visual, no redacción en el sentido legal o de seguridad. Si estás ocultando datos realmente sensibles, como números de cuenta, historiales médicos, identidades o cualquier dato regulado, cubrirlos con una caja negra y enviar el archivo es una filtración esperando a ser descubierta. La redacción real exige borrar los objetos de contenido subyacentes, no pintar encima de ellos
El nombre del método dice "Redact", y eso sirve de advertencia sobre cómo se malinterpretará el resultado, no de promesa sobre lo que elimina. RedactLoadedRect es por diseño una primitiva de redacción visual; la redacción que elimina contenido es otra operación, una que recorre y reescribe los operadores existentes del flujo de contenido. Así que la regla segura es estrecha: usa RedactLoadedRect para enmascaramiento cosmético no sensible, como ocultar una marca de agua de borrador, vaciar una región antes de una captura de pantalla o cubrir un logotipo obsoleto en una prueba interna. En cuanto lo que queda debajo de la caja importaría si se filtrara, este método es la herramienta equivocada, y la respuesta correcta es regenerar el documento sin esos datos o usar una canalización real de eliminación de contenido
StitchLoadedPage: escalar, trasladar, dibujar
La imposición N-up es un problema más amable porque no se oculta nada, solo se reorganiza. StitchLoadedPage toma un índice de página de destino, un índice de página de origen, un desplazamiento X/Y y un factor de escala, y dibuja la página de origen sobre la de destino en esa posición y tamaño:
// Superpone la página 2 (índice 1) sobre la página 1 (índice 0),
// escalada al 70% y desplazada hacia arriba a la derecha.
Pdf.StitchLoadedPage(0, 1, 40, 380, 0.7);
// Conveniencia 2-up: página de origen en la mitad derecha del destino.
Pdf.StitchLoadedPageSideBySide(0, 1);
La cadena de operadores que agrega es una secuencia estándar de transformación y pintura: q para guardar el estado gráfico, una matriz cm que lleva la escala en la diagonal y el desplazamiento en las ranuras de traslación, /StitchSrc Do para invocar un objeto externo y Q para restaurar el estado. El par q/Q importa, porque aísla la transformación para que la página ensamblada no derrame su sistema de coordenadas sobre nada que se agregue después. El método también protege contra los errores obvios, como índices fuera de rango, un destino igual al origen o una escala no positiva, que recorta a 1.0, y sale en silencio en vez de lanzar una excepción, así que revisa tus entradas porque una omisión silenciosa se ve igual que un éxito
StitchLoadedPageSideBySide es una comodidad mínima sobre el método general. Lee el ancho del media box del destino, lo divide a la mitad y llama a StitchLoadedPage con esa media anchura como desplazamiento X y una escala fija de 0.5, poniendo el origen en la mitad derecha. Ese 0.5 codificado asume que el origen y el destino comparten el mismo ancho; si no lo hacen, el origen no llenará limpiamente su mitad, y entonces querrás usar StitchLoadedPage de forma general, con una escala que calcules tú mismo a partir de ambos media boxes
Cómo el ensamblado referencia la página de origen
Este es el detalle que conviene conocer antes de confiar en el resultado entre visores. Una imposición N-up clásica envuelve el contenido de la página de origen en un Form XObject, un objeto dibujable autocontenido que, según ISO 32000-1 §8.10.1, debe llevar /Type /XObject, /Subtype /Form y su propia caja de recorte /BBox. StitchLoadedPage toma una ruta más ligera: registra el propio diccionario de la página de origen directamente en /Resources /XObject del destino con el nombre StitchSrc y luego lo dibuja con Do. Un diccionario de página y un Form XObject comparten suficiente modelo de contenido, ambos referencian un flujo de contenido y un diccionario de recursos, como para que muchos lectores rendericen el resultado
Como el objeto registrado no lleva marcador /Subtype /Form ni /BBox propio, un consumidor estricto está en su derecho de ignorar el Do o de recortarlo de forma distinta a la que esperas. Así que verifica la salida ensamblada en los visores concretos que usan tus clientes, no solo en el de tu máquina, y para PDF de archivo o limpios ante validadores estrictos, impón las páginas aguas arriba a través de un envoltorio Form XObject completo. La misma disciplina aplica a todo lo que construyas sobre el grafo de objetos cargado, y por eso una pasada de preflight de PDF en Delphi gana su lugar en la cadena de publicación cada vez que mutas documentos de forma programática
Dónde encajan, y dónde no
Ambos métodos son herramientas de flujo de contenido, así que el modelo mental es el mismo que usarías para dibujo directo. Si has construido páginas desde cero con el componente, los operadores vectoriales y de color detrás de estas llamadas te resultarán familiares desde dibujo en canvas de HotPDF en Delphi; la diferencia es solo que aquí agregas contenido al flujo de otra persona en lugar de uno que te pertenece. Ten presentes tres límites:
- La redacción aquí es visual.
RedactLoadedRectpinta sobre el contenido y nunca lo borra. Para cualquier cosa sensible, regenera la fuente o usa eliminación real de contenido, una caja negra no es seguridad - Verifica las páginas ensambladas en tus visores destino. La página de origen se referencia directamente en lugar de vía un Form XObject de §8.10.1 con
/Subtype /Formy/BBox, así que confirma el renderizado en tus visores destino e impón aguas arriba donde se exija validación estricta - Las coordenadas usan el espacio de usuario de la página. Origen abajo a la izquierda, puntos, regidos por el media box propio de la página. Lee la caja con
GetLoadedPageBoxantes de colocar cualquier cosa, porque la página que cargaste puede no ser del tamaño que asumiste
Usados con esos límites en mente, el par cubre un flujo real: reorganizar páginas para impresión, enmascarar regiones no confidenciales y escribir el resultado de vuelta con SaveLoadedDocument, todo sin un re-render completo. La API de documentos cargados que incluye estas primitivas de ensamblado y máscara viene con el HotPDF Delphi Component para Delphi y C++Builder, junto con sus métodos de campos de formulario, anotaciones y FDF