django-imagekit 3.0.4

Defining Specs In Models

The easiest way to use define an image spec is by using an ImageSpecField on your model class:

from django.db import models
from imagekit.models import ImageSpecField
from imagekit.processors import ResizeToFill

class Profile(models.Model):
    avatar = models.ImageField(upload_to='avatars')
    avatar_thumbnail = ImageSpecField(source='avatar',
                                      processors=[ResizeToFill(100, 50)],
                                      format='JPEG',
                                      options={'quality': 60})

profile = Profile.objects.all()[0]
print profile.avatar_thumbnail.url    # > /media/CACHE/images/982d5af84cddddfd0fbf70892b4431e4.jpg
print profile.avatar_thumbnail.width  # > 100

As you can probably tell, ImageSpecFields work a lot like Django’s ImageFields. The difference is that they’re automatically generated by ImageKit based on the instructions you give. In the example above, the avatar thumbnail is a resized version of the avatar image, saved as a JPEG with a quality of 60.

Sometimes, however, you don’t need to keep the original image (the avatar in the above example); when the user uploads an image, you just want to process it and save the result. In those cases, you can use the ProcessedImageField class:

from django.db import models
from imagekit.models import ProcessedImageField

class Profile(models.Model):
    avatar_thumbnail = ProcessedImageField(upload_to='avatars',
                                           processors=[ResizeToFill(100, 50)],
                                           format='JPEG',
                                           options={'quality': 60})

profile = Profile.objects.all()[0]
print profile.avatar_thumbnail.url    # > /media/avatars/MY-avatar.jpg
print profile.avatar_thumbnail.width  # > 100

This is pretty similar to our previous example. We don’t need to specify a “source” any more since we’re not processing another image field, but we do need to pass an “upload_to” argument. This behaves exactly as it does for Django ImageFields.

Defining Specs Outside of Models

Defining specs as models fields is one very convenient way to process images, but it isn’t the only way. Sometimes you can’t (or don’t want to) add fields to your models, and that’s okay. You can define image spec classes and use them directly. This can be especially useful for doing image processing in views— particularly when the processing being done depends on user input.

from imagekit import ImageSpec
from imagekit.processors import ResizeToFill

class Thumbnail(ImageSpec):
    processors = [ResizeToFill(100, 50)]
    format = 'JPEG'
    options = {'quality': 60}

It’s probaby not surprising that this class is capable of processing an image in the exact same way as our ImageSpecField above. However, unlike with the image spec model field, this class doesn’t define what source the spec is acting on, or what should be done with the result; that’s up to you:

source_file = open('/path/to/myimage.jpg')
image_generator = Thumbnail(source=source_file)
result = image_generator.generate()

The result of calling generate() on an image spec is a file-like object containing our resized image, with which you can do whatever you want. For example, if you wanted to save it to disk:

dest = open('/path/to/dest.jpg', 'w')
dest.write(result.read())
dest.close()

Using Specs In Templates

If you have a model with an ImageSpecField or ProcessedImageField, you can easily use those processed image just as you would a normal image field:

<img src="{{ profile.avatar_thumbnail.url }}" />

(This is assuming you have a view that’s setting a context variable named “profile” to an instance of our Profile model.)

But you can also generate processed image files directly in your template—from any image—without adding anything to your model. In order to do this, you’ll first have to define an image generator class (remember, specs are a type of generator) in your app somewhere, just as we did in the last section. You’ll also need a way of referring to the generator in your template, so you’ll need to register it.

from imagekit import ImageSpec, register
from imagekit.processors import ResizeToFill

class Thumbnail(ImageSpec):
    processors = [ResizeToFill(100, 50)]
    format = 'JPEG'
    options = {'quality': 60}

register.generator('myapp:thumbnail', Thumbnail)

Now that we’ve created an image generator class and registered it with ImageKit, we can use it in our templates!

{% load imagekit %}

{% generateimage 'myapp:thumbnail' source=source_image %}

<img src="/media/CACHE/images/982d5af84cddddfd0fbf70892b4431e4.jpg" width="100" height="50" />

{% load imagekit %}

{% generateimage 'myapp:thumbnail' source=source_image -- alt="A picture of Me" id="mypicture" %}

{% load imagekit %}

{% generateimage 'myapp:thumbnail' source=source_image as th %}
<a href="{{ th.url }}">Click to download a cool {{ th.width }} x {{ th.height }} image!</a>

{% load imagekit %}

{% thumbnail '100x50' source_image %}

<img src="/media/CACHE/images/982d5af84cddddfd0fbf70892b4431e4.jpg" width="100" height="50" />

{% load imagekit %}

{% thumbnail '100x50' source_image -- alt="A picture of Me" id="mypicture" %}
{% thumbnail '100x50' source_image as th %}

Using Specs in Forms

In addition to the model field above, there’s also a form field version of the ProcessedImageField class. The functionality is basically the same (it processes an image once and saves the result), but it’s used in a form class:

from django import forms
from imagekit.forms import ProcessedImageField
from imagekit.processors import ResizeToFill

class ProfileForm(forms.Form):
    avatar_thumbnail = ProcessedImageField(spec_id='myapp:profile:avatar_thumbnail',
                                           processors=[ResizeToFill(100, 50)],
                                           format='JPEG',
                                           options={'quality': 60})

The benefit of using imagekit.forms.ProcessedImageField (as opposed to imagekit.models.ProcessedImageField above) is that it keeps the logic for creating the image outside of your model (in which you would use a normal Django ImageField). You can even create multiple forms, each with their own ProcessedImageField, that all store their results in the same image field.