asciimatics.renderers package

Submodules

asciimatics.renderers.base module

This module provides common code for all Renderers.

asciimatics.renderers.base.ATTRIBUTES = {'1': 1, '2': 2, '3': 3, '4': 4}

Attribute conversion table for the ${c,a} form of attributes for paint.

class asciimatics.renderers.base.DynamicRenderer(height, width, clear=True)

Bases: Renderer

A DynamicRenderer is a Renderer that creates each image as requested. It has a defined maximum size on construction.

Parameters:

  • height – The max height of the rendered image.

  • width – The max width of the rendered image.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.base.Renderer

Bases: object

A Renderer is simply a class that will return one or more text renderings for display by an Effect.

In the simple case, this can be a single string that contains some unchanging content - e.g. a simple text message.

It can also represent a sequence of strings that can be played one after the other to make a simple animation sequence - e.g. a rotating globe.

abstract property images
Returns:

An iterator of all the images in the Renderer.

abstract property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

abstract property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

abstract property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.base.StaticRenderer(images=None, animation=None)

Bases: Renderer

A StaticRenderer is a Renderer that can create all possible images in advance. After construction the images will not change, but can by cycled for animation purposes.

This class will also convert text like ${c,a,b} into colour c, attribute a and background b for any subsequent text in the line, thus allowing multi-coloured text. The attribute and background are optional.

Parameters:

  • images – An optional set of ascii images to be rendered.

  • animation – A function to pick the image (from images) to be rendered for any given frame.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

asciimatics.renderers.box module

This module implements an ASCII box renderer.

class asciimatics.renderers.box.Box(width, height, uni=False, style=1)

Bases: StaticRenderer

Renders a simple box using ASCII characters. This does not render in extended box drawing characters as that requires non-ASCII characters in Windows and direct access to curses in Linux.

Parameters:

  • width – width of box

  • height – height of box

  • uni – True to use UNICODE character set, defaults to False

  • style – desired line style, based on line style definitions in constants: ASCII_LINE, SINGLE_LINE, DOUBLE_LINE. uni parameter takes precedence and the style will be ignored if uni==False

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

asciimatics.renderers.charts module

This module implements bar chart renderers.

class asciimatics.renderers.charts.BarChart(height, width, functions, char='#', colour=2, bg=0, gradient=None, scale=None, axes=2, intervals=None, labels=False, border=True, keys=None, gap=None)

Bases: _BarChartBase

Renderer to create a horizontal bar chart using the specified functions as inputs for each entry. Can be used to chart distributions or for more graphical effect - e.g. to imitate a sound equalizer or a progress indicator.

Parameters:

  • height – The max height of the rendered image.

  • width – The max width of the rendered image.

  • functions – List of functions to chart.

  • char – Character to use for the bar. Defaults to ‘#’

  • colour – Colour(s) to use for the bars. This can be a single value or list of values (to cycle around for each bar). Defaults to green.

  • bg – Background colour to use for the bars. This can be a single value or list of values (to cycle around for each bar). Defaults to black.

  • gradient – Colour gradient to use for the bars. This is a list of tuple pairs specifying a threshold and a colour, or triplets to include a background colour too. Defaults to no gradients.

  • scale – Maximum value for the bars. This is used to scale the function values to the maximum space available. Any value over this will be truncated when drawn. Defaults to the number of available characters in the chart.

  • axes – Which axes to draw.

  • intervals – Units for interval markers on the main axis. Defaults to none.

  • labels – Whether to draw size indication labels on the x-axis.

  • border – Whether to draw a border around the chart.

  • keys – Optional keys to name each bar on the y-axis.

  • gap – distance between bars. A value of None will auto-calculate (default).

If the scale parameter is not specified, the maximum length of the bar is based on the available space. A chart with no borders, no axes, no keys or labels will have a bar length based solely on the width of the graph.

  • Borders use 4 characters height and 6 characters width

  • Keys use the width of the widest key plus 1

  • Labels use a height of 1

  • An X_AXIS uses a height of 1

  • A Y_AXIS uses a width of 1

BOTH = 3

Constant to indicate both axes should be rendered.

