如何修复PIL库paste方法报'value error bad transparency mask'错误

该报错触发自PIL内部Image类的paste方法源码第1525行，调用底层粘贴接口时掩码参数校验不通过导致，核心触发原因和修复方案如下：

核心触发原因 #

• 尺寸不匹配：传入的mask图像尺寸，与待粘贴的源图像im尺寸、box参数划定的粘贴区域尺寸三者不统一
• 模式不合法：mask的图像模式不符合要求，仅支持1（二值图）、L（8位灰度图）、RGBA三类模式
• 实例非法：传入的mask是未正确加载、或者已被释放的无效Image实例

修复方案 #

1. 对齐粘贴尺寸 #

粘贴前先手动校验并对齐相关尺寸，避免尺寸偏差：

# 场景1：仅指定粘贴左上角坐标，要保证mask和源图im尺寸一致
if mask.size != im.size:
    mask = mask.resize(im.size)
base_img.paste(im, (x_offset, y_offset), mask=mask)

# 场景2：指定4元素box划定粘贴区域，要保证box宽高和im、mask宽高一致
paste_box = (10, 10, 110, 110) # 宽100、高100
paste_w = paste_box[2] - paste_box[0]
paste_h = paste_box[3] - paste_box[1]
im = im.resize((paste_w, paste_h))
mask = mask.resize((paste_w, paste_h))
base_img.paste(im, paste_box, mask=mask)

2. 转换掩码为合法模式 #

粘贴前统一把掩码转换为兼容性最好的8位灰度模式L：

# 统一转换掩码模式
mask = mask.convert("L")

# 如果直接用源图的alpha通道作为掩码，可直接提取无需额外构造
if im.mode == "RGBA":
    mask = im.split()[-1]
base_img.paste(im, (x_offset, y_offset), mask=mask)

3. 校验掩码实例合法性 #

粘贴前先判断掩码是否是有效Image实例，避免传入无效对象：

from PIL import Image
if isinstance(mask, Image.Image):
    base_img.paste(im, (x_offset, y_offset), mask=mask)
else:
    # 无合法掩码时不带mask参数执行粘贴
    base_img.paste(im, (x_offset, y_offset))

内容的提问来源于stack exchange，提问作者Martha R