图像文件格式¶

Python Imaging Library 支持多种栅格文件格式。该库可以识别和读取 30 多种不同的文件格式。写入支持范围较小，但支持大多数常见的交换和演示格式。

该 open() 函数根据文件的内容来识别文件，而不是文件名，但 save() 方法会查看文件名来确定使用哪种格式，除非显式给出格式。

从文件打开图像时，只有该图像实例被认为具有该格式。图像的副本将包含从文件中加载的数据，但不是文件本身，这意味着它不再被认为是原始格式。因此，如果 copy() 对图像调用，或者其他方法在内部创建图像的副本，则该格式的任何特定方法或属性将不再存在。该 fp (文件指针) 属性将不再存在，并且 format 属性将为 None。

完全支持的格式¶

BLP¶

BLP 是 Blizzard Mipmap 格式，是魔兽世界中使用的纹理格式。 Pillow 支持读取 JPEG 压缩或原始 BLP1 图像，以及所有类型的 BLP2 图像。

保存¶

Pillow 支持写入 BLP 图像。该 save() 方法可以接受以下关键字参数

blp_version: 如果存在并设置为“BLP1”，图像将被保存为 BLP1。否则，图像将被保存为 BLP2。

BMP¶

Pillow 读取和写入包含 1、L、P 或 RGB 数据的 Windows 和 OS/2 BMP 文件。 16 色图像被读取为 P 图像。Pillow 9.1.0 中添加了对读取 8 位行程长度编码的支持。Pillow 9.3.0 中添加了对读取 4 位行程长度编码的支持。

打开¶

该 open() 方法设置以下 info 属性

压缩: 如果文件是 256 色行程长度编码图像，则设置为 1。如果文件是 16 色行程长度编码图像，则设置为 2。

DDS¶

DDS 是一种流行的容器纹理格式，用于视频游戏，并由 DirectX 原生支持。

DXT1 和 DXT5 像素格式只能在 RGBA 模式下读取。

在版本 3.4.0 中添加： DXT3 图像可以在 RGB 模式下读取，DX10 图像可以在 RGB 和 RGBA 模式下读取。

在版本 6.0.0 中添加：未压缩的 RGBA 图像可以读取。

在版本 8.3.0 中添加： BC5S 图像可以在 RGB 模式下打开，未压缩的 RGB 图像可以读取。未压缩数据也可以保存到图像文件。

在版本 9.3.0 中添加： ATI1 图像可以在 L 模式下打开，ATI2 图像可以在 RGB 模式下打开。

在版本 9.4.0 中添加：未压缩的 L (“亮度”) 和 LA 图像可以打开和保存。

在版本 10.1.0 中添加： BC5U 可以以 RGB 模式读取，8 位颜色索引图像可以以 P 模式读取。

DIB¶

Pillow 读取和写入 DIB 文件。DIB 文件类似于 BMP 文件，因此有关更多信息，请参见上文。

在版本 6.0.0 中添加。

EPS¶

Pillow 识别包含图像数据的 EPS 文件，并且可以读取包含嵌入式栅格图像 (ImageData 描述符) 的文件。如果 Ghostscript 可用，其他 EPS 文件也可以读取。EPS 驱动程序也可以写入 EPS 图像。EPS 驱动程序可以读取 L、LAB、RGB 和 CMYK 模式的 EPS 图像，但 Ghostscript 可能会将图像转换为 RGB 模式，而不是保留在原始颜色空间中。EPS 驱动程序可以以 L、RGB 和 CMYK 模式写入图像。

加载¶

要使用 Ghostscript，Pillow 会搜索“gs”可执行文件。在 Windows 上，它还会搜索“gswin32c”和“gswin64c”。要自定义此行为，EpsImagePlugin.gs_binary = "gswin64" 将设置要使用的可执行文件的名字。 EpsImagePlugin.gs_binary = False 将阻止使用 Ghostscript。

如果 Ghostscript 可用，您可以使用以下参数调用 load() 方法来影响 Ghostscript 如何渲染 EPS。

缩放

影响生成的栅格化图像的比例。如果 EPS 建议图像以 100px x 100px 渲染，将此参数设置为 2 将使 Ghostscript 渲染 200px x 200px 的图像。边界框的相对位置保持不变

im = Image.open(...)
im.size  # (100,100)
im.load(scale=2)
im.size  # (200,200)

透明度

如果为真，则生成具有透明背景的 RGBA 图像，而不是默认行为（具有白色背景的 RGB 图像）。

GIF¶

Pillow 可以读取 GIF87a 和 GIF89a 版本的 GIF 文件格式。库默认以 GIF87a 格式写入文件，除非使用 GIF89a 功能或已使用 GIF89a 格式。文件使用 LZW 编码写入。

GIF 文件最初以灰度 (L) 或调色板模式 (P) 图像读取。在 P 图像中查找后面的帧会将图像更改为 RGB（如果第一帧具有透明度，则为 RGBA）。

P 模式图像更改为 RGB，因为 GIF 的每一帧可能包含自己的最多 256 色调色板。当将新帧放置到前面的帧上时，这些颜色可能会组合在一起，超过 P 模式的 256 色限制。相反，图像被转换为 RGB 来处理这种情况。

如果您希望第一个 P 图像帧也为 RGB，以便每个 P 帧都转换为 RGB 或 RGBA 模式，则可以使用一个设置

from PIL import GifImagePlugin
GifImagePlugin.LOADING_STRATEGY = GifImagePlugin.LoadingStrategy.RGB_ALWAYS

但是，GIF 帧并不总是包含单独的调色板。如果只有一个全局调色板，则所有颜色都可以容纳在 P 模式中。如果您希望在这种情况下帧保持为 P，则也有一个设置可用

