使用 mutool pages 查看 PDF 页面框Box与旋转信息的完整指南【免费下载链接】sumatrapdfSumatraPDF reader项目地址: https://gitcode.com/gh_mirrors/su/sumatrapdf本篇技术指南以 MuPDF 官方文档 mutool-pages.rst 为骨架结合仓库内 pdfpages.c 的完整实现讲解mutool pages命令的语法、参数与输出格式。读完本文你将能熟练列出 PDF 每一页的 MediaBox、CropBox、Rotate、UserUnit 等页面级属性并理解底层如何解析页码范围与输出 XML 结构化结果。该命令对应的源代码作为 MuPDF 子树内嵌于本项目SumatraPDF中mutool系列工具可在 SumatraPDF 的构建环境中直接编译使用。命令概述mutool pages是 MuPDF 工具族中负责逐页罗列页面属性的信息类命令。它会针对输入 PDF 的每一页输出一个结构化的信息块其中包含MediaBox页面物理介质尺寸纸张大小CropBox裁剪后实际显示的页面区域ArtBox / BleedBox / TrimBox印刷与出血相关页面框Rotate页面顺时针旋转角度0 / 90 / 180 / 270UserUnit用户单位缩放系数PDF 1.6 特性从 mutool.c 的命令表可以看出该命令的注册描述为show information about PDF pages入口函数为pdfpages_main其文件头部注释也将其定位为 Information tool。语法与参数详解官方文档给出的命令语法为mutool pages [options] input.pdf [pages]在源码 pdfpages.c 中infousage()打印的用法与之对应并额外提示了-p选项的完整形式Usage: SumatraPDF pages [options] file.pdf [pages] -p - password for decryption pages comma separated list of page numbers and ranges说明SumatraPDF 将 MuPDF 内置工具重命名为自身可执行文件名的输出此处为源码中原样保留的字符串。-p password指定解密密码。当输入 PDF 被加密pdf_needs_password返回真时命令会调用pdf_authenticate_password校验密码认证失败会抛出cannot authenticate password: file错误并终止处理。相关逻辑见 pdfpages.c。该选项通过fz_getopt(argc, argv, p:)解析pdfpages.cp:中的冒号表示该选项需要一个参数值。input.pdf输入文件名必须是 PDF 文件。命令通过pdf_open_document打开文档pdfpages.c。每个输入文件在被处理前都会先单独输出一行以该文件名开头的标题形如input.pdf:。[pages]可选的页码列表参数格式为逗号分隔的页码与页码范围。如果省略该参数则默认处理文档的全部页面源码中以1-N作为缺省页码范围传入showpages见 [pdfpages.c](https://link.gitcode.com/i/d445c127f93a019f713fa8ea4b257e0e#L177 与 L201)。页码范围的完整解析逻辑位于 fitz/string.c 的fz_parse_page_range支持以下语法语法含义示例N单个页码5a-b闭区间页码范围3-7a-N从第 a 页到最后一页4-NN负数从文档末尾倒数计数-1表示最后一页a, b, c-d逗号分隔的多个页与区间1,3,5-7fz_parse_page_range的实现细节值得注意string.c用strtol解析数字支持N通配符表示总页数负数页码会被转换为n 1 负值即从末尾倒数解析结果通过fz_clampi限制在[1, 总页数]范围内越界页码自动被钳制若语法非法无法推进解析位置会打印skipping invalid page range警告并跳过。在showpagespdfpages.c中若某个范围起始页大于结束页如7-3还会自动交换起止值后再逐页输出。而 string.c 的fz_is_page_range则负责判断命令行参数是否为合法的页码范围表达式只允许数字、N、-、,。输出格式结构化的页面属性 XMLmutool pages的输出是机器可读的 XML 风格结构而非纯文本表格。根据 pdfpages.c 中showpage的实现每个页面的输出形如page pagenum1 MediaBox l0 b0 r612 t792 / CropBox l0 b0 r612 t792 / ArtBox l0 b0 r612 t792 / BleedBox l0 b0 r612 t792 / TrimBox l0 b0 r612 t792 / Rotate v0 / UserUnit v1 / /page各字段说明page pagenumN页面序号从 1 开始即文档中的物理页号五个 Box 元素MediaBox、CropBox、ArtBox、BleedBox、TrimBox输出l/b/r/t四个属性分别对应左下角 X、左下角 Y、右上角 X、右上角 Y 坐标。它们通过 showbox 从页面字典中读取对应键值PDF_NAME(MediaBox)等并调用pdf_to_rect转为矩形后格式化输出Rotate v...页面旋转角度由 shownum 读取页面字典的Rotate键输出UserUnit v...PDF 1.6 引入的用户单位缩放因子同样由shownum输出。需要指出的是这些字段只有当页面字典中存在对应条目时才会输出。例如ArtBox、BleedBox、TrimBox通常仅出现在印刷用途的 PDF 中若条目缺失或类型不符pdf_is_array/pdf_is_number检查失败该字段会被跳过而不输出。实际运行示例查看整份文档的所有页面mutool pages report.pdf输出report.pdf: page pagenum1 MediaBox l0 b0 r612 t792 / CropBox l0 b0 r612 t792 / Rotate v0 / UserUnit v1 / /page page pagenum2 ... /page注意文件名标题行只出现一次随后是所有页面的信息块。只查看指定页# 查看第 1、3 以及第 5 到第 7 页 mutool pages report.pdf 1,3,5-7 # 查看倒数第 2 页到最后一页 mutool pages report.pdf -2-N # 查看第 10 页到文档末尾 mutool pages report.pdf 10-N处理加密 PDFmutool pages -p mysecret encrypted.pdf一次处理多个文件从源码结构看pdfpages_pages的参数循环pdfpages.c支持在一次调用中传入多个 PDF 文件每遇到一个非页码范围的参数即视为新输入文件并输出其文件名标题因此可以直接写出mutool pages a.pdf b.pdf输出会先罗列a.pdf:下所有页面再罗列b.pdf:下所有页面。底层实现与执行流程从源码可以梳理出mutool pages的完整调用链入口pdfpages_mainpdfpages.c解析-p选项初始化fz_context随后进入pdfpages_pages参数调度pdfpages_pages逐个检查参数——通过fz_is_page_range判断是输入文件还是页码范围若是文件则打开文档必要时认证密码若是页码范围则交给showpages页码展开showpages用fz_parse_page_range循环解析页码范围并对每个页码调用showpage单页输出showpage通过pdf_lookup_page_obj获取页面对象然后依次调用showbox五类 Box与shownumRotate、UserUnit错误处理任何一步失败如页面对象无法获取、字段类型不符都会在输出中记录失败标志并继续处理后续页面最终pdfpages_main以非零返回值表示整体失败。执行入口注册于 mutool.c{ pdfpages_main, pages, show information about PDF pages }因此可通过mutool pages ...直接调用也可通过mutool裸命令查看全部工具列表。与相关命令的定位区分在 MuPDF 工具族中mutool pages与 mutool info 容易混淆二者定位不同mutool pages聚焦页面几何属性各种 Box、旋转、UserUnit输出结构化 XMLmutool info聚焦页面资源对象字体-F、图片-I、尺寸-M、图案-P、着色-S、XObject-X、ZUGFeRD 信息-Z等。日常排查页面显示尺寸不对导出后方向颠倒印刷出血框缺失等问题时mutool pages是最直接的诊断工具而mutool info更适合排查页面上的资源引用。使用建议机器处理由于输出为 XML 风格结构可直接用脚本解析pagenum、l/b/r/t与v属性批量生成页面尺寸报告印刷校验检查 PDF 是否符合印刷规范时重点核对TrimBox/BleedBox/ArtBox是否存在且数值合理阅读器兼容性排查当 PDF 在阅读器中显示异常时先确认Rotate与CropBox的组合是否符合预期页码语法善用N通配符与负数页码避免手动计算总页数。该命令的完整实现源码位于 ext/mupdf/source/tools/pdfpages.c页码解析通用工具位于 ext/mupdf/source/fitz/string.c工具注册表位于 ext/mupdf/source/tools/mutool.c读者可继续深入研读。【免费下载链接】sumatrapdfSumatraPDF reader项目地址: https://gitcode.com/gh_mirrors/su/sumatrapdf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考