ImageFilter Module

The ImageFilter module contains definitions for a number of predefined image enhancement and convolution filters, which can be applied with the Image.filter() method.

Basic Usage

from PIL import Image, ImageFilter img = Image.open("photo.jpg") # Apply Gaussian blur blurred = img.filter(ImageFilter.GaussianBlur(radius=2)) # Apply predefined sharpen sharpened = img.filter(ImageFilter.SHARPEN) # Find edges edges = img.filter(ImageFilter.FIND_EDGES)

Blur Filters

Filter	Parameters	Description
`BLUR`	—	Simple box blur kernel. Equivalent to BoxBlur with small radius.
`GaussianBlur(radius=2)`	`radius`: float or (x,y) tuple	Gaussian blur using a weighted kernel. Higher radius = more blur. Most realistic blur for photography.
`BoxBlur(radius)`	`radius`: float or (x,y) tuple	Each output pixel is the average of the square neighbourhood. Faster than Gaussian for large radii.

Background Blur Effect

# Blur a background while keeping subject sharp (simple version) background = img.filter(ImageFilter.GaussianBlur(radius=10)) # Blur with asymmetric radius (x=0 horizontal only, y=5 vertical) motion_blur = img.filter(ImageFilter.BoxBlur(radius=(0, 5)))

Edge Detection Filters

Filter	Description
`CONTOUR`	Find image contours. Produces a white image with dark contour lines.
`EDGE_ENHANCE`	Enhance edges. Subtle — creates a look similar to slight over-sharpening.
`EDGE_ENHANCE_MORE`	More aggressive edge enhancement.
`FIND_EDGES`	Detects sharp edges. Produces a black image with white edge lines. Good for preprocessing for OCR or CV.
`EMBOSS`	Emboss the image. Creates a raised relief effect.

Sharpening Filters

Filter	Parameters	Description
`DETAIL`	—	Enhance in-image details.
`SHARPEN`	—	Sharpen the image.
`SMOOTH`	—	Smooth the image.
`SMOOTH_MORE`	—	More aggressive smoothing.
`UnsharpMask(radius=2, percent=150, threshold=3)`	`radius`, `percent`, `threshold`	Unsharp mask (USM). The industry standard sharpening technique. Radius: blur radius for edge detection. Percent: strength of sharpening (0–500%). Threshold: minimum pixel difference to sharpen.

Unsharp Mask Example

# Standard USM for photo sharpening sharpened = img.filter(ImageFilter.UnsharpMask( radius=2, percent=150, threshold=3 ))

Rank Filters

Rank filters pick a specific ranked pixel value from a neighbourhood. Useful for noise reduction and morphological operations.

Filter	Description
`MedianFilter(size=3)`	Picks the median pixel in the neighbourhood. Excellent for removing "salt and pepper" noise without blurring edges.
`MinFilter(size=3)`	Picks the minimum (darkest) pixel. Acts as morphological erosion.
`MaxFilter(size=3)`	Picks the maximum (brightest) pixel. Acts as morphological dilation.
`RankFilter(size, rank)`	General rank filter. `rank=0` = Min, `rank=sizesize//2` = Median, `rank=sizesize-1` = Max.

Custom Kernel Filter

Create arbitrary convolution kernels with ImageFilter.Kernel(). The kernel is a flat list of values applied over a square neighbourhood.

Parameter	Type	Description
`size`	tuple[int,int]	Kernel size — must be odd, e.g., `(3,3)` or `(5,5)`.
`kernel`	sequence	A sequence of `size[0]*size[1]` kernel weights. Listed from top-left, row by row.
`scale`	int	Divisor applied to the output. Usually the sum of the kernel weights.
`offset`	int	Added to each output value after scaling.

Custom Kernel Examples

# Laplacian edge detection kernel laplacian = ImageFilter.Kernel( size=(3, 3), kernel=[0, -1, 0, -1, 4, -1, 0, -1, 0], scale=1, offset=128 # Offset to make 0-diff appear gray ) edges = img.convert("L").filter(laplacian) # Identity kernel (does nothing) identity = ImageFilter.Kernel((3,3), [0,0,0,0,1,0,0,0,0], scale=1)

All Predefined Filters

Filter Constant	Type
`BLUR`	Predefined
`CONTOUR`	Predefined
`DETAIL`	Predefined
`EDGE_ENHANCE`	Predefined
`EDGE_ENHANCE_MORE`	Predefined
`EMBOSS`	Predefined
`FIND_EDGES`	Predefined
`SHARPEN`	Predefined
`SMOOTH`	Predefined
`SMOOTH_MORE`	Predefined
`GaussianBlur(radius=2)`	Parameterizable
`BoxBlur(radius)`	Parameterizable
`UnsharpMask(radius=2, percent=150, threshold=3)`	Parameterizable
`Kernel(size, kernel, scale, offset=0)`	Custom convolution
`RankFilter(size, rank)`	Rank
`MedianFilter(size=3)`	Rank
`MinFilter(size=3)`	Rank
`MaxFilter(size=3)`	Rank
`ModeFilter(size=3)`	Rank
`Color3DLUT(size, table)`	3D LUT colour transform
`MultibandFilter`	Base class for multi-band filters
`BuiltinFilter`	Base class for built-in filters
`Filter`	Abstract base class