from PIL import GifImagePlugin
GifImagePlugin.LOADING_STRATEGY = GifImagePlugin.LoadingStrategy.RGB_AFTER_DIFFERENT_PALETTE_ONLY

要恢复默认行为，即 P 模式图像仅在第一帧后转换为 RGB 或 RGBA

from PIL import GifImagePlugin
GifImagePlugin.LOADING_STRATEGY = GifImagePlugin.LoadingStrategy.RGB_AFTER_FIRST

打开¶

该 open() 方法设置以下 info 属性

背景: 默认背景颜色（调色板颜色索引）。
透明度: 透明颜色索引。如果图像不透明，则省略此键。
版本: 版本（GIF87a 或 GIF89a）。
持续时间: 可能不存在。显示 GIF 当前帧的时间，以毫秒为单位。
循环: 可能不存在。GIF 应该循环的次数。0 表示它将无限循环。
注释: 可能不存在。有关图像的注释。这是在当前帧的图像之前找到的最后一个注释。
扩展: 可能不存在。包含特定于应用程序的信息。

读取序列¶

GIF 加载器支持 seek() 和 tell() 方法。您可以将这些方法结合起来以查找下一帧 (im.seek(im.tell() + 1))。

im.seek() 如果您尝试在最后一帧后查找，则会引发 EOFError。

保存¶

当调用 save() 来写入 GIF 文件时，可以使用以下选项

im.save(out, save_all=True, append_images=[im1, im2, ...])

save_all

如果存在且为真，则将保存图像的所有帧。否则，将仅保存多帧图像的第一帧。

append_images

要附加为附加帧的图像列表。列表中的每个图像都可以是单帧或多帧图像。目前支持 GIF、PDF、PNG、TIFF 和 WebP。

也支持 ICO 和 ICNS。如果传入相关大小的图像，它们将被使用，而不是缩小主图像。

include_color_table

是否包含局部颜色表。

interlace

图像是否交错。默认情况下，它会交错，除非图像的宽度或高度小于 16 像素。

disposal

指示在显示图形后如何处理图形。

0 - 未指定处置。
1 - 不要处置。
2 - 恢复为背景颜色。
3 - 恢复为以前的内容。

为常量处置传递单个整数，或传递列表或元组以分别为每个帧设置处置。

palette

为保存的图像使用指定的调色板。调色板应为包含以 RGBRGB… 形式的调色板条目的字节或字节数组对象。它不应超过 768 个字节。或者，调色板可以作为 PIL.ImagePalette.ImagePalette 对象传递。

optimize

是否尝试通过消除未使用的颜色来压缩调色板（这仅在调色板可以压缩到下一个较小的 2 的幂元素时才有用），以及是否将下一帧中不是新像素的所有像素标记为透明。

默认情况下会尝试这样做，除非调色板作为选项或作为第一个图像的 info 字典的一部分指定。

请注意，如果您要保存的图像来自现有的 GIF，它可能在其 info 字典中具有以下属性。对于这些选项，如果您没有传入它们，它们将默认为其 info 值。

透明度: 透明颜色索引。
持续时间: 多帧 GIF 每一帧的显示持续时间，以毫秒为单位。为常量持续时间传递单个整数，或传递列表或元组以分别为每个帧设置持续时间。
循环: GIF 应该循环的次数。0 表示它将无限循环。如果省略或为 None，则图像不会循环。
注释: 有关图像的注释。

读取本地图像¶

GIF 加载器创建一个与 GIF 文件的逻辑屏幕大小相同大小的图像内存，并将实际像素数据（本地图像）粘贴到此图像中。如果您只想要实际像素矩形，您可以裁剪图像

im = Image.open(...)

if im.tile[0][0] == "gif":
    # only read the first "local image" from this GIF file
    box = im.tile[0][1]
    im = im.crop(box)

ICNS¶

Pillow 读取和写入 macOS .icns 文件。默认情况下，将读取最大的可用图标，但您可以在调用 load() 之前通过设置 size 属性来覆盖它。 open() 方法设置以下 info 属性

注意

在 8.3.0 版本之前，Pillow 只能在 macOS 上写入 ICNS 文件。

尺寸: 此图标文件中找到的支持大小列表；它们是一个 3 元组，(width, height, scale)，其中 scale 为视网膜图标为 2，标准图标为 1。

加载¶

您可以使用以下参数调用 load() 方法。

缩放: 影响结果图像的比例。如果将大小设置为 (512, 512)，在比例为 2 的情况下加载后，size 的最终值为 (1024, 1024)。

保存¶

save() 方法可以接受以下关键字参数

append_images: 要替换图像缩小版本的图像列表。图像的顺序无关紧要，因为它们的用途由每个图像的大小决定。

在 5.1.0 版本中添加。

ICO¶

ICO 用于在 Windows 上存储图标。将读取最大的可用图标。

保存¶

save() 方法支持以下选项

尺寸: 此 ICO 文件中包含的大小列表；它们是一个 2 元组，(width, height)；默认为 [(16, 16), (24, 24), (32, 32), (48, 48), (64, 64), (128, 128), (256, 256)]。任何大于原始大小或 256 的大小都将被忽略。

save() 方法可以接受以下关键字参数

append_images: 要替换图像缩小版本的图像列表。图像的顺序无关紧要，因为它们的用途由每个图像的大小决定。

在 8.1.0 版本中添加。
bitmap_format: 默认情况下，图像数据将以 PNG 格式保存。使用 “bmp” 的位图格式，图像数据将改为以 BMP 格式保存。

在 8.3.0 版本中添加。

IM¶

IM 是 LabEye 和其他基于 IFUNC 图像处理库的应用程序使用的格式。该库读取和写入此格式的大多数未压缩的交换版本。

IM 是唯一可以存储所有内部 Pillow 格式的格式。

JPEG¶

Pillow 读取包含 L、RGB 或 CMYK 数据的 JPEG、JFIF 和 Adobe JPEG 文件。它写入标准和渐进式 JFIF 文件。

