Python自动化实现PDF文档灰度转换_Python

在文档处理的日常工作中，将彩色 pdf 转换为灰度是一个非常实用的需求。无论是为了降低打印成本、压缩文件体积、统一归档标准，还是为了去除色彩干扰以专注内容本身，灰度转换都能提供有效的解决方案。本文将介绍如何使用 python 结合免费 pdf 处理库，快速、可靠地完成 pdf 灰度转换。

一、需求背景与应用场景

pdf 灰度转换的典型应用场景包括：

黑白打印：灰度输出可以避免彩色打印成本，同时保证文字与图形的清晰可读
文档归档：档案系统通常要求统一的灰度格式，便于长期存储与检索
体积优化：移除色彩通道信息后，文件体积通常会有明显下降
批量预处理：在 ocr、文档分析等流水线中，灰度化是常见的前置步骤

二、技术方案选型

python 生态中实现 pdf 灰度化主要有以下几类思路：

渲染后再合成：将 pdf 逐页渲染为位图，转灰度后重新合成 pdf。优点是通用性强，缺点是矢量信息会丢失、文件体积可能变大
调用外部工具：通过 subprocess 调用 ghostscript 等命令行工具。优点是成熟稳定，缺点是依赖外部环境、部署不便
原生 pdf 处理库：直接在 pdf 文档层面修改色彩空间，保留矢量信息。优点是质量高、体积控制好，缺点是可选库相对较少

本文采用第三种思路，使用 free spire.pdf for python 免费库来实现。该库提供了专门的灰度转换 api，能够在保留文档矢量结构的前提下完成色彩空间转换，无需依赖 adobe acrobat 或其他外部组件。

三、环境准备

安装依赖

通过 pip 安装免费版本：

pip install spire.pdf.free

版本说明

免费版支持单文档最多 10 页的处理，对于个人学习、小规模脚本和日常办公场景基本够用。

安装完成后，即可在脚本中导入相关模块：

from spire.pdf.common import *
from spire.pdf import *

四、核心实现：单文件灰度转换

基本用法

灰度转换的核心类是 pdfgrayconverter，它专门负责将输入 pdf 转换为灰度模式并输出新文件。

from spire.pdf.common import *
from spire.pdf import *

def pdf_to_grayscale(input_path: str, output_path: str) -> none:
    """将彩色pdf转换为灰度pdf"""
    # 创建灰度转换器实例，加载源文件
    converter = pdfgrayconverter(input_path)
    # 执行转换并保存到输出路径
    converter.tograypdf(output_path)

if __name__ == "__main__":
    pdf_to_grayscale("sample.pdf", "sample_grayscale.pdf")
    print("转换完成")

这段代码只有寥寥数行，实际完成的工作包括：

解析 pdf 文档结构，识别页面中的文本、矢量图形和位图图像
将所有色彩元素从 rgb/cmyk 色彩空间映射到灰度空间
保留矢量文字与图形的可缩放特性，不会栅格化
重新编码输出，保持原始页面尺寸和排版布局

代码说明

pdfgrayconverter 在构造时即加载源文档，调用 tograypdf() 后直接写入目标文件。整个过程不需要手动创建 pdfdocument 对象，也不需要逐页遍历，api 设计上做了封装。

需要注意的是，该方法会生成一个新的 pdf 文件，不会修改源文件，符合不可变操作的最佳实践。

五、进阶：批量转换目录下的 pdf

在实际工作中，我们经常需要批量处理一整个文件夹的文档。下面给出一个可直接使用的批量转换脚本：

import os
from spire.pdf.common import *
from spire.pdf import *

def batch_convert_to_grayscale(input_dir: str, output_dir: str) -> none:
    """批量将目录下所有pdf转换为灰度"""
    # 创建输出目录
    os.makedirs(output_dir, exist_ok=true)
    
    # 遍历目录下的pdf文件
    for filename in os.listdir(input_dir):
        if filename.lower().endswith(".pdf"):
            input_path = os.path.join(input_dir, filename)
            output_path = os.path.join(output_dir, f"gray_{filename}")
            
            try:
                converter = pdfgrayconverter(input_path)
                converter.tograypdf(output_path)
                print(f"[ok] {filename}")
            except exception as e:
                print(f"[fail] {filename}: {str(e)}")

if __name__ == "__main__":
    batch_convert_to_grayscale("./input_pdfs", "./output_pdfs")

建议在生产环境中加入异常捕获和日志记录，避免单个文件失败导致整个批处理中断。

六、注意事项与边界情况

1. 加密 pdf

如果源 pdf 设置了打开密码或权限密码，需要先解密才能进行灰度转换。可以先通过 pdfdocument 加载时传入密码，再保存为未加密版本后再处理。

2. 透明与渐变效果

