`gws.lib.image`¶

Raster images.

Provides Image, the implementation of gws.Image on top of a PIL image, and functions to create images from various sources and to encode them.

Images are created with the from_* functions (an empty image of a given size, encoded bytes, raw pixel data, a file, a data URL or a numpy array) or with qr_code. The Image methods resize, crop, rotate, paste and compose images and encode them as bytes, base64, data URLs or files. The output format is selected by a MIME type; PNG is the default.

Image sizes are limited to MAX_PIXELS. thumbnail scales encoded images down, pixel, empty_pixel and error_pixel return cached encoded 1x1 images. get_draw and get_font give access to PIL drawing on an image.

Example:

img = gws.lib.image.from_size((256, 256))
img.compose(gws.lib.image.from_path('/data/overlay.png'), opacity=0.5)
png = img.to_bytes(gws.lib.mime.PNG, {'mode': 'P'})

Source code: gws.lib.image

Package Contents¶

gws.lib.image.empty_pixel(mime_type: str = None)¶

Return an encoded empty 1x1 image.

The pixel is transparent, or white for JPEG.

Parameters:: mime_type – MIME type, PNG by default.
Returns:: The encoded image.
Raises:: Error – If the MIME type is not an image type.

exception gws.lib.image.Error¶

Bases: gws.Error

Image error.

gws.lib.image.error_pixel(mime_type: str = None)¶

Return an encoded 1x1 image in the error color.

Parameters:: mime_type – MIME type, PNG by default.
Returns:: The encoded image.
Raises:: Error – If the MIME type is not an image type.

class gws.lib.image.FormatConfig(*args, **kwargs)¶

Bases: gws.Config

Image format with its encoding options.

mimeTypes: list[gws.MimeType]¶: MIME types for this format.

name: str = ''¶: Name of the format.

options: dict | None¶: Image encoding options.

gws.lib.image.from_array(arr: numpy.ndarray) → Image¶

Create an image from a numpy array.

Parameters:: arr – Pixel array, as returned by Image.to_array.
Returns:: An image object.
Raises:: Error – If the image data cannot be loaded.

gws.lib.image.from_bytes(r: bytes) → Image¶

Create an image from encoded bytes.

Parameters:: r – Encoded image, in any format PIL can read.
Returns:: An image object.
Raises:: Error – If the image data cannot be loaded.

gws.lib.image.from_data_url(url: str) → Image¶

Create an image from a base64 data URL.

Only PNG, GIF and JPEG data URLs are accepted.

Parameters:: url – A data:image/...;base64, URL.
Returns:: An image object.
Raises:: Error – If the URL is not a supported data URL or the image cannot be loaded.

gws.lib.image.from_path(path: str) → Image¶

Create an image from a file.

Parameters:: path – Path to an image file.
Returns:: An image object.
Raises:: Error – If the image data cannot be loaded.

gws.lib.image.from_raw_data(r: bytes, mode: str, size: gws.Size) → Image¶

Create an image from raw pixel data.

Parameters:

r – Raw pixel data.
mode – PIL image mode of the data.
size – Image size (width, height).

Returns:

An image object.

Raises:

Error – If the image has more than MAX_PIXELS pixels.

gws.lib.image.from_size(size: gws.Size, color=None) → Image¶

Create an RGBA image filled with one color.

Parameters:

size – Image size (width, height).
color – Fill color (red, green, blue, alpha), transparent by default.

Returns:

An image object.

Raises:

Error – If the image has more than MAX_PIXELS pixels.

gws.lib.image.from_svg(xmlstr: str, size: gws.Size, mime_type=None) → Image¶

Create an image from an SVG document. Not implemented.

Parameters:

xmlstr – SVG source.
size – Image size (width, height).
mime_type – MIME type.

Returns:

An image object.

Raises:

NotImplementedError – Always.

gws.lib.image.get_draw(img: Image) → PIL.ImageDraw.ImageDraw¶

Return a PIL drawing object for an image.

Parameters:: img – An image object.
Returns:: A PIL.ImageDraw.ImageDraw that draws on the image in place.

gws.lib.image.get_font(size: int = 12, font: str | None = None) → PIL.ImageFont.ImageFont | PIL.ImageFont.FreeTypeFont¶

Return a PIL font object.

Parameters:

size – Font size, used for TrueType fonts only.
font – Path to a TrueType font file, or None for the PIL default font.

Returns:

A PIL font object.

class gws.lib.image.Image(img: PIL.Image.Image)¶

Bases: gws.Image

Image object, a wrapper around a PIL image.

img: PIL.Image.Image¶

add_box(color=None)¶

Draw a 1 pixel wide frame along the image edges.

The image is converted to RGBA.

Parameters:: color – Line color, black by default.
Returns:: The image.

add_text(text, x=0, y=0, color=None)¶

Draw text on the image with the default font.

The image is converted to RGBA.

Parameters:

text – Text, can contain multiple lines.
x – X coordinate of the top left corner of the text.
y – Y coordinate of the top left corner of the text.
color – Text color, black by default.

