Skip to content

Meringue Thumbnail¤

This package provides functionality for generating image thumbnails. It supports resizing, cropping, format conversion, and various processing strategies based on a chain of jobs (commands).

The main functionality is based on the Thumbnailer class, which processes images using a configurable job chain — a sequence of properties and actions applied to an image.

Concept¤

The job chain is a list of string commands that are executed sequentially. Commands are divided into two types:

  • Properties — set parameters for subsequent actions (e.g., target size, resize method). Properties are written in the format key:value.
  • Actions — perform image transformations (e.g., resize, crop). Actions are written as a single word.

The order of commands matters: properties must be set before the actions that use them. The order of actions is also important — for example, resize followed by crop will first scale the image and then trim the canvas, while crop followed by resize will first trim and then scale, producing different results.

Available properties¤

  • s:<width>x<height> — sets the target size for subsequent actions. If one dimension is omitted (e.g., s:400x), it will be calculated proportionally.
  • maxw:<width> — sets the maximum width.
  • maxh:<height> — sets the maximum height.
  • c:<r> <g> <b> <a> — background color for cropping in RGBA format (e.g., c:255 255 255 255).
  • cm:<horizontal> <vertical> — crop anchor point. Horizontal: left, center, right. Vertical: top, center, bottom. Single value center is also accepted.
  • rm:<method> — resize method: cover (fill the target area), contain (fit within the target area), stretch (stretch to exact size).
  • rs:<strategy> — resize strategy: standard, no_increase (do not upscale), no_reduce (do not downscale).

Available actions¤

  • resize — resizes the image according to the current target size and resize method/strategy.
  • crop — crops or extends the canvas to the current target size, positioning the image according to the crop method.

Supported formats¤

The following image formats are supported: BMP, EPS, GIF, ICO, JPEG, PNG, TIFF, WEBP.

Setup¤

Add meringue.thumbnail to INSTALLED_APPS:

settings.py
INSTALLED_APPS = (
    ...
    "meringue.thumbnail",
    ...
)

The package requires Pillow for image processing:

$ pip install Pillow

Usage¤

Shortcut¤

The simplest way to generate a thumbnail is using the get_thumbnail shortcut:

from pathlib import Path
from meringue.thumbnail.shortcuts import get_thumbnail

url = get_thumbnail(
    file_path=Path("/path/to/image.jpg"),
    job_chain=["s:300x200", "rm:cover", "resize", "crop"],
    out_format="WEBP",
)

If the source file does not exist, a dummy image URL will be returned.

Thumbnailer¤

For more control, you can use the Thumbnailer directly:

from pathlib import Path
from meringue.thumbnail.generators import DefaultThumbnailer

thumbnailer = DefaultThumbnailer(
    image_path=Path("/absolute/path/to/image.jpg"),
    job_chain=["s:600x400", "resize", "s:400x400", "crop"],
)
thumbnail = thumbnailer.get_thumbnail("WEBP")
print(thumbnail.url)

Note

The image_path must be an absolute path.

Templatetags¤

thumbnail¤

Image processing filter. Applied to an image file path; expects comma-separated processing parameters as arguments. Actions are executed in the order they are specified.

For example:

  • s:600x400,resize,s:400x400,crop — first sets the target size to 600x400, then resizes the image to that size, then sets a new target size of 400x400, and finally crops the canvas to 400x400.
  • crop,s:400x400 — produces no result because the new size is specified after the crop action (swapping the order would crop the image to a 400x400 square).

Filter arguments:

  • s:<width>x<height> — sets the target size for subsequent actions.
  • maxw:<width> — sets the maximum width.
  • maxh:<height> — sets the maximum height.
  • crop — changes the canvas size to the last specified target size.
  • resize — resizes the image to the last specified target size.
  • c:<color> — background fill color for crop in RGBA format (e.g., c:255 255 255 255).
  • cm:left|center|right top|bottom — crop anchor point.
  • rm:cover|contain|stretch — resize method.
  • rs:no_increase|standard|no_reduce — resize strategy.
{% load m_thumbnails %}

<img src="{{ image_path|thumbnail:'s:300x200,rm:cover,resize,crop' }}" />

DRF fields¤

For the Django REST Framework, the package provides two serializer fields:

MImageField¤

MImageField — a field that returns a URL to an optimized image. You can specify either size or job_chain:

from meringue.thumbnail.drf_fields import MImageField

class MySerializer(serializers.ModelSerializer):
    photo = MImageField(size=(300, 200))
    # or
    photo = MImageField(job_chain=["s:300x200", "rm:cover", "rs:no_increase", "resize"])

MImageSetField¤

MImageSetField — a field that returns a set of images in different formats (original + WebP) and dimensions (1x, 2x, etc.) for use with the <picture> element. Under the hood, the image is processed once per dimension and then saved into multiple formats, which saves resources compared to running the full job chain separately for each format:

from meringue.thumbnail.drf_fields import MImageSetField

class MySerializer(serializers.ModelSerializer):
    photo = MImageSetField(size=(300, 200), dimensions=(1, 2))

The response will contain an array of objects with srcset and type fields:

[
    {"srcset": "/media/m/thumbnail/.../image.webp 1x, .../image.webp 2x", "type": "image/webp"},
    {"srcset": "/media/m/thumbnail/.../image.jpg 1x, .../image.jpg 2x", "type": "image/jpeg"}
]

Storage¤

Thumbnails are saved to a separate storage configured via THUMBNAIL_DIR and THUMBNAIL_URL. The storage initialization can be customized through the THUMBNAIL_STORAGE_GETTER setting.

Customization¤

The thumbnail system is highly customizable through settings:

Authors: Dmitry Dobrynin