Was soll ich tun, wenn ich auf die Inhaltsverzeichnisseite einer PDF-Datei klicken kann, aber nach dem Extrahieren die Ebene verliere?

– Eine von get_toc() zurückgegebene leere Liste kann darauf hinweisen, dass in der PDF-Datei keine Lesezeichen eingebettet sind und stattdessen eine Textlayoutanalyse verwendet werden sollte.

• Wenn die Seitenzahl die Grenze überschreitet, druckt PyMuPDF möglicherweise nur eine Warnung, ohne eine Ausnahme auszulösen, und die Überprüfungsfunktion muss aktiv filtern.

Die Inhaltsverzeichnisseite der PDF-Datei kann im Reader normal umgeleitet werden, aber nach dem Extrahieren mit einem Skript ist die Hierarchie möglicherweise flach, die Seitenzahlen sind möglicherweise falsch platziert oder sogar der Index ist möglicherweise abnormal. Diese Art von Problem tritt häufig auf, wenn gescannte Dateien oder Dateien mit unregelmäßigen Lesezeichenstrukturen zusammengeführt werden. Werden die Extraktionsergebnisse direkt an nachgeschaltete Anwender übergeben, kann es zu Fehlern bei der Übersetzungssegmentierung und Verknüpfung kommen.

Dieser Artikel richtet sich an Entwickler und Dokumentationsteams, die PDF-Kataloge stapelweise verarbeiten müssen. Nach dem Lesen können Sie die Bedeutung des get_toc()-Rückgabewerts verstehen, die Überprüfungsregeln für Ebenen und Seitenzahlen beherrschen und wissen, welche Situationen auf manuelle Überprüfung umgestellt werden sollten. In diesem Artikel wird ein synthetisches Beispiel verwendet, um die Verarbeitungsmethode zu demonstrieren. Der Code wurde anhand des Beispiels in einer isolierten Umgebung überprüft. Dies stellt jedoch keine Garantie für alle tatsächlichen Dateien oder Produkteffekte dar. Bevor Sie wichtige Dokumente bearbeiten, bewahren Sie bitte die Originale auf und überprüfen Sie sie anhand der Grenzen und Akzeptanzpunkte im Text.

Was soll ich tun, wenn auf die Seite mit dem PDF-Inhaltsverzeichnis geklickt werden kann, die Hierarchie jedoch nach dem Extrahieren verloren geht? Fazit in einem Satz

Zuerst überprüfen, dann schreiben: Die Lesezeichenebene muss zuerst überprüft werden, das erste Element wird als erste Ebene betrachtet, nachfolgende Ebenen sollten das vorherige Element plus eins nicht überschreiten und Einträge mit Seitenzahlen außerhalb der Grenzen werden nicht geschrieben.

Warum verliert das Extraktionsergebnis an Ebenen?

get_toc() gibt standardmäßig eine Liste von [level, title, page]-Tripeln aus. Unter diesen ist page die physische Seitenzahl beginnend mit 1, und level stellt nur die Verschachtelungstiefe dar und garantiert keine Kontinuität oder Rechtmäßigkeit.

Wenn das Quell-PDF von einem Scan-Merge-Tool generiert wurde, treten häufig folgende Probleme auf:

• Level Jump: Springe zum Beispiel direkt von 1 auf 3
• Ausnahme Seitenzahl: Die Seitenzahl ist 0 oder überschreitet die Gesamtzahl der Seiten
• Titelausnahme: Der Titel enthält Steuerzeichen

Wenn es direkt für nachgelagerte Aufgaben verwendet wird, führt es zu Verwirrung in den Übersetzungssegmenten oder zu Verbindungsfehlern. Noch heimtückischer ist, dass einige PDFs ein visuelles Inhaltsverzeichnis, aber keine eingebetteten Lesezeichen-Metadaten haben. Es ist normal, dass get_toc() zu diesem Zeitpunkt eine leere Liste zurückgibt. Stattdessen muss eine Textlayoutanalyse verwendet werden.

Beispiel für eine eigenständige Komposition

Beispiele für Abhängigkeiten finden Sie in der Importliste. Der Code erstellt Eingaben im Speicher, und die Ausführungsdatensätze werden separat bereitgestellt und stellen keine Garantie für alle echten Dateien dar.

