PIL_usm

PIL_usm is a module for PIL that provides true Gaussian Blurring and Unsharp Mask Sharpening functions to PIL. See the PIL_usm page for details.


NOTE: as of PIL 1.7, PIL_usm and pyCMS functionality is built into the standard distribution of PIL - these stand-alone modules are no longer required or being updated/maintained!
PIL_usm is licensed under the GNU LGPL (Lesser General Public License), making it freely available in source form to programmers everywhere. Depending on how you use PIL_usm, it is possible to use it with both closed-source programs, as well as open-source programs.

Although I highly encourage you to release your works under the LGPL or GPL licenses, the choice is up to you. In either case, please follow the licensing terms provided and ensure to give credit where credit is due. If you have need of this library under different licensing terms, please contact us to discuss that possibility.

Click Here to see samples of PILusm vs. Photoshop USM

Downloads

PIL_usm License (Lesser General Public License)
Full package (vers. 0.6.0) including source code, Python wrapper module, a pre-compiled binary for Windows (compiled with Python 2.2.1, PIL 1.1.3), and sample images (with Photoshop comparison).

Please let me know if you use PIL_usm, how you like it, any bugs/errors you've found, and what features or improvements you'd like to see. You can email me at: kevin@cazabon.com

Usage

Using PIL_usm for Gaussian blurring or USM sharpening is very easy, and works very similarly to how it would in any normal painting program (like Photoshop for example).

Here are some examples:

###############################
import Image
import PIL_usm # don't use the DLL directly, the Python wrapper makes it easier

im = Image.open("c:\\temp\\test.tif")

# first, a blurring example
im2 = PIL_usm.gblur(im, radius = 6.5)
# use a radius value about the same as what you would in Photoshop.
im2.save("c:\\temp\\test_blur.tif")

# next, a sharpening example
im3 = PIL_usm.usm(im, radius = 5.25, percent = 150, threshold = 4)
# once again, use a radius value about what you would in other
# paint programs for a similar look.
im3.save("c:\\temp\\test_sharpen.tif")

################################

Documentation and Theory

Gaussian blurring is actually pretty simple. For each pixel in the image, you look at the surrounding pixels and "average" their values into the value of the current pixel. You control the amount of blur by specifying the "radius" of how many surrounding pixels are taken into consideration. Pixels that are closer to the current pixel have more effect than further ones, based on a Gaussian distribution, or "bell curve".

To improve speed, PIL_usm does this in two passes which actually result in the EXACT same output. Instead of doing a single pass with a large, square (2-dimensional) matrix, it does two 1-dimensional transformations. For example, if using a "radius" of 10, instead of doing a single pass with a 10x10 matrix (100 lookups per pixel), it does a 10x1 transform (rows) followed by a 1x10 transform (columns). This results in only 20 lookups per pixel instead of 100... a 500% speed improvement.

Unsharp masking is actually quite simple in practice, but can easily confuse you if you don't know what's happening. There are two steps to USM application: 1) creating a temporary "blurred" image using a Gaussian Blur (as above), and 2) evaluating how much the image was blurred, and applying the OPPOSITE correction to the final image.

For USM, the "radius" variable determines the radius to use in the Gaussian Blur function (see above). The "threshold" value determines the minimum amount a pixel value must change before we apply any sharpening to it (i.e. if it changes less than "threshold" values after the Gaussian Blur, we leave the pixel alone in the output image). The "percent" value is a multiplier for the correction we apply to any pixels that DID change more than "threshold" values.

The result, when properly applied, is that only "edge features" are sharpened, by effectivly increasing the contrast only in areas where there was high-contrast to begin with. This may create a "ring" effect, or white/black outline around edges, but it shouldn't be visible unless either the radius or percent values were too large.

Typical settings for USM for a starting point are:

Of course, this depends on how much sharpening the image needs, and what the final use of the image will be.

Version History

Version 0.6.0

Version 0.5.0

Version 0.4.1

Version 0.3.0

Version 0.2.0

Version 0.1.0

Please help keep shareware software going... make a small donation for us today!