NONE = 0

Constant to indicate no axes should be rendered.

X_AXIS = 1

Constant to indicate just the x axis should be rendered.

Y_AXIS = 2

Constant to indicate just the y axis should be rendered.

property axes_style

The current drawing style of the axes. Possible values are defined in constants:

  • ASCII_LINE – ASCII safe characters

  • SINGLE_LINE – UNICODE based single line

Note that your canvas must support UNICODE style characters to use them

property border_style

The current drawing style of the border. Possible values are defined in constants:

  • ASCII_LINE – ASCII safe characters

  • SINGLE_LINE – UNICODE based single line

  • DOUBLE_LINE – UNICODE based double line

Note that your canvas must support UNICODE style characters to use them

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.charts.VBarChart(height, width, functions, char='#', colour=2, bg=0, gradient=None, scale=None, axes=1, intervals=None, labels=False, border=True, keys=None, gap=None)

Bases: _BarChartBase

Renderer to create a vertical bar chart using the specified functions as inputs for each entry. Can be used to chart distributions or for more graphical effect - e.g. to imitate a sound equalizer or a progress indicator.

Parameters:

  • height – The max height of the rendered image.

  • width – The max width of the rendered image.

  • functions – List of functions to chart.

  • char – Character to use for the bar. Defaults to ‘#’

  • colour – Colour(s) to use for the bars. This can be a single value or list of values (to cycle around for each bar). Defaults to green.

  • bg – Background colour to use for the bars. This can be a single value or list of values (to cycle around for each bar). Defaults to black.

  • gradient – Colour gradient to use for the bars. This is a list of tuple pairs specifying a threshold and a colour, or triplets to include a background colour too. Defaults to no gradients.

  • scale – Maximum value for the bars. This is used to scale the function values to the maximum space available. Any value over this will be truncated when drawn. Defaults to the number of available characters in the chart.

  • axes – Which axes to draw.

  • intervals – Units for interval markers on the main axis. Defaults to none.

  • labels – Whether to draw size indication labels on the y-axis.

  • border – Whether to draw a border around the chart.

  • keys – Optional keys to name each bar on the x-axis.

  • gap – distance between bars. A value of None will auto-calculate (default). Minimum value when auto-calculated is 1, for no gaps specify 0.

If the scale parameter is not specified, the maximum length of the bar is based on the available space. A chart with no borders, no axes, no keys or labels will have a bar height based solely on the width of the graph.

  • Borders use 4 characters height and 6 characters width

  • Keys use a height of 1

  • Labels vertical bar chart use the width of the widest label plus 1 (label values depend on the scale of the chart)

  • An X_AXIS uses a height of 1

  • A Y_AXIS uses a width of 1

BOTH = 3

Constant to indicate both axes should be rendered.

NONE = 0

Constant to indicate no axes should be rendered.

X_AXIS = 1

Constant to indicate just the x axis should be rendered.

Y_AXIS = 2

Constant to indicate just the y axis should be rendered.

property axes_style

The current drawing style of the axes. Possible values are defined in constants:

  • ASCII_LINE – ASCII safe characters

  • SINGLE_LINE – UNICODE based single line

Note that your canvas must support UNICODE style characters to use them

property border_style

The current drawing style of the border. Possible values are defined in constants:

  • ASCII_LINE – ASCII safe characters

  • SINGLE_LINE – UNICODE based single line

  • DOUBLE_LINE – UNICODE based double line

Note that your canvas must support UNICODE style characters to use them

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

asciimatics.renderers.figlettext module

This module implements Figlet text renderer.

class asciimatics.renderers.figlettext.FigletText(text, font='standard', width=200)

Bases: StaticRenderer

This class renders the supplied text using the specified Figlet font. See http://www.figlet.org/ for details of available fonts.

Parameters:

  • text – The text string to convert with Figlet.

  • font – The Figlet font to use (optional).

  • width – The maximum width for this text in characters.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

asciimatics.renderers.fire module

This module implements a fire effect renderer.

class asciimatics.renderers.fire.Fire(height, width, emitter, intensity, spot, colours, bg=False)

