Gire PDF y agregue marca de agua. ¿Por qué la marca de agua sale de la página?

Si usa pypdf para agregar una marca de agua a un PDF, es posible que se haya encontrado con esta situación: la marca de agua está claramente configurada para estar centrada en el código, pero después de fusionarla se cae de la página o se gira 90 grados o 180 grados en relación con el texto. Este tipo de problema suele radicar en el atributo /Rotate de la página, no en el archivo de marca de agua en sí.

Este artículo está escrito para desarrolladores que necesitan procesar archivos PDF por lotes y encuentran páginas rotadas durante los procesos de traducción de documentos o marcas de agua. Después de leer, comprenderá la relación entre /Rotate y el sistema de coordenadas de flujo de contenido, comprenderá los límites aplicables y los efectos secundarios de transfer_rotation_to_content y obtendrá un conjunto de ideas de verificación de memoria y tablas de decisiones de aceptación.

El ejemplo se demuestra utilizando muestras sintéticas. El código se ha verificado con ejemplos en un entorno aislado, pero esto no es garantía de todos los archivos reales ni del rendimiento del producto. Antes de procesar documentos importantes, conserve los originales y revíselos de acuerdo con los límites y elementos de aceptación del texto.

¿Por qué la marca de agua superpuesta del PDF rotado se sale de la página? Conclusión de una frase

Primero transfiera /Rotate al flujo de contenido y luego combine la marca de agua; si encuentra una rotación no estándar o MediaBox se ha adaptado a la página rotada, la transferencia se omitirá y se revisará manualmente.

tu situación	Prácticas recomendadas	razón
Página MediaBox vertical `/Rotate=90` estándar	Primero llame a `transfer_rotation_to_content()` y luego combine la marca de agua.	Unificado en un sistema de coordenadas visual, el dato geométrico de la marca de agua es consistente con la página.
La marca de agua está en la posición correcta pero el texto está al revés.	Pruebe la compensación `Transformation().rotate(180)`	La propia marca de agua contiene rotación o se gira repetidamente cuando se combina.
La marca de agua está recortada o parcialmente invisible.	Verifique las dimensiones transferidas de MediaBox y CropBox	El tamaño de la caja no se actualiza simultáneamente
MediaBox ha adaptado la rotación, pero `/Rotate` aún existe	Omitir transferencia, use `merge_transformed_page()` con `Transformation` para corrección manual	Evite la doble rotación
El valor `/Rotate` no es múltiplo de 90	No llame a `transfer_rotation_to_content`, evaluación manual	La especificación PDF solo permite múltiplos de 90

El origen del desplazamiento de la posición de la marca de agua: la desalineación entre el atributo /Rotate y el sistema de coordenadas

Cuando se utiliza pypdf para agregar marcas de agua o fusionar páginas en PDF, una falla común es que la marca de agua aparece fuera del área visible de la página o se desvía 90 grados o 180 grados en relación con el texto principal. Por lo general, esto no es un problema con el archivo de marca de agua, sino más bien con el atributo /Rotate de la página de destino que no se maneja correctamente. En la especificación PDF, /Rotate es solo una directiva de visualización que le indica al lector que gire el lienzo al renderizar. El origen del sistema de coordenadas (0,0) del flujo de contenido de la página y el tamaño de MediaBox no cambiarán en consecuencia.

Al llamar a merge_page() para fusionar la marca de agua en el flujo de contenido, pypdf la superpone según el sistema de coordenadas original, en lugar de la vista rotada vista a simple vista del usuario. Por ejemplo, una página A4 visualmente apaisada aún podría tener su retrato MediaBox subyacente [0, 0, 595, 842] y /Rotate=90. En este momento, si fusiona directamente una marca de agua horizontal estándar, la referencia de coordenadas de la marca de agua no coincidirá con el contenido de la página y el cálculo de la posición de superposición será incorrecto. El núcleo de la solución de este problema es comprender la diferencia entre "rotación visual" y "rotación física" y unificar el sistema de coordenadas antes de fusionarlo.

El mecanismo y el ejemplo de síntesis de transfer_rotation_to_content

La forma estándar de resolver desalineaciones del sistema de coordenadas es llamar a page.transfer_rotation_to_content(). Este método "hornea" el valor de /Rotate en el flujo de contenido, en realidad rota el objeto gráfico insertando una matriz de transformación, restableciendo /Rotate a 0 e intercambiando el ancho y alto de MediaBox para que coincida con la nueva dirección visual. Después de la ejecución, el sistema de coordenadas lógicas de la página es consistente con la representación visual, y la posterior fusión de marcas de agua se puede basar en el dato geométrico correcto.

Para demostrar este enfoque, construimos un caso sintético puramente en memoria. Nota: El siguiente código es solo una demostración lógica y no se conecta a archivos IO reales y no incluye operaciones de red.

Configuraciones de entrada sintética:

