PDF nhìn ngang nhưng trích xuất tọa độ sai: giải thích rõ ma trận xoay

Khi xử lý PDF, tôi thấy rõ bảng nằm ở bên phải trang nhưng tọa độ trích xuất lại trỏ về góc trên bên trái, hoặc khối màu tô đậm rơi xuống vị trí tiêu đề. Loại sự cố này thường không phải là lỗi trong thư viện phân tích cú pháp mà là do sự không nhất quán giữa hệ tọa độ của tệp PDF và kết xuất trực quan. Bài viết này dành cho các nhà phát triển cần thực hiện định vị văn bản, khớp vùng hoặc vẽ chú thích. Nó giải thích cách thuộc tính /Rotate gây ra sai lệch tọa độ và sử dụng ma trận xoay của PyMuPDF để hoàn tất chuyển đổi.

Các ví dụ trong bài viết này đều được tổng hợp trong bộ nhớ và không có file thực nào được đọc. Trước khi xử lý các văn bản quan trọng, quý khách vui lòng giữ lại bản gốc rồi xem xét từng văn bản theo ranh giới và các mục chấp nhận trong văn bản.

Tôi nên làm gì nếu tọa độ của tệp PDF không khớp sau khi xoay? Một câu kết luận

Sử dụng Page.rotation_matrix để chuyển đổi tọa độ không xoay thành tọa độ hiển thị và kiểm tra từng trang page.rotation trước khi xử lý. Đừng cho rằng hướng tọa độ của tất cả các trang là nhất quán.

Hiểu sự khác biệt giữa không gian không xoay và không gian hiển thị

Các trang PDF có thể mang thuộc tính /Rotate với các giá trị 0, 90, 180 hoặc 270 độ. Việc xoay này được tự động áp dụng khi trình đọc hiển thị nhưng tọa độ của luồng nội dung trang vẫn dựa trên MediaBox gốc chưa được xoay. Nếu bạn trực tiếp sử dụng tọa độ gốc được trích xuất để vẽ hoặc khớp vùng, kết quả sẽ bị căn chỉnh sai.

PyMuPDF phân biệt rõ ràng giữa hai hệ tọa độ này bắt đầu từ v1.17.0:

• Không gian không được xoay: Tọa độ của Page.get_text(), Page.get_image_bbox() và tất cả các đối tượng chú thích được trả về tương ứng với trang không được xoay theo mặc định.
• Không gian hiển thị: Chỉ Page.rect và Page.bound() mới phản ánh kích thước hiển thị thực tế sau khi xoay.

Thiết kế này giữ cho việc trích xuất nội dung ổn định. Ngay cả khi góc xoay trang được sửa đổi, tọa độ trích xuất của cùng một văn bản sẽ không thay đổi. Nhưng khi bạn cần vẽ tọa độ trở lại trang hoặc căn chỉnh chúng bằng các tương tác trực quan như nhấp chuột, bạn phải hoàn tất quá trình chuyển đổi tọa độ theo cách thủ công.

PyMuPDF cung cấp hai ma trận chính:

1. Page.rotation_matrix: Chuyển đổi tọa độ không xoay sang tọa độ hiển thị.
2. Page.derotation_matrix: Thực hiện thao tác ngược lại.

Hai ma trận này gói gọn các phép biến đổi tịnh tiến và xoay, do đó các nhà phát triển không phải viết các phép tính hàm lượng giác bằng tay.

Ví dụ tổng hợp: Kỳ vọng đúng và sai của phép biến đổi tọa độ

Để chứng minh cơ chế này, chúng tôi xây dựng một cảnh tổng hợp hoàn toàn trong bộ nhớ không dựa vào các tệp bên ngoài. Nếu bạn cần kiểm tra một tài liệu thực, vui lòng chuẩn bị trước một tệp PDF có thuộc tính /Rotate=90 và đảm bảo CropBox của nó phù hợp với MediaBox để loại bỏ sự can thiệp của việc cắt xén.

Cài đặt đầu vào: Tạo trang dọc A4 (595 x 842 pt), đặt /Rotate = 90. Trong không gian không xoay, điểm (100, 100) nằm gần góc trên bên trái; khi xoay 90 độ, vị trí trực quan của điểm thay đổi đáng kể do hệ tọa độ quay cùng với nó.

Dự kiến kết quả đầu ra đúng: Nhân (100, 100) với rotation_matrix và tọa độ hiển thị kết quả phải nằm trong giới hạn hợp lệ của trang được xoay (tức là page.rect). Đối với trang A4 mặc định được xoay 90 độ ngược chiều kim đồng hồ, điểm góc trên bên trái ban đầu phải nằm gần góc dưới bên trái trong không gian hiển thị, nghĩa là tọa độ x lớn hơn và tọa độ y gần bằng 0. Giá trị cụ thể phụ thuộc vào định nghĩa gốc của MediaBox. Đừng chỉ cho rằng y lớn hơn x.

Xử lý trường hợp biên: Khi góc quay bằng 0, rotation_matrix phải là ma trận nhận dạng. Nếu một giá trị xoay không phải là bội số của 90 độ được truyền vào, PyMuPDF thường sẽ chuẩn hóa nó, nhưng vẫn nên kiểm tra tính hợp lệ của ma trận để tránh tạo ra tọa độ NaN.

Python triển khai logic xác minh tọa độ

Ví dụ sau đây cho thấy cách xác minh các phép biến đổi tọa độ trong bộ nhớ. Nó chỉ thể hiện logic hoạt động của ma trận và không phải là một quy trình xử lý PDF hoàn chỉnh. Vui lòng đảm bảo PyMuPDF được cài đặt trước khi chạy và thực thi nó trong môi trường nơi bạn đã khóa các phần phụ thuộc.

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()