Bases: DynamicRenderer

Renderer to create a fire effect based on a specified emitter that defines the heat source.

The implementation here uses the same techniques described in http://freespace.virgin.net/hugo.elias/models/m_fire.htm, although a slightly different implementation.

Parameters:

  • height – Height of the box to contain the flames.

  • width – Width of the box to contain the flames.

  • emitter – Heat source for the flames. Any non-whitespace character is treated as part of the heat source.

  • intensity – The strength of the flames. The bigger the number, the hotter the fire. 0 <= intensity <= 1.0.

  • spot – Heat of each spot source. Must be an integer > 0.

  • colours – Number of colours the screen supports.

  • bg – (Optional) Whether to render background colours only.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

asciimatics.renderers.fire.random() → x in the interval [0, 1).

asciimatics.renderers.images module

This module implements renderers that produce content based on image files.

class asciimatics.renderers.images.ColourImageFile(screen, filename, height=30, bg=0, fill_background=False, uni=False, dither=False)

Bases: StaticRenderer

Renderer to convert an image file (as supported by the Python Imaging Library) into an block image of available colours.

Warning

This is only compatible with 256-colour terminals. Results in other terminals with reduced colour capabilities are severely restricted. Since Windows only has 8 base colours, it is recommended that you avoid this renderer on that platform.

Parameters:

  • screen – The screen to use when displaying the image.

  • filename – The name of the file to render.

  • height – The height of the text rendered image.

  • bg – The default background colour for this image.

  • fill_background – Whether to set background colours too.

  • uni – Whether to use unicode box characters or not.

  • dither – Whether to dither the rendered image or not.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.images.ImageFile(filename, height=30, colours=8)

Bases: StaticRenderer

Renderer to convert an image file (as supported by the Python Imaging Library) into an ascii grey scale text image.

Parameters:

  • filename – The name of the file to render.

  • height – The height of the text rendered image.

  • colours – The number of colours the terminal supports.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

asciimatics.renderers.kaleidoscope module

This module implements a kaeldioscope effect renderer.

class asciimatics.renderers.kaleidoscope.Kaleidoscope(height, width, cell, symmetry)

Bases: DynamicRenderer

Renderer to create a 2-mirror kaleidoscope effect.

This is a chained renderer (i.e. it acts upon the output of another Renderer which is passed to it on construction). The other Renderer is used as the cell that is rotated over time to create the animation.

You can specify the desired rotational symmetry of the kaleidoscope (which determines the angle between the mirrors). If you chose values of less than 2, you are effectively removing one or both mirrors, thus either getting the original cell or a simple mirrored image of the cell.

Since this renderer rotates the background cell, it needs operate on square pixels, which means each character in the cell is drawn as 2 next to each other on the screen. In other words the cell needs to be half the width of the desired output (when measured in text characters).

Parameters:

  • height – Height of the box to contain the kaleidoscope.

  • width – Width of the box to contain the kaleidoscope.

  • cell – A Renderer to use as the backing cell for the kaleidoscope.

  • symmetry – The desired rotational symmetry. Must be a non-negative integer.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

asciimatics.renderers.plasma module

This module implements a plasma effect renderer.

class asciimatics.renderers.plasma.Plasma(height, width, colours)

Bases: DynamicRenderer

Renderer to create a “plasma” effect using sinusoidal functions.

The implementation here uses the same techniques described in http://lodev.org/cgtutor/plasma.html

Parameters:

  • height – Height of the box to contain the plasma.

  • width – Width of the box to contain the plasma.

  • colours – Number of colours the screen supports.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

asciimatics.renderers.players module

This module implements renderers that play content to the screen.

class asciimatics.renderers.players.AbstractScreenPlayer(height, width)

Bases: DynamicRenderer

Abstract renderer to play terminal text with support for ANSI control codes.

Parameters:

  • height – required height of the renderer.

  • width – required width of the renderer.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.players.AnsiArtPlayer(filename, height=25, width=80, encoding='cp437', strip=False, rate=2)

Bases: AbstractScreenPlayer

Renderer to play ANSI art text files.

In order to tidy up files, this must be used as a context manager (i.e. using with).

