Pillow Image图像类

​classPIL.Image.Image​

这个类表示一个图像对象。要创建 Image 对象，请使用适当的工厂函数。几乎没有任何理由直接调用Image构造函数。

• ​open()​

• new()

• frombytes()

 Image​ 类的实例具有以下方法。除非另有说明，否则所有方法都返回 ​Image​类的实例，保存生成的图像。

​Image.alpha_composite(im, dest=0, 0, source=0, 0)​

Image.alpha_composite的“就地”模拟。将图像合成到该图像上。

参数

• im -- 要在此图像上合成的图像

• dest -- 可选的2个元组（左上角），指定此（目标）图像中的左上角。

• source -- 覆盖源图像中左上角的可选2（左，上）元组，或源矩形边界的4个元组（左，上，右，下）

性能说明：目前没有在核心层中就地实现。

​Image.convert(mode=None, matrix=None, dither=None, palette=0, colors=256)​

返回此图像的转换副本。对于“P”模式，此方法通过调色板转换像素。如果省略了mode，则会选择一个模式，以便可以在不使用调色板的情况下表示图像和调色板中的所有信息。

当前版本支持“l”、“RGB”和“CMYK”之间的所有可能转换。这个 ​matrix参数只支持“L”和“RGB”。

将彩色图像转换为灰度（模式“L”）时，库使用ITU-R 601-2 Luma转换：

L = R * 299/1000 + G * 587/1000 + B * 114/1000

将灰度（“L”）或“RGB”图像转换为双层（模式“1”）图像的默认方法使用Floyd Steinberg抖动来近似原始图像的亮度级别。如果抖动 NONE ，则所有大于 127 的值都设置为 255（白色），所有其他值设置为 0（黑色）。要使用其他阈值，请使用 ​point()​方法。

当不带matrix参数从“RGBA”转换为“P”时，这会将操作传递给quantize()、 和dither并被palette忽略。

参数

• mode -- 请求的模式。见： 模式 。

• matrix -- 可选的转换矩阵。如果给定，则应该是包含浮点值的4或12元组。

• dither -- 抖动方法，在从模式“RGB”转换为“P”或从“RGB”或“L”转换为“1”时使用。可用的方法是​NONE​或​FLOYDSTEINBERG​（默认）。请注意，matrix提供时不使用此选项。

• palette -- 从模式“RGB”转换为“P”时要使用的调色板。可用的选项板有 WEB 或 ADAPTIVE .

• colors -- 要用于 ADAPTIVE 调色板。默认为256。

返回类型

Image

返回

一个 Image 对象。

以下示例将RGB图像（根据ITU-R 709线性校准，使用D65亮度）转换为CIE XYZ颜色空间：

rgb2xyz = (
    0.412453, 0.357580, 0.180423, 0,
    0.212671, 0.715160, 0.072169, 0,
    0.019334, 0.119193, 0.950227, 0)
out = im.convert("RGB", rgb2xyz)

​Image.copy()​

复制此图像。如果要将内容粘贴到图像中，但仍保留原始内容，请使用此方法。

返回类型

Image

返回

一个 Image 对象。

​Image.crop(box=None)​

返回此图像中的矩形区域。框是定义左、上、右和下像素坐标的四元组。

注意：在Pillow3.4.0之前，这是一个懒惰的操作。

参数

box -- 裁剪矩形，作为（左、上、右、下）元组。

返回类型

Image

返回

一个 Image 对象。

这将使用提供的坐标裁剪输入图像：

from PIL import Image

im = Image.open("hopper.jpg")

# The crop method from the Image module takes four coordinates as input.
# The right can also be represented as (left+width)
# and lower can be represented as (upper+height).
(left, upper, right, lower) = (20, 20, 100, 100)

# Here the image "im" is cropped and assigned to new variable im_crop
im_crop = im.crop((left, upper, right, lower))

​Image.draft(mode, size)​

配置 Mapfile 加载程序，使其返回尽可能与给定模式和大小匹配的映像版本。例如，可以使用此方法在加载彩色JPEG时将其转换为灰度。

如果进行了任何更改，则返回一个带有 mode 和 box 原始图像的坐标在修改后的图像内。

请注意，此方法修改了 Image 物体就位。如果图像已加载，则此方法无效。

