高效拆分PDF并精确保留目录结构（PyMuPDF教程）（高效.拆分.精确.保留.结构...）

本教程详细介绍了如何使用PyMuPDF库（fitz）高效地将大型PDF文档按指定页面范围拆分为多个独立文件，并确保每个拆分后的PDF都能正确地包含其对应的、且符合PyMuPDF规范的目录（Table of Contents, TOC）。文章深入探讨了PyMuPDF的TOC结构规则，提供了修正不规范TOC层级的实用方法，并通过完整的Python代码示例，指导读者实现这一复杂功能，帮助用户更好地管理和导航拆分后的文档。PyMuPDF中目录（TOC）的工作原理

在处理pdf文档时，目录（table of contents, toc）是用户导航的关键工具。pymupdf（也称为fitz）提供了强大的功能来读取和修改pdf的toc。然而，仅仅拆分pdf页面并不能自动保证新文档的toc是完整且正确的。pymupdf对toc的结构有着严格的规定，理解这些规则是实现精确拆分的关键。

TOC的数据结构

PyMuPDF通过Document.get_toc()方法获取TOC，其结果是一个列表，其中每个元素又是一个包含三个子项的列表：[层级, 标题, 页码]。

• 层级（level）: 一个整数，表示目录项的层级或缩进深度。
• 标题（title）: 字符串，目录项的文本描述。
• 页码（page）: 一个基于1的整数，表示该目录项指向的页面。

TOC的层级规则

PyMuPDF对TOC的层级结构有强制性规定，如果不遵守这些规则，Document.set_toc()操作将会失败：

1. 首项必须是层级1：整个TOC列表的第一个目录项的层级（level）必须是1。
2. 层级递增或递减：
   • 后续目录项的层级可以与前一个目录项的层级相等。
   • 后续目录项的层级可以比前一个目录项的层级恰好高1（例如，从1到2是合法的，但从1到3是非法的）。
   • 后续目录项的层级可以比前一个目录项的层级低（例如，从3到1是合法的）。

合法的层级序列示例：

• [1, 1, 1, ...]
• [1, 2, 3, 3, 3, 1, ...]

非法的层级序列示例：

• [1, 3, ...] (直接从1跳到3，中间缺少2)

当我们将一个大型PDF拆分为多个小PDF时，从原始TOC中截取的部分TOC可能不满足这些规则。例如，一个章节可能从原始PDF的层级3开始，或者在章节内部出现层级跳跃。为了使拆分后的PDF具有有效的TOC，我们必须对提取的TOC进行修正，以符合上述PyMuPDF的规范。

实现PDF拆分与目录修正

为了实现带目录的PDF拆分，我们需要执行以下步骤：

1. 打开原始PDF文档并获取其完整的TOC。
2. 根据用户定义的页面范围，从原始PDF中提取相应的页面，并创建新的PDF文档。
3. 从原始TOC中筛选出与当前页面范围相关的目录项。
4. 调整筛选出的目录项的页码，使其相对于新创建的PDF文档（即，新PDF的第一页对应原始PDF的起始页）。
5. 核心步骤： 修正筛选并调整后的TOC，使其符合PyMuPDF的层级规则。这通常涉及在必要时插入“虚拟”目录项以填充层级空缺，并确保TOC以层级1开始。
6. 将修正后的TOC设置到新的PDF文档中。
7. 保存新的PDF文档。

示例代码：带目录的PDF拆分工具

以下是一个完整的Python函数，演示了如何使用PyMuPDF实现上述逻辑：

import fitz # PyMuPDF

def correct_toc_hierarchy(toc_list):
    """
    修正TOC列表的层级结构，确保其符合PyMuPDF的规则。
    - 确保TOC以层级1开始。
    - 填充层级跳跃，例如从1直接跳到3，会插入一个层级2的虚拟项。
    """
    if not toc_list:
        return []

    corrected_toc = []

    # 获取第一个实际目录项的层级和页码
    first_entry_level = toc_list[0][0]
    first_entry_page = toc_list[0][2]

    # 1. 确保TOC以层级1开始：如果第一个目录项不是层级1，则插入虚拟项
    for l in range(1, first_entry_level):
        corrected_toc.append([l, f"Dummy Level {l}", first_entry_page])

    # 添加第一个实际目录项
    corrected_toc.append(toc_list[0])

    # 2. 遍历其余目录项，修正层级跳跃
    for k in range(1, len(toc_list)):
        prev_level = corrected_toc[-1][0]
        current_entry = toc_list[k]
        current_level = current_entry[0]
        current_page = current_entry[2]

        # 如果当前层级比前一个层级高1以上，则插入虚拟项
        if current_level > prev_level + 1:
            for l in range(prev_level + 1, current_level):
                corrected_toc.append([l, f"Dummy Level {l}", current_page])

        # 添加当前实际目录项
        corrected_toc.append(current_entry)

    return corrected_toc

