Skip to main content

A reusable app for cropping images easily and non-destructively in Django

Project description

django-image-cropping
=====================

``django-image-cropping`` is an app for cropping uploaded images via Django's admin backend using `imgareaselect
<https://github.com/odyniec/imgareaselect>`_. It keeps the original image intact, only cropping when the image
is being displayed. Large images are presented in a small format, so even very big images can easily be cropped.

``django-image-cropping`` is perfect when you need images with a specific size for your templates but want your
users or editors to upload images of any dimension. It presents a selection with a fixed aspect ratio so your users
can't break the layout with oddly-sized images.

It provides the necessary fields, widgets and a (`easy_thumbnails
<http://github.com/SmileyChris/easy-thumbnails>`_) thumbnail processor for displaying the
cropped image in your templates. Also works with `FeinCMS <https://github.com/feincms/feincms>`_ content types!

Screenshot:

.. image:: http://www.jonasundderwolf.de/media/uploads/judw_logo.png

Installation
------------

#. Install django-image-cropping using pip. For example::

pip install django-image-cropping

#. Add ``easy_thumbnails`` and ``image_cropping`` to your INSTALLED_APPS. ``image_cropping`` is only required if you are using Django 1.3 and ``contrib.staticfiles``

#. Adjust the thumbnail processors for ``easy_thumbnails`` in your ``settings.py``::

from easy_thumbnails import defaults
THUMBNAIL_PROCESSORS = (
'image_cropping.thumbnail_processors.crop_corners',
) + defaults.PROCESSORS

#. Deploy the necessary static files::

If you are using Django 1.3 and ``contrib.staticfiles`` the necessary static files should be picked up automatically.
In all other cases you have to copy or symlink the static files. Depending on your setup the command should look similiar to this::

ln -s ~/.virtualenvs/yourenv/src/django-image-cropping/image_cropping/static/image_cropping/



Configuration
-------------

In order to make a regular ImageField croppable, simply turn it into an ``ImageCropField``. Then add
an ``ImageRatioField``, which will contain the boundaries of the cropped image. The ``ImageRatioField``
expects the name of the associated ImageCropField as the first argument and the size of the final image
to be displayed as the second argument.

The size is passed in as a string and defines the aspect ratio of the selection as well as the minimum
size for the final image. If the user tries to crop an image that's smaller than this minimum, the
selection is locked.

#. Model fields and options::

from image_cropping.fields import ImageRatioField, ImageCropField

image = ImageCropField(blank=True, null=True, upload_to='uploaded_images')
# size is "width x height"
cropping = ImageRatioField('image', '430x360')

#. If your setup is correct you should automatically see the enhanced image widget that provides a selection area for the image in the admin backend.

#. Example usage of the thumbnail processor::

{% thumbnail yourmodel.image 430x360 box=yourmodel.cropping crop detail %}

#. Additionally you can define the maximum size of the preview thumbnail in your settings.py::

# size is "width x height"
IMAGE_CROPPING_THUMB_SIZE = (300, 300)


Extras
------

If you need the same image in multiple formats, simply specify another ImageRatioField. This will allow the image to be cropped twice::

from image_cropping.fields import ImageRatioField, ImageCropField

image = ImageCropField(blank=True, null=True, upload_to='uploaded_images')
# size is "width x height"
list_page_cropping = ImageRatioField('image', '200x100')
detail_page_cropping = ImageRatioField('image', '430x360')


In your templates, simply use the corresponding ratio field::

{% thumbnail yourmodel.image 200x100 box=yourmodel.list_page_cropping crop detail %}

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-image-cropping, version 0.2
Filename, size File type Python version Upload date Hashes
Filename, size django-image-cropping-0.2.tar.gz (14.0 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page