Django Daguerre¶

Requirements¶

• Python 2.6+
• PIL 1.1.7 (Or Pillow)

Installation¶

You can install the latest version of Daguerre using pip:

pip install django-daguerre

You can clone the repository yourself at https://github.com/littleweaver/django-daguerre.

Setup¶

Ensure that 'daguerre' is in your project’s INSTALLED_APPS:

INSTALLED_APPS = (
    'daguerre',
    ...
)

Add the following or similar anywhere in your URLconf:

urlpatterns = patterns('',
    url(r'^daguerre/', include('daguerre.urls')),
    ...
)

{% adjust %}¶

The easiest way to use Daguerre is through the {% adjust %} template tag:

{% load daguerre %}
<img src="{% adjust my_model.image width=128 height=256 %}" />

daguerre works directly with any ImageField (or storage path). There is no magic. You don’t need to change your models. It Just Works.

Different adjustments¶

The {% adjust %} tag currently supports three different adjustments: fit, fill, and crop. These can be passed in as an additional parameter to the tag:

<img src="{% adjust my_model.image width=128 height=256 adjustment="fit" %}" />

Take this picture:

Full size: 512x512

Let’s use {% adjust %} with width 128 (25%) and height 256 (50%), with each of the three adjustments.

“fit”	“fill” (default)	“crop”
Fits the entire image into the given dimensions without distorting it.	Fills the entire space given by the dimensions by cropping to the same width/height ratio and then scaling.	Crops the image to the given dimensions without any resizing.

Note

If you have defined Areas for an image in the admin, those will be protected as much as possible (according to their priority) when using the crop or fill adjustments. Otherwise, any cropping will be done evenly from opposing sides.

{% load daguerre %}
{% adjust my_model.image width=128 height=128 adjustment="fit" as image %}
<img src="{{ image }}" width={{ image.width }} height={{ image.height }} />

{% load daguerre %}
<img src="{% adjust my_model.image width=128 height=128 adjustment="fit" crop="face" %}" />

{% adjust_bulk %}¶

If you are using a large number of similar adjustments in one template - say, looping over a queryset and adjusting the same attribute each time - you can save yourself queries by using {% adjust_bulk %}.

{% load daguerre %}
{% adjust_bulk my_queryset "method.image" width=200 height=400 as adjusted_list %}
{% for my_model, image in adjusted_list %}
  <img src="{{ image }}" />
{% endfor %}

The syntax is similar to {% adjust %}, except that:

• as <varname> is required.
• an iterable (my_queryset) and an lookup to be performed on each item in the iterable ("method.image") are provided in place of an image file or storage path.
• {% adjust_bulk %} doesn’t support named crops.

Editing Areas¶

Daguerre provides a widget which can be used with any ImageField to edit Areas for that image file. Using this widget with a ModelAdmin is as simple as defining appropriate formfield_overrides.

from daguerre.widgets import AreaWidget

class YourModelAdmin(admin.ModelAdmin):
    formfield_overrides = {
        models.ImageField: {'widget': AreaWidget},
    }
    ...

./manage.py clean_daguerre¶

Cleans out extra data stored by daguerre:

• AdjustedImages and Areas that reference storage paths which no longer exist.
• Duplicate AdjustedImages.
• Adjusted image files which don’t have an associated AdjustedImage.

./manage.py preadjust [--remove]¶

Looks for a DAGUERRE_PREADJUSTMENTS setting using the following syntax:

DAGUERRE_PREADJUSTMENTS = {
    ('myapp.MyModel', 'template.style.lookup'): (
        {'adjustment': 'fit',
         'width': 800,
         'height': 500},
        {'adjustment': 'fill',
         'width': 300,
         'height': 216},
        ...
    ),
}

In this dictionary, the values are lists of adjustment keyword arguments. The keys are tuples where the first value is either an '<applabel>.<ModelName>' string, a model class, or a queryset, and the second value is a template-style lookup which can be applied to each item of the given model type in order to get an ImageFieldFile or a storage path.

The command will collect storage paths based on the keys and make AdjustedImages for each one based on the list of kwargs, if such an AdjustedImage doesn’t already exist.

If --remove is specified, the command will delete all AdjustedImage instances which do not match one of the model/lookup/kwargs combinations specified in DAGUERRE_PREADJUSTMENTS.

Authors¶

Django Daguerre is primarily the work of Stephen Burrows, with contributions from Harris Lapiroff. It was originally written for Oberlin College in Oberlin, Ohio.

Contributing¶

Django Daguerre is a still-nascent project and greatly appreciates any contributions—code, tests, documentation, bug reports, feature requests, & al.

Development is done through the official GitHub repository. You may fork the repository and issue pull requests. You may also add bugs and feature requests under Issues.

News¶

Built-In Adjustments¶

When used with the template tag, these adjustments should be referred to by their lowercase name:

{% adjust adjustment="fit" width=300 %}

See Using daguerre for examples.