使用 draft() 方法，可以通过将 RGB 图像转换为 L，以及在加载图像时将图像大小调整为原始大小的 1/2、1/4 或 1/8 来加快速度。

默认情况下，Pillow 不允许加载截断的 JPEG 文件，设置 ImageFile.LOAD_TRUNCATED_IMAGES 来覆盖此限制。

打开¶

如果可用，open() 方法可能会设置以下 info 属性

jfif

找到 JFIF 应用程序标记。如果文件不是 JFIF 文件，则此键不存在。

jfif_version

表示 jfif 版本的元组，(主版本，次版本)。

jfif_density

表示图像像素密度的元组，单位由 jfif_unit 指定。

jfif_unit

jfif_density 的单位

0 - 无单位
1 - 每英寸像素数
2 - 每厘米像素数

dpi

表示报告的像素密度（以每英寸像素数为单位）的元组，如果文件是 jfif 文件并且单位为英寸。

adobe

找到 Adobe 应用程序标记。如果文件不是 Adobe JPEG 文件，则此键不存在。

adobe_transform

供应商特定标记。

progression

指示这是一个渐进式 JPEG 文件。

icc_profile

图像的 ICC 颜色配置文件。

exif

图像的原始 EXIF 数据。

注释

有关图像的注释。

在版本 7.1.0 中添加。

保存¶

save() 方法支持以下选项

quality

图像质量，范围从 0（最差）到 95（最佳），或字符串 keep。默认值为 75。应避免超过 95 的值；100 会禁用 JPEG 压缩算法的一部分，导致文件大小很大，而图像质量几乎没有提高。值 keep 仅对 JPEG 文件有效，并将保留原始图像质量级别、子采样和 qtables。

optimize

如果存在且为真，则表示编码器应对图像进行额外的遍历以选择最佳编码器设置。

progressive

如果存在且为真，则表示此图像应存储为渐进式 JPEG 文件。

dpi

表示像素密度的整数元组，(x,y)。

icc_profile

如果存在且为真，则图像将使用提供的 ICC 配置文件存储。如果未提供此参数，则图像将保存，但不会附加任何配置文件。要保留现有配置文件

im.save(filename, 'jpeg', icc_profile=im.info.get('icc_profile'))

exif

如果存在，则图像将使用提供的原始 EXIF 数据存储。

keep_rgb

默认情况下，libjpeg 会将具有 RGB 颜色空间的图像转换为 YCbCr。如果此选项存在且为真，则这些图像将以 RGB 格式存储。

启用此选项后，尝试使用 subsampling 选项对 RGB 图像进行色度子采样将引发 OSError 错误。

在版本 10.2.0 中添加。

subsampling

如果存在，则设置编码器的子采样。

keep: 仅对 JPEG 文件有效，将保留原始图像设置。
4:4:4, 4:2:2, 4:2:0: 特定采样值
0: 等效于 4:4:4
1: 等效于 4:2:2
2: 等效于 4:2:0

如果不存在，则设置将由 libjpeg 或 libjpeg-turbo 确定。

restart_marker_blocks

如果存在，则每当生成指定数量的 MCU 块时，就会发出重新启动标记。

在版本 10.2.0 中添加。

restart_marker_rows

如果存在，则每当生成指定数量的 MCU 行时，就会发出重新启动标记。

在版本 10.2.0 中添加。

qtables

如果存在，则设置编码器的 qtables。在 JPEG 文档中，这被列为向导的高级选项。请谨慎使用。qtables 可以是以下几种类型的值之一

一个字符串，命名一个预设，例如 keep、web_low 或 web_high
一个列表、元组或字典（具有整数键 = 范围(len(keys))），其中包含 64 个整数的列表。必须有 2 到 4 个表。

在版本 2.5.0 中添加。

streamtype

允许存储没有量化和霍夫曼表的图像，或者具有这些表但没有图像数据。这对处理表分开并将其在图像之间共享的容器格式或网络协议很有用。

0 (默认): 交换数据流，包含表和图像数据
1: 简化表格规范 (仅表格) 数据流

在版本 10.2.0 中添加。
2: 简化图像 (仅图像) 数据流

注释

有关图像的注释。

在版本 9.4.0 中添加。

注意

要启用 JPEG 支持，需要在构建 Python Imaging Library 之前构建和安装 IJG JPEG 库。有关详细信息，请参阅发行版自述文件。

JPEG 2000¶

在版本 2.4.0 中添加。

Pillow 读取和写入包含 L、LA、RGB、RGBA 或 YCbCr 数据的 JPEG 2000 文件。在读取时，YCbCr 数据将转换为 RGB 或 RGBA，具体取决于是否存在 alpha 通道。从版本 8.3.0 开始，Pillow 可以读取（但不能写入）具有子采样分量的 RGB、RGBA 和 YCbCr 图像。Pillow 支持 JPEG 2000 原始码流（.j2k 文件），以及带框的 JPEG 2000 文件（.jp2 或 .jpx 文件）。

在加载时，如果在调用 load() 方法之前，在图像上设置了 mode，则可以要求 Pillow 将图像转换为 RGB 或 RGBA，而不是自行选择。还可以将 reduce 设置为要丢弃的分辨率数量（每个分辨率将最终图像的大小缩小 2 倍），并将 layers 设置为指定要加载的质量层数。

保存¶

save() 方法支持以下选项