import pymupdf
def validate(rows, pages):
    previous = 0
    for level, title, page in rows:
        if type(level) is not int or level < 1 or level > previous + 1:
            raise ValueError("invalid hierarchy")
        if type(page) is not int or not 1 <= page <= pages:
            raise ValueError("invalid destination")
        if not isinstance(title, str) or not title.strip():
            raise ValueError("empty title")
        previous = level
    return rows
with pymupdf.open() as doc:
    for _ in range(3):
        doc.new_page()
    rows = [[1, "Chapter", 1], [2, "Section", 2], [1, "Appendix", 3]]
    doc.set_toc(validate(rows, doc.page_count))
    assert doc.get_toc() == rows
    assert len(doc.get_toc()) == 3
    for bad in [[[2, "Bad", 1]], [[1, "Bad", 99]], [[1, "", 1]]]:
        try:
            validate(bad, doc.page_count)
        except ValueError:
            pass
        else:
            raise AssertionError("invalid outline accepted")

Verarbeitungsregeln für legale und illegale Eingaben

Die korrekte Eingabe sollte Folgendes erfüllen: eine Liste von Tripeln mit kontinuierlichen Ebenen und Seitenzahlen im Bereich [1, doc.page_count]. Beispielsweise ist [[1, "引言", 1], [2, "背景", 2], [1, "方法", 5]] zulässig, die zweite Ebene erscheint nach der ersten Ebene und entspricht der PDF-Gliederungssyntax.

Zu den häufigsten Fehleingaben gehören:

• Level ist 0 oder negativ
• Seitenzahl ist 0
• Die Anzahl der Seiten übersteigt die Gesamtanzahl der Seiten
• Der Titel ist eine leere Zeichenfolge oder enthält nur Leerzeichen

Für diese Situationen werden im Artikel folgende Methoden beschrieben:

1. Überspringen Sie Einträge mit ungültigen Seitenzahlen und protokollieren Sie eine Warnung.
2. Behalten Sie Platzhalter wie [untitled] für leere Titel bei, um die strukturelle Integrität aufrechtzuerhalten.
3. Unterbrechen Sie nicht die Analyse des gesamten Verzeichnisses aufgrund eines einzelnen Fehlers.

Für den Fall, dass der Wert unter 1 liegt, gibt es zwei Strategien, die Sie beachten sollten: Der zusammenfassende Teil des Beispiels empfiehlt, illegale Werte abzulehnen und nicht automatisch zu korrigieren, während die Regelbeschreibung im Artikel darin besteht, den Wert auf 1 zu erzwingen. Bitte entscheiden Sie sich entsprechend Ihrem Prozess für eine der beiden. Beachten Sie außerdem, dass diese Regeln die Robustheit nachgelagerter Prozesse sicherstellen sollen und keine zwingenden Anforderungen des PDF-Standards sind. Bei tatsächlichen Tests wurde festgestellt, dass PyMuPDF eine Warnung ausgibt, aber keine Ausnahme auslöst, wenn die Seitenzahl die Grenze überschreitet. Daher muss die Verifizierungsfunktion aktiv filtern und kann sich nicht auf das Verhalten der Bibliothek verlassen.

📊 Kernvergleich

In verschiedenen Dokumentsituationen sind die Ergebnisse und vorgeschlagenen Verarbeitungsmethoden von get_toc() unterschiedlich:

Akzeptanzkriterien und manuelle Überprüfungsgrenzen

Die folgende Tabelle konzentriert sich nur auf die Extraktion von PDF-Katalogmetadaten:

Es ist zu beachten, dass die Codedemonstration nur die Rechtmäßigkeit der Struktur überprüft und der End-to-End-Effekt mit dem Rendering kombiniert werden muss, um zu überprüfen, ob der Sprung korrekt ist.

🎯 Welche Methode ist für Dich geeignet?

Wenn Sie Verzeichnisse stapelweise extrahieren müssen

Führen Sie zunächst eine strukturelle Überprüfung des get_toc()-Ergebnisses durch, schreiben Sie es dann in den nachfolgenden Prozess und bewahren Sie das Protokoll zur Überprüfung auf.

Wenn Ihr PDF optisch ein Inhaltsverzeichnis hat, die Extraktion jedoch leer ist

Versuchen Sie get_toc() nicht wiederholt, sondern verwenden Sie stattdessen die Textlayout-Analyseverarbeitung.

Wenn Ihr Telefonbucheintrag auf verschiedenen Seiten mit demselben Namen erscheint

Stellen Sie diese Einträge auf manuelle Überprüfung um und wählen Sie nicht automatisch eine der Seitenzahlen aus.

