django-imagefield 0.7.1

=================
django-imagefield
=================

.. image:: https://travis-ci.org/matthiask/django-imagefield.svg?branch=master
:target: https://travis-ci.org/matthiask/django-imagefield

.. image:: https://readthedocs.org/projects/django-imagefield/badge/?version=latest
:target: https://django-imagefield.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status

Version |release|

Heavily based on `django-versatileimagefield
<https://github.com/respondcreate/django-versatileimagefield>`_, but
with a few important differences:

- The amount of code is kept at a minimum. django-versatileimagefield
has several times as much code (without tests).
- Generating images on-demand inside rendering code is made hard on
purpose. Instead, images are generated when models are saved and also
by running the management command ``process_imagefields``.
- django-imagefield does not depend on a fast storage or a cache to be
and stay fast, at least as long as the image width and height is saved
in the database. An important part of this is never determining
whether a processed image exists in the hot path at all (except if you
``force`` it).
- django-imagefield fails early when image data is incomplete or not
processable by Pillow_ for some reason.
- django-imagefield allows adding width, height and PPOI (primary point
of interest) fields to the model by adding ``auto_add_fields=True`` to
the field instead of boringly and verbosingly adding them yourself.

Replacing existing uses of django-versatileimagefield requires the
following steps:

- ``from imagefield.fields import ImageField as VersatileImageField, PPOIField``
- Specify the image sizes by either providing ``ImageField(formats=...)`` or
adding the ``IMAGEFIELD_FORMATS`` setting. The latter overrides the
former if given.
- Convert template code to access the new properties (e.g.
``instance.image.square`` instead of ``instance.image.crop.200x200``
when using the ``IMAGEFIELD_FORMATS`` setting below).
- When using django-imagefield with a PPOI, make sure that the PPOI
field is also added to ``ModelAdmin`` or ``InlineModelAdmin``
fieldsets, otherwise you'll just see the image, but no PPOI picker.
Contrary to django-versatileimagefield the PPOI field is editable
itself, which avoids apart from other complexities a pitfall with
inline form change detection.
- Add ``"imagefield"`` to ``INSTALLED_APPS``.

If you used e.g. ``instance.image.crop.200x200`` and
``instance.image.thumbnail.800x500`` before, you should add the
following setting:

.. code-block:: python

IMAGEFIELD_FORMATS = {
# image field path, lowercase
'yourapp.yourmodel.image': {
'square': ['default', ('crop', (200, 200))],
'full': ['default', ('thumbnail', (800, 500))],

# The 'full' spec is equivalent to the following format
# specification in terms of image file produced (the
# resulting file name is different though):
# 'full': [
# 'autorotate', 'process_jpeg', 'process_gif', 'autorotate',
# ('thumbnail', (800, 500)),
# ],
# Note that the exact list of default processors may
# change in the future.
},
}

After running ``./manage.py process_imagefields`` once you can now
use use ``instance.image.square`` and ``instance.image.thumbnail`` in
templates instead. Note that the properties on the ``image`` file do by
design not check whether thumbs exist.


Image processors
================

django-imagefield uses an image processing pipeline modelled after
Django's middleware.

The following processors are available out of the box:

- ``autorotate``: Autorotates an image by reading the EXIF data.
- ``process_jpeg``: Converts non-RGB images to RGB, activates
progressive encoding and sets quality to a higher value of 90.
- ``process_gif``: Preserves transparency and palette data in resized
images.
- ``preserve_icc_profile``: As the name says.
- ``thumbnail``: Resizes images to not exceed a bounding box.
- ``crop``: Crops an image to the given dimensions, also takes the PPOI
(primary point of interest) information into account if provided.
- ``default``: The combination of ``autorotate``, ``process_jpeg``,
``process_gif`` and ``preserve_icc_profile``. Additional default
processors may be added in the future. It is recommended to use
``default`` instead of adding the processors one-by-one.

Processors can be specified either using their name alone, or if they
take arguments, using a tuple ``(processor_name, args...)``.

You can easily register your own processors or even override built-in
processors if you want to:

.. code-block:: python

from imagefield.processing import register

# You could also write a class with a __call__ method, but I really
# like the simplicity of functions.

@register
def my_processor(get_image, args):
# args is either a list of arguments to the processor or an
# empty list
def processor(image, context):
# read some information from the image...
# or maybe modify it, but it's mostly recommended to modify
# the image after calling get_image

image = get_image(image, context)

# modify the image, and return it...
modified_image = ...
# maybe modify the context...
return modified_image
return processor

The processor's name is taken directly from the registered object.

An example processor which converts images to grayscale would look as
follows:

.. code-block:: python

from PIL import ImageOps
from imagefield.processing import register

@register
def grayscale(get_image, args):
def processor(image, context):
image = get_image(image, context)
return ImageOps.grayscale(image)
return processor

Now include ``"grayscale"`` in the processing spec for the image where
you want to use it.


The processing context
======================

The ``context`` is a namespace with the following attributes (feel free
to add your own):

- ``processors``: The list of processors.
- ``name``: The name of the resulting image relative to its storages'
root.
- ``extension``: The extension of the source and target.
- ``ppoi``: The primary point of interest as a list of two floats
between 0 and 1.
- ``save_kwargs``: A dictionary of keyword arguments to pass to
``PIL.Image.save``.

The ``ppoi``, ``extension``, ``processors`` and ``name`` attributes
cannot be modified when running processors anymore. Under some
circumstances ``extension`` and ``name`` will not even be there.

If you want to modify the extension or file type, or create a different
processing pipeline depending on facts not known when configuring
settings you can use a callable instead of the list of processors. The
callable will receive the fieldfile and the context instance and must at
least set the context's ``processors`` attribute to something sensible.
Just as an example here's an image field which always returns JPEG
thumbnails:

.. code-block:: python

from imagefield.processing import register

@register
def force_jpeg(get_image, args):
def processor(image, context):
image = get_image(image, context)
context.save_kwargs["format"] = "JPEG"
context.save_kwargs["quality"] = 90
return image
return processor

def jpeg_processor_spec(fieldfile, context):
context.extension = ".jpg"
context.processors = [
"force_jpeg",
"autorotate",
("thumbnail", (200, 200)),
]

class Model(...):
image = ImageField(..., formats={"thumb": jpeg_processor_spec})

Of course you can also access the model instance through the field file
by way of its ``fieldfile.instance`` attribute and use those
informations to customize the pipeline.


Development
===========

django-imagefield uses flake8 and black to keep the code clean and
formatted. Run both using tox_:

.. code-block:: bash

tox -e style

The easiest way to build the documentation and run the test suite is
also by using tox_:

.. code-block:: bash

tox -e docs # Open docs/build/html/index.html
tox -e tests


.. _documentation: https://django-imagefield.readthedocs.io/en/latest/
.. _Pillow: https://pillow.readthedocs.io/en/latest/
.. _tox: https://tox.readthedocs.io/