Parameters:

  • filename – the file containingi the ANSI art.

  • height – required height of the renderer.

  • width – required width of the renderer.

  • encoding – text encoding ofnthe file.

  • strip – whether to strip CRLF from the file content.

  • rate – number of lines to render on each update.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.players.AsciinemaPlayer(filename, height=None, width=None, max_delay=None)

Bases: AbstractScreenPlayer

Renderer to play terminal recordings created by asciinema.

This only supports the version 2 file format. Use the max_delay setting to speed up human interactions (i.e. to reduce delays from typing).

In order to tidy up files, this must be used as a context manager (i.e. using with).

Parameters:

  • filename – the file containingi the ANSI art.

  • height – required height of the renderer.

  • width – required width of the renderer.

  • max_delay – maximum time interval (in secs) to wait between frame updates.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

asciimatics.renderers.rainbow module

This module implements a rainbow effect renderer.

class asciimatics.renderers.rainbow.Rainbow(screen, renderer)

Bases: StaticRenderer

Chained renderer to add rainbow colours to output of another renderer. The embedded rendered must not use multi-colour mode (i.e. ${c,a} mark-ups) as these will be converted to explicit text by this renderer.

Parameters:

  • screen – The screen object for this renderer.

  • renderer – The renderer to wrap.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

asciimatics.renderers.rotatedduplicate module

This module implements a renderer that renders another renderer but rotated.

class asciimatics.renderers.rotatedduplicate.RotatedDuplicate(width, height, renderer)

Bases: StaticRenderer

Chained renderer to add a rotated version of the original renderer underneath and centre the whole thing within within the specified dimensions.

Parameters:

  • width – The maximum width of the rendered text.

  • height – The maximum height of the rendered text.

  • renderer – The renderer to wrap.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

asciimatics.renderers.scales module

This module implements renderers that show measuring scales to the screen.

class asciimatics.renderers.scales.Scale(width)

Bases: StaticRenderer

This renders a linear scale, useful for debugging positions of your creations. Every 5 spaces gets a tick mark, every 10 a number.

Parameters:

width – The width of the scale

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.scales.VScale(height)

Bases: StaticRenderer

This renders a vertical linear scale, useful for debugging positions of your creations. Writes lowest significant digit of a count running vertically.

Parameters:

width – The width of the scale

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

asciimatics.renderers.speechbubble module

This module implements a speech-bubble effect renderer.

class asciimatics.renderers.speechbubble.SpeechBubble(text, tail=None, uni=False)

Bases: StaticRenderer

Renders supplied text into a speech bubble.

Parameters:

  • text – The text to be put into a speech bubble.

  • tail – Where to put the bubble callout tail, specifying “L” or “R” for left or right tails. Can be None for no tail.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

Module contents

This module provides Renderers to create complex animation effects. For more details see http://asciimatics.readthedocs.io/en/latest/rendering.html

class asciimatics.renderers.AbstractScreenPlayer(height, width)

Bases: DynamicRenderer

Abstract renderer to play terminal text with support for ANSI control codes.

Parameters:

  • height – required height of the renderer.

  • width – required width of the renderer.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.AnsiArtPlayer(filename, height=25, width=80, encoding='cp437', strip=False, rate=2)

Bases: AbstractScreenPlayer

Renderer to play ANSI art text files.

In order to tidy up files, this must be used as a context manager (i.e. using with).

Parameters:

  • filename – the file containingi the ANSI art.

  • height – required height of the renderer.

  • width – required width of the renderer.

  • encoding – text encoding ofnthe file.

  • strip – whether to strip CRLF from the file content.

  • rate – number of lines to render on each update.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.AsciinemaPlayer(filename, height=None, width=None, max_delay=None)

Bases: AbstractScreenPlayer

Renderer to play terminal recordings created by asciinema.

This only supports the version 2 file format. Use the max_delay setting to speed up human interactions (i.e. to reduce delays from typing).

In order to tidy up files, this must be used as a context manager (i.e. using with).