注意：此方法不适用于大多数图像。它目前只为JPEG和MPO图像实现。

参数

• mode -- 请求的模式。

• size -- 请求的大小。

​Image.effect_spread(distance)​

在图像中随机分布像素。

参数

distance -- 扩散像素的距离。

​Image.entropy(mask=None, extrema=None)​

计算并返回图像的熵。

该方法将二级图像（模式“1”）作为灰度（“L”）图像处理。

如果提供了遮罩，则该方法对遮罩图像为非零的图像部分使用直方图。遮罩图像的大小必须与图像相同，并且是双层图像（模式“1”）或灰度图像（“L”）。

参数

• mask -- 一个可选的遮罩。

• extrema -- 手动指定的极值的可选元组。

返回

表示图像熵的浮点值

​Image.filter(filter)​

使用给定的筛选器筛选此图像。有关可用筛选器的列表，请参阅 ImageFilter 模块。

参数

filter -- 过滤内核。

返回

一个Image 对象。

这将使用来自 ​ImageFilter ​模块：

from PIL import Image, ImageFilter

im = Image.open("hopper.jpg")

# Blur the input image using the filter ImageFilter.BLUR
im_blurred = im.filter(filter=ImageFilter.BLUR)

Image.frombytes(data, decoder_name='raw', *args)​

从bytes对象加载此图像和像素数据。

此方法类似于 frombytes() 函数，但将数据加载到此图像中，而不是创建新的图像对象。

Image.getbands()​

返回一个包含此图像中每个带区的名称的元组。例如， getbands 在RGB图像上返回（“R”、“G”、“B”）。

返回

包含带区名称的元组。

返回类型

​tuple​

这有助于获取输入图像的波段：

from PIL import Image

im = Image.open("hopper.jpg")
print(im.getbands())  # Returns ('R', 'G', 'B')

​Image.getbbox()​

计算图像中非零区域的边界框。

返回

边界框作为定义左、上、右和下像素坐标的四元组返回。 如果图像完全为空，则此方法返回“​None​”。

这有助于获取输入图像的边界框坐标：

from PIL import Image

im = Image.open("hopper.jpg")
print(im.getbbox())
# Returns four coordinates in the format (left, upper, right, lower)

​Image.getchannel(channel)​

返回包含源图像的单个通道的图像。

参数

channel -- 返回哪个通道。可以是索引（“rgb”的“r”通道为0）或通道名称（“rgb a”的alpha通道为a”）。

返回

处于“L”模式的图像。

4.3.0 新版功能。

​Image.getcolors(maxcolors=256)​

返回此图像中使用的颜色列表。颜色将处于图像模式。例如，RGB 图像将返回（红色、绿色、蓝色）颜色值的元组，而 P 图像将返回调色板中颜色的索引。

参数

maxcolors -- 最大颜色数。如果超过此数字，此方法将返回​None​。默认限制为256色。

返回

（计数、像素）值的未排序列表。

​Image.getdata(band=None)​

将此图像的内容作为包含像素值的序列对象返回。序列对象被展平，因此行1的值直接位于行0的值之后，依此类推。

注意，这个方法返回的序列对象是一个内部PIL数据类型，它只支持特定的序列操作。要将其转换为普通序列（例如用于打印），请使用​list（im.getdata（））​。

参数

band -- 返回哪个波段。默认值是返回所有带区。要返回单个波段，请传递索引值（例如0，从“rgb”图像中获取“r”波段）。

返回

类似序列的对象。

​Image.getexif()​

​Image.getextrema()​

获取图像中每个波段的最小和最大像素值。

返回

对于单波段图像，包含最小和最大像素值的2元组。对于多波段图像，每个波段包含一个2元组的元组。

​Image.getpalette()​

以列表形式返回图像调色板。

返回

如果图像没有调色板，则显示颜色值列表[R、G、B…]或无。

​Image.getpixel(xy)​

返回给定位置的像素值。

参数

xy -- 坐标，以（x，y）表示。

返回

像素值。如果图像是多层图像，则此方法返回元组。

​Image.getprojection()​

得到x轴和y轴的投影

返回

两个序列，分别指示沿X轴和Y轴有非零像素的位置。

​Image.histogram(mask=None, extrema=None)​