offset: 图像偏移量，以整数元组形式表示，例如 (16, 16)
tile_offset: 平铺偏移量，同样也是 2 个整数的元组。
tile_size: 平铺大小，以 2 个整数的元组形式表示。如果未指定，或设置为 None，则图像将保存为无平铺形式。
quality_mode: 可以是 "rates" 或 "dB"，具体取决于要用来指定图像质量的单位。
quality_layers: 数字序列，每个数字代表近似大小缩减（如果质量模式为 "rates"）或以分贝为单位的信噪比值。如果未指定，则默认值为一个全质量层。
num_resolutions: 要存储的不同图像分辨率的数量（对应于离散小波变换分解的数量加 1）。
codeblock_size: 码块大小，以 2 个整数的元组形式表示。最小大小为 4 x 4，最大大小为 1024 x 1024，另外还受到限制，即任何码块不得超过 4096 个系数（即两个数字的乘积不得大于 4096）。
precinct_size: 分区大小，以 2 个整数的元组形式表示。必须是两个轴上的 2 的幂，并且必须大于码块大小。
irreversible: 如果为 True，则使用有损离散小波变换 DWT 9-7。默认值为 False，它使用无损 DWT 5-3。
mct: 如果为 1，则在编码时启用多组件变换，否则使用 0 表示不进行组件变换（默认）。如果启用了 MCT 且 irreversible 为 True，则将应用不可逆颜色变换，否则编码将使用可逆颜色变换。MCT 最适合 mode 为 RGB 的情况，并且仅适用于图像数据具有 3 个组件的情况。

在版本 9.1.0 中添加。
progression: 控制级进顺序；必须是 "LRCP"、"RLCP"、"RPCL"、"PCRL"、"CPRL" 之一。这些字母分别代表组件、位置、分辨率和层，并控制编码顺序，其理念是，例如，使用 LRCP 模式编码的图像可以随着它们到达解码器而对其质量层进行解码，而使用 RLCP 模式编码的图像将随着它们到达而对其越来越高的分辨率进行解码，等等。
signed: 如果为真，则告诉编码器以有符号形式保存图像。

在版本 9.4.0 中添加。
cinema_mode: 将编码器设置为生成符合数字影院规范的输出。此处的选项有 "no"（默认）、"cinema2k-24" 表示 24fps 2K、"cinema2k-48" 表示 48fps 2K 以及 "cinema4k-24" 表示 24fps 4K。请注意，对于符合规范的 2K 文件，图像尺寸中的至少一个必须与 2048 x 1080 相匹配，而对于符合规范的 4K 文件，至少一个尺寸必须与 4096 x 2160 相匹配。
no_jp2: 如果为 True，则在保存时不要将原始码流封装在 JP2 文件格式中，否则将使用文件名的扩展名来确定格式（默认）。

在版本 9.1.0 中添加。
注释: 向文件添加自定义注释，替换默认的“由 OpenJPEG 版本创建”注释。

在版本 9.5.0 中添加。
plt: 如果 True 并且 OpenJPEG 2.4.0 或更高版本可用，则在生成的文件中包含 PLT（数据包长度、图块部分标头）标记。默认值为 False。

在版本 9.5.0 中添加。

注意

要启用 JPEG 2000 支持，您需要在构建 Python 图像库之前构建并安装 OpenJPEG 库（版本 2.0.0 或更高版本）。

Windows 用户可以安装 OpenJPEG 网站上提供的 OpenJPEG 二进制文件，但必须将它们添加到 PATH 中才能使用 Pillow（如果您没有这样做，您将收到有关无法加载 _imaging DLL 的错误）。

MSP¶

Pillow 从 Windows 1 和 2 中识别并读取 MSP 文件。该库写入此格式的未压缩（Windows 1）版本。

PCX¶

Pillow 读取和写入包含 1、L、P 或 RGB 数据的 PCX 文件。

PFM¶

在版本 10.3.0 中添加。

Pillow 读取和写入包含 F 数据的灰度（Pf 格式）可移植浮点图（PFM）文件。

不支持彩色（PF 格式）PFM 文件。

打开¶

open() 函数设置以下 info 属性

缩放: 存储在“比例因子/字节序”行中的数字的绝对值。

PNG¶

Pillow 识别、读取和写入包含 1、L、LA、I、P、RGB 或 RGBA 数据的 PNG 文件。从 v1.1.7 开始支持交错文件。

从 Pillow 6.0 开始，可以从 PNG 图像中读取 EXIF 数据。但是，与其他图像格式不同，EXIF 数据在调用 load() 之前，不会保证存在于 info 中。

默认情况下，Pillow 不允许加载截断的 PNG 文件，请设置 ImageFile.LOAD_TRUNCATED_IMAGES 以覆盖此设置。

打开¶

open() 函数在适当的情况下设置以下 info 属性

色度

色度点，作为 8 个浮点数的元组。（White Point X、White Point Y、Red X、Red Y、Green X、Green Y、Blue X、Blue Y）

伽马

伽马，以浮点数表示。

srgb

sRGB 渲染意图，以整数表示。

0 感知

1 相对色度

2 饱和度

3 绝对色度

透明度

对于 P 图像：完全透明像素的调色板索引，或包含每个调色板条目的 alpha 值的字节字符串。

对于 1、L、I 和 RGB 图像，表示此图像中完全透明像素的颜色。

如果图像不是透明调色板图像，则省略此键。

open 还将 Image.text 设置为包含 PNG 图像的 tEXt、zTXt 和 iTXt 块值的字典。单个压缩块的解压缩大小限制为 PngImagePlugin.MAX_TEXT_CHUNK，默认值为 1MB，以防止解压缩炸弹。此外，所有文本块的总大小限制为 PngImagePlugin.MAX_TEXT_MEMORY，默认为 64MB。

保存¶

save() 方法支持以下选项

optimize

如果存在且为真，则指示 PNG 写入器使输出文件尽可能小。这包括额外的处理以找到最佳编码器设置。

透明度

对于 P、1、L、I 和 RGB 图像，此选项控制从图像中标记为透明的颜色。

对于 P 图像，这可以是调色板索引，也可以是包含每个调色板条目的 alpha 值的字节字符串。

dpi

