De PDF ziet er horizontaal uit, maar de geëxtraheerde coördinaten zijn verkeerd: leg de rotatiematrix duidelijk uit

Toen ik PDF aan het verwerken was, zag ik duidelijk dat de tabel zich aan de rechterkant van de pagina bevond, maar de geëxtraheerde coördinaten wezen naar de linkerbovenhoek, of het gemarkeerde kleurblok viel naar de koppositie. Dit type probleem is vaak geen bug in de parseerbibliotheek, maar een inconsistentie tussen het coördinatensysteem van de PDF en de visuele weergave. Dit artikel is bedoeld voor ontwikkelaars die tekstpositionering, gebiedsmatching of annotatietekenen moeten uitvoeren. Het legt uit hoe het /Rotate-attribuut een verkeerde uitlijning van de coördinaten veroorzaakt, en gebruikt de rotatiematrix van PyMuPDF om de conversie te voltooien.

De voorbeelden in dit artikel worden allemaal in het geheugen gesynthetiseerd en er worden geen echte bestanden gelezen. Voordat u belangrijke documenten verwerkt, dient u de originelen te bewaren en ze vervolgens één voor één te bekijken volgens de grenzen en acceptatie-items in het document.

Wat moet ik doen als de coördinaten van de PDF na rotatie niet overeenkomen? Conclusie in één zin

Gebruik Page.rotation_matrix om niet-geroteerde coördinaten om te zetten in weergave van coördinaten, en controleer page.rotation pagina voor pagina voordat u deze verwerkt. Ga er niet van uit dat de coördinaatrichtingen van alle pagina's consistent zijn.

Begrijp het verschil tussen niet-geroteerde ruimte en weergegeven ruimte

PDF-pagina's kunnen het kenmerk /Rotate dragen, met waarden van 0, 90, 180 of 270 graden. Deze rotatie wordt automatisch toegepast wanneer de lezer rendert, maar de coördinaten van de pagina-inhoudstroom zijn nog steeds gebaseerd op de niet-geroteerde originele MediaBox. Als u de geëxtraheerde originele coördinaten rechtstreeks gebruikt voor tekenen of gebiedsafstemming, zullen de resultaten verkeerd uitgelijnd zijn.

PyMuPDF maakt duidelijk onderscheid tussen deze twee coördinatensystemen vanaf v1.17.0:

• Niet-geroteerde ruimte: de coördinaten van Page.get_text(), Page.get_image_bbox() en alle annotatieobjecten worden standaard geretourneerd ten opzichte van de niet-geroteerde pagina.
• Weergaveruimte: alleen Page.rect en Page.bound() geven na rotatie de werkelijke weergavegrootte weer.

Dit ontwerp zorgt ervoor dat de extractie van inhoud stabiel blijft. Zelfs als de paginarotatiehoek wordt gewijzigd, veranderen de extractiecoördinaten van dezelfde tekst niet. Maar wanneer u de coördinaten terug naar de pagina moet tekenen of ze moet uitlijnen met visuele interacties zoals muisklikken, moet u de coördinatentransformatie handmatig voltooien.

PyMuPDF biedt twee belangrijke matrices:

1. Page.rotation_matrix: Converteer niet-geroteerde coördinaten om coördinaten weer te geven.
2. Page.derotation_matrix: Voer de omgekeerde bewerking uit.

Deze twee matrices omvatten translatie- en rotatietransformaties, zodat ontwikkelaars trigonometrische functieberekeningen niet met de hand hoeven te schrijven.

Synthesevoorbeeld: Juiste en onjuiste verwachtingen van coördinatentransformatie

Om dit mechanisme te demonstreren, construeren we een puur synthetische scène in het geheugen die niet afhankelijk is van externe bestanden. Als u een echt document moet testen, bereid dan vooraf een PDF voor met het /Rotate=90-attribuut en zorg ervoor dat de CropBox consistent is met de MediaBox om de interferentie van de bijsnijdafwijking te elimineren.

Invoerinstellingen: Maak een A4-staande pagina (595 x 842 pt), stel /Rotate = 90 in. In de niet-geroteerde ruimte bevindt het punt (100, 100) zich nabij de linkerbovenhoek; wanneer het punt 90 graden wordt gedraaid, verandert de visuele positie van het punt aanzienlijk omdat het coördinatensysteem ermee roteert.

Correcte uitvoer verwacht: Vermenigvuldig (100, 100) met rotation_matrix en de resulterende weergavecoördinaten moeten binnen de geldige grenzen van de geroteerde pagina vallen (d.w.z. page.rect). Voor de standaard A4-pagina die 90 graden tegen de klok in is gedraaid, moet het oorspronkelijke punt in de linkerbovenhoek zich nabij de linkeronderhoek in de weergaveruimte bevinden, dat wil zeggen dat de x-coördinaat groter is en de y-coördinaat dichtbij 0. De specifieke waarde hangt af van de oorsprongsdefinitie van de MediaBox. Ga er niet zomaar van uit dat y groter is dan x.

Afhandeling van grensgevallen: wanneer de rotatiehoek 0 is, moet rotation_matrix de identiteitsmatrix zijn. Als een rotatiewaarde wordt doorgegeven die geen veelvoud van 90 graden is, zal PyMuPDF deze doorgaans normaliseren, maar het wordt nog steeds aanbevolen om de matrixvaliditeit te controleren om te voorkomen dat er NaN-coördinaten worden gegenereerd.

Python implementeert logica voor coördinaatverificatie

