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：整个TOC列表的第一个目录项的层级（level）必须是1。
-
层级递增或递减：
- 后续目录项的层级可以与前一个目录项的层级相等。
- 后续目录项的层级可以比前一个目录项的层级恰好高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拆分，我们需要执行以下步骤：
- 打开原始PDF文档并获取其完整的TOC。
- 根据用户定义的页面范围，从原始PDF中提取相应的页面，并创建新的PDF文档。
- 从原始TOC中筛选出与当前页面范围相关的目录项。
- 调整筛选出的目录项的页码，使其相对于新创建的PDF文档（即，新PDF的第一页对应原始PDF的起始页）。
- 核心步骤： 修正筛选并调整后的TOC，使其符合PyMuPDF的层级规则。这通常涉及在必要时插入“虚拟”目录项以填充层级空缺，并确保TOC以层级1开始。
- 将修正后的TOC设置到新的PDF文档中。
- 保存新的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)代码解析与注意事项
-
correct_toc_hierarchy(toc_list) 函数：
- 这个函数是整个解决方案的核心，它负责确保生成的TOC符合PyMuPDF的严格层级要求。
- 它首先处理TOC的第一个条目，如果其层级不为1，则会插入必要的虚拟层级（例如，如果第一个实际条目是层级3，它会插入一个层级1和一个层级2的虚拟条目）。
- 接着，它遍历TOC的其余部分，检查是否存在层级跳跃（例如，从层级1直接跳到层级3）。如果发现这种跳跃，它会在中间插入虚拟的目录项，以保持层级递增不超过1的规则。
- 虚拟目录项的标题可以根据需要自定义，这里使用了"Dummy Level {level}"。
- 虚拟目录项的页码通常设置为其后紧邻的实际目录项的页码，这样在阅读器中点击虚拟项时也能跳转到相关页面。
-
页码转换：
- 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)。
-
错误处理与鲁棒性：
- 在实际应用中，您可能需要添加更健壮的错误处理机制，例如检查输入文件是否存在、输出目录是否可写等。
- 如果某个页面范围没有对应的TOC条目，chapter_toc_raw将为空，correct_toc_hierarchy会返回空列表，此时chapter_pdf.set_toc()不会被调用，确保不会设置一个空的TOC。
-
性能考虑：
- 对于非常大的PDF文件和大量的拆分范围，此方法通常是高效的，因为PyMuPDF底层是C语言实现的，性能优异。
- 多次打开和关闭PDF文件可能会带来轻微的开销，但对于大多数用例来说是可以接受的。
总结
通过PyMuPDF，我们可以不仅实现PDF的页面拆分，还能精确地处理其内部的目录结构。理解PyMuPDF对TOC层级的严格要求，并结合correct_toc_hierarchy这样的辅助函数进行修正，是确保拆分后的文档在可用性上与原始文档保持一致的关键。这使得PyMuPDF成为处理复杂PDF操作，如电子书章节提取、报告分段等任务的强大工具。通过本文提供的代码示例和详细解释，读者可以轻松地将此功能集成到自己的Python项目中。
