Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

imagine.constants

import imagine

Everything here is re-exported by imagine, so import imagine is enough and the names are called as imagine.*. Importing imagine.constants on its own works too and reaches the same definitions.

Every named constant the module takes as an argument: resampling filters, blend modes, line caps, edge handling, file formats, anchor points, text alignment and flip axes.

They are gathered here so that a call reads as imagine.BILINEAR rather than a bare number whose meaning has to be looked up.

Constants

NEAREST

imagine.NEAREST: string = 'nearest'

Nearest-neighbour. Picks the single closest source pixel and copies it, so it is the fastest filter and the only one that keeps hard edges perfectly hard.

Right for pixel art, QR codes, and any image where a blurred edge would be wrong. Wrong for photographs, where it produces visible stair-stepping.

BILINEAR

imagine.BILINEAR: string = 'bilinear'

Bilinear. Averages the four surrounding pixels.

A good default when speed matters more than sharpness. Enlarging with it looks soft; shrinking by more than about half loses detail, because it samples too few source pixels to represent what it discards.

BICUBIC

imagine.BICUBIC: string = 'bicubic'

Bicubic (Catmull-Rom). Fits a curve through sixteen surrounding pixels.

Noticeably sharper than bilinear when enlarging, at a few times the cost. A reasonable default for photographs.

GAUSSIAN

imagine.GAUSSIAN: string = 'gaussian'

Gaussian. Weights the neighbourhood by a bell curve.

Softer than bicubic on purpose. Useful when the result will be sharpened afterwards, or when resampling noisy input where a sharper filter would emphasise the noise.

LANCZOS

imagine.LANCZOS: string = 'lanczos'

Lanczos with a 3-lobe window. The highest quality filter here and the slowest.

The usual choice for thumbnails, where the image is being shrunk a long way and every remaining pixel matters. It can produce faint ringing next to very high-contrast edges, which is the price of its sharpness.

BLEND_NORMAL

imagine.BLEND_NORMAL: string = 'normal'

Ordinary alpha compositing: the source is painted over the destination according to its alpha. This is the default for every drawing and compositing operation.

BLEND_MULTIPLY

imagine.BLEND_MULTIPLY: string = 'multiply'

Multiplies the two colours. The result is never lighter than either input, so white leaves the backdrop alone and black forces black. The usual way to paint a shadow.

BLEND_SCREEN

imagine.BLEND_SCREEN: string = 'screen'

The inverse of multiply. The result is never darker than either input, so black leaves the backdrop alone and white forces white. The usual way to paint a glow.

BLEND_OVERLAY

imagine.BLEND_OVERLAY: string = 'overlay'

Multiply where the backdrop is dark, screen where it is light. Increases contrast while keeping highlights and shadows.

BLEND_DARKEN

imagine.BLEND_DARKEN: string = 'darken'

Keeps whichever channel is darker.

BLEND_LIGHTEN

imagine.BLEND_LIGHTEN: string = 'lighten'

Keeps whichever channel is lighter.

BLEND_COLOR_DODGE

imagine.BLEND_COLOR_DODGE: string = 'color_dodge'

Brightens the backdrop toward the source. Strong effect; saturates quickly.

BLEND_COLOR_BURN

imagine.BLEND_COLOR_BURN: string = 'color_burn'

Darkens the backdrop toward the source. The counterpart of dodge.

BLEND_HARD_LIGHT

imagine.BLEND_HARD_LIGHT: string = 'hard_light'

Overlay with the roles of source and backdrop swapped.

BLEND_SOFT_LIGHT

imagine.BLEND_SOFT_LIGHT: string = 'soft_light'

A gentler hard light, as if the source were a diffuse spotlight.

BLEND_DIFFERENCE

imagine.BLEND_DIFFERENCE: string = 'difference'

The absolute difference between the two colours. Identical images blended this way come out black, which makes it a quick visual diff.

BLEND_EXCLUSION

imagine.BLEND_EXCLUSION: string = 'exclusion'

Like difference, but lower contrast in the midtones.

BLEND_ADD

imagine.BLEND_ADD: string = 'add'

Adds the channels, clamped at white. Also called linear dodge.

BLEND_SUBTRACT

imagine.BLEND_SUBTRACT: string = 'subtract'

Subtracts the source from the backdrop, clamped at black.

CAP_BUTT

imagine.CAP_BUTT: string = 'butt'

The stroke stops dead at its endpoint. Nothing is drawn past the coordinates given.

The right choice when segments have to meet exactly, when a stroke’s length must be precisely what was asked for, or for the pieces of a dashed line.

CAP_ROUND

