gws.lib.image.format

Image formats.

PNG8, PNG24, JPEG_LOW, JPEG, JPEG_HIGH, WEBP and WEBP_LOSSLESS are predefined gws.ImageFormat objects. The first MIME type of a format is its content type, the others are names under which services offer it (image/png; mode=8bit). from_config creates a format from a Config, and best_mime_type selects the MIME type to request from a remote source (WMS, QGIS Server) for a format.

Encoding options

The options of a format are passed to gws.Image.to_bytes. mode, background and quality are also Config fields. mode and background are handled by gws.lib.image.core.Image, all other keys are passed to the PIL encoder (Pillow 12). Configured options replace those of a predefined format, except its mode, background and quality.

option

effect

formats

mode

convert to this PIL mode before encoding, with an adaptive palette: P (8-bit palette), RGBA, RGB, L (grayscale); JPEG accepts only RGB, L, CMYK

all

background

color of transparent areas when RGBA is converted to RGB, default white

JPEG

quality

JPEG 1-95 (default 75), WebP 0-100 (default 80); for lossless WebP the encoder effort; TIFF with compression: jpeg only

JPEG, WebP, TIFF

compress_level

zlib level 0-9, default 6; predefined PNG formats use 3

PNG

optimize

optimized Huffman tables

JPEG

progressive

progressive JPEG

JPEG

subsampling

chroma subsampling: 0 = 4:4:4, 1 = 4:2:2, 2 = 4:2:0

JPEG

lossless

lossless WebP

WebP

method

encoder effort 0-6, default 4 (higher = smaller, slower)

WebP

alpha_quality

alpha channel quality 0-100, default 100

WebP

compression

raw, tiff_lzw, tiff_adobe_deflate, jpeg, packbits

TIFF

Not to be used: PNG optimize and compress_level: 9 (6-10x slower than level 6, at most 2% smaller), PNG bits and transparency (break the palette created by mode: P), WebP exact, JPEG quality above 95, smooth, qtables, restart_marker_*, dpi (header only, no effect on maps), metadata and animation options, mode: P with WebP (converted back to RGBA).

Measured on map tiles and a 1024 px aerial image: compress_level: 3 encodes PNG24 2-3x and PNG8 3x faster than the default 6, at most 8% larger. Lossy WebP is 15-50% smaller than PNG8 and 6x slower to encode; lossless WebP is 2-4x smaller than PNG24, but larger and much slower than PNG8. JPEG on a 1024 px map: quality 50 is 35% smaller than 75, quality 90 is 70% larger; subsampling: 0 adds another 40% at quality 90.

Source code: gws.lib.image.format

Module Contents

gws.lib.image.format.best_mime_type(ifo: gws.ImageFormat, supported: list[str]) → str

Select the MIME type to request from a source for an image format.

The supported MIME types are tried longest first, so that a specific one (image/png; mode=8bit) wins over a plain one (image/png). The first one that is among the MIME types of the format is selected.

Parameters:
  • ifo – Image format.

  • supported – MIME types the source supports, normalized with gws.lib.mime.get.

Returns:

The selected MIME type, or an empty string if none matches.

class gws.lib.image.format.Config(*args, **kwargs)

Bases: gws.Config

Image format with its encoding options.

background: gws.Color | None

Color of transparent areas in formats without transparency (JPEG).

mimeTypes: list[gws.MimeType] | None

MIME types for this format, replace those of the predefined format.

mode: ImageMode | None

Image mode.

name: ImageFormatName

Predefined format.

options: dict | None

Further image encoding options.

quality: int | None

JPEG 1-95, WebP 0-100.

Type:

Encoding quality

gws.lib.image.format.find_by_mime_type(mime: gws.MimeType, formats: list[gws.ImageFormat]) → gws.ImageFormat | None

Find an image format by one of its MIME types.

Parameters:
  • mime – MIME type, normalized with gws.lib.mime.get.

  • formats – Image formats.

Returns:

The first format that has the MIME type, or None if there is none.

gws.lib.image.format.from_config(cfg: Config) → gws.ImageFormat

Create an image format from its configuration.

The format is based on the predefined format name. Configured MIME types replace those of the predefined format, and so do configured options, except that the predefined mode, background and quality are kept unless the configured options set them. The configured mode, background and quality fields are applied last.

Parameters:

cfg – Format configuration.

Returns:

The image format.

Raises:

Error – If the name is not a predefined format or the configuration has no known MIME types.

class gws.lib.image.format.ImageFormatName

Bases: gws.Enum

Predefined image format.

JPEG = 'JPEG'

JPEG with quality 75.

JPEG_HIGH = 'JPEG_HIGH'

JPEG with quality 90.

JPEG_LOW = 'JPEG_LOW'

JPEG with quality 50.

PNG24 = 'PNG24'

PNG with full color and alpha.

PNG8 = 'PNG8'

PNG with an 8-bit palette.

WEBP = 'WEBP'

Lossy WebP.

WEBP_LOSSLESS = 'WEBP_LOSSLESS'

Lossless WebP.

class gws.lib.image.format.ImageMode

Bases: gws.Enum

Image mode the image is converted to before encoding.

L = 'L'

Grayscale.

P = 'P'

8-bit palette.

RGB = 'RGB'

Full color without transparency.

RGBA = 'RGBA'

Full color with transparency.

gws.lib.image.format.JPEG
gws.lib.image.format.JPEG_HIGH
gws.lib.image.format.JPEG_LOW
gws.lib.image.format.PNG24
gws.lib.image.format.PNG8
gws.lib.image.format.WEBP
gws.lib.image.format.WEBP_LOSSLESS