django-imagekit/README.md

# ImageKit In 7 Steps #

## Step 1 - pip install django-imagekit (or clone the source and put the imagekit module on your path) ##

## Step 2 - Add ImageKit to your models ##

    # myapp/models.py

    from django.db import models
    from imagekit.models import ImageModel

    class Photo(ImageModel):
        name = models.CharField(max_length=100)
        original_image = models.ImageField(upload_to='photos')
        num_views = models.PositiveIntegerField(editable=False, default=0)

        class IKOptions:
            # This inner class is where we define the ImageKit options for the model
            spec_module = 'myapp.specs'
            cache_dir = 'photos'
            image_field = 'original_image'
            save_count_as = 'num_views'

## Step 3 - Create your specifications  ##

    # myapp/specs.py

    from imagekit.specs import ImageSpec 
    from imagekit import processors 

    # first we define our thumbnail resize processor 
    class ResizeThumb(processors.Resize): 
        width = 100 
        height = 75 
        crop = True

    # now we define a display size resize processor
    class ResizeDisplay(processors.Resize):
        width = 600 

    # now let's create an adjustment processor to enhance the image at small sizes 
    class EnchanceThumb(processors.Adjustment): 
        contrast = 1.2 
        sharpness = 1.1 

    # now we can define our thumbnail spec 
    class Thumbnail(ImageSpec): 
        access_as = 'thumbnail_image' 
        pre_cache = True 
        processors = [ResizeThumb, EnchanceThumb] 

    # and our display spec
    class Display(ImageSpec):
        increment_count = True
        processors = [ResizeDisplay]

## Step 4 - Flush the cache and pre-generate thumbnails (ImageKit has to be added to INSTALLED_APPS for management command to work) ##

    python manage.py ikflush myapp

## Step 5 - Use your new model in templates ##

    <div class="original">
    <img src="{{ photo.original_image.url }}" alt="{{ photo.name }}">
    </div>

    <div class="display">
    <img src="{{ photo.display.url }}" alt="{{ photo.name }}">
    </div>

    <div class="thumbs">
    {% for p in photos %}
    <img src="{{ p.thumbnail_image.url }}" alt="{{ p.name }}">
    {% endfor %}
    </div>

## Step 6 - Play with the API ##

    >>> from myapp.models import Photo
    >>> p = Photo.objects.all()[0]
    <Photo: MyPhoto>
    >>> p.display.url
    u'/static/photos/myphoto_display.jpg'
    >>> p.display.width
    600
    >>> p.display.height
    420
    >>> p.display.image
    <JpegImagePlugin.JpegImageFile instance at 0xf18990>
    >>> p.display.file
    <File: /path/to/media/photos/myphoto_display.jpg>
    >>> p.display.spec
    <class 'myapp.specs.Display'>

## Step 7 - Enjoy a nice beverage ##

    from refrigerator import beer

    beer.enjoy()