Welcome

This documentation will guide you through the methods available in the Inky pHAT python library.

Note

Inky pHAT is based heavily upon the PIL/Pillow Python Imaging Library. It uses PIL drawing methods, fonts and images in indexed-palette mode with the colours 0, 1 and 2 corresponding to White, Black and Red.

Some documentation is missing for PIL methods below. For general documentation about PIL/Pillow please visit: https://pillow.readthedocs.io

At A Glance

inkyphat.create_mask(source, mask=(0, 1, 2))[source]
inkyphat.get_image()[source]
inkyphat.set_border(col)[source]
inkyphat.set_image(image, colswap=None)[source]
inkyphat.set_rotation(r)[source]
inkyphat.show()[source]
inkyphat.paste(im, box=None, mask=None)

Pastes another image into this image. The box argument is either a 2-tuple giving the upper left corner, a 4-tuple defining the left, upper, right, and lower pixel coordinate, or None (same as (0, 0)). If a 4-tuple is given, the size of the pasted image must match the size of the region.

If the modes don’t match, the pasted image is converted to the mode of this image (see the convert() method for details).

Instead of an image, the source can be a integer or tuple containing pixel values. The method then fills the region with the given color. When creating RGB images, you can also use color strings as supported by the ImageColor module.

If a mask is given, this method updates only the regions indicated by the mask. You can use either “1”, “L” or “RGBA” images (in the latter case, the alpha band is used as mask). Where the mask is 255, the given image is copied as is. Where the mask is 0, the current value is preserved. Intermediate values can be used for transparency effects.

Note that if you paste an “RGBA” image, the alpha band is ignored. You can work around this by using the same image as both source image and mask.

Parameters:
  • im – Source image or pixel value (integer or tuple).
  • box –

    An optional 4-tuple giving the region to paste into. If a 2-tuple is used instead, it’s treated as the upper left corner. If omitted or None, the source is pasted into the upper left corner.

    If an image is given as the second argument and there is no third, the box defaults to (0, 0), and the second argument is interpreted as a mask image.

  • mask – An optional mask image.
inkyphat.getpixel(xy)

Returns the pixel value at a given position.

Parameters:xy – The coordinate, given as (x, y).
Returns:The pixel value. If the image is a multi-layer image, this method returns a tuple.
inkyphat.putpixel(xy, value)

Modifies the pixel at the given position. The color is given as a single numerical value for single-band images, and a tuple for multi-band images.

Note that this method is relatively slow. For more extensive changes, use paste() or the ImageDraw module instead.

See:

  • paste()
  • putdata()
  • ImageDraw
Parameters:
  • xy – The pixel coordinate, given as (x, y).
  • value – The pixel value.
inkyphat.point(xy, fill=None)
inkyphat.arc(xy, start, end, fill=None)
inkyphat.pieslice(xy, start, end, fill=None, outline=None)
inkyphat.ellipse(xy, fill=None, outline=None)
inkyphat.line(xy, fill=None, width=0)
inkyphat.rectangle(xy, fill=None, outline=None)
inkyphat.polygon(xy, fill=None, outline=None)
inkyphat.text(xy, text, fill=None, font=None, anchor=None)

Paste An Image

inkyphat.paste(im, box=None, mask=None)

Pastes another image into this image. The box argument is either a 2-tuple giving the upper left corner, a 4-tuple defining the left, upper, right, and lower pixel coordinate, or None (same as (0, 0)). If a 4-tuple is given, the size of the pasted image must match the size of the region.

If the modes don’t match, the pasted image is converted to the mode of this image (see the convert() method for details).

Instead of an image, the source can be a integer or tuple containing pixel values. The method then fills the region with the given color. When creating RGB images, you can also use color strings as supported by the ImageColor module.

If a mask is given, this method updates only the regions indicated by the mask. You can use either “1”, “L” or “RGBA” images (in the latter case, the alpha band is used as mask). Where the mask is 255, the given image is copied as is. Where the mask is 0, the current value is preserved. Intermediate values can be used for transparency effects.

Note that if you paste an “RGBA” image, the alpha band is ignored. You can work around this by using the same image as both source image and mask.

Parameters:
  • im – Source image or pixel value (integer or tuple).
  • box –

    An optional 4-tuple giving the region to paste into. If a 2-tuple is used instead, it’s treated as the upper left corner. If omitted or None, the source is pasted into the upper left corner.

    If an image is given as the second argument and there is no third, the box defaults to (0, 0), and the second argument is interpreted as a mask image.

  • mask – An optional mask image.

Get A Pixel

inkyphat.getpixel(xy)

Returns the pixel value at a given position.

Parameters:xy – The coordinate, given as (x, y).
Returns:The pixel value. If the image is a multi-layer image, this method returns a tuple.

Put A Pixel

From PIL.Image

inkyphat.putpixel(xy, value)

Modifies the pixel at the given position. The color is given as a single numerical value for single-band images, and a tuple for multi-band images.

Note that this method is relatively slow. For more extensive changes, use paste() or the ImageDraw module instead.

See:

  • paste()
  • putdata()
  • ImageDraw
Parameters:
  • xy – The pixel coordinate, given as (x, y).
  • value – The pixel value.

From PIL.ImageDraw

inkyphat.point(xy, fill=None)

Draw An Arc

From PIL.ImageDraw

inkyphat.arc(xy, start, end, fill=None)
inkyphat.pieslice(xy, start, end, fill=None, outline=None)

Draw An Ellipse

From PIL.ImageDraw

inkyphat.ellipse(xy, fill=None, outline=None)

Draw A Line

From PIL.ImageDraw

inkyphat.line(xy, fill=None, width=0)

Draw A Rectangle

From PIL.ImageDraw

inkyphat.rectangle(xy, fill=None, outline=None)

Draw A Polygon

From PIL.ImageDraw

inkyphat.polygon(xy, fill=None, outline=None)

Draw Some Text

From PIL.ImageDraw

inkyphat.text(xy, text, fill=None, font=None, anchor=None)

Note: You can use inkyphat.ImageFont(inkyphat.fonts.FONTNAME, FONTSIZE) to supply a font.

Fonts

Inky pHAT ships with some built-in OFL fonts for your convenience. You can list them by importing inkyphat and typing dir(inkyphat.fonts)

  • inkyphat.fonts.AmaticSCBold
  • inkyphat.fonts.AmaticSC
  • inkyphat.fonts.FredokaOne
  • inkyphat.fonts.PressStart2P

Constants

  • inkyphat.WHITE = 0
  • inkyphat.BLACK = 1
  • inkyphat.RED = 2