PDF vyzerá horizontálne, ale extrahované súradnice sú nesprávne: jasne vysvetlite maticu rotácie

Analyzujte problém nesprávneho zarovnania súradníc otočených stránok PDF a podrobne vysvetlite prevod matice medzi neotočeným priestorom a priestorom zobrazenia v PyMuPDF. Poskytuje príklady syntézy pamäte a akceptačné kontrolné zoznamy, ktoré vysvetľujú, ako používať OmniDoc na vyhodnotenie komplexných efektov obnovy rozloženia v pracovnom postupe prekladu dokumentov.

Keď som spracovával PDF, jasne som videl, že tabuľka je na pravej strane stránky, ale extrahované súradnice smerovali do ľavého horného rohu alebo zvýraznený farebný blok spadol na pozíciu hlavičky. Tento typ problému často nie je chybou v knižnici analýzy, ale nesúladom medzi súradnicovým systémom PDF a vizuálnym vykreslením. Tento článok je určený pre vývojárov, ktorí potrebujú polohovať text, porovnávať oblasti alebo kresliť anotácie. Vysvetľuje, ako atribút /Rotate spôsobuje nesúradenie súradníc, a na dokončenie prevodu používa rotačnú maticu PyMuPDF.

Všetky príklady v tomto článku sú syntetizované v pamäti a nečítajú sa žiadne skutočné súbory. Pred spracovaním dôležitých dokumentov si uschovajte originály a potom ich jeden po druhom skontrolujte podľa hraníc a akceptačných položiek v dokumente.

Čo mám robiť, ak sa súradnice PDF po otočení nezhodujú? Záver jednou vetou

Použite Page.rotation_matrix na konverziu neotočených súradníc na zobrazenie súradníc a skontrolujte page.rotation stránku po stránke pred spracovaním. Nepredpokladajte, že všetky stránky majú rovnakú orientáciu súradníc.

vaša situáciaOdporúčané postupydôvod
Súradnice extrahovaného textu nezodpovedajú vizuálnej polohePred vykreslením vynásobte súradnice Page.rotation_matrixV predvolenom nastavení sú súradnice textu vrátené relatívne k neotočenej stránke.
Je potrebné zmapovať polohu kliknutia späť na pôvodné súradniceNa spätnú konverziu použite Page.derotation_matrixTáto matica vykonáva inverznú transformáciu zo zobrazovaných súradníc na neotočené súradnice
Rozmer celkového posunutia pevnej vzdialenostiSkontrolujte CropBox a MediaBox, kompenzujte pomocou page.cropbox_positionNekonzistentnosť medzi týmito dvoma pôvodmi spôsobí pevný posun
Strany sa v tom istom dokumente otáčajú pod rôznymi uhlamiČítajte page.rotation stránku po stránke, nemultiplexujte maticu globálneStav rotácie rôznych stránok sa môže líšiť
Komplexné rozloženie (viac stĺpcov zmiešaných a čiastočne otočených grafov)Pozastavte automatický proces a prepnite na manuálne posudzovanieAutomatické overenie môže na takýchto stránkach zlyhať

Pochopte rozdiel medzi neotočeným priestorom a zobrazeným priestorom

Stránky PDF môžu niesť atribút /Rotate s hodnotami 0, 90, 180 alebo 270 stupňov. Toto otočenie sa automaticky použije pri vykresľovaní čítačky, ale súradnice toku obsahu stránky sú stále založené na neotočenom pôvodnom MediaBoxe. Ak priamo použijete extrahované pôvodné súradnice na kreslenie alebo porovnávanie oblastí, výsledky budú nesprávne zarovnané.

PyMuPDF jasne rozlišuje medzi týmito dvoma súradnicovými systémami od verzie 1.17.0:

  • Neotočený priestor: Súradnice Page.get_text(), Page.get_image_bbox() a všetky objekty anotácií sa štandardne vrátia vzhľadom na neotočenú stranu.
  • Priestor na displeji: Len Page.rect a Page.bound() budú odrážať skutočnú veľkosť displeja po otočení.

Tento dizajn udržuje extrakciu obsahu stabilnú. Aj keď sa zmení uhol otočenia strany, súradnice extrakcie toho istého textu sa nezmenia. Ale keď potrebujete nakresliť súradnice späť na stránku alebo ich zarovnať s vizuálnymi interakciami, ako sú kliknutia myšou, musíte transformáciu súradníc dokončiť manuálne.

PyMuPDF poskytuje dve kľúčové matice:

  1. Page.rotation_matrix: Prevod neotočených súradníc na zobrazenie súradníc.
  2. Page.derotation_matrix: Vykonajte spätnú operáciu.

