Pillow 常用函数手册

Pillow 库提供了从图像读取、创建和保存，到尺寸调整、颜色模式转换、滤镜处理与图像合成的一系列功能。图形绘制、文字标注和像素统计等操作，也可以通过相应接口完成。

这些功能分布在不同模块中。本文按模块整理常用接口，说明其用途、主要参数、返回值与使用方法，形成一份便于检索、对照和反复查阅的基础手册。

Pillow 是 Python 图像库 PIL 的后继项目，代码中仍以 PIL 作为导入名称。

安装：

pip install Pillow

本文的示例按条目独立运行。需要读取图片时，应将"photo.jpg"替换为实际文件路径；涉及字体时，应使用本机可读取且支持所需文字的字体文件。与 NumPy 互转的示例需要另行安装 NumPy。

下文给出常见写法与主要参数，不逐项展开所有可选参数。Image.open()等写法调用模块函数；img.resize()等写法调用图像对象的方法；ImageFilter.Kernel()等写法用于创建处理对象。

一、Image：图像创建与基本处理

Image 模块是图像处理的核心模块，既提供图像读取与创建函数，也定义了图像对象及其常用方法。读取、变换、像素访问和合成等基础操作，大多从这里开始。

1、图像读取、创建与输出

open()

用于读取图像文件，并建立图像对象。

Image.open(fp, mode="r", formats=None)

参数说明：

• fp：文件路径，或以二进制方式打开的文件对象

• mode：打开方式，目前使用 "r"，表示读取

• formats：限制尝试识别的文件格式，例如 ["JPEG", "PNG"]；省略时尝试已支持的格式

返回值：返回一个图像对象。

示例：

open() 采用延迟加载，通常先识别文件与读取基本信息，像素数据在实际使用时才加载。使用 with 可以在操作完成后关闭文件。size、mode 和 format 是属性，不是函数。

new()

用于创建指定模式、尺寸和底色的图像，常用于建立空白画布、背景或蒙版。

Image.new(mode, size, color=0)

参数说明：

• mode：图像模式，例如 "L"、"RGB" 或 "RGBA"

• size：图像尺寸，形式为（宽，高），单位为像素

• color：初始颜色，可使用颜色名称、十六进制字符串，或与模式对应的数值、元组

返回值：返回一个新图像对象。

示例：

RGB 使用三个颜色通道；RGBA 多一个透明度通道。在 8 位透明度通道中，0 表示完全透明，255 表示完全不透明。

save()

用于将图像对象保存为文件。

img.save(fp, format=None, **params)

参数说明：

• fp：输出文件路径，或可写入的文件对象

• format：输出格式，例如 "PNG"、"JPEG"；使用文件路径时，通常可由扩展名判断

• **params：特定格式的保存参数，例如 JPEG 的 quality、PNG 的 compress_level

返回值：None，不返回新图像。

示例：

保存不会自动改变原文件，除非指定了相同路径。JPEG 不支持透明度；将透明图像直接转为 RGB 会丢弃透明度，如需指定背景，应先完成背景合成。quality 是 JPEG 编码质量参数，不是图像分辨率。

show()

用于临时预览图像，通常借助系统中的外部图像查看程序。

img.show(title=None)

参数说明：

• title：预览标题，实际是否显示取决于查看程序

返回值：None。

示例：

show() 适合调试与临时检查。在没有图形界面的环境中，应使用 save() 保存结果。它也不是在应用程序中嵌入图像界面的替代方案。

copy()

用于复制图像，得到可以独立修改的图像对象。

img.copy()

参数说明：不需要额外参数

返回值：返回图像副本。

示例：

copy() 适合在保留原图的同时进行原地修改。副本的像素数据独立，也可以在原文件关闭后继续使用。

close()

用于关闭图像并释放相关资源。

img.close()

参数说明：不需要额外参数

返回值：None。

示例：

关闭后，不应继续使用该对象进行像素处理。读取文件时，通常优先使用 with；批量处理图像时，尤其需要注意及时释放资源。

2、裁剪与几何变换

crop()

用于截取图像中的矩形区域。

img.crop(box=None)

参数说明：

• box：裁剪范围，形式为（左，上，右，下）

返回值：返回裁剪后的新图像。

示例：

右边界和下边界不包含在结果中，因此示例输出尺寸为（300，200）。图像坐标以左上角为原点，向右 x 增大，向下 y 增大。实际裁剪时，应先确认图像尺寸与所需区域。

