Pillow 图像格式插件体系完全参考:从 44 个格式插件的源码解读到实战配置

原创2026-09-22 16:29:522,263 阅读
文章标签:图像处理库

Pillow 图像格式插件体系完全参考:从 44 个格式插件的源码解读到实战配置

本文以 docs/reference/plugins.rst 为骨架,系统梳理 Python Imaging Library (Pillow) 的图像格式插件(Image Plugin)注册机制与全部内置格式模块。你将掌握 Pillow 的插件注册 API、懒加载初始化流程、Image.open 的格式探测原理,以及 AVIF、BMP、GIF、JPEG、PNG、TIFF、WebP 等 44 个格式插件的职责划分与典型用法,并能据此判断在何种场景下该选用哪个插件模块。

一、插件参考文档的性质:Pillow 格式扩展的地图

docs/reference/plugins.rst 是 Pillow 文档站中针对"格式插件"这一层级的自动生成式 API 参考页。它本身不包含长篇教程,而是通过 Sphinx 的 automodule 指令,把 src/PIL 目录下 44 个 *ImagePlugin.py 模块的公开成员(类、函数、常量)逐一生成为可检索的 API 文档,并支持 :members:、:undoc-members:、:show-inheritance: 等选项展示继承关系与未文档化成员。

这份文档的价值在于:它精确刻画了 Pillow 的架构分层——核心库(Image、ImageFile、ImageDraw 等)与格式扩展(*ImagePlugin)之间通过"插件注册表"解耦。读懂这份参考,等于拿到了一张 Pillow 全部内置格式能力的地图:哪些格式可以打开、哪些可以保存、哪些只是"Stub 占位插件"。

值得注意的是,文档对 PNG 插件 使用了显式成员白名单:

:members: ChunkStream, PngImageFile, PngStream, getchunks, is_cid, putchunk,
    Blend, Disposal, MAX_TEXT_CHUNK, MAX_TEXT_MEMORY
:member-order: groupwise

这意味着 PNG 插件是整个体系中最复杂、最值得单独研读的模块——它既有流式块解析器(ChunkStream、PngStream)、帧混合枚举(Blend、Disposal),又有面向 APNG 动画与文本块(iTXt/zTXt)的安全常量(MAX_TEXT_CHUNK、MAX_TEXT_MEMORY)。

二、插件注册机制:一切格式能力的源头

所有格式插件的接入点都在 src/PIL/Image.py 的"Plugin registry"区块。Pillow 维护了 ID、OPEN、SAVE、SAVE_ALL、MIME、EXTENSION、DECODERS、ENCODERS 等多张注册表,并提供以下注册函数(这些函数在官方文档中被明确标注"不应在应用代码中直接调用",它们是供插件模块自身在导入时调用的基础设施):

函数 作用 写入的注册表
register_open(id, factory, accept=None) 注册一个图像打开工厂,accept 是用于快速拒识其他格式的可选谓词(返回 True/False 或警告字符串) ID、OPEN
register_mime(id, mimetype) 将格式标识符映射到 MIME 类型,供 Image.MIME 查询 MIME
register_save(id, driver) 注册单帧保存函数 SAVE
register_save_all(id, driver) 注册多帧格式的"保存全部帧"函数(GIF/APNG/TIFF 等多帧格式使用) SAVE_ALL
register_extension(id, extension) / register_extensions(id, extensions) 把扩展名映射到格式标识符,驱动 Image.open 的按扩展名导入优化 EXTENSION
register_decoder(name, decoder) / register_encoder(name, encoder) 注册 Python 侧编解码器(ImageFile.PyDecoder / PyEncoder),自 4.1.0 版本引入 DECODERS、ENCODERS

所有 id 都会被统一转为大写。以 GifImagePlugin.py 的注册收尾为例,一个完整插件模块的注册代码通常长这样:

Image.register_open(GifImageFile.format, GifImageFile, _accept)
Image.register_save(GifImageFile.format, _save)
Image.register_save_all(GifImageFile.format, _save_all)
Image.register_extension(GifImageFile.format, ".gif")
Image.register_mime(GifImageFile.format, "image/gif")

可以看到:GIF 是"打开 + 单帧保存 + 多帧保存 + 扩展名 + MIME"五项齐全的完整插件;而像 MpegImagePlugin 这类只读格式则只注册打开与扩展名,不注册任何保存函数。

三、懒加载初始化:preinit 与 init 的两级策略

插件模块不会被 Pillow 启动时全部导入,而是采用两级懒加载,这是 plugins.rst 所描述能力能保持轻量的关键设计,实现在 src/PIL/Image.py:

  1. preinit():只导入最常用的五个格式插件——BMP、GIF、JPEG、PPM、PNG。它在打开或保存图像时被调用,保证常见格式的极速可用。
  2. init():通过 _plugins 列表(由 src/PIL/__init__.py 维护)遍历导入全部 *ImagePlugin 模块。由于每个插件模块导入时会自动调用自己的 register_*,因此 init() 之后注册表即被填满。

Image.open 在 src/PIL/Image.py 中实际执行了这样的调度逻辑:

prefix = fp.read(16)                     # 读取 16 字节文件头
ext = os.path.splitext(filename)[1] if filename else ""
if not _import_plugin_for_extension(ext):  # 先按扩展名只导入对应插件
    preinit()                             # 兜底加载五个常见插件

随后 _open_core 按 formats 顺序遍历注册表:先调用插件的 accept(prefix) 快速嗅探文件头魔数,命中后 fp.seek(0) 并调用工厂构造 ImageFile.ImageFile 实例,再做 _decompression_bomb_check(im.size) 解压炸弹防护。若 accept 返回字符串,则该字符串作为警告消息被收集(用于 WARN_POSSIBLE_FORMATS 诊断模式)。

formats 参数允许调用方显式限定尝试的格式集合;不传则默认使用全部 ID。查看当前环境实际可用的格式列表,可运行 python3 -m PIL,或调用 features.pilinfo() 打印详细报告。

四、44 个格式插件全景清单

按 plugins.rst 的编排顺序,Pillow 内置插件可分为以下五类(模块均位于 src/PIL 目录):

4.1 核心位图与光栅格式

插件模块 格式说明 典型扩展名
BmpImagePlugin Windows 位图 BMP,兼容 DIB .bmp、.dib
DdsImagePlugin DirectDraw Surface,含 BC1–BC7 等压缩块格式 .dds
PcxImagePlugin ZSoft PC Paintbrush .pcx
PpmImagePlugin PBM/PGM/PPM(含 ASCII 与二进制变体) .pbm、.pgm、.ppm
PngImagePlugin 便携网络图形 PNG 及 APNG 动画,见下文专题 .png、.apng
TgaImagePlugin Truevision TGA .tga
TiffImagePlugin TIFF/TIFF 多页,与 libtiff 深度集成 .tif、.tiff
WebPImagePlugin Google WebP(含有损/无损/动画/元数据) .webp
AvifImagePlugin AVIF(基于 libavif),支持 HDR 与深色模式 .avif、.avifs
JpegImagePlugin 经典 JPEG,支持 EXIF、ICC、量化表、渐进式 .jpg、.jpeg、.jpe
Jpeg2KImagePlugin JPEG 2000,依赖 OpenJPEG .j2k、.jp2、.jpx、.j2c
XbmImagePlugin / XpmImagePlugin X BitMap / X PixMap .xbm、.xpm

4.2 动画与多帧格式

插件模块 格式说明 典型扩展名
GifImagePlugin GIF,支持帧动画、调色板、透明与循环控制 .gif
FliImagePlugin Autodesk FLI/FLC 动画 .fli、.flc
MngImagePlugin(在文档中由 PngImagePlugin 承担) 见 PNG 插件对 APNG 的 Blend/Disposal 支持 —
MpoImagePlugin 多画面对象(多镜头相机输出,基于 JPEG) .mpo
MpegImagePlugin MPEG 视频首帧提取(只读) .mpg、.mpeg