Tieto dve matice zapuzdrujú translačné a rotačné transformácie, takže vývojári nemusia písať výpočty goniometrických funkcií ručne.

Príklad syntézy: Správne a nesprávne očakávania transformácie súradníc

Na demonštráciu tohto mechanizmu vytvárame čisto syntetickú scénu v pamäti, ktorá sa nespolieha na externé súbory. Ak potrebujete otestovať skutočný dokument, pripravte si vopred PDF s atribútom /Rotate=90 a uistite sa, že jeho CropBox je konzistentný s MediaBoxom, aby sa eliminovalo rušenie odsadenia orezania.

Nastavenia vstupu: Vytvorte stránku A4 na výšku (595 x 842 bodov), nastavte /Rotate = 90. V neotočenom priestore sa bod (100, 100) nachádza blízko ľavého horného rohu; pri otočení o 90 stupňov sa vizuálna poloha bodu výrazne zmení, pretože sa s ním otáča aj súradnicový systém.

Očakáva sa správny výstup: Vynásobte (100, 100) hodnotou rotation_matrix a výsledné súradnice zobrazenia by mali spadať do platných hraníc otočenej stránky (t. j. page.rect). Pre predvolenú stranu A4 otočenú o 90 stupňov proti smeru hodinových ručičiek by sa mal pôvodný ľavý horný rohový bod nachádzať v blízkosti ľavého dolného rohu zobrazovacieho priestoru, to znamená, že súradnica x je väčšia a súradnica y sa blíži k 0. Konkrétna hodnota závisí od definície pôvodu MediaBoxu. Nepredpokladajte, že y je väčšie ako x.

Spracovanie okrajových prípadov: Keď je uhol otočenia 0, maticou identity by mala byť rotation_matrix. Ak sa zadá hodnota rotácie, ktorá nie je násobkom 90 stupňov, PyMuPDF ju zvyčajne normalizuje, ale stále sa odporúča skontrolovať platnosť matice, aby sa zabránilo generovaniu súradníc NaN.

Python implementuje logiku overovania súradníc

Nasledujúci príklad ukazuje, ako overiť transformácie súradníc v pamäti. Demonštruje iba logiku maticovej operácie a nie je úplným potrubím na spracovanie PDF. Pred spustením sa uistite, že je nainštalovaný PyMuPDF a spustite ho v prostredí, kde máte uzamknuté závislosti.

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

Tento kód nečíta žiadny skutočný súbor, ale vytvára stav stránky v pamäti. Príkaz assert kontroluje racionalitu matematického vzťahu, nie obchodnú správnosť. Ak skutočné PDF obsahuje neštandardný MediaBox alebo vnorené transformácie, môže byť potrebné ďalšie ladenie.

📊 Základné porovnanie

Porovnávacia položkaneotočený priestorzobrazovací priestor
Typické zdrojeget_text(), get_image_bbox(), súradnice anotáciePage.rect,Page.bound()
súradnicový dátumŠírka a výška pôvodného MediaBoxuSkutočná veľkosť displeja po otočení
Bežné použitieExtrakcia obsahu, stabilné zaznamenávanie zónNakreslite anotácie a zarovnajte ich s pozíciou kliknutia
Konverzná metódaVynásobte rotation_matrixVynásobením derotation_matrix obnovíte

Kritériá prijatia a hranice manuálnej kontroly

Len preto, že kód môže prejsť tvrdením, neznamená, že produkčné prostredie je spoľahlivé. Nasledujúca tabuľka uvádza bežné výnimky a rozhodnutia o ich spracovaní, ktoré vám pomôžu rozlíšiť scenáre, ktoré možno automatizovať a vyžadujú si manuálny zásah.

Pozorovať javyMožné dôvodyrozhodnutie o spracovaní
Rozmer celkového posunutia pevnej vzdialenostiPôvod CropBox a MediaBox je nekonzistentnýNa kompenzáciu posunu použite page.cropbox_position
Po otočení sú súradnice textu normálne, ale obrázok je nesprávne zarovnaný.Obrázok používa nezávislú maticu transformácie CTMNamiesto get_image_bbox() použite get_image_rects()
Niektoré strany sú otočené správne a niektoré nesprávne.Dokument kombinuje strany s rôznymi uhlami natočeniaSkontrolujte page.rotation stránku po stránke, zakážte maticu globálnej vyrovnávacej pamäte
Po transformácii súradnice presahujú hranicu stránky.Samotný pôvodný obsah je orezaný alebo má záporné súradniceOznačiť ako abnormálnu stránku a prejsť na manuálnu kontrolu
0 stupňovú stranu nie je potrebné transformovať, ale stále má odchýlkyMetadáta skrytého otáčania napísané nástrojmi tretích stránVynútiť volanie remove_rotation() na resetovanie a následné spracovanie

