Artículo técnico

Aplanar la rotación de páginas PDF sin romper cajas

Un número de página dibujado en x = 560, y = 30 del espacio de usuario PDF (origen en la esquina inferior izquierda) pertenece a la esquina inferior derecha de una página Letter. En una página apaisada escaneada y guardada como vertical, con /MediaBox [0 0 612 792] y /Rotate 90, la misma llamada de dibujo pone el número a 30 puntos del borde izquierdo y 52 puntos por encima del borde inferior de lo que el lector ve, con los dígitos corriendo directamente hacia abajo por el margen. El código de estampado hizo exactamente lo que le pidieron. Escribió en un sistema de coordenadas que todo visor gira un cuarto de vuelta en el sentido horario antes de que nadie lo mire

Los escáneres y las apps de captura de teléfono producen páginas así constantemente, porque poner un flag de rotación es mucho más barato que recodificar un JPEG. Los visores honran /Rotate, así que el archivo se ve bien hasta que algo trabaja en espacio de usuario crudo: una rutina de estampado, un paso de imposición que dimensiona sus huecos solo con /MediaBox, un RIP de impresión con sus propias ideas sobre la orientación. La reparación duradera es aplanar la rotación, moviendo el giro al content stream y poniendo /Rotate a 0 para que la geometría almacenada y la geometría mostrada por fin concuerden. Eso suena a una única matriz. En la práctica alcanza cinco page boxes, tres clases de geometría de anotación, cada enlace que apunta a la página y el árbol de estructura, e ISO 32000-1 tiene una regla separada para cada uno

¿Hacia dónde gira /Rotate una página PDF?

/Rotate gira la página en el sentido horario para visualización e impresión, en múltiplos de 90 grados (ISO 32000-1 §7.7.3.3, Tabla 30). A 90 grados el borde izquierdo del medio pasa a ser la parte superior y el borde superior pasa al lado derecho, así que en un espacio de dispositivo con y hacia abajo el mapeo es X = (y - Bottom) * Scale y Y = (x - Left) * Scale. A 270 grados el borde derecho pasa a ser la parte superior. La clave además es heredable: junto con /Resources, /MediaBox y /CropBox es uno de los cuatro atributos de página que un ancestro /Pages puede suministrar (§7.7.3.4), de modo que un diccionario de página sin /Rotate propio puede estar girado igual. THotPDF.GetLoadedPageRotation recorre la cadena de /Parent, toma el primer /Rotate que encuentra y lo normaliza a 0–359, así que un -90 almacenado vuelve como 270

La dirección es la parte que sale mal sin que nadie lo note. Una matriz de página a dispositivo con las componentes y intercambiadas para 90 y 270 grados no gira la página en absoluto: la refleja a través de la diagonal, y el determinante cambia de signo. Ambos ángulos siguen pareciendo girados. El bitmap tiene la anchura y la altura intercambiadas, y mapear un punto a la vista y de vuelta devuelve el punto de partida, así que las comprobaciones de dimensiones y las pruebas de ida y vuelta pasan sin queja. Lo que caza el error es una página con un marcador asimétrico en una esquina, renderizada y comparada píxel a píxel contra un renderer independiente; comprobar una implementación de geometría solo contra sí misma no prueba casi nada aquí. En HotPDF, FlattenLoadedPageRotation y RenderLoadedPageToBitmap comparten una única convención horaria, así que una esquina que el renderer dibuja arriba a la izquierda de una página girada sigue arriba a la izquierda tras aplanar

Cómo aplana HotPDF la rotación de página en Delphi: una página vertical guardada con /Rotate 90 se muestra en horario como una vista apaisada de 792 por 612, el mapeo a dispositivo X = (y - Bottom) * Scale, Y = (x - Left) * Scale mueve cada esquina, e intercambiar las componentes y de la matriz produce un reflejo que solo caza una comparación de marcadores de esquina
Los visores giran la página en horario para mostrarla mientras los bytes siguen verticales — GetLoadedPageRotation recorre primero la cadena /Parent, porque /Rotate es uno de los cuatro atributos de página heredables

Aplanar un rango de páginas con FlattenLoadedPageRotation

