wagtail/docs/advanced_topics/images/renditions.md

(image_renditions)=

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:

(prefetching_image_renditions)=

Prefetching image renditions

When using a queryset to render a list of images or objects with images, you can prefetch the renditions needed 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.

The `prefetch_renditions` method is only applicable in Wagtail versions 4.0 and above.

Image QuerySets

When working with an Image QuerySet, you can make use of Wagtail's built-in prefetch_renditions queryset method to prefetch the renditions needed.

For example, say you were rendering a list of all the images uploaded by a certain user:

def get_images_uploaded_by_user(user):
    return ImageModel.objects.filter(uploaded_by_user=user)

The above can be modified slightly to prefetch the renditions of the images returned:

def get_images_uploaded_by_user(user)::
    return ImageModel.objects.filter(uploaded_by_user=user).prefetch_renditions()

The above will prefetch all renditions even if we may not need them.

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 specifying a set of filters to the prefetch_renditions method and only select the renditions you need for rendering. For example:

def get_images_uploaded_by_user(user):
    # Only specify the renditions required for rendering
    return ImageModel.objects.filter(uploaded_by_user=user).prefetch_renditions(
        "fill-700x586", "min-600x400", "max-940x680"
    )

Non Image Querysets

If you're working with a non Image Model, you can make use of Django's built-in prefetch_related() queryset method to prefetch renditions.

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 you know in advance the renditions you'll need, you can filter the renditions queryset to use:

from django.db.models import Prefetch
from wagtail.images import get_image_model


def get_events():
    Image = get_image_model()
    filters = ["fill-300x186", "fill-600x400", "fill-940x680"]

    # `Prefetch` is used to fetch only the required renditions
    prefetch_images_and_renditions = Prefetch(
        "listing_image",
        queryset=Image.objects.prefetch_renditions(*filters)
    )
    return EventPage.objects.live().prefetch_related(prefetch_images_and_renditions)

(image_rendition_methods)=

Model methods involved in rendition generation

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:

.. automodule:: wagtail.images.models

.. class:: AbstractImage
    :noindex:

    .. automethod:: get_rendition

    .. automethod:: find_existing_rendition

    .. automethod:: create_rendition

    .. automethod:: generate_rendition_file