Skip to content
Back to top
View this page

# `ImageFilter` module

The `ImageFilter` module contains definitions for a pre-defined set of filters, which can be be used with the `Image.filter()` method.

## Example: Filter an image

    from PIL import ImageFilter

    im1 = im.filter(ImageFilter.BLUR)

    im2 = im.filter(ImageFilter.MinFilter(3))
    im3 = im.filter(ImageFilter.MinFilter)  # same as MinFilter(3)

## Filters

Pillow provides the following set of predefined image enhancement filters:

- BLUR

- CONTOUR

- DETAIL

- EDGE_ENHANCE

- EDGE_ENHANCE_MORE

- EMBOSS

- FIND_EDGES

- SHARPEN

- SMOOTH

- SMOOTH_MORE

class PIL.ImageFilter.Color3DLUT(size: int | tuple[int, int, int], table: Sequence[float] | Sequence[Sequence[int]] | NumpyArray, channels: int = 3, target_mode: str | None = None, **kwargs: bool)

  Three-dimensional color lookup table.

  Transforms 3-channel pixels using the values of the channels as coordinates in the 3D lookup table and interpolating the nearest elements.

  This method allows you to apply almost any color transformation in constant time by using pre-calculated decimated tables.

  Added in version 5.2.0.

  Parameters:

    - size – Size of the table. One int or tuple of (int, int, int). Minimal size in any dimension is 2, maximum is 65.

    - table – Flat lookup table. A list of `channels * size**3` float elements or a list of `size**3` channels-sized tuples with floats. Channels are changed first, then first dimension, then second, then third. Value 0.0 corresponds lowest value of output, 1.0 highest.

    - channels – Number of channels in the table. Could be 3 or 4. Default is 3.

    - target_mode – A mode for the result image. Should have not less than `channels` channels. Default is `None`, which means that mode wouldn’t be changed.

  classmethod generate(size: int | tuple[int, int, int], callback: Callable[[float, float, float], tuple[float, ...]], channels: int = 3, target_mode: str | None = None) → Color3DLUT

    Generates new LUT using provided callback.

    Parameters:

      - size – Size of the table. Passed to the constructor.

      - callback – Function with three parameters which correspond three color channels. Will be called `size**3` times with values from 0.0 to 1.0 and should return a tuple with `channels` elements.

      - channels – The number of channels which should return callback.

      - target_mode – Passed to the constructor of the resulting lookup table.

  transform(callback: Callable[..., tuple[float, ...]], with_normals: bool = False, channels: int | None = None, target_mode: str | None = None) → Color3DLUT

    Transforms the table values using provided callback and returns a new LUT with altered values.

    Parameters:

      - callback – A function which takes old lookup table values and returns a new set of values. The number of arguments which function should take is `self.channels` or `3 + self.channels` if `with_normals` flag is set. Should return a tuple of `self.channels` or `channels` elements if it is set.

      - with_normals – If true, `callback` will be called with coordinates in the color cube as the first three arguments. Otherwise, `callback` will be called only with actual color values.

      - channels – The number of channels in the resulting lookup table.

      - target_mode – Passed to the constructor of the resulting lookup table.

class PIL.ImageFilter.BoxBlur(radius: float | Sequence[float])

  Blurs the image by setting each pixel to the average value of the pixels in a square box extending radius pixels in each direction. Supports float radius of arbitrary size. Uses an optimized implementation which runs in linear time relative to the size of the image for any radius value.

  Parameters:

    radius –

    Size of the box in a direction. Either a sequence of two numbers for x and y, or a single number for both.

    Radius 0 does not blur, returns an identical image. Radius 1 takes 1 pixel in each direction, i.e. 9 pixels in total.

class PIL.ImageFilter.GaussianBlur(radius: float | Sequence[float] = 2)

  Blurs the image with a sequence of extended box filters, which approximates a Gaussian kernel. For details on accuracy see <https://www.mia.uni-saarland.de/Publications/gwosdek-ssvm11.pdf>

  Parameters:

    radius – Standard deviation of the Gaussian kernel. Either a sequence of two numbers for x and y, or a single number for both.

class PIL.ImageFilter.UnsharpMask(radius: float = 2, percent: int = 150, threshold: int = 3)

  Unsharp mask filter.

  See Wikipedia’s entry on digital unsharp masking for an explanation of the parameters.

  Parameters:

    - radius – Blur Radius

    - percent – Unsharp strength, in percent

    - threshold – Threshold controls the minimum brightness change that will be sharpened

class PIL.ImageFilter.Kernel(size: tuple[int, int], kernel: Sequence[float], scale: float | None = None, offset: float = 0)

  Create a convolution kernel. This only supports 3x3 and 5x5 integer and floating point kernels.

  Kernels can only be applied to “L” and “RGB” images.

  Parameters:

    - size – Kernel size, given as (width, height). This must be (3,3) or (5,5).

    - kernel – A sequence containing kernel weights. The kernel will be flipped vertically before being applied to the image.

    - scale – Scale factor. If given, the result for each pixel is divided by this value. The default is the sum of the kernel weights.

    - offset – Offset. If given, this value is added to the result, after it has been divided by the scale factor.

class PIL.ImageFilter.RankFilter(size: int, rank: int)

  Create a rank filter. The rank filter sorts all pixels in a window of the given size, and returns the `rank`’th value.

  Parameters:

    - size – The kernel size, in pixels.

    - rank – What pixel value to pick. Use 0 for a min filter, `size * size / 2` for a median filter, `size * size - 1` for a max filter, etc.

class PIL.ImageFilter.MedianFilter(size: int = 3)

  Create a median filter. Picks the median pixel value in a window with the given size.

  Parameters:

    size – The kernel size, in pixels.

class PIL.ImageFilter.MinFilter(size: int = 3)

  Create a min filter. Picks the lowest pixel value in a window with the given size.

  Parameters:

    size – The kernel size, in pixels.

class PIL.ImageFilter.MaxFilter(size: int = 3)

  Create a max filter. Picks the largest pixel value in a window with the given size.

  Parameters:

    size – The kernel size, in pixels.

class PIL.ImageFilter.ModeFilter(size: int = 3)

  Create a mode filter. Picks the most frequent pixel value in a box with the given size. Pixel values that occur only once or twice are ignored; if no pixel value occurs more than twice, the original pixel value is preserved.

  Parameters:

    size – The kernel size, in pixels.

class PIL.ImageFilter.Filter

  An abstract mixin used for filtering images (for use with `filter()`).

  Implementors must provide the following method:

  filter(self, image)

    Applies a filter to a single-band image, or a single band of an image.

    Returns:

      A filtered copy of the image.

class PIL.ImageFilter.MultibandFilter

  An abstract mixin used for filtering multi-band images (for use with `filter()`).

  Implementors must provide the following method:

  filter(self, image)

    Applies a filter to a multi-band image.

    Returns:

      A filtered copy of the image.