Táto tabuľka sa zaoberá iba logikou transformácie súradníc a nezaoberá sa presnosťou OCR ani problémami s kódovaním písma. Keď narazíte na komplexnú sadzbu, automatické overenie môže zlyhať. V tomto čase by sa malo potrubie pozastaviť a malo by sa manuálne rozhodnúť, či pokračovať.

Na preklad dokumentov používajte kontrolné zoznamy

Pred prekladom potvrďte poradie strán, umiestnenie zdroja a integritu textu a potom odošlite rovnakú znecitlivenú vzorku do procesu prekladu. Po preklade ešte treba skontrolovať, či názov, text a ilustrácie správne korešpondujú, nielen či je preklad plynulý.

OmniDoc (produktový portál) poskytuje portál na preklad dokumentov vo viacerých formátoch a oficiálna webová stránka predstavuje funkcie OCR, slovník a dvojjazyčné porovnávanie. Pre tímy, ktoré chcú pracovať priamo zo súborov, je to cesta, ktorú sa oplatí vyhodnotiť pomocou reálnych vzoriek. Použite znecitlivené súbory, ktoré máte oprávnenie nahrať, a pomocou kontrolných položiek v tomto článku skontrolujte výsledky. Neexistuje žiadne tvrdenie, že OmniDoc používa knižnice s otvoreným zdrojom alebo interné algoritmy uvedené v tomto článku, ani tento príklad nenahrádza testovanie výkonu produktu.

Ďalšie čítanie:

🎯 Ktorá metóda je pre vás vhodná?

Ak potrebujete nakresliť súradnice extrahovaného textu späť na stránku

Najprv použite rotation_matrix na konverziu na zobrazenie súradníc a potom nakreslite zvýraznenia alebo anotácie.

Ak potrebujete namapovať kliknutia myšou späť na pôvodný obsah

Na spätnú konverziu použite derotation_matrix a skontrolujte, či bod spadá do platného rozsahu oproti page.rect.

Ak máte čo do činenia s dokumentom so zmiešanými uhlami otočenia

Čítajte page.rotation stránku po stránke, nepoužívajte znova globálnu maticu a označte strany mimo hraníc.

Ak vaša stránka obsahuje zložité rozloženia alebo čiastočne otočené grafy

Najprv prejdite syntetické vzorky a malé skutočné vzorky a potom sa rozhodnite, či ich odovzdať do automatického procesu. Ak sa stretnete s abnormalitami, odovzdajte ich na manuálnu kontrolu.

❓ Často kladené otázky (FAQ)

1. Prečo sú súradnice vrátené get_text() nekonzistentné s vizuálnou polohou?

Pretože tieto rozhrania API sa štandardne vracajú relatívne k neotáčanej stránke, pri vykresľovaní čítačky sa použije atribút /Rotate.

2. Sú súradnicové vzťažné body Page.rect a get_text() rovnaké?

nie to isté. Page.rect a Page.bound() odrážajú veľkosť otočeného displeja, zatiaľ čo súradnice API, ako je get_text(), sú ukotvené na pôvodnú neotočenú šírku a výšku.

3. Je stále potrebná konverzia, keď je uhol natočenia 0?

zbytočné. V tomto bode by rotation_matrix mala byť matica identity, ale stále sa odporúča skontrolovať zaujatosť, pretože nástroje tretích strán môžu zapisovať skryté metaúdaje rotácie.

4. Dá sa kód použiť priamo na výrobu po absolvovaní tvrdenia?

Neodporúča sa. Tvrdenie iba kontroluje racionalitu matematických vzťahov. Skutočný súbor PDF môže mať neštandardný MediaBox, nezávislú transformáciu CTM alebo abnormálne stránky, ktoré je stále potrebné skontrolovať položku po položke podľa akceptačného formulára.

📝 Zhrnutie

Zdroj nesúladu súradníc spočíva v rozdiele medzi neotočeným priestorom a priestorom zobrazenia. Pomocou rotation_matrix a derotation_matrix na konverziu v kombinácii s kontrolou po stránke a manuálnou kontrolou možno riziko kontrolovať v overiteľnom rozsahu.

Skúste to teraz: Odovzdajte dokument a spustite preklad, pričom sa zachová pôvodné rozloženie

Aktualizované 2026-11-16