Página de destino: A4 vertical (595 x 842 puntos), /Rotate = 90. Visualmente es horizontal, pero MediaBox sigue siendo [0, 0, 595, 842].
Página con marca de agua: los lectores deben preparar un PDF estándar A4 horizontal (842 x 595 puntos) con el texto "CONFIDENCIAL" impreso en el centro y sin atributo de rotación.
Resultado esperado: la marca de agua está centrada horizontalmente en el centro visual de la página horizontal, con el texto orientado paralelo al borde largo de la página.

Cuando trabaje con archivos reales, primero debe leer la página de destino y verificar su estado de rotación. En circunstancias estándar, primero se llama a transfer_rotation_to_content() y luego se fusiona la marca de agua. Para casos extremos, como que MediaBox tiene rotación adaptada pero /Rotate aún existe, debe omitir este paso y usar directamente merge_transformed_page() con Transformation para la corrección manual; o primero verifique si la relación de aspecto de page.rotation coincide con la relación de aspecto de MediaBox y luego decida si transferir la rotación.

Marco de código de verificación de estado ejecutable

El siguiente ejemplo de Python muestra cómo crear casos de prueba en la memoria y afirmar estados clave. Instale pypdf>=3.0.0 primero. La versión específica debe determinarse de acuerdo con el archivo de bloqueo del proyecto. Este código no incluye lectura y escritura de archivos, comandos de Shell ni operaciones de credenciales. Solo verifica la lógica de cambio de estado del objeto y es una demostración didáctica.

from pypdf import PdfWriter

# 合成示例：模拟一个 /Rotate=90 但 MediaBox 未变的页面
writer = PdfWriter()
page = writer.add_blank_page(width=595, height=842)

# 使用标准属性设置旋转，而非直接操作底层字典
page.rotation = 90

# 记录原始状态
original_mediabox = page.mediabox
assert float(original_mediabox.width) == 595
assert float(original_mediabox.height) == 842

# 执行旋转转移：将 /Rotate 烘焙进内容流
page.transfer_rotation_to_content()

# 验证后置条件：/Rotate 归零，MediaBox 宽高交换
assert page.rotation == 0, "旋转属性应被清除"
new_mb = page.mediabox
assert float(new_mb.width) == 842, "MediaBox 宽度应随旋转调整"
assert float(new_mb.height) == 595, "MediaBox 高度应随旋转调整"

# 边界检查逻辑示意：若 MediaBox 已是横向，则不应盲目调用此方法
# 实际应用中需在调用前判断
is_already_adapted = (
    float(original_mediabox.width) > float(original_mediabox.height)
) and (page.rotation != 0)
assert not is_already_adapted, "MediaBox 已适配旋转时，应跳过 transfer_rotation_to_content"

Este código verifica el contrato principal de transfer_rotation_to_content(): eliminar /Rotate y actualizar MediaBox sincrónicamente. Si la afirmación falla, significa que el comportamiento de la versión actual de pypdf ha cambiado o que hay una interferencia de campo no estándar en la estructura de la página. Este ejemplo no incluye el paso de fusión de marcas de agua porque el lector debe preparar el archivo de marcas de agua. Aquí solo nos centramos en la verificación de confiabilidad del estado de rotación para garantizar que el dato geométrico de las operaciones de fusión posteriores sea correcto.

Criterios de aceptación y condiciones de activación de revisión manual

El hecho de que el código pueda ejecutarse no significa que los resultados sean utilizables. La siguiente tabla enumera los indicadores clave y las decisiones correspondientes que deben observarse en el procesamiento real y distingue los límites entre la verificación automatizada y la intervención manual. Estos estándares son aplicables a escenarios de procesamiento por lotes y ayudan a identificar fallas ocultas donde "el programa no informa errores pero tiene anomalías visuales".

Observar fenómenos	Posibles razones	Decisiones de procesamiento automatizadas	Condiciones de activación de revisión manual
La marca de agua está en la posición correcta y la dirección del texto es normal.	Giro transferido exitosamente	aceptar	ninguno
La marca de agua está en la posición correcta pero el texto está al revés.	La propia marca de agua contiene rotación o se gira repetidamente cuando se combina.	Pruebe la compensación `Transformation().rotate(180)`	Sigue siendo anormal después de la compensación o el texto también está invertido.
La marca de agua está recortada o parcialmente invisible.	MediaBox y CropBox no se actualizan simultáneamente	Marque el tamaño de la casilla después de `transfer_rotation_to_content`	El tamaño del cuadro es razonable pero aún está recortado; se sospecha que tiene ClipPath anidado
Las fuentes del texto están borrosas o los vectores están distorsionados	La transferencia de rotación introduce una rasterización de baja calidad	No aplicable (pypdf mantiene los vectores por defecto)	Se confirma que se ha producido una rasterización y es necesario reemplazar la cadena de herramientas.
`/Rotate` existe pero el valor no es múltiplo de 90	Ángulo de rotación no estándar (la especificación PDF solo permite múltiplos de 90)	`transfer_rotation_to_content` no se llama	Todas las páginas rotadas no ortogonalmente requieren evaluación manual