返回图像的直方图。柱状图以像素计数列表的形式返回，每个像素值对应一个源图像。如果图像有多个波段，则所有波段的柱状图都会连接起来（例如，“RGB”图像的柱状图包含768个值）。

该方法将二级图像（模式“1”）作为灰度（“L”）图像处理。

如果提供了遮罩，该方法将返回图像中遮罩图像非零部分的直方图。遮罩图像必须与图像具有相同的大小，并且是双层图像（模式“1”）或灰度图像（“L”）。

参数

• mask -- 一个可选的遮罩。

• extrema -- 手动指定的极值的可选元组。

返回

包含像素计数的列表。

​Image.paste(im, box=None, mask=None)​

将另一个图像粘贴到此图像中。box参数要么是给出左上角的2元组，要么是定义左、上、右和下像素坐标的4元组，要么是​None​（与（0，0）相同）。如果给定4元组，则粘贴图像的大小必须与区域的大小匹配。

如果模式不匹配，则粘贴的图像将转换为此图像的模式（请参见 convert() 详细方法）。

源可以是包含像素值的整数或元组，而不是图像。然后，该方法用给定的颜色填充该区域。创建RGB图像时，还可以使用ImageColor模块支持的颜色字符串。

如果给定了遮罩，则此方法仅更新遮罩指示的区域。您可以使用“1”、“l”或“rgba”图像（在后一种情况下，alpha带用作遮罩）。如果遮罩为255，则按原样复制给定图像。如果遮罩为0，则保留当前值。中间值将两个图像混合在一起，包括它们的alpha通道（如果有的话）。

如果你想结合图像的阿尔法通道，可以参考alpha_composite() 。

参数

• im -- 源图像或像素值（整数或元组）。

• box -- 一个可选的4元组，给出要粘贴到的区域。如果使用2元组，则将其视为左上角。如果省略或没有，则源将粘贴到左上角。如果将图像作为第二个参数提供，而没有第三个参数，则框默认为（0，0），第二个参数将解释为遮罩图像。

• mask -- 可选的遮罩图像。

​Image.point(lut, mode=None)​

通过查找表或函数映射此图像。

参数

• lut -- 一个查找表，包含图像中每个波段的256个（或65536个，如果self.mode==“i”和mode==“l”）值。可以使用函数代替，它应该采用单个参数。对每个可能的像素值调用一次函数，结果表将应用于图像的所有波段。它也可能是一个​​​ImagePointHandler​​ ​对象：

  class Example(Image.ImagePointHandler):
    def point(self, data):
      # Return result

• mode -- 输出模式（默认与输入相同）。在当前版本中，只有当源图像具有模式“L”或“P”，并且输出具有模式“1”或源图像模式为“I”，并且输出模式为“L”时，才能使用此选项。

返回

一个 Image 对象。

​Image.putalpha(alpha)​

添加或替换此图像中的alpha层。如果图像没有alpha层，它将转换为“la”或“rgba”。新层必须是“l”或“1”。

参数

alpha -- 新的alpha层。这可以是与此图像大小相同的“l”或“1”图像，也可以是整数或其他颜色值。

​Image.putdata(data, scale=1.0, offset=0.0)​

将像素数据复制到此图像。此方法将数据从序列对象复制到图像中，从左上角（0，0）开始，一直复制到图像或序列结束。比例和偏移值用于调整序列值： 像素=值*比例+偏移.

参数

• data -- 序列对象。

• scale -- 可选的比例值。默认值为1.0。

• offset -- 可选的偏移值。默认值为0.0。

​Image.putpalette(data, rawmode='RGB')​

将调色板附加到此图像。图像必须是“p”、“p a”、“l”或“la”图像，调色板序列必须包含768个整数值，其中每组三个值代表对应像素索引的红色、绿色和蓝色值。您可以使用8位字符串代替整数序列。

参数

• data -- 调色板序列（列表或字符串）。

• rawmode -- 调色板的原始模式。

​Image.putpixel(xy, value)​

修改给定位置的像素。对于单波段图像，颜色以单个数值表示，对于多波段图像，颜色以元组表示。除此之外，p图像还接受rgb和rgba元组。

请注意，此方法相对较慢。要进行更广泛的更改，请使用 paste() 或 ImageDraw 模块代替。

参见：

• paste()

• putdata()

