diff --git a/PIL/ImageFilter.py b/PIL/ImageFilter.py index c13f75bbc..ac8fe9f19 100644 --- a/PIL/ImageFilter.py +++ b/PIL/ImageFilter.py @@ -17,31 +17,28 @@ from functools import reduce + class Filter(object): pass -## -# Convolution filter kernel. class Kernel(Filter): + """ + Create a convolution kernel. The current version only + supports 3x3 and 5x5 integer and floating point kernels. - ## - # Create a convolution kernel. The current version only - # supports 3x3 and 5x5 integer and floating point kernels. - #

- # In the current version, kernels can only be applied to - # "L" and "RGB" images. - # - # @def __init__(size, kernel, **options) - # @param size Kernel size, given as (width, height). In - # the current version, this must be (3,3) or (5,5). - # @param kernel A sequence containing kernel weights. - # @param **options Optional keyword arguments. - # @keyparam scale Scale factor. If given, the result for each - # pixel is divided by this value. The default is the sum - # of the kernel weights. - # @keyparam offset Offset. If given, this value is added to the - # result, after it has been divided by the scale factor. + In the current version, kernels can only be applied to + "L" and "RGB" images. + + :param size: Kernel size, given as (width, height). In the current + version, this must be (3,3) or (5,5). + :param kernel: A sequence containing kernel weights. + :param scale: Scale factor. If given, the result for each pixel is + divided by this value. the default is the sum of the + kernel weights. + :param offset: Offset. If given, this value is added to the result, + after it has been divided by the scale factor. + """ def __init__(self, size, kernel, scale=None, offset=0): if scale is None: @@ -56,24 +53,23 @@ class Kernel(Filter): raise ValueError("cannot filter palette images") return image.filter(*self.filterargs) + class BuiltinFilter(Kernel): def __init__(self): pass -## -# Rank filter. class RankFilter(Filter): - name = "Rank" + """ + Create a rank filter. The rank filter sorts all pixels in + a window of the given size, and returns the **rank**'th value. - ## - # Create a rank filter. The rank filter sorts all pixels in - # a window of the given size, and returns the rank'th value. - # - # @param size The kernel size, in pixels. - # @param 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. + :param size: The kernel size, in pixels. + :param 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. + """ + name = "Rank" def __init__(self, size, rank): self.size = size @@ -85,99 +81,99 @@ class RankFilter(Filter): image = image.expand(self.size//2, self.size//2) return image.rankfilter(self.size, self.rank) -## -# Median filter. Picks the median pixel value in a window with the -# given size. class MedianFilter(RankFilter): - name = "Median" + """ + Create a median filter. Picks the median pixel value in a window with the + given size. - ## - # Create a median filter. - # - # @param size The kernel size, in pixels. + :param size: The kernel size, in pixels. + """ + name = "Median" def __init__(self, size=3): self.size = size self.rank = size*size//2 -## -# Min filter. Picks the lowest pixel value in a window with the given -# size. class MinFilter(RankFilter): - name = "Min" + """ + Create a min filter. Picks the lowest pixel value in a window with the + given size. - ## - # Create a min filter. - # - # @param size The kernel size, in pixels. + :param size: The kernel size, in pixels. + """ + name = "Min" def __init__(self, size=3): self.size = size self.rank = 0 -## -# Max filter. Picks the largest pixel value in a window with the -# given size. class MaxFilter(RankFilter): - name = "Max" + """ + Create a max filter. Picks the largest pixel value in a window with the + given size. - ## - # Create a max filter. - # - # @param size The kernel size, in pixels. + :param size: The kernel size, in pixels. + """ + name = "Max" def __init__(self, size=3): self.size = size self.rank = size*size-1 -## -# 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. class ModeFilter(Filter): - name = "Mode" + """ - ## - # Create a mode filter. - # - # @param size The kernel size, in pixels. + 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. + + :param size: The kernel size, in pixels. + """ + name = "Mode" def __init__(self, size=3): self.size = size + def filter(self, image): return image.modefilter(self.size) -## -# Gaussian blur filter. class GaussianBlur(Filter): + """Gaussian blur filter. + + :param radius: Blur radius. + """ name = "GaussianBlur" def __init__(self, radius=2): self.radius = radius + def filter(self, image): return image.gaussian_blur(self.radius) -## -# Unsharp mask filter. class UnsharpMask(Filter): + """Unsharp mask filter. + + See Wikipedia's entry on `digital unsharp masking`_ for an explanation of + the parameters. + + .. _digital unsharp masking: https://en.wikipedia.org/wiki/Unsharp_masking#Digital_unsharp_masking + """ name = "UnsharpMask" def __init__(self, radius=2, percent=150, threshold=3): self.radius = radius self.percent = percent self.threshold = threshold + def filter(self, image): return image.unsharp_mask(self.radius, self.percent, self.threshold) -## -# Simple blur filter. class BLUR(BuiltinFilter): name = "Blur" @@ -189,8 +185,6 @@ class BLUR(BuiltinFilter): 1, 1, 1, 1, 1 ) -## -# Simple contour filter. class CONTOUR(BuiltinFilter): name = "Contour" @@ -200,8 +194,6 @@ class CONTOUR(BuiltinFilter): -1, -1, -1 ) -## -# Simple detail filter. class DETAIL(BuiltinFilter): name = "Detail" @@ -211,8 +203,6 @@ class DETAIL(BuiltinFilter): 0, -1, 0 ) -## -# Simple edge enhancement filter. class EDGE_ENHANCE(BuiltinFilter): name = "Edge-enhance" @@ -222,8 +212,6 @@ class EDGE_ENHANCE(BuiltinFilter): -1, -1, -1 ) -## -# Simple stronger edge enhancement filter. class EDGE_ENHANCE_MORE(BuiltinFilter): name = "Edge-enhance More" @@ -233,8 +221,6 @@ class EDGE_ENHANCE_MORE(BuiltinFilter): -1, -1, -1 ) -## -# Simple embossing filter. class EMBOSS(BuiltinFilter): name = "Emboss" @@ -244,8 +230,6 @@ class EMBOSS(BuiltinFilter): 0, 0, 0 ) -## -# Simple edge-finding filter. class FIND_EDGES(BuiltinFilter): name = "Find Edges" @@ -255,8 +239,6 @@ class FIND_EDGES(BuiltinFilter): -1, -1, -1 ) -## -# Simple smoothing filter. class SMOOTH(BuiltinFilter): name = "Smooth" @@ -266,8 +248,6 @@ class SMOOTH(BuiltinFilter): 1, 1, 1 ) -## -# Simple stronger smoothing filter. class SMOOTH_MORE(BuiltinFilter): name = "Smooth More" @@ -279,8 +259,6 @@ class SMOOTH_MORE(BuiltinFilter): 1, 1, 1, 1, 1 ) -## -# Simple sharpening filter. class SHARPEN(BuiltinFilter): name = "Sharpen" diff --git a/docs/reference/ImageFilter.rst b/docs/reference/ImageFilter.rst new file mode 100644 index 000000000..0a4f29bfa --- /dev/null +++ b/docs/reference/ImageFilter.rst @@ -0,0 +1,47 @@ +.. py:module:: PIL.ImageFilter +.. py:currentmodule:: PIL.ImageFilter + +:mod:`ImageFilter` Module +========================= + +The :py:mod:`ImageFilter` module contains definitions for a pre-defined set of +filters, which can be be used with :py:meth:`Image.filter() +`. + +Example Filter an image +----------------------- + +.. code-block:: python + + import ImageFilter + + im1 = im.filter(ImageFilter.BLUR) + + im2 = im.filter(ImageFilter.MinFilter(3)) + im3 = im.filter(ImageFilter.MinFilter) # same as MinFilter(3) + +Filters +------- + +The current version of the library provides the following set of predefined +image enhancement filters: + +* **BLUR** +* **CONTOUR** +* **DETAIL** +* **EDGE_ENHANCE** +* **EDGE_ENHANCE_MORE** +* **EMBOSS** +* **FIND_EDGES** +* **SMOOTH** +* **SMOOTH_MORE** +* **SHARPEN** + +.. autoclass:: PIL.ImageFilter.GaussianBlur +.. autoclass:: PIL.ImageFilter.UnsharpMask +.. autoclass:: PIL.ImageFilter.Kernel +.. autoclass:: PIL.ImageFilter.RankFilter +.. autoclass:: PIL.ImageFilter.MedianFilter +.. autoclass:: PIL.ImageFilter.MinFilter +.. autoclass:: PIL.ImageFilter.MaxFilter +.. autoclass:: PIL.ImageFilter.ModeFilter diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 0ef01aa56..510970303 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -10,4 +10,5 @@ Reference ImageDraw ImageEnhance ImageFile + ImageFilter ../PIL