Image Processors

Easy thumbnails generates thumbnail images by passing the source image through a series of image processors. Each processor may alter the image, often dependent on the options it receives.

This makes the system very flexible, as the processors an image passes through can be defined in THUMBNAIL_PROCESSORS and even overridden by an individual easy_thumbnails.files.Thumbnailer (via the thumbnail_processors attribute).

Built-in processors

Following is a list of the built-in processors, along with the thumbnail options which they use.

easy_thumbnails.processors.autocrop(im, autocrop=False, **kwargs)

Remove any unnecessary whitespace from the edges of the source image.

Only pure white (#fff) pixels are trimmed, with no tolerance, and fully transparent areas are treated as white.

This processor should be listed before scale_and_crop() so the whitespace is removed from the source image before it is resized.

autocrop: Activates the autocrop method for this image.

easy_thumbnails.processors.background(im, size, background=None, **kwargs)

Add borders of a certain color to make the resized image fit exactly within the dimensions given.

The image is centered on the new canvas. Nothing is done if either dimension of size is zero or the image already fills size on both axes. Any transparency is replaced by the background color. If the image is smaller than size on only one axis, it is cropped on the other.

The result is always opaque, so padding with transparency is not possible: the alpha part of a color such as #0000 is ignored and the border becomes black. To keep transparency, do not use this option and let the thumbnail keep its fitted size, or add a custom processor.

background: Background color to use

easy_thumbnails.processors.colorspace(im, bw=False, replace_alpha=False, **kwargs)

Convert images to the correct color space.

A passive option (i.e. always processed) of this method is that all images (unless grayscale) are converted to RGB colorspace.

This processor should be listed before scale_and_crop() so palette is changed before the image is resized.

bw: Make the thumbnail grayscale (not really just black & white).
replace_alpha: Replace any transparency layer with a solid color. For example, replace_alpha='#fff' would replace the transparency layer with white.

easy_thumbnails.processors.filters(im, detail=False, sharpen=False, **kwargs)

Pass the source image through post-processing filters.

sharpen: Sharpen the thumbnail image (using the PIL sharpen filter)
detail: Add detail to the image, like a mild sharpen (using the PIL detail filter).

easy_thumbnails.processors.scale_and_crop(im, size, crop=False, upscale=False, zoom=None, target=None, **kwargs)

Handle scaling and cropping the source image.

Images can be scaled / cropped against a single dimension by using zero as the placeholder in the size. For example, size=(100, 0) will cause the image to be resized to 100 pixels wide, keeping the aspect ratio of the source image.

crop

Crop the source image height or width to exactly match the requested thumbnail size (the default is to proportionally resize the source image to fit within the requested thumbnail size).

By default, the image is centered before being cropped. To crop from the edges, pass a comma separated string containing the x and y percentage offsets (negative values go from the right/bottom). Some examples follow:

crop="0,0" will crop from the left and top edges.
crop="-10,-0" will crop from the right edge (with a 10% offset) and the bottom edge.
crop=",0" will keep the default behavior for the x axis (horizontally centering the image) and crop from the top edge.

The image can also be “smart cropped” by using crop="smart". The image is incrementally cropped down to the requested size by removing slices from edges with the least entropy.

Finally, you can use crop="scale" to simply scale the image so that at least one dimension fits within the size dimensions given (you may want to use the upscale option too).

upscale

Allow upscaling of the source image during scaling.

zoom

A percentage to zoom in on the scaled image. For example, a zoom of 40 will clip 20% off each side of the source image before thumbnailing.

target

Set the focal point as a percentage for the image if it needs to be cropped (defaults to (50, 50)).

For example, target="10,20" will set the focal point as 10% and 20% from the left and top of the image, respectively. If the image needs to be cropped, it will trim off the right and bottom edges until the focal point is centered.

Can either be set as a two-item tuple such as (20, 30) or a comma separated string such as "20,10".

A null value such as (20, None) or ",60" will default to 50%.

Option combinations and pitfalls

All options are passed to every processor and the processors run in order (see THUMBNAIL_PROCESSORS), so the result of an option depends on what ran before it. These combinations are covered by tests/test_pixel_processors.py.

size

A zero in size leaves that dimension unbounded. size=(0, 0) has nothing to derive a scale from and gives a 1x1 image.
background() needs both dimensions and does nothing if one is zero.

crop

Without upscale a smaller source is never enlarged, so the result can be smaller than size even with crop (background can pad it to the exact size).
crop="scale" never crops. Combined with zoom the result is larger than size.
The W,H offsets are a percentage of the requested thumbnail size (not of the source) and are limited to the available overflow. For W,H the target option only applies to an axis that has no offset, e.g. crop=",0".
An empty crop="," is the same as crop=True.

target

Only used when the image is cropped, otherwise it has no effect.
Invalid values ("abc", "-5,5", "1,2,3") are silently ignored and the image is centered. Use None or an empty part for the default of 50%.

zoom

Without crop the image is scaled to fit size and then cropped to that size, so zoom implies cropping.
Is limited by upscale like any other scaling: a source smaller than size is not zoomed in unless upscale is set.

autocrop

Runs before scaling, so crop and size apply to the trimmed image (and its aspect ratio).
Only pure white (#fff) is whitespace; off-white borders are kept. Transparent areas count as white, so white content on a transparent background is trimmed as well.

replace_alpha and background

background also replaces transparency with its color, even without replace_alpha, but only if padding is needed. If both are set, replace_alpha is applied first by colorspace(), so the image is flat before it is padded.
background cannot pad with transparency. The result is always opaque and the alpha part of a color like #0000 is ignored (black border).
bw is passed through to background, so a padded image is grayscale as well.
background pads whenever the image is smaller than size on one axis, and crops around the center on the other axis if the image is larger there.

Custom processors

You can replace or leave out any default processor as suits your needs. Following is an explanation of how to create and activate a custom processor.

When defining the THUMBNAIL_PROCESSORS setting, remember that this is the order through which the processors are run. The image received by a processor is the output of the previous processor.

Create the processor

First create a processor like this:

def whizzbang_processor(image, bang=False, **kwargs):
    """
    Whizz bang the source image.

    """
    if bang:
        image = whizz(image)
    return image

The first argument for a processor is the source image.

All other arguments are keyword arguments which relate to the list of options received by the thumbnail generator (including size and quality). Ensure you list all arguments which could be used (giving them a default value of False), as the processors arguments are introspected to generate a list of valid options.

You must also use **kwargs at the end of your argument list because all options used to generate the thumbnail are passed to processors, not just the ones defined.

Whether a processor actually modifies the image or not, they must always return an image.

Use the processor

Next, add the processor to THUMBNAIL_PROCESSORS in your settings module:

from easy_thumbnails.conf import Settings as easy_thumbnails_defaults

THUMBNAIL_PROCESSORS = easy_thumbnails_defaults.THUMBNAIL_PROCESSORS + (
    'wb_project.thumbnail_processors.whizzbang_processor',
)