Parameters:

  • filename – the file containingi the ANSI art.

  • height – required height of the renderer.

  • width – required width of the renderer.

  • max_delay – maximum time interval (in secs) to wait between frame updates.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.BarChart(height, width, functions, char='#', colour=2, bg=0, gradient=None, scale=None, axes=2, intervals=None, labels=False, border=True, keys=None, gap=None)

Bases: _BarChartBase

Renderer to create a horizontal bar chart using the specified functions as inputs for each entry. Can be used to chart distributions or for more graphical effect - e.g. to imitate a sound equalizer or a progress indicator.

Parameters:

  • height – The max height of the rendered image.

  • width – The max width of the rendered image.

  • functions – List of functions to chart.

  • char – Character to use for the bar. Defaults to ‘#’

  • colour – Colour(s) to use for the bars. This can be a single value or list of values (to cycle around for each bar). Defaults to green.

  • bg – Background colour to use for the bars. This can be a single value or list of values (to cycle around for each bar). Defaults to black.

  • gradient – Colour gradient to use for the bars. This is a list of tuple pairs specifying a threshold and a colour, or triplets to include a background colour too. Defaults to no gradients.

  • scale – Maximum value for the bars. This is used to scale the function values to the maximum space available. Any value over this will be truncated when drawn. Defaults to the number of available characters in the chart.

  • axes – Which axes to draw.

  • intervals – Units for interval markers on the main axis. Defaults to none.

  • labels – Whether to draw size indication labels on the x-axis.

  • border – Whether to draw a border around the chart.

  • keys – Optional keys to name each bar on the y-axis.

  • gap – distance between bars. A value of None will auto-calculate (default).

If the scale parameter is not specified, the maximum length of the bar is based on the available space. A chart with no borders, no axes, no keys or labels will have a bar length based solely on the width of the graph.

  • Borders use 4 characters height and 6 characters width

  • Keys use the width of the widest key plus 1

  • Labels use a height of 1

  • An X_AXIS uses a height of 1

  • A Y_AXIS uses a width of 1

BOTH = 3

Constant to indicate both axes should be rendered.

NONE = 0

Constant to indicate no axes should be rendered.

X_AXIS = 1

Constant to indicate just the x axis should be rendered.

Y_AXIS = 2

Constant to indicate just the y axis should be rendered.

property axes_style

The current drawing style of the axes. Possible values are defined in constants:

  • ASCII_LINE – ASCII safe characters

  • SINGLE_LINE – UNICODE based single line

Note that your canvas must support UNICODE style characters to use them

property border_style

The current drawing style of the border. Possible values are defined in constants:

  • ASCII_LINE – ASCII safe characters

  • SINGLE_LINE – UNICODE based single line

  • DOUBLE_LINE – UNICODE based double line

Note that your canvas must support UNICODE style characters to use them

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.Box(width, height, uni=False, style=1)

Bases: StaticRenderer

Renders a simple box using ASCII characters. This does not render in extended box drawing characters as that requires non-ASCII characters in Windows and direct access to curses in Linux.

Parameters:

  • width – width of box

  • height – height of box

  • uni – True to use UNICODE character set, defaults to False

  • style – desired line style, based on line style definitions in constants: ASCII_LINE, SINGLE_LINE, DOUBLE_LINE. uni parameter takes precedence and the style will be ignored if uni==False

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.ColourImageFile(screen, filename, height=30, bg=0, fill_background=False, uni=False, dither=False)

Bases: StaticRenderer

Renderer to convert an image file (as supported by the Python Imaging Library) into an block image of available colours.

Warning

This is only compatible with 256-colour terminals. Results in other terminals with reduced colour capabilities are severely restricted. Since Windows only has 8 base colours, it is recommended that you avoid this renderer on that platform.

Parameters:

  • screen – The screen to use when displaying the image.

  • filename – The name of the file to render.

  • height – The height of the text rendered image.

  • bg – The default background colour for this image.

  • fill_background – Whether to set background colours too.

  • uni – Whether to use unicode box characters or not.

  • dither – Whether to dither the rendered image or not.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.DynamicRenderer(height, width, clear=True)

Bases: Renderer

A DynamicRenderer is a Renderer that creates each image as requested. It has a defined maximum size on construction.