imagine.CAP_ROUND: string = 'round'

The stroke ends in a half-disc, so it reaches half its width past the endpoint. The default.

CAP_SQUARE

imagine.CAP_SQUARE: string = 'square'

The stroke ends in a square, so it reaches half its width past the endpoint, the same distance a round cap does but with corners.

EDGE_CLAMP

imagine.EDGE_CLAMP: string = 'clamp'

Pixels off the edge take the value of the nearest edge pixel. The default, and what keeps a blur from darkening the border.

EDGE_TRANSPARENT

imagine.EDGE_TRANSPARENT: string = 'transparent'

Pixels off the edge are treated as transparent black. Correct when the image really does end there and you want the blur to fade out.

EDGE_WRAP

imagine.EDGE_WRAP: string = 'wrap'

Pixels off the edge wrap to the opposite side. For images meant to tile seamlessly.

PNG

imagine.PNG: string = 'png'

PNG. Lossless, alpha, universally supported. The right default for anything with sharp edges, text or transparency.

JPEG

imagine.JPEG: string = 'jpeg'

JPEG. Lossy, no alpha. The right choice for photographs, and the wrong one for anything with hard edges. Transparent pixels are flattened against the background option on export, white unless you say otherwise.

GIF

imagine.GIF: string = 'gif'

GIF. At most 256 colours per frame, one-bit transparency, and the only animated format this module can write.

BMP

imagine.BMP: string = 'bmp'

BMP. Uncompressed and enormous, but readable by anything.

TIFF

imagine.TIFF: string = 'tiff'

TIFF. Lossless, alpha, common in printing and scanning workflows.

TGA

imagine.TGA: string = 'tga'

Truevision TGA. Lossless with alpha, still common in game asset pipelines.

WEBP

imagine.WEBP: string = 'webp'

WebP. Lossless with alpha, and smaller than PNG for the same pixels.

Reading handles lossy and lossless WebP, still and animated. Writing produces a lossless still, so the quality option does not apply and a photograph written here will be larger than one a lossy WebP encoder would produce. Reach for JPEG or AVIF when size matters more than exactness.

AVIF

imagine.AVIF: string = 'avif'

AVIF. The smallest files of anything here at a given quality.

Write only. Opening an AVIF raises DecodeError, and [[imagine.capabilities]] lists AVIF under encode but not decode, so a program can check rather than discover it at run time.

QOI

imagine.QOI: string = 'qoi'

QOI, the Quite OK Image format. Lossless with alpha, encodes and decodes several times faster than PNG at a modest size penalty. Good for caches and intermediate files.

ICO

imagine.ICO: string = 'ico'

Windows ICO. An icon container; a single image is written as one entry.

PNM

imagine.PNM: string = 'pnm'

Netpbm (PBM, PGM, PPM). Trivially simple and trivially large.

WBMP

imagine.WBMP: string = 'wbmp'

Wireless Bitmap. One bit per pixel, no compression, no alpha.

Writing thresholds each pixel on its perceived brightness, so a colour image comes out as a black and white silhouette. Reading gives opaque black and white pixels.

TOP_LEFT

imagine.TOP_LEFT: string = 'top_left'

Where a smaller image or a piece of text sits inside a larger box, used by Image.cover(), Image.contain() and Image.place().

TOP

imagine.TOP: string = 'top'

TOP_RIGHT

imagine.TOP_RIGHT: string = 'top_right'

LEFT

imagine.LEFT: string = 'left'

CENTER

imagine.CENTER: string = 'center'

imagine.RIGHT: string = 'right'

BOTTOM_LEFT

imagine.BOTTOM_LEFT: string = 'bottom_left'

BOTTOM

imagine.BOTTOM: string = 'bottom'

BOTTOM_RIGHT

imagine.BOTTOM_RIGHT: string = 'bottom_right'

ALIGN_LEFT

imagine.ALIGN_LEFT: string = 'left'

Lines of a multi-line string start at the same left edge. The default.

ALIGN_CENTER

imagine.ALIGN_CENTER: string = 'center'

Lines of a multi-line string are centred against each other.

ALIGN_RIGHT

imagine.ALIGN_RIGHT: string = 'right'

Lines of a multi-line string end at the same right edge.

FLIP_HORIZONTAL

imagine.FLIP_HORIZONTAL: number = 1

Mirror left to right.

FLIP_VERTICAL

imagine.FLIP_VERTICAL: number = 2

Mirror top to bottom.

FLIP_BOTH

imagine.FLIP_BOTH: number = 3

Mirror both ways at once, which is the same as rotating 180 degrees.

2026, Richard Ore and Zuri contributors