PDF转图片工具 (PDF2Image Tool)

一个功能强大的PDF批量转图片工具，支持灵活的配置选项、复杂的页数范围规则和自定义命名方案。

特性

• ✨ 批量转换多个PDF文件
• 📁 支持文件夹递归扫描
• 🎯 灵活的页数范围配置（支持复杂的多文件规则）
• 🎨 多种图片格式支持（PNG、JPG、TIFF、BMP等）
• 📦 可选ZIP压缩输出
• 🏷️ 自定义文件命名规则
• ⚙️ YAML配置文件 + CLI参数
• 🐍 使用Conda管理环境

环境要求

• Python 3.10+
• Conda（推荐使用Miniconda或Anaconda）
• Poppler（系统依赖）

安装Poppler

PDF转图片需要系统安装Poppler：

macOS:

brew install poppler

Ubuntu/Debian:

sudo apt-get install poppler-utils

Windows: 下载预编译版本：https://github.com/oschwartz10612/poppler-windows/releases/

安装

1. 创建Conda环境

# 克隆或下载项目
cd my-pdf2img

# 使用environment.yml创建环境
conda env create -f environment.yml

# 激活环境
conda activate pdf2img

2. 手动安装（可选）

如果不使用Conda，也可以用pip安装：

pip install -r requirements.txt

快速开始

1. 配置文件方式

编辑 config.yaml 文件：

output_format: png
output_quality: 95
input_path: ./input        # PDF文件或文件夹
output_dir: ./output       # 输出目录
zip_output: false          # 是否压缩为ZIP
page_ranges: all           # 页数范围
dpi: 200                   # 图片分辨率

运行：

python pdf2img.py --config config.yaml

2. 命令行方式

# 转换单个PDF
python pdf2img.py --input document.pdf --output ./images --format png

# 转换文件夹内所有PDF
python pdf2img.py --input ./pdfs --output ./images --format jpg --quality 90

# 只转换特定页面
python pdf2img.py --input file.pdf --output ./out --pages "1-3,5"

# 输出为ZIP压缩包
python pdf2img.py --input ./pdfs --output ./out --zip

配置详解

基本参数

参数	类型	默认值	说明
output_format	string	png	输出图片格式：png, jpg, jpeg, tiff, bmp
output_quality	int	95	图片质量（1-100），仅对jpg/jpeg有效
input_path	string	./input	输入PDF文件或文件夹路径
output_dir	string	./output	输出文件夹路径
zip_output	bool	false	是否将每个PDF的输出压缩为ZIP
dpi	int	200	输出图片DPI（50-600）

页数范围规则 (page_ranges)

支持多种灵活的页数范围配置：

单个PDF的规则

使用空格分隔不同的页数范围段：

page_ranges: "all"          # 所有页面
page_ranges: "odd"          # 所有奇数页（1, 3, 5, 7...）
page_ranges: "even"         # 所有偶数页（2, 4, 6, 8...）
page_ranges: "1-4"          # 第1到第4页
page_ranges: "3"            # 只转换第3页
page_ranges: "1-4 7-9 11"   # 第1-4页、第7-9页、第11页
page_ranges: "1 3 5 7"      # 第1、3、5、7页
page_ranges: "1-3 8-10"     # 第1-3页和第8-10页

多个PDF的复杂规则

使用逗号分隔为不同PDF指定不同规则：

# 示例1: 两个PDF分别指定不同的页数范围
page_ranges: "1-4 7-9,1-4 5"

• 第1个PDF: 转换第1-4页和第7-9页
• 第2个PDF: 转换第1-4页和第5页

# 示例2: 使用特殊规则标记
page_ranges: "1-4,all,-1,2,-2"

规则解释：

• 第1个PDF: 转换第1-4页
• 第2个PDF: 转换所有页（逗号间为空或"all"）
• 第3个PDF: -1 表示与上一个（第2个）相同，即所有页
• 第4个PDF: 只转换第2页
• 第5个及后续PDF: -2 表示后续都与上一个（第4个）相同，即第2页

示例场景：

假设有5个PDF文件，配置为 "1-4,,-1,2,-2":

PDF编号	规则	转换页面
PDF 1	1-4	第1-4页
PDF 2	（空）	所有页
PDF 3	-1	所有页（同上一个）
PDF 4	2	第2页
PDF 5	-2	第2页（启用重复模式）

更多示例：

# 3个PDF，各自指定不同的间隔页
page_ranges: "1-5 10-15,2 4 6 8,all"

• PDF 1: 第1-5页和第10-15页
• PDF 2: 第2、4、6、8页
• PDF 3: 所有页

# 使用奇数页/偶数页功能
page_ranges: "odd,even"

• PDF 1: 所有奇数页
• PDF 2: 所有偶数页

命名规则 (naming_rules)

自定义输出文件和图片的命名方式：

naming_rules:
  folder_prefix: "converted_"    # 文件夹/ZIP前缀
  folder_suffix: "_output"        # 文件夹/ZIP后缀
  image_prefix: "page_"           # 图片名前缀
  image_suffix: "_img"            # 图片名后缀

示例：

