gws.lib.image.core

Image object and factories.

Provides Image, the implementation of gws.Image on top of a PIL image, and the from_* functions that create images from a size, encoded bytes, raw pixel data, a file, a data URL or a numpy array.

Image sizes are limited to MAX_PIXELS.

Source code: gws.lib.image.core

Module Contents

exception gws.lib.image.core.Error

Bases: gws.Error

Image error.

gws.lib.image.core.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.core.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.core.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.core.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.core.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.core.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.core.from_svg(xmlstr: str, size: gws.Size, mime: gws.MimeType = '') → Image

Create an image from an SVG document. Not implemented.

Parameters:
  • xmlstr – SVG source.

  • size – Image size (width, height).

  • mime – MIME type.

Returns:

An image object.

Raises:

NotImplementedError – Always.

class gws.lib.image.core.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='', options=None)

Encode the image as a base64 string.

Parameters:
  • mime – MIME type of the output, PNG by default.

  • options – Encoding options, as in to_bytes.

Returns:

The base64 encoded image.

to_bytes(mime='', 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 – MIME type of the output, PNG by default.

  • options – Encoding options.

Returns:

The encoded image.

to_data_url(mime='', options=None)

Encode the image as a base64 data URL.

Parameters:
  • mime – MIME type of the output, PNG by default.

  • options – Encoding options, as in to_bytes.

Returns:

A data: URL.

to_path(path, mime='', options=None)

Encode the image and save it to a file.

Parameters:
  • path – File path.

  • mime – MIME type of the output, PNG by default.

  • options – Encoding options, as in to_bytes.

Returns:

The file path.

gws.lib.image.core.MAX_PIXELS = 1000000000

Maximum number of pixels of an image created from a size or raw data.