No aplicable: Archivos PDF cifrados, páginas con campos de formulario complejos o capas de anotaciones, y casos en los que el valor /Rotate no es 0, 90, 180, 270. En estos escenarios, la transferencia de rotación puede romper elementos interactivos o producir resultados de representación impredecibles. La demostración del código solo cubre la transformación geométrica de páginas de contenido puro y el efecto de un extremo a otro debe verificarse con documentos específicos. Si los procesos automatizados desencadenan con frecuencia condiciones de revisión manual, se debe considerar la posibilidad de introducir capacidades de procesamiento de documentos más completas.

📊 Comparación central

Método de procesamiento	práctica	Escenarios aplicables	Principales riesgos
Fusionar marcas de agua directamente	No procese `/Rotate`, superponga según el sistema de coordenadas original	La página no tiene atributo de rotación	La referencia de la marca de agua no coincide y la desviación de posición en la página rotada
Transferir la rotación primero y luego fusionar	Llame a `transfer_rotation_to_content()` para realizar la rotación en el flujo de contenido e intercambiar el ancho y el alto de MediaBox	Página estándar `/Rotate`	Es necesario comprobar si el tamaño del cuadro está sincronizado y prestar atención a la calidad del vector.
Corrección de transformación manual	Ajuste usando `merge_transformed_page()` y `Transformation`	MediaBox ha adaptado la rotación pero `/Rotate` aún existe	Requiere confirmación manual de dirección y ubicación.

Utilice esta lista de verificación para la traducción de documentos

La división, fusión, cifrado o procesamiento de archivos adjuntos son preparativos antes de la entrega y la traducción no puede reemplazar estas comprobaciones. Conserve el documento original y la lista de operaciones antes de procesarlo y verifique el orden de las páginas, los enlaces y la integridad del contenido de la traducción una vez completada.

OmniDoc proporciona un portal para la traducción de documentos multiformato. El sitio web oficial presenta funciones como OCR, glosario y comparación bilingüe. Si el equipo quiere comenzar a procesar directamente desde el archivo, esta ruta se puede evaluar con muestras reales. Utilice archivos no sensibles que tenga permiso para cargar y revise los resultados según los elementos de verificación de este artículo. No se afirma que OmniDoc utilice las bibliotecas de código abierto o los algoritmos internos mencionados en este artículo, ni el ejemplo reemplaza las pruebas de rendimiento del producto.

🎯 ¿Qué método es el adecuado para ti?

Si su página es un MediaBox vertical `/Rotate=90` estándar

Primero llame a transfer_rotation_to_content(), luego combine la marca de agua y verifique el tamaño de MediaBox.

Si la marca de agua está en la posición correcta pero el texto está al revés

Pruebe la compensación Transformation().rotate(180); Si el error sigue siendo anormal después de la compensación, se requiere una revisión manual.

Si la MediaBox se ha adaptado a la rotación

Omita el paso de transferencia y utilice merge_transformed_page() con Transformation para la corrección manual.

Si la página está cifrada, contiene formularios o comentarios, o `/Rotate` no es múltiplo de 90

No lo procese automáticamente, evalúelo manualmente primero.

❓ Preguntas frecuentes (FAQ)

1. ¿Por qué la página `/Rotate` queda desalineada después de fusionar marcas de agua?

Debido a que /Rotate es solo una instrucción de visualización, el sistema de coordenadas del flujo de contenido y MediaBox no cambian. merge_page() se superpone según el sistema de coordenadas original y la referencia geométrica de la marca de agua no coincidirá con la página visual.

2. ¿`transfer_rotation_to_content()` cambiará el contenido de la página?

Incorpora el valor de rotación en el flujo de contenido, restablece /Rotate a 0 e intercambia el ancho y el alto de MediaBox. De esta manera, el sistema de coordenadas lógico de la página es coherente con la representación visual.

3. Si el código se puede ejecutar, ¿significa que el resultado es utilizable?

incierto. El paso del código solo indica que el estado del objeto cambia como se esperaba. Los efectos visuales todavía deben comprobarse elemento por elemento según el formulario de aceptación, prestando especial atención al recorte, la dirección del texto y la calidad del vector.

4. ¿Se puede utilizar este método para cifrar PDF directamente?

El alcance de la inaplicabilidad se enumera claramente en el artículo. Para archivos PDF cifrados, páginas con formularios complejos o capas de anotaciones, la rotación y la transferencia pueden destruir elementos interactivos y deben verificarse individualmente junto con el documento específico.

📝 Resumen

/Rotate es inconsistente con el sistema de coordenadas del flujo de contenido, que es la razón principal de la desalineación de la marca de agua en la página rotada. Las páginas estándar se transfieren y rotan primero y luego se fusionan las marcas de agua. En casos fronterizos, la transferencia se omite y se revisa manualmente.

Pruébelo ahora: cargue el documento para comenzar la traducción, conservando el diseño original

Referencias y próximos pasos

Documento oficial de rotación y marca de agua de pypdf: https://pypdf.readthedocs.io/en/stable/user/add-watermark.html