The ImageTools module

The ImageDraw module provides simple 2D effects for Image objects, this includes some image filters, custom cropping/filling and more.

Example: Round off corners of an image

from PIL import Image
from PILTools import ImageTools

with Image.open("test.png") as im:
    draw = ImageTools.Draw(im)
    draw.rounded_edges(radius=50)

    # write to stdout
    im.save(sys.stdout, "PNG")

Concepts

Colours / Colour names

Just like with PIL you can define colours using both integers and tuples. For more info on how PIL’s colour system works refer to the PIL documentation.

Draw class

class Draw(im)

Creates a draw object that can be used to edit the defined image.

Note: the image will be modified in place.

Parameters

im (PIL.Image.Image) – The image to draw in.

Methods

Draw.black_and_white(threshold=150)

Converts replaces the colour in the image with just black and white without changing the base image mode.

New in version 1.0: Supports alpha transparency

Parameters

threshold (int) – The threshold for the selection between black and white between 0-255, the higher the threshold the more black the image will be. Defaults to 150.

Raises

InvalidThreshold() if the threshold provided was invalid (not in 0-255).

Draw.blue_screen(r_threshold: int = 80, g_threshold: int = 80, b_threshold: int = 100)

Attempts to remove blue from an image based on the thresholds set.

Parameters

  • r_threshold (int) – The red threshold to use between 0-255, anything above this threshold will be kept. Defaults to 80.

  • g_threshold (int) – The green threshold to use between 0-255, anything above this threshold will be kept. Defaults to 80.

  • b_threshold (int) – The blue threshold to use between 0-255, anything below this threshold will be kept. Defaults to 100.

Raises

InvalidThreshold() if one of the thresholds provided were invalid (not in 0-255).

Draw.create_mask(image=None)

Creates a mask of the current image or a defined image.

New in 1.1.0

Parameters

image (PIL.Image.Image) – The image you wish to create a mask of, will use the current image if not defined.

Returns

A generated mask in L mode.

Return type

PIL.Image.Image

Draw.grayscale()

Converts replaces the colour in the image with shades of gray without changing the base image mode.

New in version 1.0: Supports alpha transparency

Draw.greyscale()

Alias for Draw.grayscale()

New in version 1.0: Supports alpha transparency

Draw.green_screen(r_threshold: int = 80, g_threshold: int = 100, b_threshold: int = 80)

Attempts to remove green from an image based on the thresholds set.

Parameters

  • r_threshold (int) – The red threshold to use between 0-255, anything above this threshold will be kept. Defaults to 80.

  • g_threshold (int) – The green threshold to use between 0-255, anything below this threshold will be kept. Defaults to 100.

  • b_threshold (int) – The blue threshold to use between 0-255, anything above this threshold will be kept. Defaults to 80.

Raises

InvalidThreshold() if one of the thresholds provided were invalid (not in 0-255).

Draw.invert()

Inverts the colours on the base image (supports transparency).

Draw.rainbow_text(xy, text, fill=None, randomise=False, font=None, align='left', alignY='top', stroke_width=0, stroke_fill=None, embedded_color=None)

Draws a string of text at the defined position but uses different colours for each letter.

Note: This method is slightly different to vanilla PIL’s PIL.ImageDraw.ImageDraw.text() function as anchors are not used.

Parameters

  • xy (tuple) – The anchor coordinates of the text.

  • text (str) – String to be drawn. If it contains any newline characters, the text is passed on to Draw.rainbow_multiline_text().

  • fill (list) – List of colours to use for the rainbow. Will uses the default rainbow colours (RAINBOW_DEFAULT) if none parsed.

  • randomise (bool) – Make the chosen colours randomised instead of rendering in order. Makes use of random.choice() for this.

  • font (PIL.ImageFont.ImageFont) – An PIL.ImageFont.ImageFont instance.

  • align (str) – Determines the relative alignment of the text based off of the x co-ord.

  • alignY (str) – Determines the relative alignment of the text based off of the y co-ord.

  • stroke_width (int) – The width of the text stroke.

  • stroke_fill (tuple) – Color to use for the text stroke. If not given, will default to the fill parameter colours.

  • embedded_color (bool) – Whether to use font embedded color glyphs (COLR or CBDT).

Draw.rainbow_multiline_text(xy, text, fill=None, randomise=False, font=None, spacing=4, align='left', alignY='top', text_align='left', stroke_width=0, stroke_fill=None, embedded_color=None)

Draws a string of text at the defined position but uses different colours for each letter.

Note: This method is slightly different to vanilla PIL’s PIL.ImageDraw.ImageDraw.multiline_text() function as anchors are not used.

Parameters

  • xy (tuple) – The anchor coordinates of the text.

  • text (str) – String to be drawn.

  • fill (list) – List of colours to use for the rainbow. Will uses the default rainbow colours (RAINBOW_DEFAULT) if none parsed.

  • randomise (bool) –

    Make the chosen colours randomised instead of rendering in order. Makes use of random.choice() for this.

  • font (PIL.ImageFont.ImageFont) –

    An PIL.ImageFont.ImageFont instance.

  • spacing (int) – The number of pixels between lines.

  • align (str) – Determines the relative alignment of the text based off of the x co-ord.

  • alignY (str) –

    • Determines the relative alignment of the text based off of the y co-ord.

  • text_align (str) –

    Sets the text alignment similar to the PIL.ImageDraw.ImageDraw.multiline_text()’s align argument.

  • stroke_width (int) – The width of the text stroke.

  • stroke_fill (tuple) – Color to use for the text stroke. If not given, will default to the fill parameter colours.

  • embedded_color (bool) – Whether to use font embedded color glyphs (COLR or CBDT).

Draw.red_screen(r_threshold: int = 100, g_threshold: int = 80, b_threshold: int = 80)

Attempts to remove red from an image based on the thresholds set.

Parameters

  • r_threshold (int) – The red threshold to use between 0-255, anything below this threshold will be kept. Defaults to 100.

  • g_threshold (int) – The green threshold to use between 0-255, anything above this threshold will be kept. Defaults to 80.

  • b_threshold (int) – The blue threshold to use between 0-255, anything above this threshold will be kept. Defaults to 80.

Raises

InvalidThreshold() if one of the thresholds provided were invalid (not in 0-255).

rounded_edges(radius, fill=None, inverted=False, tl=True, tr=True, bl=True, br=True)

Adds a rounded edge (corner) effect to the image.

Parameters

  • radius (int) – Radius of the edges in pixels.

  • fill (tuple) – Colour to fill corners with, makes transparent if None. Uses black if image not in transparent friendly mode like RGBA.

  • inverted (bool) – Determines if the fill colour covers the cropped corners or the rest of the image.

  • tl (bool) – Determines whether the top left corner gets rounded.

  • tr (bool) – Determines whether the top right corner gets rounded.

  • bl (bool) – Determines whether the bottom left corner gets rounded.

  • br (bool) – Determines whether the bottom right corner gets rounded.

Constants

RAINBOW_DEFAULT

A simple list of tuples that define the default colours used in the rainbow text.

List of colours:

  • (255, 0, 0) - Red

  • (255, 106, 0) - Orange

  • (255, 216, 0) - Yellow

  • (0, 170, 0) - Green

  • (0, 148, 255) - Blue

  • (0, 65, 106) - Indigo

  • (120, 0, 175) - Violet

Type

list