4.3 Stub 占位插件:容器格式的门卫

BufrStubImagePlugin、GribStubImagePlugin、Hdf5StubImagePlugin 属于特殊的 Stub 插件:它们本身不解析图像数据,而是识别容器格式的文件头(BUFR 气象数据、GRIB 气象网格、HDF5 科学数据),把文件"占位"包装成 ImageFile 并延迟到真正需要时再交给外部解析。其行为由 ImageFile.py 中的 StubImageFile 基类定义。它们与 CurImagePlugin(Windows 光标)、IcoImagePlugin(Windows 图标,读取多尺寸帧)、IcnsImagePlugin(Apple 图标集)一起构成了"系统资源类格式"家族。

4.4 科学与专用数据格式

插件模块 格式说明 典型扩展名
FitsImagePlugin 天文学 FITS 图像 .fits
FpxImagePlugin FlashPix(依赖 _imaging 与 IOCA 解码) .fpx
McIdasImagePlugin McIDAS 卫星图像 .mcidas、.ara
MicImagePlugin Microsoft Image Composer .mic
PalmImagePlugin Palm OS 位图 .palm
PcdImagePlugin Kodak PhotoCD(仅基础读取) .pcd
PixarImagePlugin Pixar 工作站格式 .pxr
SgiImagePlugin Silicon Graphics RGB .sgi、.rgb
SpiderImagePlugin SPIDER 科学图像(附带 SpiderImagePlugin 系列辅助函数) .spider
SunImagePlugin Sun Rasterfile .ras
ImImagePlugin IFUNC Image 内部格式(伴随 Image.py 的历史格式) .im
ImtImagePlugin IM Tools 内部格式 .imt
MspImagePlugin Microsoft Paint(老式 MSP) .msp

4.5 矢量、页面描述与其他

插件模块 格式说明 典型扩展名
EpsImagePlugin Encapsulated PostScript,通过 Ghostscript 栅格化 .eps
PdfImagePlugin PDF 页面栅格化(经 Ghostscript 或 pdf2image) .pdf
PsdImagePlugin Adobe Photoshop PSD(含图层与合并图像读取) .psd
WmfImagePlugin Windows 图元文件,仅提取元信息供外部渲染 .wmf、.emf
DcxImagePlugin DCX 多页 PCX 容器 .dcx
GbrImagePlugin GIMP brush 文件 .gbr
IptcImagePlugin IPTC/NAA 头信息(常嵌入 JPEG) 嵌入场景使用
XVThumbImagePlugin XV 缩略图格式 .xv

说明:仓库 src/PIL 中还包含 BlpImagePlugin、FtexImagePlugin、GdImageFile、QoiImagePlugin、WalImageFile 等模块,但它们未出现在 plugins.rst 的参考列表中,本文从略,仅提示读者留意。

五、PNG 插件专题:plugins.rst 中唯一显式列成员的模块

文档对 PNG 插件单独指定了成员清单,这背后是 PngImagePlugin.py 中值得深入的三组设计:

5.1 魔数与模式映射表

_MAGIC = b"\211PNG\r\n\032\n"

_accept 正是据此嗅探。而 _MODES 表(PngImagePlugin.py)把 PNG 的"位深 × 颜色类型"组合映射到 Pillow 模式与 rawmode,例如 (16, 0) 灰度 16 位映射到 ("I;16", "I;16B")、(8, 6) 真彩带透明映射到 ("RGBA", "RGBA")。这份表决定了 PNG 解码后你会拿到什么模式的图像对象。

5.2 文本块的解压炸弹防护

