:Author: Benoit Bryon <>
:Copyright: This document being part of the django-imagethumbnail package, it's 
            being distributed under the terms of the MIT license. See LICENSE 
            file for details.


django-imagethumbnail provides these functionalities:

* a template modifier that dynamically generates the thumbnail of an image, and 
  then returns the path to the generated thumbnail
* uses file system cache in MEDIA_ROOT to store generated thumbnails


This code is based on code from by
`danfairs <>`_. This Django snippet 
provides similar functionnality. The differences are:

* this package is bundled as an application. This reduces the risk of having 
  several template tags that perform the same thing.
* the way the original image is resized is a bit different


Django-imagethumbnail requires PIL and Django.
The development focuses latest Django version. Tests pass with Django-1.2.3.
It has first been developped for Django-0.96. It works with Django-1.0.


* Get the code. You can download the latest version at or with the following
  mercurial command:
  # hg clone imagethumbnail
* Rename the folder to "imagethumbnail" and move it in a location in your 
  PythonPath. Typically in your project directory.
* Add 'imagethumbnail' to your project settings.INSTALLED_APPS
* Optionnally you can define IMAGETHUMBNAIL_THUMBNAILS_PATH, which is the path
  relative to MEDIA_ROOT where thumbnails will be written. Default value is
* Make sure that the IMAGETHUMBNAIL_THUMBNAILS_PATH folder is writeable for the
  web service user. 


* In a template, load the thumbnail template tag with {% load image_thumbnail %}
* In the same template, if {{ image_url }} is an image url relative to 
  MEDIA_ROOT, then you can generate the corresponding thumbnail with 
  {{ image_url|thumbnail:"BOX_WIDTH,BOX_HEIGHT" }}
  where BOX_WIDTH and BOX_HEIGHT are the width and height of the thumbnail
  bounding box. The image ratio will be kept.
  If {{ image }} is an ImageField, then you can use:
  {{ image|thumbnail:"BOX_WIDTH,BOX_HEIGHT" }}

Thumbnail storage

The application uses the IMAGETHUMBNAIL_THUMBNAILS_PATH to store thumbnails.
If it does not exist, then the application automatically tries to create it.
In this directory, thumbnails are grouped by bounding-box dimensions (one 
subdirectory by WIDTHxHEIGHT values).

It uses the following schema:
where the original image is located at path/to/image.jpg within MEDIA_ROOT