原PDF文件名：report.pdf

配置后的输出：

• 文件夹/ZIP名称：converted_report_output
• 图片文件名：page_report_img_1.png, page_report_img_2.png, ...

如果不设置前缀/后缀（留空），则使用原文件名。

CLI参数说明

所有配置都可以通过命令行参数覆盖：

python pdf2img.py [OPTIONS]

选项:
  -c, --config PATH          配置文件路径
  -i, --input PATH           输入PDF文件或文件夹路径
  -o, --output PATH          输出文件夹路径
  -f, --format [png|jpg|jpeg|tiff|bmp]
                             输出图片格式
  -q, --quality INTEGER      输出图片质量 (1-100)
  --dpi INTEGER              DPI设置 (50-600)
  --zip                      将每个PDF的输出压缩为ZIP文件
  --pages TEXT               页数范围规则
  --folder-prefix TEXT       输出文件夹/ZIP名称前缀
  --folder-suffix TEXT       输出文件夹/ZIP名称后缀
  --image-prefix TEXT        图片文件名前缀
  --image-suffix TEXT        图片文件名后缀
  --help                     显示帮助信息

使用示例

示例1：转换文件夹内所有PDF为高质量PNG

python pdf2img.py \
  --input ./documents \
  --output ./images \
  --format png \
  --dpi 300 \
  --quality 95

示例2：批量转换并压缩为ZIP

python pdf2img.py \
  --input ./reports \
  --output ./archives \
  --format jpg \
  --quality 85 \
  --zip

示例3：单页和间隔页输出

转换PDF的特定间隔页面：

# 转换第1-4页、第7-9页和第11页
python pdf2img.py \
  --input document.pdf \
  --output ./output \
  --pages "1-4 7-9 11"

# 只转换奇数页
python pdf2img.py \
  --input document.pdf \
  --output ./output \
  --pages "odd"

# 只转换偶数页
python pdf2img.py \
  --input document.pdf \
  --output ./output \
  --pages "even"

# 手动指定奇数页
python pdf2img.py \
  --input document.pdf \
  --output ./output \
  --pages "1 3 5 7 9 11 13 15"

示例4：多个PDF的复杂页数规则

假设有3个PDF需要不同的页数处理：

# 方式1: 使用空格分隔每个PDF内的不同页数范围
python pdf2img.py \
  --input ./pdfs \
  --output ./output \
  --pages "1-3 8-10,all,2 4 6"

• 第1个PDF：转换第1-3页和第8-10页
• 第2个PDF：转换所有页
• 第3个PDF：转换第2、4、6页

# 方式2: 使用奇数页/偶数页关键字
python pdf2img.py \
  --input ./pdfs \
  --output ./output \
  --pages "odd,even,all"

• 第1个PDF：转换所有奇数页
• 第2个PDF：转换所有偶数页
• 第3个PDF：转换所有页

# 方式3: 使用-1和-2标记
python pdf2img.py \
  --input ./pdfs \
  --output ./output \
  --pages "1-3,all,-1"

• 第1个PDF：转换第1-3页
• 第2个PDF：转换所有页
• 第3个PDF：转换所有页（-1表示重复上一个规则）

示例5：自定义命名规则

python pdf2img.py \
  --input ./contracts \
  --output ./processed \
  --folder-prefix "contract_" \
  --image-suffix "_scan" \
  --format png

输出示例：

• 文件夹：contract_agreement/
• 图片：agreement_scan_1.png, agreement_scan_2.png, ...

输出结构

普通模式（zip_output: false）

output/
├── document1/
│   ├── document1_1.png
│   ├── document1_2.png
│   └── document1_3.png
└── document2/
    ├── document2_1.png
    └── document2_2.png

ZIP模式（zip_output: true）

output/
├── document1.zip
│   ├── document1_1.png
│   ├── document1_2.png
│   └── document1_3.png
└── document2.zip
    ├── document2_1.png
    └── document2_2.png

故障排除

问题1：找不到Poppler

错误信息：

PDFInfoNotInstalledError: Unable to get page count. Is poppler installed and in PATH?

解决方法：

• 确保已安装Poppler（见"安装Poppler"部分）
• 用户需要将Poppler添加到PATH：

  export PATH="/usr/local/bin:$PATH"

问题2：内存不足

处理大型PDF或高DPI时可能出现内存问题。

解决方法：

• 降低DPI值（如从300降到200）
• 使用页数范围规则，分批处理
• 处理单个文件而不是整个文件夹

问题3：输出图片质量不佳

解决方法：

• 提高DPI值（建议：屏幕显示150-200，打印300-600）
• 对于JPG格式，提高quality参数
• 改用PNG格式（无损压缩）

性能提示

• DPI设置：DPI越高，质量越好但文件越大、转换越慢

  • 屏幕浏览：150-200 DPI
  • 一般打印：200-300 DPI
  • 高质量打印：300-600 DPI

• 格式选择：

  • PNG：无损压缩，文件较大，适合文字和图表
  • JPG：有损压缩，文件较小，适合照片和复杂图像

• 批量处理：文件夹模式会自动递归查找所有PDF文件