Generating renditions in Python¶
Rendered versions of original images generated by the Wagtail {% image %}
template tag are called “renditions”,
and are stored as new image files in the site’s [media]/images
directory on the first invocation.
Image renditions can also be generated dynamically from Python via the native get_rendition()
method, for example:
newimage = myimage.get_rendition('fill-300x150|jpegquality-60')
If myimage
had a filename of foo.jpg
, a new rendition of the image file called
foo.fill-300x150.jpegquality-60.jpg
would be generated and saved into the site’s [media]/images
directory.
Argument options are identical to the {% image %}
template tag’s filter spec, and should be separated with |
.
The generated Rendition
object will have properties specific to that version of the image, such as
url
, width
and height
, so something like this could be used in an API generator, for example:
url = myimage.get_rendition('fill-300x186|jpegquality-60').url
Properties belonging to the original image from which the generated Rendition was created, such as title
, can
be accessed through the Rendition’s image
property:
>>> newimage.image.title
'Blue Sky'
>>> newimage.image.is_landscape()
True
See also: How to use images in templates
Prefetching image renditions¶
New in version 3.0: This following guidance is only applicable in Wagtail versions 3.0 and above.
When using a queryset to render a list of objects with images, you can make use of Django’s built-in prefetch_related()
queryset method to prefetch the renditions needed for rendering with a single additional query. For long lists of items, or where multiple renditions are used for each item, this can provide a significant boost to performance.
For example, say you were rendering a list of events (with thumbnail images for each). Your code might look something like this:
def get_events():
return EventPage.objects.live().select_related("listing_image")
The above can be modified slightly to prefetch the renditions for listing images:
def get_events():
return EventPage.objects.live().select_related("listing_image").prefetch_related("listing_image__renditions")
If images in your project tend to have very large numbers of renditions, and you know in advance the ones you need, you might want to consider using a Prefetch
object to select only the renditions you need for rendering. For example:
from django.db.models import Prefetch
from wagtail.images import get_image_model
def get_events():
# These are the renditions required for rendering
renditions_queryset = get_image_model().get_rendition_model().objects.filter(
filter_spec__in=["fill-300x186", "fill-600x400", "fill-940x680"]
)
# `Prefetch` is used to fetch only the required renditions
return EventPage.objects.live().select_related("listing_image").prefetch_related(
Prefetch("listing_image__renditions", queryset=renditions_queryset)
)
Model methods involved in rendition generation¶
New in version 3.0: The following method references are only applicable to Wagtail versions 3.0 and above.
The following AbstractImage
model methods are involved in finding and generating a renditions. If using a custom image model, you can customise the behaviour of either of these methods by overriding them on your model:
- class wagtail.images.models.AbstractImage
- get_rendition(filter: Union[wagtail.images.models.Filter, str]) wagtail.images.models.AbstractRendition ¶
Returns a
Rendition
instance with afile
field value (an image) reflecting the suppliedfilter
value and focal point values from this object.Note: If using custom image models, an instance of the custom rendition model will be returned.
- find_existing_rendition(filter: wagtail.images.models.Filter) wagtail.images.models.AbstractRendition ¶
Returns an existing
Rendition
instance with afile
field value (an image) reflecting the suppliedfilter
value and focal point values from this object.If no such rendition exists, a
DoesNotExist
error is raised for the relevant model.Note: If using custom image models, an instance of the custom rendition model will be returned.
- create_rendition(filter: wagtail.images.models.Filter) wagtail.images.models.AbstractRendition ¶
Creates and returns a
Rendition
instance with afile
field value (an image) reflecting the suppliedfilter
value and focal point values from this object.This method is usually called by
Image.get_rendition()
, after first checking that a suitable rendition does not already exist.Note: If using custom image models, an instance of the custom rendition model will be returned.
- generate_rendition_file(filter: wagtail.images.models.Filter) django.core.files.base.File ¶
Generates an in-memory image matching the supplied
filter
value and focal point value from this object, wraps it in aFile
object with a suitable filename, and returns it. The return value is used as thefile
field value for rendition objects saved byAbstractImage.create_rendition()
.NOTE: The responsibility of generating the new image from the original falls to the supplied
filter
object. If you want to do anything custom with rendition images (for example, to preserve metadata from the original image), you might want to consider swapping outfilter
for an instance of a customFilter
subclass of your design.