THotPDF.FlattenLoadedPageRotation(PageRange, Info) procesa cada página de PageRange cuya rotación efectiva sea 90, 180 o 270 y devuelve cuántas aplanó. Un PageRange vacío significa el documento entero; si no, la cadena usa la sintaxis one-based '1-3,7', y un número de página pasado del final lanza una excepción en lugar de salir discretamente del rango. Los content streams originales se quedan byte a byte como estaban. El método pone un stream nuevo al frente de /Contents con un q y un giro cm, pone un stream con Q al final, y luego escribe /Rotate 0 en el propio diccionario de página

Rotate efectivoStream de prefijoNuevo MediaBox
90q 0 -1 1 0 -Bottom Width+Left cm[0 0 Height Width]
180q -1 0 0 -1 Width+Left Height+Bottom cm[0 0 Width Height]
270q 0 1 -1 0 Height+Bottom -Left cm[0 0 Height Width]

El cero explícito importa más de lo que parece. Borrar la clave /Rotate parecería más limpio, y rompe cada página cuyo 90 vino de un nodo /Pages: la página hereda el giro otra vez y el visor rota contenido que ya está vertical. Un /Rotate 0 en el diccionario de página bloquea esa herencia, lo que lo hace el único valor seguro de escribir

var
  Pdf: THotPDF;
  Info: THPDFRotationFlattenInfo;
  Flattened: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    if Pdf.LoadFromFile('scanned-batch.pdf') > 0 then
    begin
      // '' = todas las páginas; las que ya están a 0 grados se cuentan pero no se tocan
      Flattened := Pdf.FlattenLoadedPageRotation('', Info);
      Writeln(Format('Scanned %d, flattened %d pages',
        [Info.ScannedPageCount, Info.FlattenedPageCount]));
      Writeln(Format('Turned %d annotations, %d destinations, %d tagged geometry entries',
        [Info.TransformedAnnotationCount, Info.TransformedDestinationCount,
         Info.TransformedStructureGeometryCount]));
      if Flattened > 0 then
        Pdf.SaveLoadedDocument('scanned-batch-upright.pdf');
    end;
  finally
    Pdf.Free;
  end;
end;

Registre el registro THPDFRotationFlattenInfo en lugar de descartarlo. ScannedPageCount es el número de páginas del rango, FlattenedPageCount coincide con el valor de retorno, y los tres contadores Transformed... muestran si enlaces, bookmarks o geometría etiquetada apuntaban a las páginas giradas. Cero destinos en un lote de escáner es normal, porque los escáneres rara vez escriben enlaces. Un archivo PDF/UA etiquetado que reporte cero geometría de estructura cuando usted sabe que lleva bounding boxes de figuras es el que hay que abrir a mano

Leer todos los page boxes antes de escribir ninguno

El aplanado reescribe solo las cajas que la página ya tiene, y las lee todas antes de escribir la primera. El orden importa por la cadena de defaults del §14.11.2: GetLoadedPageBox(PageIndex, pbCropBox, ...) devuelve el MediaBox cuando la página no tiene /CropBox, y /BleedBox, /TrimBox y /ArtBox caen a la CropBox. Un bucle que lee, gira y escribe una caja cada vez se mete de lleno en esa cadena. Gira el MediaBox y lo guarda, lee la «CropBox», recibe de vuelta el MediaBox recién girado, lo gira una segunda vez y escribe una CropBox que la página nunca tuvo. En una página Letter ese segundo giro da [0 -180 612 612], y recortado al nuevo MediaBox la página visible se encoge a un cuadrado de 612 × 612

La herencia parte las cinco cajas en dos grupos. MediaBox y CropBox se buscan por la cadena de /Parent, mientras que BleedBox, TrimBox y ArtBox solo cuentan cuando están en el propio diccionario de página. FlattenLoadedPageRotation sigue la misma división al decidir qué cajas existen: una CropBox heredada se gira y se escribe en la página, y un /TrimBox perdido en un nodo /Pages se trata como ausente y jamás se copia hacia abajo

procedure DumpPageGeometry(Pdf: THotPDF; PageIndex: Integer);
var
  L, B, R, T: Single;