resize()

用于将图像调整为指定尺寸。

img.resize(size, resample=None, box=None, reducing_gap=None)

参数说明：

• size：目标尺寸，形式为（宽，高）

• resample：重采样（Resampling）方法

• box：参与缩放的原图区域，省略时使用整张图像

• reducing_gap：大幅缩小时的优化参数，基础使用中可省略

常见重采样方法：

• Image.Resampling.NEAREST：最近邻，不混合相邻像素，常用于类别标签图或像素风格图像

• Image.Resampling.BILINEAR：双线性插值，速度与平滑效果较均衡

• Image.Resampling.BICUBIC：双三次插值，通常具有更平滑的效果

• Image.Resampling.LANCZOS：常用于照片缩小，兼顾细节与平滑效果

返回值：返回指定尺寸的新图像。

示例：

目标宽高比与原图不同时，画面会变形。若需保持比例，可使用 thumbnail() 或 ImageOps 中的尺寸适配函数。

thumbnail()

用于生成不超过指定尺寸、并保持原图比例的缩略图。

)

参数说明：

• size：允许的最大宽度和高度

• resample：重采样方法

• reducing_gap：缩小时的优化参数

返回值：None，直接修改当前图像对象。

示例：

thumbnail() 不会为达到目标尺寸而放大小图，也不保证输出尺寸恰好等于传入尺寸。不能写成 result = img.thumbnail(...)，否则 result 会得到 None。

rotate()

用于按指定角度旋转图像。

)

参数说明：

• angle：旋转角度，单位为度，正值表示逆时针旋转

• resample：重采样方法，支持 NEAREST、BILINEAR、BICUBIC

• expand：是否扩大输出画布以容纳旋转结果

• center：旋转中心，省略时使用图像中心

• translate：旋转后的平移量，形式为（水平位移，垂直位移）

• fillcolor：旋转产生的空白区域颜色

返回值：返回旋转后的新图像。

示例：

expand=False 时，旋转后超出原画布的内容可能被裁掉。需要简单翻转或旋转 90° 的整数倍时，也可以使用 transpose()。

transpose()

用于左右翻转、上下翻转或按固定角度旋转图像。

img.transpose(method)

参数说明：

• method：变换方式

常见选项：

• Image.Transpose.FLIP_LEFT_RIGHT：左右翻转

• Image.Transpose.FLIP_TOP_BOTTOM：上下翻转

• Image.Transpose.ROTATE_90：逆时针旋转 90°

• Image.Transpose.ROTATE_180：旋转 180°

• Image.Transpose.ROTATE_270：逆时针旋转 270°

返回值：返回变换后的新图像。

示例：

图像对象的 transpose() 表示像素位置变换，其参数与 NumPy 数组的转置用法不同。

3、模式转换与像素访问

convert()

用于转换图像的像素表示模式。

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

参数说明：

• mode：目标模式，例如 "L"、"RGB"、"RGBA"

• matrix：特定颜色转换使用的转换矩阵，基础使用中通常省略

• dither：特定降色转换中的抖动处理方式

• palette：转换为调色板模式时的调色板策略

• colors：使用自适应调色板时的颜色数量

返回值：返回模式转换后的新图像。

示例：

模式与文件格式不同。convert("L") 改变像素表示方式，save("gray.png") 则指定文件编码。转为 RGBA 也不表示自动去除背景。

split()/merge()

split() 用于拆分颜色通道，merge() 用于将单通道图像组合成多通道图像。

Image.merge(mode, bands)

参数说明：

• mode：合并后的目标模式，例如 "RGB"

• bands：单通道图像组成的序列，数量需与目标模式匹配，各通道尺寸应一致

返回值：

• split() 返回由各通道图像组成的元组。

• merge() 返回合并后的新图像。

示例：

拆出的 RGB 通道是单通道图像，单独显示时表现为灰度。通道分离常用于观察颜色分布或进行分通道处理。

getpixel()/putpixel()

用于读取或修改指定位置的像素。

img.putpixel(xy, value)

参数说明：

• xy：像素坐标，形式为（x，y）

• value：新像素值。L 模式通常使用整数；RGB 模式使用三元组；RGBA 模式使用四元组

返回值：

• getpixel() 返回该位置的像素值。

• putpixel() 返回 None，直接修改当前图像。