含有复杂透明度混合、渐变填充的 pdf，灰度转换后视觉效果可能与预期略有差异。这是因为渐变的色彩阶映射到灰度后，对比度会发生变化，属于正常现象。

3. 文件体积变化

大多数情况下灰度 pdf 会比彩色版更小，尤其是包含大量彩色图片的文档。但对于纯文本 pdf，体积变化可能不明显，甚至因为内部结构重排而略有浮动。

4. 免费版页数限制

free 版本单文档最多处理前 10 页。如果超过限制，超出部分不会被转换。对于页数较多的文档，可以考虑拆分后分批处理，或使用完整授权版本。

七、知识扩展

在 python 中实现 pdf 的灰度转换，最理想的方式是直接修改 pdf 的颜色空间，在保留文本、矢量图形等可编辑性的同时去除彩色信息。目前最成熟的做法有两种：

调用 ghostscript 命令行工具（推荐）
将 pdf 逐页渲染为灰度图像再重新合成（会丢失文本层）

下面分别给出实现方案。

准备工作：安装依赖

方案一（ghostscript）：需要系统安装 ghostscript，并在 python 中通过 subprocess 调用。
方案二（图像转换）：需要安装 pymupdf（fitz）、pillow 和 img2pdf，可通过 pip 安装。

pip install pymupdf pillow img2pdf

方案一：使用 ghostscript 直接转换 pdf 颜色空间（推荐）

ghostscript 的 pdfwrite 设备支持 -scolorconversionstrategy=gray 参数，能高效地将 pdf 中所有彩色元素转为灰度，保留文本结构和可搜索性。

import subprocess
import os
def convert_pdf_to_grayscale_gs(input_pdf, output_pdf, gs_path='gswin64c'):  # windows 下用 gswin64c，linux/macos 用 gs
    """
    使用 ghostscript 将 pdf 转为灰度（保留文本）
    """
    if not os.path.exists(input_pdf):
        raise filenotfounderror(f"输入文件不存在: {input_pdf}")
    # 构建命令
    cmd = [
        gs_path,
        '-sdevice=pdfwrite',
        '-scolorconversionstrategy=gray',
        '-dprocesscolormodel=/devicegray',
        '-dcompatibilitylevel=1.4',
        '-dnopause',
        '-dquiet',
        '-dbatch',
        f'-soutputfile={output_pdf}',
        input_pdf
    ]
    try:
        subprocess.run(cmd, check=true, capture_output=true)
        print(f"✅ 灰度转换完成: {output_pdf}")
    except subprocess.calledprocesserror as e:
        print(f"❌ ghostscript 错误: {e.stderr.decode()}")
        raise
# 使用示例
convert_pdf_to_grayscale_gs('彩色文档.pdf', '灰度文档.pdf')

参数解释：

-scolorconversionstrategy=gray：强制颜色转换策略为灰度。
-dprocesscolormodel=/devicegray：设置目标颜色模型为设备灰度。
-dcompatibilitylevel=1.4：保证兼容性。

优点：速度快、文件体积变化小、保留文本和超链接。

缺点：需要外部安装 ghostscript。

方案二：使用 pymupdf + pillow 逐页转灰度图像并合成 pdf（备选）

如果无法安装 ghostscript，可以先将 pdf 每一页渲染为灰度图像，再将图像合成为新 pdf。此方法会丢失文本层，输出为纯图像 pdf，不可搜索。

import fitz  # pymupdf
from pil import image
import img2pdf
import io
import os
def convert_pdf_to_grayscale_image(input_pdf, output_pdf, dpi=150):
    """
    将 pdf 每一页渲染为灰度图像，再合成 pdf（文本丢失）
    """
    doc = fitz.open(input_pdf)
    image_list = []
    for page_num in range(len(doc)):
        page = doc[page_num]
        # 渲染为像素图（颜色空间设为灰度）
        pix = page.get_pixmap(colorspace=fitz.csgray, dpi=dpi)
        # 转换为 pil image
        img = image.frombytes("l", [pix.width, pix.height], pix.samples)
        image_list.append(img)
    doc.close()
    # 将图像列表转为 pdf
    with open(output_pdf, "wb") as f:
        # 使用 img2pdf 将图像转换为 pdf
        f.write(img2pdf.convert([img.tobytes() for img in image_list],
                                layout_fun=img2pdf.get_layout_fun((img.width, img.height))))
    print(f"✅ 图像化灰度转换完成: {output_pdf}")
# 使用示例
convert_pdf_to_grayscale_image('彩色文档.pdf', '灰度图像文档.pdf', dpi=150)

优点：不依赖 ghostscript。

缺点：输出 pdf 为图像，体积大、不可搜索、文字可能模糊。

适用场景：仅用于预览或打印，不要求保留文本。