begin
  Writeln('Effective /Rotate: ', Pdf.GetLoadedPageRotation(PageIndex));
  if Pdf.GetLoadedPageBox(PageIndex, pbMediaBox, L, B, R, T) then
    Writeln(Format('MediaBox [%g %g %g %g]', [L, B, R, T]));
  // True incluso sin clave /TrimBox: el valor recurre a CropBox, luego a MediaBox
  if Pdf.GetLoadedPageBox(PageIndex, pbTrimBox, L, B, R, T) then
    Writeln(Format('TrimBox  [%g %g %g %g]', [L, B, R, T]));
  // Precargado Letter; GetLoadedPageVisibleBox deja las salidas intactas si falla
  L := 0; B := 0; R := 612; T := 792;
  Pdf.GetLoadedPageVisibleBox(PageIndex, L, B, R, T);
  Writeln(Format('Visible  [%g %g %g %g]', [L, B, R, T]));
end;

Corra ese helper antes y después de aplanar. Para una página de 90 grados con MediaBox [0 0 612 792], el MediaBox aplanado lee [0 0 792 612]. Cada caja reescrita pasa por el mismo giro horario respecto al origen del MediaBox original, así que el nuevo MediaBox siempre arranca en 0,0, y un TrimBox de [18 18 594 774] pasa a [18 18 774 594]: sigue a 18 puntos de cada borde de la página apaisada

GetLoadedPageVisibleBox devuelve la región que un visor muestra y una impresora imprime: la CropBox recortada al MediaBox, normalizada de modo que Left sea menor que Right y Bottom menor que Top. El renderer de páginas y la exportación SVG dimensionan su salida desde esa misma caja. El código que quiere el tamaño que una persona ve de verdad debería llamar a GetLoadedPageVisibleBox, porque leer /MediaBox para eso da la respuesta equivocada en cualquier página con CropBox

Por qué HotPDF lee todas las cajas de página antes de escribir ninguna durante FlattenLoadedPageRotation: BleedBox, TrimBox y ArtBox caen por defecto a la CropBox, que a su vez recurre al MediaBox, así que girar las cajas de una en una hizo que la CropBox leyera el MediaBox ya reescrito, y un segundo giro escribió una caja que la página jamás tuvo, recortando una página apaisada hasta dejarla cuadrada
La cadena de valores por defecto hace que la salida de una caja sea la entrada de otra — léalo todo primero, transforme contra el origen del MediaBox original, y escriba después

¿Por qué se rompen las anotaciones si solo gira /Rect?

Las anotaciones se rompen porque un appearance stream nunca se dibuja directamente en /Rect. Bajo §12.5.5 el visor primero transforma el /BBox del form por su /Matrix, luego escala y traslada el bounding box del resultado hacia /Rect. Gire solo el /Rect y un stamp de 200 × 40 queda apretado en un hueco de 40 × 200, donde nadie puede leerlo. Por eso FlattenLoadedPageRotation multiplica por la derecha el giro horario de la página en cada /Matrix de apariencia ([0 -1 1 0 0 0] a 90 grados, en convención de vector fila) a través de las apariencias /N, /R y /D y de todos los estados dentro de ellas. Un mismo appearance stream puede servir a varias anotaciones o estados, así que cada stream se gira exactamente una vez por llamada; un stream compartido por páginas con rotaciones distintas toma el giro de la primera página que lo alcanza

Dos reglas más pequeñas mantienen los campos de formulario y las notas adhesivas en su sitio. La entrada /MK /R de un widget (§12.5.6.19) es un ángulo antihorario, así que el ángulo horario de la página se le resta, módulo 360. Dejarla en paz hace que la siguiente regeneración de apariencia dibuje el texto del campo en la dirección equivocada. Las anotaciones con el flag NoRotate (posición de bit 5, valor 16, §12.5.3) se mantienen verticales sobre una página girada y pivotan alrededor de la esquina superior izquierda de su /Rect; para esas el método conserva la anchura, la altura y la apariencia vertical, y solo mueve esa esquina a donde el giro la deja

Más allá de los diccionarios de anotación, la misma llamada gira /QuadPoints, /Vertices, /L y /InkList. Reescribe los destinos explícitos que nombran la página: los puntos /XYZ y los rectángulos /FitR se mapean a través del giro, y a 90 o 270 grados /FitH y /FitBH pasan a /FitV y /FitBV, y al revés (§12.3.2.2). También transforma la geometría etiquetada, como las entradas /BBox de atributos en elementos de estructura cuyo /Pg es la página