Returns:

The image.

compare_to(other)¶

Compare this image to another one.

Computes the mean squared difference of the RGBA channels over all pixels, normalized to the range 0 to 1. Both images must be RGBA and have the same size.

Parameters:: other – Image to compare to.
Returns:: 0 if the images are equal, larger values for larger differences.

compose(other, opacity=1)¶

Place another image on top of this one, using alpha composition.

The other image is resized to the size of this one if needed.

Parameters:

other – Image to place on top.
opacity – Opacity of the other image, from 0 to 1.

Returns:

The image.

convert(mode)¶

Convert the image to a mode.

Parameters:: mode – PIL image mode.
Returns:: The image.

crop(box)¶

Crop the image.

Parameters:: box – Crop rectangle (left, upper, right, lower) in pixels.
Returns:: The image.

mode()¶

Get the image mode.

Returns:: PIL image mode, e.g. RGBA.

paste(other, where=None)¶

Paste another image into this one.

Parameters:

other – Image to paste.
where – Position (x, y) of the upper left corner, or a box (left, upper, right, lower). By default, the image is pasted at (0, 0).

Returns:

The image.

resize(size, **kwargs)¶

Resize the image to a size, without keeping the aspect ratio.

Parameters:

size – New size (width, height).
**kwargs – Options for PIL.Image.resize. The default resampling is bicubic.

Returns:

The image.

resize_to(width=0, height=0, **kwargs)¶

Resize the image to a width, a height or both.

If only one dimension is given, the other is computed to keep the aspect ratio. If none is given, the image is not changed.

Parameters:

width – New width.
height – New height.
**kwargs – Options for PIL.Image.resize.

Returns:

The image.

rotate(angle, **kwargs)¶

Rotate the image counter-clockwise.

Parameters:

angle – Angle in degrees.
**kwargs – Options for PIL.Image.rotate. The default resampling is bicubic.

Returns:

The image.

size()¶

Get the image size.

Returns:: A tuple (width, height) in pixels.

to_array()¶

Convert the image to a numpy array.

Returns:: An array of shape (height, width) or (height, width, channels).

to_base64(mime_type=None, options=None)¶

Encode the image as a base64 string.

Parameters:

mime_type – MIME type of the output, PNG by default.
options – Encoding options, as in to_bytes.

Returns:

The base64 encoded image.

to_bytes(mime_type=None, options=None)¶

Encode the image.

The options dict can contain any PIL save option (see https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html).

An additional option mode is the image mode (see https://pillow.readthedocs.io/en/stable/handbook/concepts.html#concept-modes). If provided, the image is converted to that mode before saving, with an adaptive palette.

An additional option background sets the color to replace the alpha channel with when an RGBA image is saved as JPEG (default is white).

Parameters:

mime_type – MIME type of the output, PNG by default.
options – Encoding options.

Returns:

The encoded image.

to_data_url(mime_type=None, options=None)¶

Encode the image as a base64 data URL.

Parameters:

mime_type – MIME type of the output, PNG by default.
options – Encoding options, as in to_bytes.

Returns:

A data: URL.

to_path(path, mime_type=None, options=None)¶

Encode the image and save it to a file.

Parameters:

path – File path.
mime_type – MIME type of the output, PNG by default.
options – Encoding options, as in to_bytes.

Returns:

The file path.

gws.lib.image.MAX_PIXELS = 1000000000¶: Maximum number of pixels of an image created from a size or raw data.

gws.lib.image.pixel(mime_type, color)¶

Return an encoded 1x1 image of a color.

Results are cached.

Parameters:

mime_type – MIME type, PNG by default.
color – Pixel color, or None for a transparent pixel.

Returns:

The encoded image.

Raises:

Error – If the MIME type is not an image type.

gws.lib.image.qr_code(data: str, level='M', scale=4, border=True, color='black', background='white') → Image¶

Create an image with a QR code.

See https://github.com/lincolnloop/python-qrcode/blob/main/README.rst#advanced-usage.

Parameters:

data – Data to encode.
level – Error correction level, one of L, M, Q, H.
scale – Box size in pixels.
border – If True, include a quiet zone of 4 boxes.
color – Foreground color.
background – Background color.

Returns:

An image object.

Raises:

Error – If the image cannot be created.

gws.lib.image.thumbnail(r: bytes, size: gws.Size, max_pixels=0, mime_type=None, options=None) → bytes¶

Create a thumbnail from an encoded image.

The image is scaled to fit into size, keeping the aspect ratio. Small images are not scaled up.

Parameters:

r – Encoded image.
size – Maximum thumbnail size (width, height).
max_pixels – Maximum number of source pixels, 0 for no limit.
mime_type – MIME type of the thumbnail, PNG by default.
options – Encoding options, as in Image.to_bytes.

Returns:

The encoded thumbnail.

Raises:

Error – If the image is too big or cannot be processed.

`gws.lib.image`¶

Package Contents¶

Table of Contents

Previous topic

Next topic

gws.lib.image¶

Package Contents¶

`gws.lib.image`¶