PyMuPDF分割PDF与目录生成教程

本文详细介绍了如何使用Python的PyMuPDF库来实现PDF文件的分割，并为分割后的文件动态生成符合规范的目录（TOC）。在PDF处理中，分割PDF的同时保留甚至动态生成TOC是一项具有挑战性的任务，因为PyMuPDF对TOC的结构有着严格的要求，例如层级必须从1开始，且层级之间不能跳跃。本文深入剖析了PyMuPDF的TOC机制，并提供了一种解决方案，通过筛选原始TOC条目、调整页码和层级，甚至添加“虚拟”条目来确保新生成的PDF文件拥有一个完整且可用的TOC。该方法能够帮助用户高效地处理大型PDF文档，使其分割后的每个部分都易于导航和管理。

本教程详细介绍了如何使用PyMuPDF库高效地按页码范围分割PDF文件，并为每个分割后的文件动态生成并维护对应的目录（TOC）。文章重点阐述了PyMuPDF中TOC结构的严格规则，包括层级（level）的合法性检查与调整策略，特别是通过添加“虚拟”条目来确保TOC的正确性，从而实现分割PDF后TOC的完整保留和可用性。

引言：分割PDF与目录管理的挑战

在处理大型PDF文档时，例如书籍或报告，我们经常需要将其分割成更小的、更易于管理的章节或部分。然而，简单的页面提取操作往往会丢失原始PDF中重要的导航信息——目录（Table of Contents, TOC）。用户期望分割后的PDF文件也能拥有一个功能完整的、与其内容相对应的TOC，以便于快速导航。PyMuPDF（也称为fitz）是一个功能强大的Python库，能够高效地处理PDF文件，包括读取和设置TOC。本文将深入探讨如何利用PyMuPDF实现这一目标，特别是如何处理TOC的复杂结构规则。

PyMuPDF中的目录（TOC）机制

PyMuPDF通过Document.get_toc()方法获取PDF的目录，并通过Document.set_toc()方法设置目录。理解TOC的数据结构和其严格的规则是成功实现动态TOC生成的关键。

Document.get_toc()返回一个列表，其中每个元素都是一个子列表，表示一个TOC条目。每个子列表的结构为 [level, title, page]：

• level：一个整数，表示该TOC条目的层级（或缩进级别）。
• title：一个字符串，表示该TOC条目的标题。
• page：一个整数，表示该TOC条目对应的页面编号，注意这里是1-based索引。

TOC结构的关键规则：

Document.set_toc()方法对TOC列表的结构有严格要求。如果违反这些规则，TOC将无法正确设置或显示。主要规则包括：

1. 首个条目必须为层级1（level = 1）：TOC列表的第一个条目必须以层级1开始。
2. 后续层级变化规则：
   • 后续条目的层级可以与前一个条目相等。
   • 后续条目的层级可以比前一个条目正好高一级（例如，从层级1到层级2是合法的，但从层级1直接到层级3是非法的）。
   • 后续条目的层级可以比前一个条目低（例如，从层级3到层级1是合法的）。

合法与非法TOC层级序列示例：

• 合法： [1, 1, 1, ...]
• 合法： [1, 2, 3, 3, 3, 1, ...]
• 非法： [1, 3, ...] (跳过了层级2)

这些规则对于我们动态生成TOC至关重要。当分割PDF时，我们提取的TOC子集可能不满足这些规则，特别是其第一个条目可能不是层级1，或者中间存在层级跳跃。

实现PDF分割与动态TOC生成

要实现带有动态TOC的PDF分割，我们需要一个多步骤的策略，以确保分割后的每个PDF文件都拥有符合PyMuPDF规则的TOC。

核心思路

1. 获取原始TOC： 从原始PDF中提取完整的TOC。
2. 筛选相关TOC条目： 根据指定的页码范围，从原始TOC中筛选出属于当前分割部分的条目。
3. 调整页码： 将筛选出的TOC条目中的原始绝对页码转换为在新分割PDF中的相对页码。
4. 调整层级合规性： 这是最关键的一步。根据PyMuPDF的TOC规则，对筛选并调整页码后的TOC条目进行层级修正，包括插入“虚拟”条目来满足层级1和层级连续性要求。
5. 保存新PDF与TOC： 将修正后的TOC设置到新生成的PDF文件中，并保存。

辅助函数：调整TOC层级以符合规则

为了处理TOC层级规则，我们首先定义一个辅助函数_adjust_toc_for_rules。该函数将接收一系列TOC条目和一个起始相对页码，然后返回一个符合PyMuPDF规则的新TOC列表。

import fitz
import os

def _adjust_toc_for_rules(toc_entries, first_relative_page):
    """
    调整TOC条目列表，使其符合PyMuPDF的set_toc()规则。
    确保第一个条目是层级1，并维护有效的层级层次结构（例如，不允许1 -> 3的跳跃）。

    Args:
        toc_entries (list): 原始的、已筛选并调整页码的TOC条目列表。
                            每个条目为 [level, title, page] (page为1-based相对页码)。
        first_relative_page (int): 新PDF中第一个实际内容的1-based相对页码。
                                   用于填充虚拟条目的页码。

    Returns:
        list: 符合PyMuPDF规则的TOC条目列表。

好了，本文到此结束，带大家了解了《PyMuPDF分割PDF与目录生成教程》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！