El árbol de estructura es donde un recorrido directo sale torcido de forma desagradable. El /Pg de un elemento de estructura apunta de vuelta al objeto de página, así que un escáner que arrastra «esto pertenece a la página» por cada clave sigue el /Pg hacia la página, luego hacia /Annots —girando los rectángulos de anotación una segunda vez— y hacia Form XObjects cuyo /BBox vive en espacio de form y ya está cubierto por el cm exterior. Seguir el /P trepa hasta la raíz del árbol y arrastra elementos de otras páginas. Que cualquiera de esto se dispare depende del orden en que los objetos resultan visitados; cuando /Pages precede a /StructTreeRoot en el catálogo, la página suele alcanzarse primero y el daño queda escondido, así que archivos de prueba ordinarios pueden pasar. FlattenLoadedPageRotation lleva contexto de página solo a través de /K (hijos) y /A (atributos), y un hijo con /Pg propio de otra página se deja para esa página

Por qué se rompen las anotaciones cuando una página de HotPDF se aplana girando solo el /Rect: un sello de 200 por 40 se escala hasta un hueco de 40 por 200 y queda ilegible, así que FlattenLoadedPageRotation multiplica por la derecha el giro horario en cada /Matrix de appearance a través de /N, /R y /D, ajusta el /MK /R antihorario y pivota las anotaciones NoRotate sobre su esquina superior izquierda
El visor encaja el BBox transformado de la appearance dentro del /Rect, así que el stream en sí tiene que girar — un pase por appearance compartida, exactamente una vez por llamada

Comprobar el resultado antes de enviar el lote

Una página aplanada debería verse idéntica en un visor, y las comprobaciones útiles son las que notarían si no lo es. Unos cuantos comportamientos moldean cómo se verifica

  • Las páginas cuya rotación efectiva ya es 0, o cuyo MediaBox falta o tiene anchura o altura cero, se saltan sin excepción, así que compare el valor de retorno con el recuento que esperaba cambiar
  • Los Form XObjects referenciados desde los recursos de la página conservan su /BBox y su /Matrix, porque el cm exterior ya gira todo lo que dibujan
  • Los destinos se encuentran recorriendo cada objeto indirecto una vez por página aplanada; en un archivo grande con cientos de páginas giradas, presupueste ese recorrido por cada una
  • RenderLoadedPageToBitmap dibuja los content streams de la página y deja fuera las anotaciones, así que una comprobación visual de stamps girados necesita FlattenLoadedAnnotations primero, sobre una copia de prueba del documento

La página de prueba que se paga sola lleva algo asimétrico en una esquina, como un cuadrado relleno arriba a la izquierda de la página mostrada. Renderícela antes de aplanar y después, y compare los píxeles alrededor de ese marcador. La anchura y la altura solas concuerdan igual de contentas en una página reflejada

// Solo en una copia de prueba: FlattenLoadedAnnotations hornea las anotaciones
// dentro del contenido de la página y las quita de la página
Pdf.FlattenLoadedAnnotations('1');              // rango de páginas one-based
Before := Pdf.RenderLoadedPageToBitmap(0, 96);  // índice de página zero-based
if Before = nil then
  raise Exception.Create('Page 1 did not render');
try
  Pdf.FlattenLoadedPageRotation('1', Info);
  After := Pdf.RenderLoadedPageToBitmap(0, 96);
  if After = nil then
    raise Exception.Create('Flattened page 1 did not render');
  try
    // Comprobaciones suyas, no llamadas de la biblioteca: los tamaños deben coincidir...
    Assert((Before.Width = After.Width) and (Before.Height = After.Height));
    // ...y también los píxeles del marcador en la esquina superior izquierda
    Assert(Before.Canvas.Pixels[8, 8] = After.Canvas.Pixels[8, 8]);
  finally
    After.Free;
  end;
finally
  Before.Free;
end;

Si los stamps de sus páginas giradas aún no tienen appearance streams, sintetizar apariencias de anotación antes de aplanarlas cubre ese paso. El renderer detrás de la comparación de esquinas está descrito en renderizar una página PDF cargada a un bitmap, y redacción y empalme N-up sobre PDFs cargados se apoya en la misma idea de añadir streams a /Contents sin recodificar los originales. FlattenLoadedPageRotation, GetLoadedPageBox y GetLoadedPageVisibleBox vienen con HotPDF para Delphi y C++Builder: la página del componente PDF HotPDF para Delphi tiene los detalles