图像转 PDF

使用 scripts/images_to_pdf.py 进行确定性转换。该脚本可同时接受文件与目录输入，自动应用 EXIF 方向信息、展平透明度，并为每张图像生成独立的 PDF 页面。

工作流程

1. 解析用户指定的输入项与输出路径。不得修改源图像文件。
2. 严格保留用户显式指定的文件/目录顺序；在每个目录内部，按脚本默认的自然文件名排序规则处理（例如 2.jpg 排在 10.jpg 之前）。
3. 选择页面处理方式：
   • 默认使用 --page-size auto，为每张图像分配与其原始尺寸完全匹配的 PDF 页面。
   • 仅当用户明确要求统一纸张尺寸或输出用于打印时，才使用 --page-size a4、letter 或 legal。
   • 对于固定纸张尺寸的页面，默认使用 --fit contain；仅当可接受边缘裁剪时使用 fill；仅当明确需要拉伸变形时使用 stretch。
4. 若环境提供已打包的 Codex Python 运行时，则优先调用该运行时执行转换；否则回退至系统默认 python 命令。
5. 使用 pypdf 对结果进行校验（验证页数及 MediaBox 可读性）。为获得视觉层面的信心，应使用 Poppler 渲染若干代表性页面并人工检查——尤其在使用固定纸张尺寸、页边距、透明度或 fill 模式时。
6. 返回最终生成的 PDF 路径，并明确说明其总页数。

命令示例

转换单张图像：

python scripts/images_to_pdf.py "C:pathscan.png" -o "C:pathscan.pdf"

按指定顺序合并多个显式列出的文件：

python scripts/images_to_pdf.py "cover.png" "page2.jpg" "page3.webp" -o "book.pdf"

按自然文件名顺序合并整个目录：

python scripts/images_to_pdf.py "C:pathimages" -o "C:pathimages.pdf"

创建带 10 mm 页边距的统一 A4 尺寸页面：

python scripts/images_to_pdf.py "C:pathimages" -o "C:pathprint.pdf" --page-size a4 --margin-mm 10

使用 --recursive 包含嵌套子目录，使用 --overwrite 覆盖已存在的输出文件，使用 --background white（或其他 Pillow 支持的颜色值）在展平透明图像时指定背景色，使用 --dpi 控制物理尺寸与光栅分辨率。运行 python scripts/images_to_pdf.py --help 查看全部选项。

依赖项回退机制

该脚本依赖 Pillow 库。若未安装，请在当前环境中执行 python -m pip install Pillow 安装。校验阶段使用 pypdf；渲染阶段在可用时调用 Poppler 工具集中的 pdftoppm。

安全性与质量保障

• 拒绝空输入集，或输出路径与任一输入图像路径发生别名冲突的情形。
• 禁止静默覆盖已有 PDF 文件；仅当用户明确意图替换时，方可添加 --overwrite 参数。
• 对于含边缘文字的文档，避免使用 fill 模式（因其会导致裁剪）。
• 除非用户另行指定，否则对截图及含透明通道的 PNG 图像优先采用浅色背景。