.. _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: .. code-block:: python 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: .. code-block:: python 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: .. code-block:: python >>> newimage.image.title 'Blue Sky' >>> newimage.image.is_landscape() True See also: :ref:`image_tag` .. _prefetching_image_renditions: Prefetching image renditions ---------------------------- .. versionadded:: 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: .. code-block:: python def get_events(): return EventPage.objects.live().select_related("listing_image") The above can be modified slightly to prefetch the renditions for listing images: .. code-block:: python 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: .. code-block:: python 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) ) .. _image_rendition_methods: Model methods involved in rendition generation ---------------------------------------------- .. versionadded:: 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: .. automodule:: wagtail.images.models .. class:: AbstractImage :noindex: .. automethod:: get_rendition .. automethod:: find_existing_rendition .. automethod:: create_rendition .. automethod:: generate_rendition_file