示例：

这组方法适合检查少量像素。大规模像素计算通常更适合使用 NumPy 数组，避免逐像素 Python 循环。

point()

用于按照映射规则逐像素转换数值，可用于阈值处理或简单亮度映射。

img.point(lut, mode=None)

参数说明：

• lut：查找表（Lookup Table），或用于生成映射表的函数

• mode：输出模式，基础使用中通常省略

返回值：返回映射后的新图像。

示例：

示例得到只有 0 和 255 两种值的 L 模式图像，并不是自动转换为 1 模式。point() 根据当前像素值进行映射，不进行邻域加权计算。

histogram()

用于统计各像素值出现的次数。

img.histogram(mask=None, extrema=None)

参数说明：

• mask：可选蒙版（Mask），用于限定统计区域

• extrema：某些模式下的统计范围，普通 8 位图像通常不必设置

返回值：返回计数列表。

示例：

8 位灰度图像通常返回 256 个计数。RGB 图像返回三个通道直方图的顺序拼接，共 768 个计数。它返回统计数据，不会直接绘制直方图。

fromarray()

用于将 NumPy 等数组接口对象转换为图像。

Image.fromarray(obj, mode=None)

参数说明：

• obj：具有数组接口的对象

• mode：目标模式，通常让 Pillow 根据数组结构与类型推断即可

返回值：返回图像对象。

示例：

本例需要通过 pip install numpy 安装 NumPy。数组形状为（高，宽，通道数），图像 size 为（宽，高）。普通 RGB 图像常使用 uint8 数组；浮点数或其他形状的数组不能一概当作普通彩色图像处理。

4、粘贴与图像合成

paste()

用于将图像或颜色粘贴到当前图像中。

img.paste(im, box=None, mask=None)

参数说明：

• im：待粘贴图像，或填充颜色

• box：目标位置，可为（左，上），或（左，上，右，下）

• mask：可选蒙版，用于控制各位置的粘贴程度

返回值：None，直接修改当前图像。

示例：

使用四元素区域粘贴图像时，其尺寸应与区域匹配。paste() 适合拼图、局部替换或按蒙版混合；需要保留正确的透明度叠加结果时，可使用 alpha_composite()。

blend()

用于按固定比例混合两张图像。

Image.blend(im1, im2, alpha)

参数说明：

• im1、im2：模式和尺寸相同的两张图像

• alpha：第二张图像的混合比例，常用范围为 0～1

返回值：返回混合后的新图像

示例：

alpha=0 得到第一张图，alpha=1 得到第二张图。这里是固定比例的像素插值，不是依据每张图像透明度通道完成叠加。

composite()

用于依据蒙版，将两张图像组合起来。

Image.composite(image1, image2, mask)

参数说明：

• image1、image2：模式和尺寸相同的两张图像

• mask：与图像尺寸一致的蒙版，可使用 "1"、"L" 或 "RGBA" 模式

返回值：返回合成后的新图像。

示例：

对于 L 模式蒙版，255 选择第一张图，0 选择第二张图，中间值按比例混合。蒙版控制的是选择与混合程度。

alpha_composite()

用于依据透明度通道，将一张图像叠加到另一张图像上。

Image.alpha_composite(im1, im2)

参数说明：

• im1：底层图像，模式为 RGBA 或 LA

• im2：上层图像，模式和尺寸必须与底层图像相同

返回值：返回透明度合成后的新图像。

示例：

这里介绍的是模块函数 Image.alpha_composite()。图像对象也有同名方法 img.alpha_composite(...)，但该方法会修改当前图像，不应混淆其返回值。

putalpha()

用于添加或替换图像的透明度通道。

img.putalpha(alpha)

参数说明：

• alpha：0～255 的整数，或与图像尺寸相同的单通道蒙版

返回值：None，直接修改当前图像。

示例：

整数控制整张图像的透明度；蒙版可以为不同位置设置不同透明度。需要保留透明效果时，应保存为支持透明度的格式，例如 PNG。

二、ImageOps：常用图像操作

ImageOps 模块将方向校正、保持比例的尺寸适配，以及一些常见像素变换封装为模块函数，适合简化图像预处理代码。

exif_transpose()

用于根据照片中的 EXIF 方向信息校正像素方向。

ImageOps.exif_transpose(image, in_place=False)

参数说明：

• image：待处理图像

