下面给你一个 Pillow（PIL Fork）中 ImageFilter 模块 的完整入门指南，包含所有内置滤镜、用法、代码示例、自定义滤镜方法以及常见应用场景。
（基于 Pillow ≥ 9.0，Python 3.8+）
1. 安装 Pillow
pip install --upgrade pillow
2. 基本导入
from PIL import Image, ImageFilter
3. 所有内置滤镜一览
| 滤镜名称 | 说明 | 参数 |
|---|
BLUR | 标准模糊 | 无 |
CONTOUR | 提取轮廓（边缘检测） | 无 |
DETAIL | 增强细节 | 无 |
EDGE_ENHANCE | 边缘增强 | 无 |
EDGE_ENHANCE_MORE | 更强边缘增强 | 无 |
EMBOSS | 浮雕效果 | 无 |
FIND_EDGES | 边缘检测（类似 Sobel） | 无 |
SHARPEN | 锐化 | 无 |
SMOOTH | 平滑 | 无 |
SMOOTH_MORE | 更强平滑 | 无 |
GaussianBlur(radius) | 高斯模糊 | radius（浮点数） |
BoxBlur(radius) | 方框模糊（更快） | radius（整数） |
UnsharpMask(radius, percent, threshold) | 反锐化蒙版 | 三个参数 |
Kernel(size, kernel, scale=None, offset=0) | 自定义卷积核 | 自定义 |
RankFilter(size, rank) | 排序滤镜（如中值） | size 为邻域大小 |
MedianFilter(size=3) | 中值滤镜（去噪） | size 奇数 |
MinFilter(size=3) | 最小值滤镜 | size |
MaxFilter(size=3) | 最大值滤镜 | size |
ModeFilter(size=3) | 众数滤镜 | size |
4. 基础用法：image.filter(filter)
img = Image.open("input.jpg")
# 高斯模糊
blurred = img.filter(ImageFilter.GaussianBlur(radius=5))
# 锐化
sharpened = img.filter(ImageFilter.SHARPEN)
# 边缘检测
edges = img.filter(ImageFilter.FIND_EDGES)
blurred.save("blurred.jpg")
sharpened.save("sharpened.jpg")
edges.save("edges.jpg")
5. 常用滤镜详解 + 示例
5.1 高斯模糊 GaussianBlur
img.filter(ImageFilter.GaussianBlur(radius=3)) # radius 越大越模糊
5.2 方框模糊 BoxBlur（速度快）
img.filter(ImageFilter.BoxBlur(radius=2)) # radius 必须是整数
5.3 反锐化蒙版 UnsharpMask
# radius: 模糊半径
# percent: 增强百分比 (100~500 常见)
# threshold: 仅对差异大于此值的像素增强
sharp = img.filter(ImageFilter.UnsharpMask(radius=2, percent=150, threshold=3))
5.4 自定义卷积核 Kernel
# 3x3 拉普拉斯边缘检测
kernel = ImageFilter.Kernel(
size=(3, 3),
kernel=(0, -1, 0, -1, 4, -1, 0, -1, 0),
scale=1,
offset=0
)
edges = img.filter(kernel)
常用卷积核示例：
| 效果 | 3×3 卷积核 |
|---|
| 身份（原图） | [0,0,0, 0,1,0, 0,0,0] |
| 均值模糊 | [1,1,1, 1,1,1, 1,1,1] → scale=1/9 |
| 边缘检测 | [0,-1,0, -1,4,-1, 0,-1,0] |
| 浮雕 | [-2,-1,0, -1,1,1, 0,1,2] |
6. 高级技巧
6.1 多重滤镜叠加
result = img.filter(ImageFilter.GaussianBlur(1)) \
.filter(ImageFilter.UnsharpMask(radius=1, percent=200, threshold=5))
6.2 局部滤镜（只处理部分区域）
mask = Image.new("L", img.size, 0) # 全黑掩码
draw = ImageDraw.Draw(mask)
draw.ellipse((100, 100, 300, 300), fill=255) # 圆形白区域
blurred = img.filter(ImageFilter.GaussianBlur(10))
result = Image.composite(blurred, img, mask) # 圆内模糊，外面原图
6.3 中值滤镜去椒盐噪声
noisy_img = Image.open("noisy.jpg")
denoised = noisy_img.filter(ImageFilter.MedianFilter(size=3))
7. 自定义滤镜类（继承 ImageFilter.Filter）
from PIL import ImageFilter
class CustomEmbossFilter(ImageFilter.Filter):
name = "CustomEmboss"
def filter(self, image):
return image.filter(ImageFilter.Kernel(
(3, 3),
(-2, -1, 0, -1, 1, 1, 0, 1, 2),
scale=1, offset=128
))
# 使用
img.filter(CustomEmbossFilter())
8. 完整示例：图片特效合集
from PIL import Image, ImageFilter, ImageDraw
import os
def apply_filters(input_path, output_dir):
os.makedirs(output_dir, exist_ok=True)
img = Image.open(input_path).convert("RGB")
filters = {
"原图": None,
"模糊": ImageFilter.GaussianBlur(3),
"锐化": ImageFilter.SHARPEN,
"边缘": ImageFilter.FIND_EDGES,
"浮雕": ImageFilter.EMBOSS,
"轮廓": ImageFilter.CONTOUR,
"反锐化": ImageFilter.UnsharpMask(2, 150, 3),
"中值去噪": ImageFilter.MedianFilter(3),
}
for name, filt in filters.items():
if filt is None:
result = img.copy()
else:
result = img.filter(filt)
result.save(f"{output_dir}/{name}.jpg")
# 使用
apply_filters("cat.jpg", "filters_output")
9. 性能优化建议
| 场景 | 建议 |
|---|
| 大图处理 | 先 resize 缩小，再滤镜，最后放大 |
| 批量处理 | 使用 BoxBlur 替代 GaussianBlur |
| 实时预览 | 使用 image.filter() + thumbnail 快速反馈 |
10. 常见问题
| 问题 | 解决 |
|---|
AttributeError: module 'PIL.ImageFilter' has no attribute 'XXX' | 检查 Pillow 版本，MedianFilter 在 5.3.0+ |
| 滤镜后图像变暗/变亮 | 使用 offset 参数（如浮雕加 offset=128） |
| 自定义核不生效 | scale 必须正确（如均值模糊 scale=1/9） |
官方参考
- https://pillow.readthedocs.io/en/stable/reference/ImageFilter.html
- 滤镜源码：https://github.com/python-pillow/Pillow/blob/main/src/PIL/ImageFilter.py
需要我帮你实现 艺术滤镜（如卡通、油画）、人像磨皮、智能边缘保留模糊 等高级效果吗？直接说需求，我给你完整代码！