Parameters:

  • height – The max height of the rendered image.

  • width – The max width of the rendered image.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.FigletText(text, font='standard', width=200)

Bases: StaticRenderer

This class renders the supplied text using the specified Figlet font. See http://www.figlet.org/ for details of available fonts.

Parameters:

  • text – The text string to convert with Figlet.

  • font – The Figlet font to use (optional).

  • width – The maximum width for this text in characters.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.Fire(height, width, emitter, intensity, spot, colours, bg=False)

Bases: DynamicRenderer

Renderer to create a fire effect based on a specified emitter that defines the heat source.

The implementation here uses the same techniques described in http://freespace.virgin.net/hugo.elias/models/m_fire.htm, although a slightly different implementation.

Parameters:

  • height – Height of the box to contain the flames.

  • width – Width of the box to contain the flames.

  • emitter – Heat source for the flames. Any non-whitespace character is treated as part of the heat source.

  • intensity – The strength of the flames. The bigger the number, the hotter the fire. 0 <= intensity <= 1.0.

  • spot – Heat of each spot source. Must be an integer > 0.

  • colours – Number of colours the screen supports.

  • bg – (Optional) Whether to render background colours only.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.ImageFile(filename, height=30, colours=8)

Bases: StaticRenderer

Renderer to convert an image file (as supported by the Python Imaging Library) into an ascii grey scale text image.

Parameters:

  • filename – The name of the file to render.

  • height – The height of the text rendered image.

  • colours – The number of colours the terminal supports.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.Kaleidoscope(height, width, cell, symmetry)

Bases: DynamicRenderer

Renderer to create a 2-mirror kaleidoscope effect.

This is a chained renderer (i.e. it acts upon the output of another Renderer which is passed to it on construction). The other Renderer is used as the cell that is rotated over time to create the animation.

You can specify the desired rotational symmetry of the kaleidoscope (which determines the angle between the mirrors). If you chose values of less than 2, you are effectively removing one or both mirrors, thus either getting the original cell or a simple mirrored image of the cell.

Since this renderer rotates the background cell, it needs operate on square pixels, which means each character in the cell is drawn as 2 next to each other on the screen. In other words the cell needs to be half the width of the desired output (when measured in text characters).

Parameters:

  • height – Height of the box to contain the kaleidoscope.

  • width – Width of the box to contain the kaleidoscope.

  • cell – A Renderer to use as the backing cell for the kaleidoscope.

  • symmetry – The desired rotational symmetry. Must be a non-negative integer.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.Plasma(height, width, colours)

Bases: DynamicRenderer

Renderer to create a “plasma” effect using sinusoidal functions.

The implementation here uses the same techniques described in http://lodev.org/cgtutor/plasma.html

Parameters:

  • height – Height of the box to contain the plasma.

  • width – Width of the box to contain the plasma.

  • colours – Number of colours the screen supports.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.Rainbow(screen, renderer)

Bases: StaticRenderer

Chained renderer to add rainbow colours to output of another renderer. The embedded rendered must not use multi-colour mode (i.e. ${c,a} mark-ups) as these will be converted to explicit text by this renderer.

Parameters:

  • screen – The screen object for this renderer.

  • renderer – The renderer to wrap.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.Renderer

Bases: object

A Renderer is simply a class that will return one or more text renderings for display by an Effect.

In the simple case, this can be a single string that contains some unchanging content - e.g. a simple text message.

It can also represent a sequence of strings that can be played one after the other to make a simple animation sequence - e.g. a rotating globe.

abstract property images
Returns:

An iterator of all the images in the Renderer.

abstract property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

abstract property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

abstract property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.RotatedDuplicate(width, height, renderer)

Bases: StaticRenderer

Chained renderer to add a rotated version of the original renderer underneath and centre the whole thing within within the specified dimensions.

Parameters:

  • width – The maximum width of the rendered text.

  • height – The maximum height of the rendered text.

  • renderer – The renderer to wrap.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.Scale(width)

Bases: StaticRenderer

This renders a linear scale, useful for debugging positions of your creations. Every 5 spaces gets a tick mark, every 10 a number.