• in_place：是否原地修改，默认为 False

返回值：默认返回处理后的图像；in_place=True 时修改原对象并返回 None。

示例：

某些照片只记录了方向标记，而没有实际旋转像素。裁剪或统一尺寸之前先校正方向，有助于避免坐标和显示方向不一致。该操作还会移除已应用的方向标记，避免重复旋转。

mirror()/flip()

用于左右翻转或上下翻转图像。

ImageOps.flip(image)

参数说明：

• image：输入图像

返回值：返回翻转后的新图像。

示例：

mirror() 对应左右翻转，flip() 对应上下翻转。这两个函数表达更直观，也可以用 Image 中的 transpose() 完成。

contain()

用于保持原图比例，将图像调整到目标尺寸范围之内。

)

参数说明：

• image：输入图像

• size：允许的最大宽度和高度

• method：重采样方法

返回值：返回缩放后的新图像。

示例：

contain() 不裁剪也不补边，因此输出尺寸可能小于目标尺寸。与 thumbnail() 不同，它返回新图像，而且可能放大较小的原图。

fit()

用于保持比例缩放并裁剪，得到指定尺寸的图像。

)

参数说明：

• image：输入图像

• size：目标输出尺寸

• method：重采样方法

• bleed：先从四周去除的边缘比例，默认为 0，取值应小于 0.5

• centering：裁剪位置，两个数分别控制水平与垂直方向，取值范围为 0～1

返回值：返回指定尺寸的新图像。

示例：

默认从中心裁剪。fit() 可以避免直接拉伸，但会舍弃部分画面，可能裁掉边缘处的主体。

pad()

用于保持比例缩放并补边，得到指定尺寸的图像。

)

参数说明：

• image：输入图像

• size：目标输出尺寸

• method：重采样方法

• color：补边颜色

• centering：缩放后图像在目标画布中的位置

返回值：返回指定尺寸的新图像。

示例：

pad() 保留完整画面，但会引入补边。模型输入需要固定尺寸时，应根据任务要求选择 fit() 或 pad()，并保持训练与推理时的处理方式一致。

grayscale()/invert()

grayscale() 用于转为灰度图像，invert() 用于反转像素值。

ImageOps.invert(image)

参数说明：

• image：输入图像。本例使用 RGB 或 L 图像

返回值：返回处理后的新图像。

示例：

grayscale() 返回 L 模式图像。对 8 位灰度值，反转相当于用 255 减去原值。RGBA 图像不能直接套用本例的 invert()，需要单独处理颜色与透明度通道。

autocontrast()

自动对比度，用于依据图像直方图扩展明暗范围。

)

参数说明：

• image：输入图像，常使用 L 或 RGB 模式

• cutoff：从直方图低端和高端忽略的像素百分比，可使用单个数或二元组

• ignore：不参与范围估计的像素值

• mask：用于限定范围估计区域的蒙版

• preserve_tone：是否采用保持色调的处理方式

返回值：返回调整后的新图像。

示例：

cutoff=1 表示在低端与高端各忽略 1% 的像素，以减弱极端值对范围估计的影响。它与按固定系数调整对比度的 ImageEnhance.Contrast() 不同。

equalize()

用于直方图均衡化（Histogram Equalization），重新分配像素值，以调整明暗层次。

ImageOps.equalize(image, mask=None)

参数说明：

• image：输入图像，常使用 L 或 RGB 模式

• mask：可选蒙版，用于限定参与直方图统计的区域

返回值：返回均衡化后的新图像。

示例：

均衡化可能增强部分细节，也可能放大噪声。直接对 RGB 图像处理还可能改变颜色表现，因此应结合具体任务判断。

expand()

用于在图像四周添加边框。

ImageOps.expand(image, border=0, fill=0)

参数说明：

• image：输入图像

• border：边框宽度，可使用整数，或（左，上，右，下）四元组

• fill：边框颜色

返回值：返回扩展后的新图像。

示例：

expand() 添加固定像素宽度的边框，不会自动缩放原图。pad() 则围绕目标输出尺寸进行缩放与补边。

三、ImageFilter：模糊、锐化与邻域滤波

ImageFilter 模块提供预定义滤镜和可配置的滤镜类。一般先创建或选择滤镜，再通过图像对象的 filter() 方法应用。

filter()与预定义滤镜

用于将滤镜应用到图像。

img.filter(filter)

参数说明：