Wenn Sie Ihr Dokument einem Übersetzungsprozess unterziehen

Vergewissern Sie sich vor der Übersetzung zunächst, dass die Verzeichnisstruktur und die Seitenzahlen korrekt sind, um Verwirrung bei der Segmentierung zu vermeiden.

❓ Häufig gestellte Fragen (FAQ)

1. Warum beginnt die Seitenzahl bei 1, während der Seitenindex normalerweise bei 0 beginnt?

Lesezeichen-Seitenzahlen sind physische Seitenzahlen, die bei 1 beginnen, während Seitenindizes in Bibliotheken wie PyMuPDF normalerweise bei 0 beginnen. Sie müssen diesen Unterschied beim Konvertieren beachten, da sonst die Seitenzahlen falsch ausgerichtet werden.

2. Bedeutet es, dass etwas mit der Datei nicht stimmt, wenn get_toc() eine leere Liste zurückgibt?

unsicher. Einige PDFs verfügen optisch über eine Seite mit einem Inhaltsverzeichnis, betten jedoch keine Lesezeichen-Metadaten ein. Es ist normal, eine leere Liste zurückzugeben. In diesem Fall sollte stattdessen eine Textlayoutanalyse verwendet werden.

3. Wird die Bibliothek direkt einen Fehler melden, wenn die Seitenzahl die Grenze überschreitet?

Gewohnheit. Die eigentliche Messung in diesem Artikel ergab, dass PyMuPDF eine Warnung ausgibt, aber keine Ausnahme auslöst, wenn die Seitenzahl die Grenze überschreitet, sodass die Überprüfungsfunktion aktiv filtern muss.

4. Müssen Sie die mittleren Ebenen für Levelsprünge ausfüllen (z. B. direkt von 1 auf 3 gehen)?

Der Vorschlag im Artikel besteht darin, die ursprüngliche Hierarchie beizubehalten und keine Zwischenebenen hinzuzufügen, da diese Struktur immer noch zulässig ist.

📝 Zusammenfassung

Die Hierarchie und Seitenzahlen des PDF-Verzeichnisses müssen vor der Verwendung überprüft werden. Die ursprüngliche Ausgabe von get_toc() kann nicht direkt als zuverlässige Struktur angesehen werden. Wenn Sie auf Unklarheiten oder fehlende Lesezeichen stoßen, können Sie Fehler in nachgelagerten Prozessen vermeiden, indem Sie rechtzeitig auf manuelle Arbeit umsteigen oder andere Methoden anwenden.

Probieren Sie es jetzt aus: Laden Sie das Dokument hoch, um mit der Übersetzung zu beginnen, und behalten Sie dabei das ursprüngliche Layout bei

Referenzen und nächste Schritte

• Offizielles Dokument von PyMuPDF Document.get_toc

Empfohlener nächster Schritt: Bereiten Sie ein Test-PDF mit bekannten Verzeichnisproblemen vor, führen Sie das obige Überprüfungsskript aus und zählen Sie den Anteil verschiedener Anomalien. Wenn es häufig zu Ebenensprüngen oder Seitenzahlverschiebungen kommt, sollten Sie erwägen, vor der Übersetzung einen Schritt zur Verzeichnisrekonstruktion hinzuzufügen.

Verwenden Sie diese Checkliste für die Dokumentenübersetzung

Überprüfen Sie zunächst die Seitenreihenfolge, den Quellort und die Textintegrität und senden Sie dann das gleiche desensibilisierte Beispiel an den Übersetzungsprozess. Nach der Übersetzung müssen Sie noch prüfen, ob Titel, Text und Abbildungen korrekt übereinstimmen. Sie können nicht einfach prüfen, ob der Text glatt ist.

OmniDoc bietet ein Multiformat-Dokumentübersetzungsportal und die offizielle Website führt OCR-, Glossar- und zweisprachige Vergleichsfunktionen ein. Für Teams, die direkt mit Dateien arbeiten möchten, ist dies ein Weg, den es wert ist, anhand realer Beispiele zu evaluieren. Bitte verwenden Sie desensibilisierte Dateien, für deren Hochladen Sie berechtigt sind, und verwenden Sie die Prüfpunkte in diesem Artikel, um die Ergebnisse zu überprüfen. Es besteht hier kein Anspruch darauf, dass OmniDoc die Open-Source-Bibliotheken oder internen Algorithmen in diesem Artikel verwendet, noch ersetzt das Beispiel Produktleistungstests.