MAX_TEXT_CHUNK = ImageFile.SAFEBLOCK          # 单个 iTXt/zTXt 块最大解压尺寸
MAX_TEXT_MEMORY = 64 * MAX_TEXT_CHUNK         # 全部文本块累计上限

这是针对"压缩文本块可膨胀 1000 倍"的拒绝服务攻击的防御常量:MAX_TEXT_CHUNK 限制单个块,MAX_TEXT_MEMORY 限制总和。API 文档把二者显式暴露,正是为了让高级用户能在必要时调整阈值。

5.3 APNG 动画与块级工具

Blend、Disposal 两个枚举定义了 APNG 帧的混合与清除策略;ChunkStream/PngStream 实现面向流的块读取;getchunks/putchunk 提供块级读写工具,is_cid 是块类型标识符的正则谓词。配合 Tests/test_file_apng.py 与 Tests/test_file_png.py 中的用例,可以完整还原 APNG 帧序列的处理路径。

六、插件与 Image 核心的协作流程

一个典型的打开操作,其完整调用链为:

  1. Image.open(fp) 读取 16 字节前缀;
  2. 按扩展名调用 _import_plugin_for_extension,命中则只导入该插件;
  3. 否则 preinit() 加载五个常见插件;若 formats 中还有未注册格式,_open_core 内会触发 init() 全量导入;
  4. 依次调用各插件 accept(prefix) 嗅探,命中后构造 ImageFile 子类并执行解压炸弹检查;
  5. 真正的像素解码被推迟到 .load()(懒加载),对应 ImageFile.py 中的 PyDecoder/PyEncoder 编解码工厂与 core 层的 C 实现(见 src/libImaging 目录下的 decode.c、encode.c)。

这一流程解释了为何 plugins.rst 中所有模块都以 ImagePlugin 命名:它们通过统一的 register_* 协议与 Image 核心交互,用户侧几乎不需要直接 import 任何插件模块——Image.open 自动完成格式识别。

七、如何验证插件能力与编写自定义格式

7.1 查看可用格式

python3 -m PIL        # 打印支持的格式、扩展名与特性

或在代码中:

from PIL import Image, features

Image.registered_extensions()   # {'bmp': 'BMP', 'gif': 'GIF', ...}
features.pilinfo()              # 详细特性与依赖报告

7.2 自定义插件的最小形态

虽然文档强调 register_* 不应在应用代码中使用,但第三方格式包正是通过它们接入 Pillow 的。一个最小插件需要:

from PIL import Image, ImageFile

class MyFormatImageFile(ImageFile.ImageFile):
    format = "MYFMT"
    format_description = "My custom format"

    def _open(self):
        # 解析文件头,设置 self._mode 与 self._size,注册 raw decoder
        self.tile = [("raw", (0, 0) + self.size, self.fp.tell(), (self.mode, 0, 1))]

def _accept(prefix: bytes) -> bool:
    return prefix[:4] == b"MYFM"

Image.register_open(MyFormatImageFile.format, MyFormatImageFile, _accept)
Image.register_extension(MyFormatImageFile.format, ".myfmt")

将文件放入 sys.path 并确保其被 init() 的 _plugins 扫描路径覆盖,或直接在应用启动时导入该模块完成注册。

八、测试佐证与进一步阅读

每个插件模块在 Tests 目录下都有对应的回归测试文件,例如:

若需深入底层,可继续阅读:

结语

plugins.rst 虽然只是一份自动生成的索引,却是理解 Pillow 扩展性的钥匙:44 个格式插件通过统一注册协议接入核心库,两级懒加载保证了轻量启动,accept 嗅探 + formats 限定提供了可控的格式探测,而 PNG 插件中显式暴露的成员则展示了深度集成(APNG 动画、文本块安全限制)可以做到什么程度。无论是排查"为什么某格式打不开"、评估"自定义格式如何接入",还是研究"多帧格式如何设计保存 API",这份参考与 src/PIL 源码都是最佳起点。

登录后查看全文
Pillow