Что мне делать, если я могу щелкнуть страницу оглавления PDF-файла, но после извлечения уровень теряется?

— Когда номер страницы пересекает границу, PyMuPDF может только печатать предупреждение, не вызывая исключения, а функция проверки должна активно фильтровать.

Страница оглавления PDF-файла может быть перенаправлена обычным образом в программе чтения, но после извлечения с помощью сценария иерархия может быть плоской, номера страниц могут быть неуместными или даже индекс может быть ненормальным. Проблемы такого типа часто возникают при объединении отсканированных файлов или файлов с нестандартной структурой закладок. Если результаты извлечения передаются непосредственно последующим пользователям, могут возникнуть ошибки в сегментации перевода и связывании.

Эта статья предназначена для разработчиков и групп документации, которым требуется пакетная обработка каталогов PDF. Прочитав, вы сможете понять смысл возвращаемого значения get_toc(), освоить правила проверки уровней и номеров страниц, а также узнать, в каких ситуациях следует перевести на ручную проверку. В этой статье для демонстрации метода обработки используется синтетический образец, а код был проверен на образце в изолированной среде, но это не является гарантией всех реальных файлов или эффектов продукта. Перед обработкой важных документов, пожалуйста, сохраните оригиналы и просмотрите их по границам и пунктам приема в тексте.

Что делать, если на странице оглавления PDF можно щелкнуть, но после извлечения иерархия теряется? Вывод в одно предложение

Сначала проверьте, затем напишите: сначала необходимо проверить уровень закладки, первый элемент считается первым уровнем, последующие уровни не должны превышать предыдущий элемент плюс один, а записи с номерами страниц, выходящими за пределы поля, не будут записаны.

Почему результат извлечения теряет уровни?

По умолчанию get_toc() выводит список троек [level, title, page]. Среди них page — это номер физической страницы, начиная с 1, а level представляет только глубину вложенности и не гарантирует непрерывности или законности.

Если исходный PDF-файл был создан с помощью инструмента слияния сканов, распространенные проблемы включают в себя:

• Прыжок по уровню: например, прыгайте напрямую с 1 на 3.
• Исключение номера страницы: номер страницы равен 0 или превышает общее количество страниц.
• Исключение заголовка: заголовок содержит управляющие символы.

Если использовать его непосредственно для последующих задач, это приведет к путанице в сегментах перевода или сбою соединения. Еще более коварно то, что некоторые PDF-файлы имеют визуальную страницу оглавления, но не имеют встроенных метаданных закладок. В это время get_toc() обычно возвращает пустой список, и вместо этого необходимо использовать анализ макета текста.

Пример автономной композиции

См. список импорта для примера зависимостей. Код конструирует ввод в память, а записи запуска предоставляются отдельно и не являются гарантией всех реальных файлов.

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

Правила обработки легального и нелегального ввода

Правильный ввод должен удовлетворять: список троек с непрерывными уровнями и номерами страниц в диапазоне [1, doc.page_count]. Например, [[1, "引言", 1], [2, "背景", 2], [1, "方法", 5]] является допустимым, второй уровень появляется после первого уровня и соответствует синтаксису структуры PDF.

К частым неправильным вводам относятся:

• Уровень равен 0 или отрицательный
• Номер страницы – 0.
• Количество страниц превышает общее количество страниц.
• Заголовок представляет собой пустую строку или содержит только пробельные символы.

Для этих ситуаций методы, приведенные в статье, следующие:

1. Пропускайте записи с неверными номерами страниц и регистрируйте предупреждение.
2. Оставьте заполнители, такие как [untitled], для пустых заголовков, чтобы сохранить структурную целостность.
3. Не прерывать парсинг всего каталога из-за единственной ошибки.

В случаях с уровнями меньше 1 следует рассмотреть две стратегии: краткое изложение примера призывает отклонять незаконные уровни и не исправлять их автоматически, тогда как правила в тексте обеспечивают 1. Выбор между ними — это ваш собственный процесс. Следует также отметить, что эти правила разработаны для обеспечения устойчивости последующих процессов и не являются обязательными требованиями стандарта PDF. Тесты показывают, что когда номера страниц выходят за пределы, PyMuPDF печатает предупреждения, но не создаёт исключений, поэтому функция валидации должна активно фильтровать и не может полагаться на поведение библиотеки.

