Welcome to django-versatileimagefield’s documentation!

---

A drop-in replacement for django’s ImageField that provides a flexible, intuitive and easily-extensible interface for creating new images from the one assigned to the field.

Click here for a quick overview of what it is, how it works and whether or not it’s the right fit for your project.

Compatibility

• Python:
  • 2.7
  • 3.3
  • 3.4
• Django:
  • 1.6.x
  • 1.7.x
  • 1.8.x
• Pillow >= 2.4.0
• Django REST Framework:
  • 2.3.14
  • 2.4.4
  • 3.0.x
  • 3.1.x

Code

django-versatileimagefield is hosted on github.

Table of Contents

• Overview
  • Works just like ImageField
  • Create Images Wherever You Need Them
    • Crop images at specific sizes
  • Custom, Per-Image Cropping
  • Filters, too!
  • Write your own Sizers & Filters
  • Django REST Framework Integration
  • Flexible in development, light-weight in production
  • Fully Tested & Python 3 Ready
  • Get Started
• Installation
  • Python Compatibility
  • Django Compatibility
  • Dependencies
  • Settings
    • VERSATILEIMAGEFIELD_SETTINGS
    • VERSATILEIMAGEFIELD_USE_PLACEHOLDIT
    • VERSATILEIMAGEFIELD_RENDITION_KEY_SETS
      • Writing Rendition Keys
      • Using Rendition Key Sets
• Model Integration
  • Specifying Placeholder Images
    • OnDiscPlaceholderImage
      • Where OnDiscPlaceholderImage saves images to
    • OnStoragePlaceholderImage
      • Where OnStoragePlaceholderImage saves images to
• Specifying a Primary Point of Interest (PPOI)
  • The PPOIField
    • How PPOI is Stored in the Database
  • Setting PPOI
    • Via The Shell
  • FormField/Admin Integration
• Using Sizers and Filters
  • Sizers
    • Included Sizers
      • thumbnail
      • crop
  • Filters
    • Included Filters
      • invert
    • Using Sizers with Filters
    • How Filtered Image Files are Named/Stored
  • Using Sizers / Filters in Templates
• Writing Custom Sizers and Filters
  • Writing a Custom Sizer
  • Writing a Custom Filter
  • What process_image should return
  • The Pre-processing API
    • Pre-processor Naming Convention
  • Registering Sizers and Filters
    • Unallowed Sizer & Filter Names
  • Overriding an existing Sizer or Filter
• Django REST Framework Integration
  • Example
    • Reusing Rendition Key Sets
• Improving Performance
  • Turning off on-demand image creation
  • Ensuring images are created
    • Auto-creating sets of images on post_save

Release Notes

1.0.1

• Squashed a critical bug in OnDiscPlaceholderImage

1.0

• Added support for Django 1.8.
• Numerous documentation edits/improvements.

0.6.2

• Squashed a bug that caused the javascript ‘click’ widget to fail to initialize correctly when multiple VersatileImageFields were displayed on the same page in the admin.
• Added django.contrib.staticfiles integration to widgets.

0.6.1

• Squashed a bug that was throwing an AttributeError when uploading new images.

0.6

• Squashed a bug that raised a ValueError in the admin when editing a model instance with a VersatileImageField that specified ppoi_field, width_field and height_field.
• Admin ‘click’ widget now works in Firefox.
• django-versatileimagefield is now available for installation via wheel.

0.5.4

• Squashed a bug that was causing the admin ‘click’ widget to intermittently fail
• Simplified requirements installation (which makes django-versatileimagefield installable by pip<=1.6)

0.5.3

• Changed PPOIField to be editable=False by default to address a bug that consistently raised ValidationError in ModelForms and the admin

0.5.2

• Squashed a bug that prevented PPOIField from serializing correctly

0.5.1

• Squashed an installation bug with pip 6+

0.5

• Added Python 3.3 & 3.4 compatibility
• Improved cropping with extreme PPOI values

0.4

• Dropped support for Django 1.5.x
• Introducing per-field placeholder image image support! (Note: global placeholder support has been deprecated.)
• Added the VERSATILEIMAGEFIELD_USE_PLACEHOLDIT setting (docs)

0.3.1

• Squashed a pip installation bug.

0.3

• Added a test suite with Travis CI and coveralls integration.
• Introduced support for Django REST Framework 3.0 serialization.

0.2.1

• Ensuring admin widget-dependent thumbnail images are created even if VERSATILEIMAGEFIELD_SETTINGS['create_on_demand'] is set to False

0.2

• Introduced Django REST Framework support!
• Added ability to turn off on-demand image creation and pre-warm images to improve performance.

0.1.5

• Squashed CroppedImage bug that was causing black stripes to appear on crops of images with PPOI values that were to the right and/or bottom of center (greater-than 0.5).

0.1.4

• Overhauled how CroppedImage processes PPOI value when creating cropped images. This new approach yields significantly more accurate results than using the previously utilized ImageOps.fit function, especially when dealing with PPOI values located near the edges of an image or aspect ratios that differ significantly from the original image.
• Improved PPOI validation
• Squashed unset VERSATILEIMAGEFIELD_SETTINGS['global_placeholder_image'] bug.
• Set crop Sizer default resample to PIL.Image.ANTIALIAS

0.1.3

• Added support for auto-rotation during pre-processing as dictated by ‘Orientation’ EXIF data, if available.
• Added release notes to docs

0.1.2

• Removed redundant javascript from ppoi ‘click’ widget (thanks, @skumar!)

0.1.1

• Converted giant README into Sphinx-friendly RST
• Docs added to readthedocs

0.1

• Initial open source release