In het volgende voorbeeld ziet u hoe u coördinaattransformaties in het geheugen kunt verifiëren. Het demonstreert alleen matrixbewerkingslogica en is geen volledige PDF-verwerkingspijplijn. Zorg ervoor dat PyMuPDF is geïnstalleerd voordat u het uitvoert, en voer het uit in een omgeving waarin u de afhankelijkheden hebt vergrendeld.

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

Deze code leest geen echt bestand, maar bouwt de paginastatus in het geheugen op. De assert-instructie controleert de rationaliteit van de wiskundige relatie, niet de zakelijke correctheid. Extra foutopsporing kan nodig zijn als de daadwerkelijke PDF niet-standaard MediaBox of geneste transformaties bevat.

📊 Kernvergelijking

Acceptatiecriteria en grenzen voor handmatige beoordeling

Het feit dat de code de bewering doorstaat, betekent niet dat de productieomgeving onfeilbaar is. De volgende tabel bevat veelvoorkomende uitzonderingen en hun afhandelingsbeslissingen om scenario's te helpen onderscheiden die kunnen worden geautomatiseerd en handmatige tussenkomst vereisen.

Deze tabel behandelt alleen de logica voor coördinaattransformatie en heeft geen betrekking op de nauwkeurigheid van de OCR of op problemen met de codering van lettertypen. Wanneer u te maken krijgt met complexe typografie, kan automatische verificatie mislukken. Op dit moment moet de pijplijn worden gepauzeerd en moet handmatig worden beoordeeld of deze wordt voortgezet.

Gebruik checklists voor documentvertaling

Controleer vóór de vertaling de paginavolgorde, de bronlocatie en de tekstintegriteit en dien vervolgens hetzelfde ongevoelig gemaakte voorbeeld in voor het vertaalproces. Na de vertaling moet je nog steeds controleren of de titel, tekst en illustraties correct overeenkomen, en niet alleen of de vertaling vlot verloopt.

OmniDoc (productportaal) biedt een documentvertalingsportaal in meerdere formaten, en de officiële website introduceert OCR-, woordenlijst- en tweetalige vergelijkingsfuncties. Voor teams die rechtstreeks vanuit de bestanden willen werken, is dit een pad dat de moeite waard is om te evalueren met praktijkvoorbeelden. Gebruik ongevoelige bestanden waarvoor u toestemming heeft om te uploaden, en gebruik de controle-items in dit artikel om de resultaten te bekijken. Er wordt niet beweerd dat OmniDoc de open source-bibliotheken of interne algoritmen gebruikt die in dit artikel worden genoemd, noch vervangt het voorbeeld het testen van productprestaties.

Verder lezen:

• PyMuPDF Page.rotation_matrix officiële documentatie
• PyMuPDF coördineert conceptnota

🎯 Welke methode is geschikt voor jou?

Als u de geëxtraheerde tekstcoördinaten terug naar de pagina wilt tekenen

Gebruik eerst rotation_matrix om te converteren naar weergavecoördinaten en teken vervolgens hoogtepunten of annotaties.

Als u muisklikken wilt terugverwijzen naar de originele inhoud

Gebruik derotation_matrix voor omgekeerde conversie en controleer of het punt binnen het geldige bereik valt ten opzichte van page.rect.

Als u te maken heeft met documenten met gemengde rotatiehoeken

Lees page.rotation pagina voor pagina, gebruik de globale matrix niet opnieuw en markeer pagina's die buiten de grenzen vallen.

Als uw pagina complexe lay-outs of gedeeltelijk geroteerde diagrammen bevat

Doorloop eerst synthetische monsters en kleinschalige echte monsters en beslis vervolgens of u deze aan het automatische proces wilt overdragen. Wanneer u afwijkingen tegenkomt, dient u deze over te dragen aan handmatige beoordeling.

❓ Veelgestelde vragen (FAQ)

1. Waarom zijn de door get_text() geretourneerde coördinaten inconsistent met de visuele positie?

Omdat deze API's standaard terugkeren ten opzichte van de niet-geroteerde pagina, wordt het kenmerk /Rotate toegepast wanneer de lezer wordt weergegeven.

2. Zijn de coördinaatdatums van Page.rect en get_text() hetzelfde?

nee hetzelfde. Page.rect en Page.bound() weerspiegelen de geroteerde weergavegrootte, terwijl de coördinaten van API's zoals get_text() zijn verankerd aan de oorspronkelijke, niet-geroteerde breedte en hoogte.

3. Is conversie nog steeds nodig als de rotatiehoek 0 is?

onnodig. Op dit punt zou rotation_matrix een identiteitsmatrix moeten zijn, maar het wordt nog steeds aanbevolen om te controleren op bias, omdat tools van derden verborgen rotatie-metagegevens kunnen schrijven.

4. Kan de code direct voor productie worden gebruikt nadat de bewering is doorgegeven?

Niet aanbevolen. De bewering controleert alleen de rationaliteit van wiskundige relaties. De daadwerkelijke PDF kan niet-standaard MediaBox, onafhankelijke CTM-transformatie of abnormale pagina's bevatten, die nog steeds item voor item moeten worden beoordeeld volgens het acceptatieformulier.

📝 Samenvatting

De oorzaak van een verkeerde uitlijning van de coördinaten ligt in het verschil tussen de niet-geroteerde ruimte en de weergaveruimte. Door gebruik te maken van rotation_matrix en derotation_matrix voor conversie, gecombineerd met pagina-voor-pagina inspectie en handmatige beoordeling, kan het risico binnen een verifieerbaar bereik worden beheerst.

Probeer het nu: upload het document om de vertaling te starten, waarbij de oorspronkelijke lay-out behouden blijft