• ImageDraw

参数

• xy -- 像素坐标，表示为（x，y）。

• value -- 像素值。

​Image.quantize(colors=256, method=None, kmeans=0, palette=None, dither=1)​

使用指定的颜色数将图像转换为“p”模式。

参数

• colors -- 所需的颜色数，<=256

• method -- MEDIANCUT （中位数切割）， MAXCOVERAGE （最大覆盖率）， FASTOCTREE （快速八叉树）， LIBIMAGEQUANT （libimagequant；检查支持使用 PIL.features.check_feature() 具有 feature="libimagequant" ）默认情况下，​MEDIANCUT​将使用。

  RGBA 图像除外。​MEDIANCUT​并且 ​MAXCOVERAGE​不支持 RGBA 图像，因此 ​FASTOCTREE​默认使用。

• kmeans -- 整数

• palette -- 量化到给定的调色板 ​PIL.Image.Image​ .

• dither -- 抖动方法，从模式“RGB”转换为“P”或从“RGB”或“L”转换为“1”时使用。可用的方法有 ​NONE​ 或 ​FLOYDSTEINBERG​ （默认）。默认值：1（传统设置）

返回

一个新的image对象

​Image.reduce(factor, box=None)​

返回图像减少factor次数的副本。如果图像的大小不能被 整除factor，则结果大小将被四舍五入。

参数

• factor -- 宽度和高度分别大于0的整数或两个整数的元组。

• box -- 一个可选的4元组整数，提供要缩小的源图像区域。值必须在（0，0，width，height）矩形内。如果省略或​None​，则使用整个源。

​Image.remap_palette(dest_map, source_palette=None)​

重写图像以重新排序调色板。

参数

• dest_map -- 原始调色板中的索引列表。例如​ [1,0] ​将交换一个两项调色板，​list（range（256））​是标识转换。

• source_palette -- Bytes 或 None。

返回

一个Image 对象。

​Image.resize(size, resample=3, box=None, reducing_gap=None)​

返回此图像的已调整大小的副本。

参数

• size -- 以像素为单位的请求大小，作为2元组：（宽度、高度）。

• resample -- 可选的重新采样过滤器。这可能是 PIL.Image.NEAREST ， PIL.Image.BOX ， PIL.Image.BILINEAR ， PIL.Image.HAMMING ， PIL.Image.BICUBIC 或 PIL.Image.LANCZOS 。默认筛选器为 PIL.Image.BICUBIC 。 如果图像具有模式“1”或“P”，则始终设置为 PIL.Image.NEAREST 。

• box -- 一个可选的4元组浮点数，提供要缩放的源图像区域。值必须在（0，0，width，height）矩形内。如果省略或​None​，则使用整个源。

• reducing_gap --  通过分两步调整图像大小来应用优化。首先，使用 将图像缩小整数倍​reduce()​。其次，使用常规重采样调整大小。最后一步改变大小不少于reducing_gap次。 reducing_gap可以是 ​None​（不执行第一步）或应该大于 1.0。越大reducing_gap，结果越接近公平重采样。越小reducing_gap，调整大小越快。随着reducing_gap大于或等于3.0，结果是公平的，从在大多数情况下重采样难以区分。默认值为 ​None​（无优化）。

返回

一个 Image 对象。

这将调整给定图像的大小​ (width, height)​ 到 ​(width/2, height/2)​ ：

from PIL import Image

im = Image.open("hopper.jpg")