• filter：滤镜对象，或预定义滤镜

常见预定义滤镜：

• ImageFilter.BLUR：模糊

• ImageFilter.SHARPEN：锐化

• ImageFilter.SMOOTH / SMOOTH_MORE：平滑或较强平滑

• ImageFilter.DETAIL：增强细节

• ImageFilter.EDGE_ENHANCE / EDGE_ENHANCE_MORE：边缘增强

• ImageFilter.FIND_EDGES：突出局部边缘变化

• ImageFilter.CONTOUR：轮廓效果

• ImageFilter.EMBOSS：浮雕效果

返回值：filter() 返回处理后的新图像。

示例：

filter() 本身属于 Image 图像对象的方法，ImageFilter 提供它使用的滤镜。预定义滤镜适合快速获得效果；需要控制强度时，可选择带参数的滤镜。

BoxBlur()

用于盒式模糊（Box Blur），按照周围区域的平均值进行平滑。

ImageFilter.BoxBlur(radius)

参数说明：

• radius：模糊半径，可使用非负数，也可分别指定水平与垂直方向的半径

返回值：返回滤镜对象；传给 filter() 后得到新图像。

示例：

radius=0 不产生模糊；整数半径为 1 时，邻域为 3 × 3。半径增大通常会增强平滑效果，同时削弱更多细节。

GaussianBlur()

用于高斯模糊（Gaussian Blur），按随距离变化的权重进行平滑。

ImageFilter.GaussianBlur(radius=2)

参数说明：

• radius：高斯核的标准差，可使用非负数，也可分别指定两个方向

返回值：返回滤镜对象。

示例：

radius 通常越大，模糊程度越大。Pillow 使用扩展盒式滤波近似高斯核，并不是固定使用某个 3 × 3 矩阵。

MedianFilter()

用于中值滤波（Median Filtering），将邻域像素排序，并选取中间位置的值。

ImageFilter.MedianFilter(size=3)

参数说明：

• size：邻域边长，应使用正奇数，例如 3、5、7

返回值：返回滤镜对象。

示例：

中值滤波常用于减弱椒盐噪声。它采用排序规则，是非线性滤波，不是固定核权重的卷积。RGB 图像会按通道处理，结果不一定对应邻域中某个原有的完整颜色。

UnsharpMask()

USM 锐化，用于反锐化掩模（Unsharp Mask）锐化，通过原图与模糊图之间的差异增强细节。

ImageFilter.UnsharpMask(radius=2, percent=150, threshold=3)

参数说明：

• radius：生成模糊参考图时的半径

• percent：锐化强度，以百分数表示

• threshold：触发锐化所需的最小明暗变化，用于抑制轻微变化的增强

返回值：返回滤镜对象。

示例：

虽然名称包含“反锐化”，它实际用于锐化。过高的强度可能放大噪声或产生边缘光晕，不能把它理解为恢复所有丢失的细节。

Kernel()

用于创建自定义核，按邻域权重进行加权计算。

ImageFilter.Kernel(size, kernel, scale=None, offset=0)

参数说明：

• size：核尺寸，支持（3，3）和（5，5）

• kernel：按行排列、展平后的权重序列，数量需与核尺寸匹配

• scale：加权总和的除数；省略时使用权重之和

• offset：除以 scale 后增加的偏移量

返回值：返回自定义滤镜对象。

示例：

Kernel() 支持 L 和 RGB 图像。权重和为 0 的核应显式设置非零 scale，例如 scale=1。Pillow 应用前会将核上下翻转；无法完整应用核的边界像素保留原值。8 位输出会限制在 0～255，若需保留带符号或小数的响应，应使用数组进行计算。

四、ImageEnhance：亮度、对比度与颜色增强

ImageEnhance 模块使用统一接口调整图像表现：先建立增强对象，再调用 enhance()。各增强类用于创建增强对象，调用其 enhance() 方法后，才返回调整后的新图像。

Brightness()/Contrast()/Color()/Sharpness()

分别用于调整亮度、对比度、颜色强度和锐度。

ImageEnhance.Sharpness(image).enhance(factor)

参数说明：

• image：输入图像

• factor：调整系数，常用非负值；1 表示保持原有表现，小于 1 表示减弱，大于 1 表示增强

各类的含义：

• Brightness：factor=0 得到黑色图像，透明度通道在存在时保留

• Contrast：factor=0 得到均匀灰色的颜色内容

