=====
Usage
=====

The simplest and most common way easy-thumbnails is used is via the
``{% thumbnail %}`` Django template tag, which generates images from a model
with an ``ImageField``.

A Python class is also provided which can be used to assist generation of
thumbnail images.

Overview
========

The primary function of easy-thumbnail is to create thumbnails based on a
source image on the fly.

So whenever a thumbnail does not exist or if the source was modified
more recently than the existing thumbnail, a new thumbnail is generated (and
saved).

Image quality and format
------------------------

The default format used to save thumbnail images is a JPEG of quality 85 (out
of 100).

The thumbnail tag (and thumbnail generator) accept a ``quality`` option
which changes the image quality. The default value of 85 can also be changed
via the :ref:`THUMBNAIL_QUALITY setting <setting-thumbnail_quality>`.

Similarly, the :ref:`THUMBNAIL_EXTENSION <setting-thumbnail_extension>` and
:ref:`THUMBNAIL_TRANSPARENCY_EXTENSION
<setting-thumbnail_transparency_extension>`
settings can be used to specify an alternate image format.

.. currentmodule:: easy_thumbnails.processors 

.. note:: If you want to drop the transparency layer for a specific thumbnail
          (to ensure it always uses ``THUMBNAIL_EXTENSION``) then use the
          ``replace_alpha`` option of the :func:`colorspace` processor. 

Templates
=========

To generate thumbnails in your template, use the ``{% thumbnail %}`` tag. To
make this tag available for use in your template, use::
    
    {% load thumbnail %}

.. _thumbnail_tag:

``{% thumbnail %}`` tag
-----------------------

.. autofunction:: easy_thumbnails.templatetags.thumbnail.thumbnail

For a full list of options, read the :doc:`ref/processors` reference
documentation.


Models
======

You can use the ``ThumbnailerField`` or ``ThumbnailerImageField`` fields (based
on ``FileField`` and ``ImageField``, respectively) for easier access to
retrieve (or generate) thumbnail images, use different storages and resize
source images before saving.

.. autoclass:: easy_thumbnails.fields.ThumbnailerField

.. autoclass:: easy_thumbnails.fields.ThumbnailerImageField


Python
======

.. currentmodule:: easy_thumbnails.files

Easy thumbnails uses a Django ``File``-like object called a
:class:`Thumbnailer` to generate thumbnail images from the source file which
it references.

``get_thumbnailer``
-------------------

The easy way to create a :class:`Thumbnailer` instance is to use the following
utility function:

.. autofunction:: get_thumbnailer
   :noindex:

Once you have an instance, you can use the :meth:`Thumbnailer.get_thumbnail`
method to retrieve a thumbnail, which will generate it if it doesn't exist (or
if the source image has been modified since it was created).

For example, assuming an ``aardvark.jpg`` image exists in the default storage::

    from easy_thumbnails.files import get_thumbnailer
    
    thumbnailer = get_thumbnail('animals/aardvark.jpg')
    
    thumbnail_options = {'crop': True} 
    for size in (50, 100, 250):
        thumbnail_options.update({'size': (size, size)})
        thumbnailer.get_thumbnail(thumbnail_options)

Non-Django file objects
-----------------------

If you need to process a standard file object as opposed to a Django one (i.e.
one retrieved from a Django file storage), use :func:`get_thumbnailer` and
provide a ``relative_name`` like this::

	picture = open('/home/zookeeper/pictures/my_anteater.jpg')
	thumbnailer = get_thumbnailer(picture, relative_name='animals/anteater.jpg')
	thumb = thumbnailer.get_thumbnail({'size': (100, 100)})

If you don't even need to save the thumbnail to storage because you are
planning on using it in some more direct way, you can use the
:meth:`Thumbnailer.generate_thumbnail` method. 