包含两个数字的元组，分别对应于每个方向所需的 dpi。

pnginfo

包含块的 PIL.PngImagePlugin.PngInfo 实例。

compress_level

ZLIB 压缩级别，介于 0 到 9 之间的数字：1 提供最佳速度，9 提供最佳压缩，0 完全不压缩。默认值为 6。当 optimize 选项为 True 时，compress_level 不会产生影响（无论传递的值是多少，它都将设置为 9）。

icc_profile

要包含在保存的文件中的 ICC 配置文件。

exif

要包含在保存的文件中的 exif 数据。

在版本 6.0.0 中添加。

bits（实验性）

对于 P 图像，此选项控制要存储的位数。如果省略，PNG 写入器将使用 8 位（256 色）。

dictionary（实验性）

设置 ZLIB 编码器字典。

注意

要启用 PNG 支持，您需要在构建 Python 图像库之前构建并安装 ZLIB 压缩库。有关详细信息，请参阅安装文档。

APNG 序列¶

PNG 加载程序包括对读取和写入动画可移植网络图形 (APNG) 文件的有限支持。当加载 APNG 文件时，get_format_mimetype() 将返回 "image/apng"。当 n_frames 属性的值大于 1 时，is_animated 属性的值将为 True。对于 APNG 文件，n_frames 属性取决于动画帧数以及是否存在默认图像。有关更多详细信息，请参阅下面的 default_image 属性文档。支持 seek() 和 tell() 方法。

im.seek() 如果您尝试在最后一帧后查找，则会引发 EOFError。

这些 info 属性将在适当的情况下针对 APNG 帧设置

default_image

指定此 APNG 文件是否包含单独的默认图像，该图像不是实际 APNG 动画的一部分。

当 APNG 文件包含默认图像时，最初加载的图像（即 seek(0) 的结果）将是默认图像。为了解释默认图像的存在，n_frames 属性将设置为 frame_count + 1，其中 frame_count 是实际的 APNG 动画帧数。要加载第一个 APNG 动画帧，必须调用 seek(1)。

True - APNG 包含默认图像，该图像不是动画帧。
False - APNG 不包含默认图像。n_frames 属性将设置为实际的 APNG 动画帧数。最初加载的图像（即 seek(0)）将是第一个 APNG 动画帧。

循环

循环此 APNG 的次数，0 表示无限循环。

持续时间

显示此 APNG 帧的时间（以毫秒为单位）。

注意

APNG 加载器返回与 APNG 文件逻辑屏幕大小相同的图像。返回的图像包含给定帧的像素数据，在应用任何 APNG 帧处置和帧混合操作后（即，它包含 Web 浏览器将为此帧渲染的内容 - 所有先前帧和此帧的合成）。

任何包含序列错误的 APNG 文件都被视为无效图像。APNG 加载器不会尝试修复和重新排序包含序列错误的文件。

保存¶

调用 save() 时，默认情况下只会保存单个帧 PNG 文件。要保存 APNG 文件（包括单个帧 APNG），必须将 save_all 参数设置为 True。还可以设置以下参数

default_image

布尔值，指定基础图像是否为默认图像。如果为 True，则基础图像将用作默认图像，而 append_images 序列中的第一张图像将作为第一个 APNG 动画帧。如果为 False，则基础图像将用作第一个 APNG 动画帧。默认值为 False。

append_images

要追加为附加帧的图像列表或元组。列表中的每个图像都可以是单帧或多帧图像。每个帧的大小应与基础图像的大小相匹配。还要注意，如果帧的模式与基础图像的模式不匹配，则帧将转换为基础图像模式。

循环

循环此 APNG 的次数，0 表示无限循环。默认值为 0。

持续时间

显示此 APNG 帧的时间长度（以毫秒为单位）的整数（或整数列表或元组）。默认值为 0。

disposal

整数（或整数列表或元组），指定要在此帧之前用于此帧的 APNG 处置操作，以渲染下一帧。默认值为 0。