• Color：factor=0 去除颜色差异，呈现灰度效果

• Sharpness：factor=0 得到平滑结果，1 保持原图，大于 1 增强锐度

返回值：构造调用返回增强对象；enhance() 返回调整后的新图像。

示例：

示例中的四项分别作用于同一张原图。需要连续处理时，应把上一步的返回图像传给下一步。增强颜色不等于转换颜色模式，增强锐度也不等于提高像素尺寸。

五、ImageDraw：图形与文字绘制

ImageDraw 模块用于在图像上绘制线条、矩形、椭圆、多边形和文字。它通常直接修改所绑定的图像，而不是返回一张新图像。

Draw()

用于建立绘图对象。

ImageDraw.Draw(im, mode=None)

参数说明：

• im：准备绘制的图像

• mode：可选绘图模式；基础使用中通常省略。对 RGB 图像，可使用 "RGBA" 绘制带透明度混合的颜色

返回值：返回绘图对象。

示例：

绘图对象与 img 关联，后续绘制会改变 img 的像素。希望保留原图时，应先创建副本。

line()

用于绘制线段或折线。

draw.line(xy, fill=None, width=0, joint=None)

参数说明：

• xy：点坐标序列，可使用（x，y）元组组成的列表

• fill：线条颜色

• width：线宽，单位为像素

• joint：折线连接样式，可使用 "curve" 获得圆滑连接

返回值：None，直接绘制到图像。

示例：

多组点会依次连接，适合标记路径或添加引导线。需要图表坐标、刻度和图例时，通常使用 Matplotlib 更方便。

rectangle()/rounded_rectangle()

用于绘制矩形或圆角矩形。

draw.rounded_rectangle(xy, radius=0, fill=None, outline=None, width=1)

参数说明：

• xy：矩形范围，形式为（左，上，右，下）

• radius：圆角半径

• fill：填充颜色

• outline：边框颜色

• width：边框宽度

返回值：None。

示例：

rectangle() 的边界坐标包含端点，与 crop() 排除右、下边界的规则不同。给检测框或标注区域绘制边框时，应核对数据采用的坐标约定。

ellipse()/polygon()

用于绘制椭圆或多边形。

draw.polygon(xy, fill=None, outline=None, width=1)

参数说明：

• ellipse() 的 xy：椭圆外接矩形，形式为（左，上，右，下）

• polygon() 的 xy：多边形顶点坐标序列

• fill：填充颜色

• outline：边框颜色

• width：边框宽度

返回值：None。

示例：

椭圆的外接矩形宽高相同时，可绘制圆。多边形会自动连接首尾顶点，也常用于建立区域蒙版。

text()/multiline_text()

用于绘制单行或多行文字。

)

参数说明：

• xy：文字定位点

• text：文字内容，多行文字可使用换行符

• fill：文字颜色

• font：字体对象

• anchor：文字相对于定位点的位置。单行文字可用 "lt" 表示左上、"mm" 表示居中；横向多行文字不支持 "lt" 等包含顶部或底部定位的锚点，基础使用可保留默认值

• stroke_width / stroke_fill：文字描边宽度与颜色

• spacing：行间额外间距，单位为像素

• align：多行文字的行间对齐方式，例如 "left"、"center"、"right"

返回值：None。

示例：

中文显示取决于字体是否包含相应字形。align 控制多行文字之间的对齐，anchor 控制整段文字相对于 xy 的位置，两者作用不同。

textbbox()/textlength()

用于测量文字占用范围或排版推进长度。

draw.textlength(text, font=None)

参数说明：

• xy：用于测量文字边界的定位点

• text：待测量文字

• font：字体对象

• anchor：边界计算使用的文字定位方式

• stroke_width：计算边界时考虑的描边宽度

返回值：

• textbbox() 返回（左，上，右，下）。

• textlength() 返回文字的水平排版长度，通常为浮点数。

示例：

可见字形边界与排版推进长度不一定相同。边界宽高应使用 right-left、bottom-top 计算；多行文字的整体边界应使用 multiline_textbbox()。

六、ImageFont：字体加载与测量

ImageFont 负责创建字体对象，通常与 ImageDraw 配合使用。字体决定字形、字号与可显示的字符范围。

truetype()

用于读取 TrueType 或 OpenType 字体。

)

参数说明：

• font：字体文件路径，或可读取的字体文件对象

