API Reference

models Module

class imagekit.models.fields.ImageSpecField(processors=None, format=None, options=None, image_field=None, pre_cache=None, storage=None, cache_to=None, autoconvert=True, image_cache_backend=None)

The heart and soul of the ImageKit library, ImageSpecField allows you to add variants of uploaded images to your models.

Parameters:
  • processors – A list of processors to run on the original image.
  • format – The format of the output file. If not provided, ImageSpecField will try to guess the appropriate format based on the extension of the filename and the format of the input image.
  • options – A dictionary that will be passed to PIL’s Image.save() method as keyword arguments. Valid options vary between formats, but some examples include quality, optimize, and progressive for JPEGs. See the PIL documentation for others.
  • image_field – The name of the model property that contains the original image.
  • storage – A Django storage system to use to save the generated image.
  • cache_to

    Specifies the filename to use when saving the image cache file. This is modeled after ImageField’s upload_to and can be either a string (that specifies a directory) or a callable (that returns a filepath). Callable values should accept the following arguments:

    • instance – The model instance this spec belongs to
    • path – The path of the original image
    • specname – the property name that the spec is bound to on
      the model instance
    • extension – A recommended extension. If the format of the
      spec is set explicitly, this suggestion will be based on that format. if not, the extension of the original file will be passed. You do not have to use this extension, it’s only a recommendation.
  • autoconvert – Specifies whether automatic conversion using prepare_image() should be performed prior to saving.
  • image_cache_backend – An object responsible for managing the state of cached files. Defaults to an instance of IMAGEKIT_DEFAULT_IMAGE_CACHE_BACKEND
class imagekit.models.fields.ProcessedImageField(processors=None, format=None, options=None, verbose_name=None, name=None, width_field=None, height_field=None, autoconvert=True, **kwargs)

ProcessedImageField is an ImageField that runs processors on the uploaded image before saving it to storage. This is in contrast to specs, which maintain the original. Useful for coercing fileformats or keeping images within a reasonable size.

The ProcessedImageField constructor accepts all of the arguments that the django.db.models.ImageField constructor accepts, as well as the processors, format, and options arguments of imagekit.models.ImageSpecField.

processors Module

Imagekit image processors.

A processor accepts an image, does some stuff, and returns the result. Processors can do anything with the image you want, but their responsibilities should be limited to image manipulations–they should be completely decoupled from both the filesystem and the ORM.

class imagekit.processors.resize.AddBorder(thickness, color=None)

Add a border of specific color and size to an image.

Parameters:
  • color – Color to use for the border
  • thickness – Thickness of the border. Can be either an int or a 4-tuple of ints of the form (top, right, bottom, left).
class imagekit.processors.resize.Resize(width, height)

Resizes an image to the specified width and height.

Parameters:
  • width – The target width, in pixels.
  • height – The target height, in pixels.
class imagekit.processors.resize.ResizeCanvas(width, height, color=None, anchor=None, x=None, y=None)

Resizes the canvas, using the provided background color if the new size is larger than the current image.

Parameters:
  • width – The target width, in pixels.
  • height – The target height, in pixels.
  • color – The background color to use for padding.
  • anchor

    Specifies the position of the original image on the new canvas. Valid values are:

    • Anchor.TOP_LEFT
    • Anchor.TOP
    • Anchor.TOP_RIGHT
    • Anchor.LEFT
    • Anchor.CENTER
    • Anchor.RIGHT
    • Anchor.BOTTOM_LEFT
    • Anchor.BOTTOM
    • Anchor.BOTTOM_RIGHT

    You may also pass a tuple that indicates the position in percentages. For example, (0, 0) corresponds to “top left”, (0.5, 0.5) to “center” and (1, 1) to “bottom right”. This is basically the same as using percentages in CSS background positions.

class imagekit.processors.resize.ResizeToCover(width, height)

Resizes the image to the smallest possible size that will entirely cover the provided dimensions. You probably won’t be using this processor directly, but it’s used internally by ResizeToFill and SmartResize.

Parameters:
  • width – The target width, in pixels.
  • height – The target height, in pixels.
class imagekit.processors.resize.ResizeToFill(width=None, height=None, anchor=None)

Resizes an image, cropping it to the exact specified width and height.

Parameters:
  • width – The target width, in pixels.
  • height – The target height, in pixels.
  • anchor – Specifies which part of the image should be retained when cropping.
class imagekit.processors.resize.ResizeToFit(width=None, height=None, upscale=None, mat_color=None, anchor='c')

Resizes an image to fit within the specified dimensions.

Parameters:
  • width – The maximum width of the desired image.
  • height – The maximum height of the desired image.
  • upscale – A boolean value specifying whether the image should be enlarged if its dimensions are smaller than the target dimensions.
  • mat_color – If set, the target image size will be enforced and the specified color will be used as a background color to pad the image.
class imagekit.processors.resize.SmartResize(width, height)

The SmartResize processor is identical to ResizeToFill, except that it uses entropy to crop the image instead of a user-specified anchor point. Internally, it simply runs the ResizeToCover and SmartCrop processors in series.

Parameters:
  • width – The target width, in pixels.
  • height – The target height, in pixels.
class imagekit.processors.crop.Crop(width=None, height=None, anchor=None, x=None, y=None)

Crops an image, cropping it to the specified width and height. You may optionally provide either an anchor or x and y coordinates. This processor functions exactly the same as ResizeCanvas except that it will never enlarge the image.

class imagekit.processors.crop.SmartCrop(width=None, height=None)

Crop an image to the specified dimensions, whittling away the parts of the image with the least entropy.

Based on smart crop implementation from easy-thumbnails:
https://github.com/SmileyChris/easy-thumbnails/blob/master/easy_thumbnails/processors.py#L193
Parameters:
  • width – The target width, in pixels.
  • height – The target height, in pixels.
compare_entropy(start_slice, end_slice, slice, difference)

Calculate the entropy of two slices (from the start and end of an axis), returning a tuple containing the amount that should be added to the start and removed from the end of the axis.

class imagekit.processors.crop.TrimBorderColor(color=None, tolerance=0.3, sides=('t', 'r', 'b', 'l'))

Trims a color from the sides of an image.

Parameters:
  • color – The color to trim from the image, in a 4-tuple RGBA value, where each component is an integer between 0 and 255, inclusive. If no color is provided, the processor will attempt to detect the border color automatically.
  • tolerance – A number between 0 and 1 where 0. Zero is the least tolerant and one is the most.
  • sides – A list of sides that should be trimmed. Possible values are provided by the Side enum class.

admin Module

class imagekit.admin.AdminThumbnail(image_field, template=None)

A convenience utility for adding thumbnails to Django’s admin change list.

Parameters:
  • image_field – The name of the ImageField or ImageSpecField on the model to use for the thumbnail.
  • template – The template with which to render the thumbnail

Table Of Contents

Related Topics

This Page