def split_pdf_with_toc(input_pdf_path, output_folder, page_ranges):
    """
    将PDF文件按指定页面范围拆分，并为每个拆分后的文件生成对应的TOC。

    Args:
        input_pdf_path (str): 输入PDF文件的路径。
        output_folder (str): 拆分后PDF文件的保存目录。
        page_ranges (list): 一个元组列表，每个元组包含(起始页码, 结束页码)，
                            页码基于1。
    """
    pdf_document = fitz.open(input_pdf_path)
    full_toc = pdf_document.get_toc()

    for i, (start_orig_page, end_orig_page) in enumerate(page_ranges, start=1):
        # 创建一个新的PDF文档用于当前章节
        chapter_pdf = fitz.open()

        # 从原始PDF中插入指定页码范围的页面。
        # fitz的insert_pdf方法页码基于0，所以需要减1。
        chapter_pdf.insert_pdf(
            pdf_document, 
            from_page=start_orig_page - 1, 
            to_page=end_orig_page - 1
        )

        # 筛选与当前章节相关的TOC条目
        chapter_toc_raw = []
        for level, title, page_num_orig in full_toc:
            if start_orig_page <= page_num_orig <= end_orig_page:
                # 调整页码，使其相对于新PDF的起始页（1-based）
                page_num_new = page_num_orig - (start_orig_page - 1)
                chapter_toc_raw.append([level, title, page_num_new])

        # 修正TOC的层级结构以符合PyMuPDF的规则
        final_chapter_toc = correct_toc_hierarchy(chapter_toc_raw)

        # 将修正后的TOC设置到新的章节PDF中
        if final_chapter_toc: # 只有当TOC不为空时才设置
            chapter_pdf.set_toc(final_chapter_toc)

        # 保存新的章节PDF
        output_pdf_path = f"{output_folder}/Chapter_{i}_pages_{start_orig_page}-{end_orig_page}.pdf"
        chapter_pdf.save(output_pdf_path)
        chapter_pdf.close()
        print(f"Generated: {output_pdf_path}")

    pdf_document.close()
    print("PDF splitting complete.")

# 示例用法
if __name__ == "__main__":
    # 确保 'demo' 文件夹中有一个 'robin.pdf' 文件，并且 'output' 文件夹存在
    # 或者根据您的实际情况修改路径
    input_pdf_path = "demo/robin.pdf" # 替换为您的PDF文件路径
    output_folder = "output" # 替换为您的输出文件夹路径

    import os
    if not os.path.exists(output_folder):
        os.makedirs(output_folder)

    # 定义您想要拆分的页面范围 (页码基于1)
    # 示例: 拆分原始PDF的第45到81页为一个文件，第100到120页为另一个文件
    page_ranges = [(45, 81), (100, 120)] 

    split_pdf_with_toc(input_pdf_path, output_folder, page_ranges)

代码解析与注意事项

1. correct_toc_hierarchy(toc_list) 函数：

   • 这个函数是整个解决方案的核心，它负责确保生成的TOC符合PyMuPDF的严格层级要求。
   • 它首先处理TOC的第一个条目，如果其层级不为1，则会插入必要的虚拟层级（例如，如果第一个实际条目是层级3，它会插入一个层级1和一个层级2的虚拟条目）。
   • 接着，它遍历TOC的其余部分，检查是否存在层级跳跃（例如，从层级1直接跳到层级3）。如果发现这种跳跃，它会在中间插入虚拟的目录项，以保持层级递增不超过1的规则。
   • 虚拟目录项的标题可以根据需要自定义，这里使用了"Dummy Level {level}"。
   • 虚拟目录项的页码通常设置为其后紧邻的实际目录项的页码，这样在阅读器中点击虚拟项时也能跳转到相关页面。

2. 页码转换：

   • Document.get_toc()返回的页码是基于1的，与PDF阅读器中显示的页码一致。
   • Document.insert_pdf()方法中的from_page和to_page参数是基于0的索引。因此，在调用insert_pdf时，需要将基于1的页码减1。
   • 当为新的拆分PDF生成TOC时，原始TOC中的页码需要进行调整。如果原始PDF的start_orig_page是新PDF的第一页，那么原始页码page_num_orig在新PDF中的对应页码就是page_num_orig - (start_orig_page - 1)。

3. 错误处理与鲁棒性：

   • 在实际应用中，您可能需要添加更健壮的错误处理机制，例如检查输入文件是否存在、输出目录是否可写等。
   • 如果某个页面范围没有对应的TOC条目，chapter_toc_raw将为空，correct_toc_hierarchy会返回空列表，此时chapter_pdf.set_toc()不会被调用，确保不会设置一个空的TOC。

4. 性能考虑：

   • 对于非常大的PDF文件和大量的拆分范围，此方法通常是高效的，因为PyMuPDF底层是C语言实现的，性能优异。
   • 多次打开和关闭PDF文件可能会带来轻微的开销，但对于大多数用例来说是可以接受的。

总结

通过PyMuPDF，我们可以不仅实现PDF的页面拆分，还能精确地处理其内部的目录结构。理解PyMuPDF对TOC层级的严格要求，并结合correct_toc_hierarchy这样的辅助函数进行修正，是确保拆分后的文档在可用性上与原始文档保持一致的关键。这使得PyMuPDF成为处理复杂PDF操作，如电子书章节提取、报告分段等任务的强大工具。通过本文提供的代码示例和详细解释，读者可以轻松地将此功能集成到自己的Python项目中。

以上就是高效拆分PDF并精确保留目录结构（PyMuPDF教程）的详细内容，更多请关注知识资源分享宝库其它相关文章！