Mã này không đọc bất kỳ tệp thực nào mà xây dựng trạng thái trang trong bộ nhớ. Câu lệnh assert kiểm tra tính hợp lý của mối quan hệ toán học chứ không phải tính đúng đắn trong kinh doanh. Có thể cần phải gỡ lỗi bổ sung nếu tệp PDF thực tế chứa MediaBox không chuẩn hoặc các biến đổi lồng nhau.

📊 So sánh cốt lõi

Tiêu chí chấp nhận và ranh giới đánh giá thủ công

Chỉ vì mã có thể vượt qua xác nhận không có nghĩa là môi trường sản xuất hoàn hảo. Bảng sau liệt kê các trường hợp ngoại lệ phổ biến và quyết định xử lý chúng để giúp phân biệt các tình huống có thể được tự động hóa và yêu cầu can thiệp thủ công.

Bảng này chỉ đề cập đến logic chuyển đổi tọa độ và không đề cập đến các vấn đề về độ chính xác của OCR hoặc mã hóa phông chữ. Khi gặp phải việc sắp chữ phức tạp, việc xác minh tự động có thể không thành công. Tại thời điểm này, quy trình nên được tạm dừng và phải đưa ra đánh giá thủ công xem có nên tiếp tục hay không.

Sử dụng danh sách kiểm tra để dịch tài liệu

Trước khi dịch, hãy xác nhận thứ tự trang, vị trí nguồn và tính toàn vẹn của văn bản, sau đó gửi cùng một mẫu đã được giải mẫn cảm cho quá trình dịch. Sau khi dịch, bạn vẫn cần kiểm tra xem tiêu đề, văn bản và hình ảnh minh họa có tương ứng chính xác hay không chứ không chỉ là bản dịch có mượt mà hay không.

OmniDoc (cổng thông tin sản phẩm) cung cấp cổng dịch thuật tài liệu đa định dạng và trang web chính thức giới thiệu các chức năng so sánh OCR, bảng thuật ngữ và song ngữ. Đối với các nhóm muốn làm việc trực tiếp từ các tệp, đây là con đường đáng để đánh giá bằng các mẫu thực tế. Vui lòng sử dụng các tệp đã được giải mẫn cảm mà bạn có quyền tải lên và sử dụng các mục kiểm tra trong bài viết này để xem lại kết quả. Không có tuyên bố nào cho thấy OmniDoc sử dụng các thư viện nguồn mở hoặc thuật toán nội bộ được đề cập trong bài viết này và ví dụ này cũng không thay thế việc kiểm tra hiệu suất sản phẩm.

Đọc thêm:

• Tài liệu chính thức của PyMuPDF Page.rotation_matrix
• Khái niệm tọa độ PyMuPDF Ghi chú

🎯 Phương pháp nào phù hợp với bạn?

Nếu bạn cần vẽ tọa độ văn bản đã trích xuất trở lại trang

Trước tiên, hãy sử dụng rotation_matrix để chuyển đổi sang hiển thị tọa độ, sau đó vẽ các điểm nổi bật hoặc chú thích.

Nếu bạn cần ánh xạ các cú nhấp chuột trở lại nội dung ban đầu

Sử dụng derotation_matrix để chuyển đổi ngược và kiểm tra xem điểm có nằm trong phạm vi hợp lệ so với page.rect hay không.

Nếu bạn đang xử lý tài liệu có nhiều góc xoay khác nhau

Đọc page.rotation từng trang, không sử dụng lại ma trận chung và đánh dấu các trang ngoài ranh giới.

Nếu trang của bạn có bố cục phức tạp hoặc biểu đồ được xoay một phần

Trước tiên hãy xem xét các mẫu tổng hợp và mẫu thực quy mô nhỏ, sau đó quyết định xem có nên chuyển chúng sang quy trình tự động hay không. Khi gặp bất thường, hãy giao chúng để xem xét thủ công.

❓ Câu hỏi thường gặp (FAQ)

1. Tại sao tọa độ được get_text() trả về không nhất quán với vị trí trực quan?

Vì các API này trả về tương ứng với trang không được xoay theo mặc định nên thuộc tính /Rotate được áp dụng khi trình đọc hiển thị.

2. Dữ liệu tọa độ của Page.rect và get_text() có giống nhau không?

không giống nhau. Page.rect và Page.bound() phản ánh kích thước hiển thị được xoay, trong khi tọa độ của các API như get_text() được cố định theo chiều rộng và chiều cao không được xoay ban đầu.

3. Có cần chuyển đổi khi góc quay bằng 0 không?

không cần thiết. Tại thời điểm này, rotation_matrix phải là một ma trận nhận dạng, nhưng vẫn nên kiểm tra độ lệch vì các công cụ của bên thứ ba có thể ghi siêu dữ liệu xoay vòng ẩn.

4. Mã có thể được sử dụng trực tiếp để sản xuất sau khi chuyển xác nhận không?

Không được khuyến khích. Khẳng định chỉ kiểm tra tính hợp lý của các mối quan hệ toán học. PDF thực tế có thể có MediaBox không chuẩn, chuyển đổi CTM độc lập hoặc các trang bất thường, vẫn cần được xem xét từng mục theo biểu mẫu chấp nhận.

📝 Tóm tắt

Nguồn gốc của sai lệch tọa độ nằm ở sự khác biệt giữa không gian không xoay và không gian hiển thị. Sử dụng rotation_matrix và derotation_matrix để chuyển đổi, kết hợp với kiểm tra từng trang và xem xét thủ công, rủi ro có thể được kiểm soát trong phạm vi có thể kiểm chứng được.

Thử ngay: Tải tài liệu lên để bắt đầu dịch, giữ nguyên bố cục ban đầu