• size：字号，单位为像素

• index：字体集合中的字体索引，通常使用默认值 0

• encoding：字符编码设置，通常保留默认值

• layout_engine：文字布局引擎，基础使用中通常不必设置

返回值：返回 FreeTypeFont 字体对象。

示例：

示例使用 Windows 上常见的微软雅黑字体路径，运行前应确认文件存在。其他系统应改为实际字体路径。文件不可读取时会产生异常；缺少中文字形时，即使字体成功加载，也不能正确显示中文。

load_default()

用于加载 Pillow 提供的默认字体。

ImageFont.load_default(size=None)

参数说明：

• size：可选字号；可调整大小的默认字体需要 FreeType 支持

返回值：返回默认字体对象，具体类型取决于运行环境。

示例：

默认字体适合简单英文标注，不应假定它支持中文。需要中文或特定排版风格时，应加载合适的字体文件。

getbbox()/getlength()

用于通过字体对象测量文字。

font.getlength(text)

参数说明：

• text：待测量文字

返回值：

• getbbox() 返回文字相对于字体定位原点的边界四元组。

• getlength() 返回文字排版推进长度。

示例：

这组方法适合尚未建立画布时进行测量。已在画布上定位文字时，使用 ImageDraw 的 textbbox() 通常更直接。

七、ImageColor：颜色解析

ImageColor 模块用于把颜色名称或字符串转换为可计算的颜色值，也被图像创建和绘图操作内部使用。

getrgb()/getcolor()

getrgb() 解析颜色字符串；getcolor() 根据目标模式返回对应颜色值。

ImageColor.getcolor(color, mode)

参数说明：

• color：颜色名称或字符串，例如 "red"、""、"rgb(255, 0, 0)"

• mode：目标模式，例如 "RGB"、"RGBA"、"L"

返回值：

• getrgb() 通常返回 RGB 元组；字符串包含透明度时可返回 RGBA 元组。

• getcolor() 返回与目标模式对应的颜色值。

示例：

颜色字符串便于阅读，数值或元组便于计算。RGB 元组的通道值通常使用 0～255，而 Matplotlib 的浮点 RGB 元组常使用 0～1，不能直接混用。

八、ImageChops：逐像素图像运算

ImageChops 模块提供图像之间的逐像素运算，适合比较图像差异、组合蒙版或实现简单混合效果。下列示例使用模式和尺寸相同的 8 位图像。

difference()

用于计算两张图像对应像素的绝对差。

ImageChops.difference(image1, image2)

参数说明：

• image1、image2：待比较图像

返回值：返回差异图像。

示例：

相同位置的相同数值产生 0。差异图有助于观察处理改变了哪些区域，但不等于对图像质量的完整评价。

lighter()/darker()/multiply()

用于逐像素取较大值、较小值，或进行归一化乘法。

ImageChops.multiply(image1, image2)

参数说明：

• image1、image2：参与运算的两张图像

返回值：返回运算后的新图像。

示例：

对 8 位图像，multiply() 相当于对应值相乘后除以 255。白色不改变另一个输入，黑色使结果为黑。RGB 运算分别作用于各通道，不是比较整像素的视觉亮度。

九、ImageStat：图像基础统计

ImageStat 模块用于计算整张图像或指定区域的像素统计量，适合快速查看各通道的均值、标准差和取值情况。

Stat()

用于建立图像统计对象。

ImageStat.Stat(image_or_list, mask=None)

参数说明：

• image_or_list：输入图像，或预先计算的直方图列表

• mask：可选蒙版，用于限定统计区域

返回值：返回统计对象，结果通过属性读取。

常用属性：

• mean：各通道平均值

• median：各通道中位数

• stddev：各通道标准差

• var：各通道方差

• extrema：各通道最小值与最大值

• count：各通道参与统计的像素数量

示例：

RGB 图像的结果通常按红、绿、蓝顺序排列。ImageStat 的统计基于直方图，尤其适合每通道 8 位图像；高位深或浮点数据需要精确数值统计时，通常应转为 NumPy 数组处理。

小结

PIL 常用接口按模块分工，涵盖图像读写、尺寸变换、滤镜与增强、图形与文字绘制，以及颜色解析、像素运算和统计。使用时应核对图像模式、参数含义与返回值，尤其要区分创建新图像和原地修改。

“点赞有美意，赞赏是鼓励”