El PDF parece horizontal, pero las coordenadas extraídas son incorrectas: explique claramente la matriz de rotación

Cuando estaba procesando PDF, vi claramente que la tabla estaba en el lado derecho de la página, pero las coordenadas extraídas apuntaban a la esquina superior izquierda, o el bloque de color resaltado caía hasta la posición del encabezado. Este tipo de problema a menudo no es un error en la biblioteca de análisis, sino una inconsistencia entre el sistema de coordenadas del PDF y la representación visual. Este artículo está dirigido a desarrolladores que necesitan posicionar texto, hacer coincidir áreas o dibujar anotaciones. Explica cómo el atributo /Rotate provoca la desalineación de las coordenadas y utiliza la matriz de rotación de PyMuPDF para completar la conversión.

Todos los ejemplos de este artículo se sintetizan en la memoria y no se leen archivos reales. Antes de procesar documentos importantes, conserve los originales y luego revíselos uno por uno de acuerdo con los límites y los elementos de aceptación del documento.

¿Qué debo hacer si las coordenadas del PDF no coinciden después de la rotación? Conclusión de una frase

Utilice Page.rotation_matrix para convertir coordenadas no rotadas para mostrar coordenadas y verifique page.rotation página por página antes de procesar. No asuma que las direcciones de coordenadas de todas las páginas son consistentes.

Comprenda la diferencia entre el espacio no rotado y el espacio mostrado

Las páginas PDF pueden llevar el atributo /Rotate con valores de 0, 90, 180 o 270 grados. Esta rotación se aplica automáticamente cuando el lector procesa, pero las coordenadas del flujo de contenido de la página aún se basan en el MediaBox original sin rotar. Si utiliza directamente las coordenadas originales extraídas para dibujar o comparar áreas, los resultados estarán desalineados.

PyMuPDF distingue claramente entre estos dos sistemas de coordenadas a partir de la v1.17.0:

• Espacio sin rotar: las coordenadas de Page.get_text(), Page.get_image_bbox() y todos los objetos de anotación se devuelven en relación con la página sin rotar de forma predeterminada.
• Espacio de visualización: solo Page.rect y Page.bound() reflejarán el tamaño de visualización real después de la rotación.

Este diseño mantiene estable la extracción de contenido. Incluso si se modifica el ángulo de rotación de la página, las coordenadas de extracción del mismo texto no cambiarán. Pero cuando necesites volver a dibujar las coordenadas en la página o alinearlas con interacciones visuales como clics del mouse, debes completar la transformación de coordenadas manualmente.

PyMuPDF proporciona dos matrices clave:

1. Page.rotation_matrix: convierte coordenadas no rotadas para mostrar coordenadas.
2. Page.derotation_matrix: Realice la operación inversa.

Estas dos matrices encapsulan transformaciones de traslación y rotación, por lo que los desarrolladores no tienen que escribir cálculos de funciones trigonométricas a mano.

Ejemplo de síntesis: expectativas correctas e incorrectas de transformación de coordenadas

Para demostrar este mecanismo, construimos una escena sintética puramente en memoria que no depende de archivos externos. Si necesita probar un documento real, prepare un PDF con el atributo /Rotate=90 con anticipación y asegúrese de que su CropBox sea consistente con MediaBox para eliminar la interferencia del desplazamiento de recorte.

Configuración de entrada: cree una página vertical A4 (595 x 842 pt), configure /Rotate = 90. En el espacio sin rotar, el punto (100, 100) se encuentra cerca de la esquina superior izquierda; cuando se gira 90 grados, la posición visual del punto cambia significativamente porque el sistema de coordenadas gira con él.

Se espera un resultado correcto: multiplique (100, 100) por rotation_matrix y las coordenadas de visualización resultantes deben estar dentro de los límites válidos de la página rotada (es decir, page.rect). Para la página A4 predeterminada girada 90 grados en sentido antihorario, el punto de la esquina superior izquierda original debe ubicarse cerca de la esquina inferior izquierda en el espacio de visualización, es decir, la coordenada x es mayor y la coordenada y está cerca de 0. El valor específico depende de la definición de origen de MediaBox. No asumas simplemente que y es mayor que x.

Manejo de casos límite: cuando el ángulo de rotación es 0, rotation_matrix debe ser la matriz de identidad. Si se pasa un valor de rotación que no es múltiplo de 90 grados, PyMuPDF generalmente lo normalizará, pero aun así se recomienda verificar la validez de la matriz para evitar generar coordenadas NaN.

Python implementa la lógica de verificación de coordenadas

El siguiente ejemplo muestra cómo verificar transformaciones de coordenadas en la memoria. Solo demuestra la lógica de operación matricial y no es un proceso completo de procesamiento de PDF. Asegúrese de que PyMuPDF esté instalado antes de ejecutarlo y ejecútelo en un entorno donde tenga dependencias bloqueadas.

import fitz  # PyMuPDF