# Provide the target width and height of the image
(width, height) = (im.width // 2, im.height // 2)
im_resized = im.resize((width, height))

Image.rotate(angle, resample=0, expand=0, center=None, translate=None, fillcolor=None)

返回此图像的旋转副本。此方法返回此图像的副本，围绕其中心逆时针旋转给定的度数。

参数

• angle -- 逆时针角度。

• resample -- 可选的重新采样过滤器。这可能是 PIL.Image.NEAREST （使用最近的邻居） PIL.Image.BILINEAR （2x2环境中的线性插值），或 PIL.Image.BICUBIC （4x4环境中的三次样条插值）。如果省略，或者图像具有模式“1”或“P”，则设置为 PIL.Image.NEAREST 。

• expand -- 可选扩展标志。如果为真，则展开输出图像，使其足够大以容纳整个旋转图像。如果为false或省略，则使输出图像与输入图像大小相同。请注意，展开标志假定围绕中心旋转，不进行平移。

• center -- 可选旋转中心（2元组）。原点是左上角。默认为图像的中心。

• translate -- 可选的后旋转翻译（2元组）。

• fillcolor -- 旋转图像外部区域的可选颜色。

返回

一个 Image 对象。

这将使输入图像旋转 ​theta ​逆时针度数：

from PIL import Image

im = Image.open("hopper.jpg")

# Rotate the image by 60 degrees counter clockwise
theta = 60
# Angle is in degrees counter clockwise
im_rotated = im.rotate(angle=theta)

​Image.save(fp, format=None, **params)​

以给定的文件名保存此图像。如果未指定格式，则尽可能根据文件扩展名确定要使用的格式。

关键字选项可用于向作者提供附加说明。如果作者不认识一个选项，它会被默默地忽略

您可以使用文件对象而不是文件名。在这种情况下，您必须始终指定格式。文件对象必须实现​seek​，​tell​和​write ​方法，并在二进制模式打开。

参数

• fp -- 文件名（字符串）、​pathlib.path​对象或文件对象。

• format -- 可选格式替代。如果省略，则使用的格式由文件扩展名决定。如果使用的是文件对象而不是文件名，则应始终使用此参数。

• params -- 图像编写器的额外参数。

返回

None

引发

• ​ValueError​ -- 如果无法从文件名确定输出格式。使用“格式”选项解决此问题。

• ​OSError​ -- 如果无法写入文件。文件可能已创建，并且可能包含部分数据。

​Image.seek(frame)​

查找此序列文件中的给定帧。如果在序列结尾之外查找，该方法将引发 EOFError 例外。打开序列文件时，库自动查找第0帧。

见 tell() .

参数

frame -- 帧编号，从0开始。

引发

​EOFError​-- 如果调用试图在序列结束后查找。

​Image.show(title=None, command=None)​

显示此图像。此方法主要用于调试目的。

该方法在​PIL.ImageShow.show()​内部调用。您可以使用 ​PIL.ImageShow.register()​覆盖其默认行为。

图像首先保存到一个临时文件中。默认情况下，它将采用 PNG 格式。

在 Unix 上，然后使用display、eog或 xv实用程序打开图像，具体取决于可以找到的那个。

在 macOS 上，图像是使用本机预览应用程序打开的。

在 Windows 上，图像使用标准的 PNG 显示实用程序打开。

参数

title -- 在可能的情况下，用于图像窗口的可选标题。

​Image.split()​

将此图像拆分为单独的波段。此方法从图像返回单个图像带的元组。例如，分割一个“RGB”图像将创建三个新图像，每个新图像包含一个原始波段（红色、绿色、蓝色）的副本。

如果你只需要一个波段， getchannel() 方法更方便快捷。

返回

包含波段的元组。

​Image.tell()​

返回当前帧号。见 seek() 

返回

帧编号，从0开始。

​Image.thumbnail(size, resample=3, reducing_gap=2.0)​

将此图像制作成缩略图。此方法修改图像以包含不大于给定大小的自身缩略图版本。此方法计算适当的缩略图大小以保留图像的方面，调用 draft() 方法来配置文件读取器（如果适用），并最终调整图像的大小。

请注意，此函数会就地修改 Image 对象。如果还需要使用全分辨率图像，请将此方法应用于 一个copy() 的原始图像。

参数

• size -- 请求的大小。

• resample -- 可选的重新采样过滤器。这可能是 PIL.Image.NEAREST ， PIL.Image.BILINEAR ， PIL.Image.BICUBIC 或 PIL.Image.LANCZOS . 如果省略，则默认为 PIL.Image.BICUBIC . 是 PIL.Image.NEAREST 2.5.0之前的版本）。

• reducing_gap --  通过分两步调整图像大小来应用优化。首先，使用​reduce()​或 ​draft()​对于 JPEG 图像将图像缩小整数倍。其次，使用常规重采样调整大小。最后一步改变大小不少于reducing_gap次。 reducing_gap可以是 ​None​（不执行第一步）或应该大于 1.0。reducing_gap越大，结果越接近公平重采样。reducing_gap越小，调整大小越快。随着reducing_gap大于或等于3.0，结果是公平的，从在大多数情况下重采样难以区分。默认值为 2.0（非常接近公平重采样，但在许多情况下仍然更快）。

返回

None

​Image.tobitmap(name='image')​

返回转换为x11位图的图像。

此方法仅适用于模式“1”图像。

参数

name -- 用于位图变量的名称前缀。

返回

包含x11位图的字符串。

引发

​ValueError​ -- 如果模式不是“1”

​Image.tobytes(encoder_name='raw', *args)​

以字节对象的形式返回图像。

此方法从内部存储器返回原始图像数据。对于压缩图像数据（如PNG、JPEG），请使用​ save() ​，内存中的数据带有一个​BytesIO​参数。

参数

• encoder_name -- 使用什么编码器。默认使用标准的“原始”编码器。

• args -- 编码器的额外参数。

返回类型

一个 ​bytes ​对象

Image.transform(size, method, data=None, resample=0, fill=1, fillcolor=None)

转换此图像。此方法创建具有给定大小和与原始图像相同模式的新图像，并使用给定的转换将数据复制到新图像。

参数

• size -- 输出大小。

• method -- 转换方法。这是其中之一 PIL.Image.EXTENT （切出矩形子区域） PIL.Image.AFFINE （仿射变换） PIL.Image.PERSPECTIVE （透视变换） PIL.Image.QUAD （将四边形映射到矩形），或 PIL.Image.MESH （在一个操作中映射多个源四边形）。它也可能是一个​ImageTransformHandler​ 对象：

  class Example(Image.ImageTransformHandler):
      def transform(self, size, data, resample, fill=1):
          # Return result

  它也可能是一个对象，其​method.getdata​方法返回一个提供 new​method​和​data​值的元组：

  class Example:
      def getdata(self):
          method = Image.EXTENT
          data = (0, 0, 100, 100)
          return method, data

• data -- 转换方法的额外数据。

• resample -- 可选的重新采样过滤器。它可以是 PIL.Image.NEAREST （使用最近邻算法） PIL.Image.BILINEAR （2x2环境中的线性插值），或 PIL.Image.BICUBIC （4x4环境中的三次样条插值）。如果省略，或者图像具有模式“1”或“P”，则设置为 PIL.Image.NEAREST 。

• fill -- 如果​ method ​是一个 ImageTransformHandler 对象，这是传递给它的参数之一。否则，它是未使用的。

• fillcolor -- 输出图像中转换外部区域的可选填充颜色。

返回

一个Image 对象。

​Image.transpose(method)​

转置图像（以90度的步幅翻转或旋转）

参数

method -- 其中一个 PIL.Image.FLIP_LEFT_RIGHT ， PIL.Image.FLIP_TOP_BOTTOM ， PIL.Image.ROTATE_90 ， PIL.Image.ROTATE_180 ， PIL.Image.ROTATE_270 ， PIL.Image.TRANSPOSE 或 PIL.Image.TRANSVERSE 。

返回

返回此图像的翻转或旋转副本。

这将使用FLIP_LEFT_RIGHT方法翻转输入图像。

from PIL import Image

im = Image.open("hopper.jpg")

# Flip the image from left to right
im_flipped = im.transpose(method=Image.FLIP_LEFT_RIGHT)
# To flip the image from top to bottom,
# use the method "Image.FLIP_TOP_BOTTOM"

​Image.verify()​

验证文件的内容。对于从文件读取的数据，此方法尝试确定文件是否已损坏，而不实际解码图像数据。如果此方法发现任何问题，则会引发适当的异常。如果使用此方法后需要加载图像，则必须重新打开图像文件。

​Image.load()​

为图像分配存储空间并加载像素数据。在正常情况下，不需要调用此方法，因为当首次访问打开的图像时，Image类会自动加载该图像。

如果与图像相关联的文件是通过 Pillow 打开的，那么此方法将关闭它。例外情况是如果图像有多个帧，在这种情况下，文件将保持打开状态以进行查找操作。

返回

一个图像访问对象。

返回类型

PixelAccess Class 或者 PIL.PyAccess

​Image.close()​

如果可能，关闭文件指针。

此操作将破坏图像核心并释放其内存。之后图像数据将无法使用。

此函数仅用于关闭未被 load() 方法。