0 (OP_NONE，默认） - 在渲染下一帧之前，不会对此帧进行任何处置。
1 (PIL.PngImagePlugin.Disposal.OP_BACKGROUND) - 在渲染下一帧之前，此帧的修改区域将被清除为完全透明的黑色。
2 (OP_PREVIOUS) - 在渲染下一帧之前，此帧的修改区域将恢复到上一帧的内容。

混合

整数（或整数列表或元组），指定在渲染下一帧之前要为此帧使用的 APNG 混合操作。默认值为 0。

0 (OP_SOURCE) - 此帧的所有颜色分量（包括 alpha）都将覆盖先前的输出图像内容。
1 (OP_OVER) - 此帧应与先前的输出图像内容进行 alpha 合成。

注意

The duration, disposal and blend parameters can be set to lists or tuples to specify values for each individual frame in the animation. The length of the list or tuple must be identical to the total number of actual frames in the APNG animation. If the APNG contains a default image (i.e. default_image is set to True), these list or tuple parameters should not include an entry for the default image.

PPM¶

Pillow 读取和写入包含 1, L, I 或 RGB 数据的 PBM、PGM、PPM 和 PNM 文件。

“原始” (P4 到 P6) 格式可以读取，并在写入时使用。

从 Pillow 9.2.0 开始，“普通” (P1 到 P3) 格式也可以读取。

SGI¶

Pillow 读取和写入未压缩的 L、RGB 和 RGBA 文件。

SPIDER¶

Pillow 读取和写入 32 位浮点数据 (“F;32F”) 的 SPIDER 图像文件。

Pillow 还可以读取包含 SPIDER 图像序列的 SPIDER 堆栈文件。支持 seek() 和 tell() 方法，并允许随机访问。

打开¶

The open() method sets the following attributes

格式: 设置为 SPIDER
istack: 如果文件是图像堆栈，则设置为 1，否则设置为 0。
n_frames: 设置为堆栈中的图像数量。

提供了便利方法 convert2byte()，用于将浮点数据转换为字节数据（模式 L）

im = Image.open("image001.spi").convert2byte()

保存¶

SPIDER 文件的扩展名可以是任何 3 个字母数字字符。因此，必须明确指定输出格式

im.save('newimage.spi', format='SPIDER')

有关 SPIDER 图像处理软件包的更多信息，请参阅 https://github.com/spider-em/SPIDER

TGA¶

Pillow 读取和写入包含 L、LA、P、RGB 和 RGBA 数据的 TGA 图像。Pillow 可以读取和写入未压缩和行程长度编码的 TGA。

保存¶

save() 方法可以接受以下关键字参数

压缩: 如果设置为“tga_rle”，则文件将进行行程长度编码。

在版本 5.3.0 中添加。
id_section: 识别字段。

在版本 5.3.0 中添加。
方向: 如果存在且为正数，则第一个像素位于左上角，而不是左下角。

在版本 5.3.0 中添加。

TIFF¶

Pillow 读取和写入 TIFF 文件。它可以读取带状和平铺图像、像素和平面交错的多波段图像。如果您安装了 libtiff 及其头文件，Pillow 可以读取和写入多种压缩的 TIFF 文件。如果没有，Pillow 只能读取和写入未压缩的文件。

注意

从版本 5.0.0 开始，Pillow 需要 libtiff 才能读取或写入压缩文件。在此版本发布之前，Pillow 在没有使用 libtiff 的情况下对读取 Packbits、LZW 和 JPEG 压缩的 TIFF 的支持存在错误。

打开¶

该 open() 方法设置以下 info 属性

压缩: 压缩模式。

在版本 2.0.0 中添加。
dpi: 图像分辨率，作为 (xdpi, ydpi) 元组，如果适用。您可以使用 tag 属性获取有关图像分辨率的更详细的信息。

在版本 1.1.5 中添加。
分辨率: 图像分辨率，作为 (xres, yres) 元组，如果适用。这是以文件指定的任何单位进行的测量。

在版本 1.1.5 中添加。

The tag_v2 attribute contains a dictionary of TIFF metadata. The keys are numerical indexes from TiffTags.TAGS_V2. Values are strings or numbers for single items, multiple values are returned in a tuple of values. Rational numbers are returned as a IFDRational object.

在版本 3.0.0 中添加。

为了与旧版代码兼容，tag 属性包含 TIFF 字段的解码字典，如 3.0.0 之前的版本返回。值将作为字符串或数字值的元组返回。有理数将作为 (numerator, denominator) 的元组返回。

自版本 3.0.0 起已弃用。

读取多帧 TIFF 图像¶

TIFF 加载器支持 seek() 和 tell() 方法，接收和返回图像文件中的帧号。您可以组合这些方法来跳转到下一帧 (im.seek(im.tell() + 1))。帧从 0 到 im.n_frames - 1 编号，可以按任何顺序访问。

im.seek() 如果您尝试在最后一帧后查找，则会引发 EOFError。

保存¶

save() 方法可以接受以下关键字参数

save_all

如果为真，Pillow 会将图像的所有帧保存到多帧 tiff 文档中。

在版本 3.4.0 中添加。

append_images

要追加作为附加帧的图像列表。列表中的每个图像可以是单帧图像或多帧图像。但是请注意，为了获得正确的结果，所有追加的图像应具有相同的 encoderinfo 和 encoderconfig 属性。

在版本 4.2.0 中添加。

tiffinfo

包含 tiff 标签和值的 ImageFileDirectory_v2 对象或 dict 对象。TIFF 字段类型将自动检测数字和字符串值，任何其他类型都需要使用 ImageFileDirectory_v2 对象，并在 tagtype 中使用来自 TiffTags.TYPES 的相应数值设置类型。

在版本 2.3.0 中添加。

应使用 IFDRational 对象传入属于有理数类型的元数据值。

在版本 3.1.0 中添加。

为了与旧代码兼容，可以将 ImageFileDirectory_v1 对象传递到此字段中。但是，此方法已弃用。

在版本 5.4.0 中添加。

以前的版本仅支持使用 libtiff 写入时的一些标签。支持的列表在 TiffTags.LIBTIFF_CORE 中。

在版本 6.1.0 中添加。

添加了对带符号类型（例如 TIFF_SIGNED_LONG）和多个值的支持。单个标签的多个值必须作为元组传递给 ImageFileDirectory_v2，并在 tagtype 中需要匹配的类型。

exif

与其他格式保持一致的“tiffinfo”的备用关键字。

在版本 8.4.0 中添加。

压缩

包含文件所需压缩方法的字符串。（仅在安装了 libtiff 时有效）有效的压缩方法是：None、"group3"、"group4"、"jpeg"、"lzma"、"packbits"、"tiff_adobe_deflate"、"tiff_ccitt"、"tiff_lzw"、"tiff_raw_16"、"tiff_sgilog"、"tiff_sgilog24"、"tiff_thunderscan"、"webp"、"zstd"

quality

JPEG 压缩的图像质量，范围从 0（最差）到 100（最佳）。默认值为 75。

在版本 6.1.0 中添加。

这些用于设置 tiff 头字段的参数是通过 tiffinfo 使用通用标签的替代方法。

description

software

date_time

artist

copyright: 字符串
icc_profile: 要包含在保存的文件中的 ICC 配置文件。
resolution_unit: 整数。1 表示无单位，2 表示英寸，3 表示厘米。
分辨率: 整数或浮点数，用于 x 和 y 分辨率。
x_resolution: 整数或浮点数。
y_resolution: 整数或浮点数。
dpi: 一个包含 (x_resolution, y_resolution) 的元组，单位为英寸。为了与其他图像格式保持一致，dpi 的 x 和 y 分辨率将四舍五入到最接近的整数。

WebP¶

Pillow 读取和写入 WebP 文件。需要 libwebp v0.5.0 或更高版本。

保存¶

save() 方法支持以下选项

lossless: 如果存在且为真，则指示 WebP 写入器使用无损压缩。
quality: 整数，0-100，默认为 80。对于有损压缩，0 表示最小尺寸，100 表示最大尺寸。对于无损压缩，此参数是压缩工作量：0 表示最快，但与最慢但最佳的 100 相比，生成的较大的文件。
alpha_quality: 整数，0-100，默认为 100。仅用于有损压缩。0 表示最小尺寸，100 表示无损。
method: 质量/速度权衡（0=快，6=慢-好）。默认为 4。
exact: 如果为真，则保留透明的 RGB 值。否则，丢弃不可见的 RGB 值以获得更好的压缩。默认为 false。
icc_profile: 要包含在保存的文件中的 ICC 配置文件。
exif: 要包含在保存的文件中的 exif 数据。
xmp: 要包含在保存的文件中的 XMP 数据。

保存序列¶

当调用 save() 来写入 WebP 文件时，默认情况下只保存多帧图像的第一帧。如果存在 save_all 参数且为真，则所有帧都将保存，并且以下选项也将可用。

append_images: 要追加作为附加帧的图像列表。列表中的每个图像可以是单帧图像或多帧图像。
持续时间: 每帧的显示时长，以毫秒为单位。传递一个整数表示常数时长，或传递一个列表或元组表示为每帧分别设置时长。
循环: 重复动画的次数。默认为 [0 = 无限]。
背景: 画布的背景颜色，以 RGBA 元组的形式表示，值范围为 (0-255)。
minimize_size: 如果为真，则最小化输出尺寸（慢）。隐式禁用关键帧插入。
kmin, kmax: 输出中连续关键帧之间的最小和最大距离。库可能根据需要插入一些关键帧以满足此条件。请注意，这些条件应成立：kmax > kmin 且 kmin >= kmax / 2 + 1。此外，如果 kmax <= 0，则禁用关键帧插入；如果 kmax == 1，则所有帧都将是关键帧（kmin 值对于这些特殊情况无关紧要）。
allow_mixed: 如果为真，则使用混合压缩模式；编码器将根据启发式方法为每帧选择有损压缩或无损压缩。

XBM¶

Pillow 读取和写入 X 位图文件（模式 1）。

只读格式¶

CUR¶

CUR 用于存储 Windows 上的鼠标光标。CUR 解码器读取最大的可用鼠标光标。不支持动画鼠标光标。

DCX¶

DCX 是由英特尔定义的 PCX 文件的容器文件格式。DCX 格式通常用于传真应用程序。DCX 解码器可以读取包含 1、L、P 或 RGB 数据的文件。

打开文件时，只读取第一个图像。您可以使用 seek() 或 ImageSequence 读取其他图像。

FITS¶

在版本 9.1.0 中添加。

Pillow 识别并读取 FITS 文件，通常用于天文学。可以读取未压缩和 GZIP_1 压缩的图像。

FLI, FLC¶

Pillow 读取 Autodesk FLI 和 FLC 动画。

该 open() 方法设置以下 info 属性

持续时间: 每帧之间的延迟（以毫秒为单位）。

FPX¶

Pillow 读取柯达 FlashPix 文件。只读取文件中的最高分辨率图像，并且不考虑查看变换。

要启用 FPX 支持，您必须安装 olefile。

注意

要启用完整的 FlashPix 支持，您需要在构建 Python 图像库之前构建并安装 IJG JPEG 库。有关详细信息，请参阅发行版自述文件。

FTEX¶

在版本 3.2.0 中添加。

FTEX 解码器读取在 Independence War 2: Edge Of Chaos 中用于 3D 对象的纹理。该插件以压缩和未压缩格式读取每个文件中的单个纹理。

GBR¶

GBR 解码器读取 GIMP 笔刷文件，版本 1 和 2。

打开¶

该 open() 方法设置以下 info 属性

注释: 笔刷名称。
spacing: 笔刷之间的间距，以像素为单位。仅限版本 2。

GD¶

Pillow 读取未压缩的 GD2 文件。请注意，您必须使用 PIL.GdImageFile.open() 读取此类文件。

打开¶

该 open() 方法设置以下 info 属性

透明度: 透明颜色索引。如果图像不透明，则省略此键。

IMT¶

Pillow 读取包含 L 数据的 Image Tools 图像。

IPTC/NAA¶

Pillow 为 IPTC/NAA 新闻照片文件提供有限的读取支持。

MCIDAS¶

Pillow 识别并读取 8 位 McIdas 区域文件。

MIC¶

Pillow 识别并读取 Microsoft Image Composer (MIC) 文件。打开时，将加载文件中的第一个精灵。您可以使用 seek() 和 tell() 从文件中读取其他精灵。

请注意，MIC 文件中可能嵌入了 2.2 的伽马值。

要启用 MIC 支持，您必须安装 olefile。

MPO¶

Pillow 识别并读取多图对象 (MPO) 文件，在首次打开时加载主图像。可以使用 seek() 和 tell() 方法从文件中读取其他图片。图片从零开始索引，支持随机访问。

保存¶

调用save()保存 MPO 文件时，默认情况下只会保存多帧图像的第一帧。如果save_all参数存在且为真，则所有帧都将被保存，并且以下选项也将可用。

append_images: 要追加为附加图片的图像列表。列表中的每个图像可以是单帧图像或多帧图像。

在 9.3.0 版本中添加。

PCD¶

Pillow 读取包含 RGB 数据的 PhotoCD 文件。这仅读取文件中的 768x512 分辨率图像。更高的分辨率使用专有编码进行编码。

PIXAR¶

Pillow 对 PIXAR 光栅文件提供有限的支持。库可以识别并读取“转储”的 RGB 文件。

格式代码为 PIXAR。

PSD¶

Pillow 识别并读取由 Adobe Photoshop 2.5 和 3.0 编写的 PSD 文件。

QOI¶

在版本 9.5.0 中添加。

Pillow 使用 Python 解码器读取 Quite OK Image 格式的图像。如果您希望专门为这种格式编写代码，qoi 是一个使用 C 解码图像并与 NumPy 交互的替代库。

SUN¶

Pillow 识别并读取 Sun 光栅文件。

WAL¶

在 1.1.4 版本中添加。

Pillow 读取 Quake2 WAL 纹理文件。

请注意，此文件格式无法自动识别，因此您必须使用 WalImageFile 模块中的 open 函数来读取此格式的文件。

默认情况下，Quake2 标准调色板附加到纹理。要覆盖调色板，请使用 PIL.Image.Image.putpalette() 方法。

WMF, EMF¶

Pillow 可以识别 WMF 和 EMF 文件。

在 Windows 上，它可以读取 WMF 和 EMF 文件。默认情况下，它将以 72 dpi 加载图像。要以其他分辨率加载它

from PIL import Image

with Image.open("drawing.wmf") as im:
    im.load(dpi=144)

要添加其他读写支持，请使用 PIL.WmfImagePlugin.register_handler() 注册 WMF 和 EMF 处理程序。

from typing import IO

from PIL import Image, ImageFile
from PIL import WmfImagePlugin


class WmfHandler(ImageFile.StubHandler):
    def open(self, im: ImageFile.StubImageFile) -> None:
        ...

    def load(self, im: ImageFile.StubImageFile) -> Image.Image:
        ...
        return image

    def save(self, im: Image.Image, fp: IO[bytes], filename: str) -> None:
        ...


wmf_handler = WmfHandler()

WmfImagePlugin.register_handler(wmf_handler)

im = Image.open("sample.wmf")

XPM¶

Pillow 读取具有 256 种或更少颜色的 X 像素图文件（模式 P）。

打开¶

该 open() 方法设置以下 info 属性

透明度: 透明颜色索引。如果图像不透明，则省略此键。

只写格式¶

PALM¶

Pillow 提供对 PALM 像素图文件的只写支持。

格式代码为 Palm，扩展名为 .palm。

PDF¶

Pillow 可以写入 PDF（Acrobat）图像。这些图像被写入为二进制 PDF 1.4 文件。根据图像模式使用不同的编码方法。

1 模式图像使用 TIFF 编码，如果 libtiff 支持不可用，则使用 JPEG 编码
L、RGB 和 CMYK 模式图像使用 JPEG 编码
P 模式图像使用 HEX 编码
LA 和 RGBA 模式图像使用 JPEG2000 编码

保存¶

save() 方法可以接受以下关键字参数

save_all: 如果使用多帧图像，默认情况下只会保存第一张图像。要将所有帧保存到 PDF 的单独页面，save_all 参数必须存在且设置为 True。

在版本 3.0.0 中添加。
append_images: 要追加为附加页面的 PIL.Image.Image 对象列表。列表中的每个图像可以是单帧图像或多帧图像。save_all 参数必须存在且设置为 True，并与 append_images 一起使用。

在版本 4.2.0 中添加。
追加: 设置为 True 以将页面追加到现有的 PDF 文件。如果文件不存在，将引发 OSError。

在 5.1.0 版本中添加。
分辨率: 图像分辨率（以 DPI 为单位）。这将与图像中的像素数量一起确定将在 PDF 中保存的页面的物理尺寸。
dpi: (x_resolution, y_resolution) 的元组，以英寸为分辨率单位。如果 resolution 参数和 dpi 参数都存在，则 resolution 将被忽略。
标题: 文档的标题。如果未追加到现有 PDF 文件，则默认为文件名。

在 5.1.0 版本中添加。
作者: 创建文档的人员的姓名。

在 5.1.0 版本中添加。
主题: 文档的主题。

在 5.1.0 版本中添加。
关键字: 与文档相关的关键字。

在 5.1.0 版本中添加。
创建者: 如果文档是从另一种格式转换为 PDF，则创建原始文档的符合规范的产品的名称。

在 5.1.0 版本中添加。
生产者: 如果文档是从另一种格式转换为 PDF，则将文档转换为 PDF 的符合规范的产品的名称。

在 5.1.0 版本中添加。
创建日期: 文档的创建日期。如果未追加到现有 PDF 文件，则默认为当前时间。

在版本 5.3.0 中添加。
修改日期: 文档的修改日期。如果未追加到现有 PDF 文件，则默认为当前时间。

在版本 5.3.0 中添加。

XV 缩略图¶

Pillow 可以读取 XV 缩略图文件。

仅识别格式¶

BUFR¶

在 1.1.3 版本中添加。

Pillow 为 BUFR 文件提供一个存根驱动程序。

要向您的应用程序添加读写支持，请使用 PIL.BufrStubImagePlugin.register_handler()。

GRIB¶

在版本 1.1.5 中添加。

Pillow 为 GRIB 文件提供一个存根驱动程序。

驱动程序要求文件以 GRIB 头部开头。如果您有包含嵌入式 GRIB 数据的文件，或者有多个 GRIB 字段的文件，则您的应用程序必须在将文件句柄传递给 Pillow 之前先定位到头部。

要向您的应用程序添加读写支持，请使用 PIL.GribStubImagePlugin.register_handler()。

HDF5¶

在版本 1.1.5 中添加。

Pillow 为 HDF5 文件提供一个存根驱动程序。

要向您的应用程序添加读写支持，请使用 PIL.Hdf5StubImagePlugin.register_handler()。

MPEG¶

Pillow 识别 MPEG 文件。