Parameters:

width – The width of the scale

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.SpeechBubble(text, tail=None, uni=False)

Bases: StaticRenderer

Renders supplied text into a speech bubble.

Parameters:

  • text – The text to be put into a speech bubble.

  • tail – Where to put the bubble callout tail, specifying “L” or “R” for left or right tails. Can be None for no tail.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.StaticRenderer(images=None, animation=None)

Bases: Renderer

A StaticRenderer is a Renderer that can create all possible images in advance. After construction the images will not change, but can by cycled for animation purposes.

This class will also convert text like ${c,a,b} into colour c, attribute a and background b for any subsequent text in the line, thus allowing multi-coloured text. The attribute and background are optional.

Parameters:

  • images – An optional set of ascii images to be rendered.

  • animation – A function to pick the image (from images) to be rendered for any given frame.

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.VBarChart(height, width, functions, char='#', colour=2, bg=0, gradient=None, scale=None, axes=1, intervals=None, labels=False, border=True, keys=None, gap=None)

Bases: _BarChartBase

Renderer to create a vertical bar chart using the specified functions as inputs for each entry. Can be used to chart distributions or for more graphical effect - e.g. to imitate a sound equalizer or a progress indicator.

Parameters:

  • height – The max height of the rendered image.

  • width – The max width of the rendered image.

  • functions – List of functions to chart.

  • char – Character to use for the bar. Defaults to ‘#’

  • colour – Colour(s) to use for the bars. This can be a single value or list of values (to cycle around for each bar). Defaults to green.

  • bg – Background colour to use for the bars. This can be a single value or list of values (to cycle around for each bar). Defaults to black.

  • gradient – Colour gradient to use for the bars. This is a list of tuple pairs specifying a threshold and a colour, or triplets to include a background colour too. Defaults to no gradients.

  • scale – Maximum value for the bars. This is used to scale the function values to the maximum space available. Any value over this will be truncated when drawn. Defaults to the number of available characters in the chart.

  • axes – Which axes to draw.

  • intervals – Units for interval markers on the main axis. Defaults to none.

  • labels – Whether to draw size indication labels on the y-axis.

  • border – Whether to draw a border around the chart.

  • keys – Optional keys to name each bar on the x-axis.

  • gap – distance between bars. A value of None will auto-calculate (default). Minimum value when auto-calculated is 1, for no gaps specify 0.

If the scale parameter is not specified, the maximum length of the bar is based on the available space. A chart with no borders, no axes, no keys or labels will have a bar height based solely on the width of the graph.

  • Borders use 4 characters height and 6 characters width

  • Keys use a height of 1

  • Labels vertical bar chart use the width of the widest label plus 1 (label values depend on the scale of the chart)

  • An X_AXIS uses a height of 1

  • A Y_AXIS uses a width of 1

BOTH = 3

Constant to indicate both axes should be rendered.

NONE = 0

Constant to indicate no axes should be rendered.

X_AXIS = 1

Constant to indicate just the x axis should be rendered.

Y_AXIS = 2

Constant to indicate just the y axis should be rendered.

property axes_style

The current drawing style of the axes. Possible values are defined in constants:

  • ASCII_LINE – ASCII safe characters

  • SINGLE_LINE – UNICODE based single line

Note that your canvas must support UNICODE style characters to use them

property border_style

The current drawing style of the border. Possible values are defined in constants:

  • ASCII_LINE – ASCII safe characters

  • SINGLE_LINE – UNICODE based single line

  • DOUBLE_LINE – UNICODE based double line

Note that your canvas must support UNICODE style characters to use them

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.VScale(height)

Bases: StaticRenderer

This renders a vertical linear scale, useful for debugging positions of your creations. Writes lowest significant digit of a count running vertically.

Parameters:

width – The width of the scale

property images
Returns:

An iterator of all the images in the Renderer.

property max_height
Returns:

The max height of the rendered text (across all images if an animated renderer).

property max_width
Returns:

The max width of the rendered text (across all images if an animated renderer).

property rendered_text
Returns:

The next image and colour map in the sequence as a tuple.