📊 Сравнение ядра

Результаты и рекомендуемые методы обработки для get_toc() варьируются в зависимости от документа:

Критерии приема и границы ручной проверки

Таблица ниже сосредоточена только на этапе извлечения метаданных каталога PDF:

Обратите внимание, что демонстрация кода проверяет только структурную законность; сквозные эффекты также должны сочетаться с рендерингом для проверки точности прыжков.

🎯 Какой способ тебе подходит?

Если нужно пакетировать каталоги для извлечения

Сначала проведите структурную валидацию результатов get_toc(), затем запишите их в последующие рабочие процессы и ведите журналы для проверки.

Если ваш PDF визуально содержит оглавление, но он извлекается пустым

Не повторяйте get_toc(); переходите к анализу и обработке текста.

Если ваша запись в каталоге имеет то же название, но на разных страницах

Проверьте эти записи вручную; не выбирайте автоматически один из номеров страниц.

Если вы хотите передать документы в процесс перевода,

Во-первых, проверьте правильную структуру содержания и номера страниц перед переводом, чтобы избежать путаницы в абзацах.

❓ Часто задаваемые вопросы (FAQ)

1. Почему номер страницы начинается с 1, а индексы страниц обычно начинаются с 0?

Номера страниц закладок — это физические номера страниц, начинающиеся с 1, тогда как индексы страниц в библиотеках вроде PyMuPDF обычно начинаются с 0. Это различие важно при конвертации, иначе номера страниц могут быть неправильно выровнены.

2. get_toc(): Обязательно ли возвращение пустого списка означает проблему с файлом?

Не обязательно. Некоторые PDF визуально имеют страницу с оглавлением, но без встроенных метаданных закладок, поэтому возвращение пустого списка — это нормально. В этом случае следует использовать анализ верстки текста.

3. Если номер страницы выходит за рамки, библиотека сразу же сообщает об ошибке?

Нет. Тесты в этой статье показывают, что PyMuPDF печатает предупреждения, когда номера страниц выходят за пределы, но не создаёт исключений, поэтому функция валидации должна активно фильтровать.

4. Требуют ли иерархические прыжки (например, прямой переход с 1 на 3) заполнять средние слои?

В статье предлагается сохранить исходную иерархию и не заполнять средние слои, так как эта структура всё ещё легитимна.

📝 Краткое содержание

Иерархия и номера страниц каталогов PDF необходимо проверить перед использованием, поэтому исходный вывод get_toc() нельзя напрямую считать надёжной структурой. При возникновении неоднозначностей или отсутствия закладок незамедлительно переходите к ручному труду или другим методам, чтобы избежать ошибок в дальнейших процессах.

Опыт сейчас: загрузите документ, чтобы начать перевод, сохраняя оригинальное форматирование

Ссылки и следующие шаги

• PyMuPDF Document.get_toc официальная документация

Следующий шаг — подготовить тестовый PDF с известными проблемами каталога, запустить вышеуказанный скрипт проверки и вычислить долю различных аномалий. Если часто случаются иерархические пропуски или смещения номера страниц, рассмотрите возможность добавления этапа реконструкции оглавления перед переводом.

Используйте этот чек-лист для перевода документов

Сначала тщательно проверьте порядок страниц, местоположение источника и целостность текста, затем отправьте тот же образец десенсибилизации в процесс перевода. После перевода всё равно необходимо проверить, совпадают ли заголовок, основной текст и подписи; недостаточно судить только по плавности текста.

OmniDoc предоставляет многоформатные порталы для перевода документов, а официальный сайт вводит OCR, глоссарии и билингвальные справочные функции. Для команд, которые хотят начинать напрямую с файлов, этот путь стоит оценивать с помощью реальных образцов. Пожалуйста, используйте анонимный файл, который вы разрешили загрузить, и проверьте результаты с помощью чек-листа в этой статье. Это не означает, что OmniDoc использует библиотеку с открытым исходным кодом или внутренние алгоритмы из этой статьи, и не заменяет тестирование производительности продукта примерами.