Overview

=====================
django-imagethumbnail
=====================

:Author: Benoit Bryon <benoit@marmelune.net>
: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.

Summary
=======

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

Credits
=======

This code is based on code from http://www.djangosnippets.org/snippets/453/ by
`danfairs <http://djangosnippets.org/users/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

Requirements
============

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.

Installation
============

* Get the code. You can download the latest version at 
  http://bitbucket.org/benoitbryon/django-imagethumbnail or with the following
  mercurial command:
  # hg clone http://bitbucket.org/benoitbryon/django-imagethumbnail 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
  'thumbnails'.
* Make sure that the IMAGETHUMBNAIL_THUMBNAILS_PATH folder is writeable for the
  web service user. 

Usage
=====

* 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:
MEDIA_ROOT/IMAGETHUMBNAIL_THUMBNAILS_PATH/WIDTHxHEIGHT/path/to/image.jpg
where the original image is located at path/to/image.jpg within MEDIA_ROOT