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¶
- 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_PIXELSpixels.
- 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_PIXELSpixels.
- 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.ImageImage 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:
0if 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
optionsdict can contain any PIL save option (see https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html).An additional option
modeis 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
backgroundsets 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.