阅读(1.7k) 书签赞(0) 我要纠错

Pillow Image图像类

2021-07-12 17:56 更新

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方法返回一个提供 newmethod和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"