luma.core.virtual

luma.core.virtual.calc_bounds(xy, entity)

For an entity with width and height attributes, determine the bounding box if were positioned at (x, y).

class luma.core.virtual.character(device, font=None, undefined='_')

Bases: object

Abstraction that wraps a device, this class provides a text property which can be used to set and get a text value allowing the device to be treated as a character style display such as the HD44780 LCD

If the device is actually a character style device, be careful to provide a font that adheres to the pixel dimensions of the display.

Parameters:

• device – A device instance.

• font (PIL.ImageFont object) – The font to be used to paint the characters within the text property. If the device contains a font (e.g. hd44780, ws0010) it will be used as the default if no font is provided.

• undefined (char) – The default character to substitute when an unrenderable character is supplied to the text property.

New in version 1.15.0.

property text

Returns the current state of the text buffer. This may not reflect accurately what is displayed on the device if the font does not have a symbol for a requested text value.

class luma.core.virtual.history(device)

Bases: capabilities

Wraps a device (or emulator) to provide a facility to be able to make a savepoint (a point at which the screen display can be “rolled-back” to).

This is mostly useful for displaying transient error/dialog messages which could be subsequently dismissed, reverting back to the previous display.

display(image)

Should be overridden in sub-classed implementations.

Parameters:

image (PIL.Image.Image) – An image to display.

Raises:

NotImplementedError –

restore(drop=0)

Restores the last savepoint. If drop is supplied and greater than zero, then that many savepoints are dropped, and the next savepoint is restored.

Parameters:

drop (int) –

savepoint()

Copies the last displayed image.

class luma.core.virtual.hotspot(width, height, draw_fn=None)

Bases: capabilities

A hotspot (a place of more than usual interest, activity, or popularity) is a live display which may be added to a virtual viewport - if the hotspot and the viewport are overlapping, then the update() method will be automatically invoked when the viewport is being refreshed or its position moved (such that an overlap occurs).

You would either:

• create a hotspot instance, suppling a render function (taking an PIL.ImageDraw object, width & height dimensions. The render function should draw within a bounding box of (0, 0, width, height), and render a full frame.

• sub-class hotspot and override the should_redraw() and update() methods. This might be more useful for slow-changing values where it is not necessary to update every refresh cycle, or your implementation is stateful.

paste_into(image, xy)

should_redraw()

Override this method to return true or false on some condition (possibly on last updated member variable) so that for slow changing hotspots they are not updated too frequently.

update(draw)

luma.core.virtual.range_overlap(a_min, a_max, b_min, b_max)

Neither range is completely greater than the other.

class luma.core.virtual.sevensegment(device, undefined='_', segment_mapper=None)

Bases: object

Abstraction that wraps a device, this class provides a text property which can be used to set and get a text value, which when combined with a segment_mapper sets the correct bit representation for seven-segment displays and propagates that onto the underlying device.

Parameters:

• device – A device instance.

• segment_mapper – An optional function that maps strings into the correct representation for the 7-segment physical layout. If not provided, the default mapper from compatible devices is used instead.

• undefined (char) – The default character to substitute when an unrenderable character is supplied to the text property.

property text

Returns the current state of the text buffer. This may not reflect accurately what is displayed on the seven-segment device, as certain alpha-numerics and most punctuation cannot be rendered on the limited display.

class luma.core.virtual.snapshot(width, height, draw_fn=None, interval=1.0)

Bases: hotspot

A snapshot is a type of hotspot, but only updates once in a given interval, usually much less frequently than the viewport requests refresh updates.

paste_into(image, xy)

should_redraw()

Only requests a redraw after interval seconds have elapsed.

class luma.core.virtual.terminal(device, font=None, color='white', bgcolor='black', tabstop=4, line_height=None, animate=True, word_wrap=False)

Bases: object

Provides a terminal-like interface to a device (or a device-like object that has mixin.capabilities characteristics).

background_color(value)

Sets the background color.

Parameters:

value (str or tuple) – The new color value, either string name or RGB tuple.

backspace()

Moves the cursor one place to the left, erasing the character at the current position. Cannot move beyond column zero, nor onto the previous line.

carriage_return()

Returns the cursor position to the left-hand side without advancing downwards.

clear()

Clears the display and resets the cursor position to (0, 0).

erase()

Erase the contents of the cursor’s current position without moving the cursor’s position.

flush()

Cause the current backing store to be rendered on the nominated device.

foreground_color(value)

Sets the foreground color.

Parameters:

value (str or tuple) – The new color value, either string name or RGB tuple.

newline()

Advances the cursor position ot the left hand side, and to the next line. If the cursor is on the lowest line, the displayed contents are scrolled, causing the top line to be lost.

println(text='')

Prints the supplied text to the device, scrolling where necessary. The text is always followed by a newline.

Parameters:

text (str) – The text to print.

putch(char)

Prints the specific character, which must be a valid printable ASCII value in the range 32..127 only, or one of carriage return (r), newline (n), backspace (b) or tab (t).

Parameters:

char – The character to print.

puts(text)

Prints the supplied text, handling special character codes for carriage return (r), newline (n), backspace (b) and tab (t). ANSI color codes are also supported.

If the animate flag was set to True (default), then each character is flushed to the device, giving the effect of 1970’s teletype device.

Parameters:

text (str) – The text to print.

reset()

Resets the foreground and background color value back to the original when initialised.

reverse_colors()

Flips the foreground and background colors.

tab()

Advances the cursor position to the next (soft) tabstop.

class luma.core.virtual.viewport(device, width, height, mode=None, dither=False)

Bases: capabilities

The viewport offers a positionable window into a larger resolution pseudo-display, that also supports the concept of hotspots (which act like live displays).

Parameters:

• device – The device to project the enlarged pseudo-display viewport onto.

• width (int) – The number of horizontal pixels.

• height (int) – The number of vertical pixels.

• mode (str) – The supported color model, one of "1", "RGB" or "RGBA" only.

• dither (bool) – By default, any color (other than black) will be generally treated as white when displayed on monochrome devices. However, this behaviour can be changed by adding dither=True and the image will be converted from RGB space into a 1-bit monochrome image where dithering is employed to differentiate colors at the expense of resolution.

add_hotspot(hotspot, xy)

Add the hotspot at (x, y). The hotspot must fit inside the bounds of the virtual device. If it does not then an AssertError is raised.

display(image)

Should be overridden in sub-classed implementations.

Parameters:

image (PIL.Image.Image) – An image to display.

Raises:

NotImplementedError –

is_overlapping_viewport(hotspot, xy)

Checks to see if the hotspot at position (x, y) is (at least partially) visible according to the position of the viewport.

refresh()

remove_hotspot(hotspot, xy)

Remove the hotspot at (x, y): Any previously rendered image where the hotspot was placed is erased from the backing image, and will be “undrawn” the next time the virtual device is refreshed. If the specified hotspot is not found for (x, y), a ValueError is raised.

set_position(xy)