PyMuPDF处理PDF页面旋转时的文本插入技巧

在使用PyMuPDF处理PDF文件时，经常会遇到页面旋转(rotation)的情况。当页面被旋转90度或270度时，直接插入文本可能会出现位置错乱或文本方向不正确的问题。本文将详细介绍如何正确处理旋转页面的文本插入操作。

问题现象

当尝试在旋转后的PDF页面上插入文本时，开发者可能会遇到以下两种典型问题：

1. 文本出现在错误的位置：原本应该在左上角的文本跑到了页面右侧
2. 文本方向不正确：从左到右的文本变成了从上到下排列

原因分析

PDF页面可以存储旋转信息(0度、90度、180度或270度)，但PyMuPDF的坐标系始终基于未旋转的页面。当页面有旋转时，需要特殊的转换才能确保文本插入到预期的视觉位置。

解决方案

PyMuPDF提供了处理页面旋转的专用方法：

1. 获取页面旋转角度：通过page.rotation属性
2. 获取去旋转矩阵：通过page.derotation_matrix属性
3. 应用矩阵变换：将目标坐标点乘以去旋转矩阵
4. 设置文本旋转角度：在插入文本时指定与页面相同的旋转角度

完整示例代码

import pymupdf

# 打开PDF文件
doc = pymupdf.open("input.pdf")
page = doc[0]

# 获取页面旋转信息
rotation = page.rotation  # 页面旋转角度(0,90,180,270)
derotation_matrix = page.derotation_matrix  # 去旋转矩阵

# 定义视觉上的插入点(左上角100,100)
visual_point = pymupdf.Point(100, 100)

# 计算实际插入坐标
actual_point = visual_point * derotation_matrix

# 插入文本，保持与页面相同的旋转
page.insert_text(
    actual_point, 
    "示例文本", 
    fontsize=60, 
    rotate=rotation
)

# 保存结果
doc.save("output.pdf")

关键点说明

1. 去旋转矩阵：derotation_matrix是一个转换矩阵，可以将视觉坐标转换为实际PDF坐标
2. 文本旋转：插入文本时需要明确指定旋转角度，否则文本方向可能与页面不匹配
3. 坐标转换：所有视觉上的坐标点都需要通过去旋转矩阵转换后使用

实际应用建议

1. 对于需要精确定位的文本插入，建议先检查页面旋转状态
2. 批量处理多个PDF时，每个页面的旋转角度可能不同，需要单独处理
3. 对于复杂的布局需求，可以结合页面尺寸和旋转角度计算转换后的坐标

通过正确理解和使用PyMuPDF的旋转处理功能，开发者可以确保文本在各种旋转状态的PDF页面上都能准确插入到预期位置。