def validate_rotation_transform():
    """合成示例：验证旋转矩阵在未旋转坐标与显示坐标间的转换"""
    doc = fitz.open()  # 空文档，无需文件路径
    page = doc.new_page(width=595, height=842)

    # 设置页面旋转90度，模拟横向显示的PDF
    page.set_rotation(90)

    # 定义一个在未旋转空间中的测试点 (左上角附近)
    unrotated_point = fitz.Point(100, 100)

    # 获取旋转矩阵并执行变换
    mat = page.rotation_matrix
    display_point = unrotated_point * mat

    # 验证1: 变换后的点必须位于旋转后的页面可视区域内
    assert page.rect.contains(display_point), (
        f"变换后坐标 {display_point} 超出显示边界 {page.rect}"
    )

    # 验证2: 对于默认A4逆时针旋转90度，原(100,100)应变为左下角
    # 即 x 接近页宽(842)，y 接近 0。注意：此处纠正了常见的 y>x 误区
    assert display_point.x > 500 and display_point.y < 200, (
        f"90度旋转预期左下角，实际得到 ({display_point.x:.1f}, {display_point.y:.1f})"
    )

    # 验证3: 逆变换可精确恢复原始坐标
    inv_mat = page.derotation_matrix
    recovered = display_point * inv_mat
    assert abs(recovered.x - unrotated_point.x) < 0.01
    assert abs(recovered.y - unrotated_point.y) < 0.01

    doc.close()
    print("坐标变换逻辑校验通过（合成数据）")

# 请在本地环境运行，不要假设线上环境已安装fitz
validate_rotation_transform()

Este código no lee ningún archivo real, sino que construye el estado de la página en la memoria. La declaración assert verifica la racionalidad de la relación matemática, no la corrección comercial. Es posible que se requiera una depuración adicional si el PDF real contiene MediaBox no estándar o transformaciones anidadas.

📊 Comparación central

Criterios de aceptación y límites de revisión manual

El hecho de que el código pueda pasar la afirmación no significa que el entorno de producción sea infalible. La siguiente tabla enumera excepciones comunes y sus decisiones de manejo para ayudar a distinguir escenarios que pueden automatizarse y requieren intervención manual.

Esta tabla solo aborda la lógica de transformación de coordenadas y no cubre la precisión del OCR ni los problemas de codificación de fuentes. Cuando se encuentra con una composición tipográfica compleja, la verificación automática puede fallar. En este momento, se debe pausar la tubería y se debe juzgar manualmente si se debe continuar.

Utilice listas de verificación para la traducción de documentos

Antes de la traducción, confirme el orden de las páginas, la ubicación de origen y la integridad del texto y luego envíe la misma muestra insensibilizada al proceso de traducción. Después de la traducción, aún necesita verificar si el título, el texto y las ilustraciones corresponden correctamente, no solo si la traducción es fluida.

OmniDoc (portal de productos) proporciona un portal de traducción de documentos multiformato y el sitio web oficial presenta funciones de OCR, glosario y comparación bilingüe. Para los equipos que quieran trabajar directamente desde los archivos, este es un camino que vale la pena evaluar con ejemplos de la vida real. Utilice archivos no sensibles que tenga permiso para cargar y utilice los elementos de verificación de este artículo para revisar los resultados. 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.

Lectura adicional:

• PyMuPDF Page.rotation_matrix documentación oficial
• Nota conceptual de coordenadas de PyMuPDF

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

Si necesita dibujar las coordenadas del texto extraído en la página

Primero use rotation_matrix para convertir para mostrar coordenadas y luego dibuje resaltados o anotaciones.

Si necesita asignar los clics del mouse al contenido original

Utilice derotation_matrix para la conversión inversa y verifique si el punto se encuentra dentro del rango válido con respecto a page.rect.

Si trabaja con documentos con ángulos de rotación mixtos

Lea page.rotation página por página, no reutilice la matriz global y marque las páginas fuera de los límites.

Si su página contiene diseños complejos o gráficos parcialmente rotados

Primero analice muestras sintéticas y muestras reales a pequeña escala, y luego decida si las entregará al proceso automático. Cuando encuentre anomalías, entréguelas para revisión manual.

❓ Preguntas frecuentes (FAQ)

1. ¿Por qué las coordenadas devueltas por get_text() no coinciden con la posición visual?

Debido a que estas API regresan en relación con la página sin rotar de forma predeterminada, el atributo /Rotate se aplica cuando el lector procesa.

2. ¿Son iguales los datos de coordenadas de Page.rect y get_text()?

no lo mismo. Page.rect y Page.bound() reflejan el tamaño de visualización girado, mientras que las coordenadas de API como get_text() están ancladas al ancho y alto originales sin girar.

3. ¿Aún se necesita la conversión cuando el ángulo de rotación es 0?

innecesario. En este punto, rotation_matrix debería ser una matriz de identidad, pero aún así se recomienda verificar si hay sesgos, ya que las herramientas de terceros pueden escribir metadatos de rotación ocultos.

4. ¿Se puede utilizar el código directamente para producción después de pasar la afirmación?

No recomendado. La afirmación sólo comprueba la racionalidad de las relaciones matemáticas. El PDF real puede tener MediaBox no estándar, transformación CTM independiente o páginas anormales, que aún deben revisarse elemento por elemento de acuerdo con el formulario de aceptación.

📝 Resumen

La fuente de la desalineación de coordenadas radica en la diferencia entre el espacio no rotado y el espacio de visualización. Al utilizar rotation_matrix y derotation_matrix para la conversión, combinados con la inspección página por página y la revisión manual, el riesgo se puede controlar dentro de un rango verificable.

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