The Canvas

import chafa

config = chafa.CanvasConfig()
canvas = chafa.Canvas(config)

pixels = [0, 0, 0, 0]

canvas.draw_all_pixels(
    chafa.PixelType.CHAFA_PIXEL_RGBA8_UNASSOCIATED,
    pixels,
    1, 1, 1
)

for row in canvas[5:-5,5:-5]:
    for pix in row:
        pix.bg_color = (0, 255, 0)

print(canvas.print().decode())

Canvas

A Canvas is a canvas that can render its contents as text strings.

When you want to make a Canvas, you can specify it’s properties like the width, height, output pixel mode etc. by first creating a CanvasConfig and then initialising Canvas with that.

You can draw an image to the canvas using Canvas.draw_all_pixels() and convert it to output bytes for printing with Canvas.print(). (pssst: check out the :py:class:`loader.Loader` to make drawing images easier).

The Canvas supports indexing (and slicing) with []! This will return a CanvasInspector or a generator for the relevant CanvasInspector objects.

class chafa.Canvas(config: None | CanvasConfig)

Parameters:

config (CanvasConfig|None) – The config to initialise the canvas with. If None is passed, the canvas will be initialised with hard-coded defaults.

Raises:

TypeError – If config is not None or CanvasConfig

self[pos]

You can inspect pixels in the canvas by indexing, similar to if the canvas were a 2d array. When indexing, the first coordinate represents the row (or y coordinate) and the second represents the column (or x coordinate).

When indexing using a single value, a generator of relevant CanvasInspector objects will be returned, representing each pixel in the given row.

for pixel in canvas[0]:
    pixel.char = "a"

When indexing using two values, a single CanvasInspector will be returned representing the given pixel.

canvas[1, 4].fg_color = (0, 0, 255)

Slicing is also supported! You can slice either the row or column coordinates and this will return generators as expected. For example; if you index using [:,3] you will get a generator for each pixel in the 3rd column of the canvas (0 indexed).

for pixel in canvas[:,3]:
    print(pixel.char)

Slicing using [3:6,:5] will return generators for rows 3 to 5 inclusive. Each of these rows will be represented by a generator for CanvasInspector objects representing pixels 0 to 4 inclusive.

for row in canvas[3:6,:5]:
    for pixel in row:
        pixel.remove_background()

The take-away from this all is that indexing and slicing should work (mostly) the same as you would expect a 2d array to work. Check out the tutorial for more details.

Parameters:

pos (int|slice|tuple) – The position to index

Return type:

CanvasInspector

peek_config()

Returns a read only version of the CanvasConfig used to initialise the canvas.

Attention

This ReadOnlyCanvasConfig’s properties can be inspected but not changed.

Return type:

ReadOnlyCanvasConfig

draw_all_pixels(src_pixel_type: PixelType, src_pixels, src_width: int, src_height: int, src_rowstride: int)

Draws the given src_pixels to the canvas. Depending on your set PixelMode, this will be symbols, kitty sequences or sixel sequences.

To output the data after drawing, use the print() method.

Note

Best performance is achieved by passing a ctypes.Array for src_pixels. The chafa.loader.Loader class provides convenient (and reasonably fast) methods for this using the MagickWand C-library.

Parameters:

• src_pixel_type (PixelType) – The pixel type of src_pixels. This will determine what order the color channels will be read in and whether there is an alpha channel.

• src_pixels (list|tuple|array.array|ctypes.Array) – The source pixel data. This is a one dimensional array where every block of 3 (or 4 depending on the PixelType) values represents one pixel of the image. The order of the channels is determined by src_pixel_type.

• src_width (int) – The width of the source image.

• src_height (int) – The width of the source image.

• src_rowstride (int) – The number of values in src_image that represents one line pixels in the source image. Typically this will be the number of channels in the source image multiplied by src_width, e.g. for an image with no alpha channel and a width of 300 pixels, this will be 3*300.

Raises:

ValueError – if src_width, src_height or src_rowstride are less than or equal to 0.

print(term_info: TermInfo = None, fallback: bool = False)

Builds a UTF-8 string of terminal control sequences and symbols representing the canvas’ current contents. This can e.g. be printed to a terminal. The exact choice of escape sequences and symbols, dimensions, etc. is determined by the configuration assigned to canvas on its creation.

All output lines except for the last one will end in a newline.

Note

The output of this method will need to be decoded with bytes.decode()

Parameters:

• term_info (TermInfo) – The TermInfo that will provide the control sequences used when printing. If None is specified, the term_info will be initialised with TermDb.detect().

• fallback (bool) – If True, the term_info (the one provided by TermDb.detect() or the one provided by the user) will be supplemented with fallback control sequences.

Raises:

TypeError – If term_info is not None or TermInfo

Return type:

bytes

CanvasInspector

The CanvasInspector is an object that can inspect (and edit) individual characters in a Canvas. It is mainly generated by indexing or slicing a Canvas, however, you can initialise it yourself if you prefer.

You can think of the CanvasInspector like a detective with a magnifying glass who’s standing on the Canvas. They can only inspect the current character they are on and have the authority to make changes to that pixel. You can then move the detective to another pixel by changing their coordinates.

class chafa.CanvasInspector(canvas: Canvas, y: int, x: int)

Parameters:

• canvas (Canvas) – The canvas to inspect

• y (int) – The initial y coordinate (starting from 0)

• x (int) – The initial x coordinate (starting from 0)

Raises:

ValueError – if x or y are greater than or equal to the canvas’s width or height respectively.

property y

Type:

int

The y coordinate of the inspector.

Raises:

ValueError – if y is not less than the height of the canvas.

property x

Type:

int

The x coordinate of the inspector.

Raises:

ValueError – if x is not less than the height of the canvas.

property fg_color

Type:

tuple[int, int, int] | None

The foreground color at the inspector’s pixel. The color is represented as None if transparent or a tuple of 3 integers in range [0,255], representing the color in (R, G, B) format.

For double-width characters, both cells will be set to the same color.

Raises:

• TypeError – if fg_color is not an Iterable other than str.

• ValueError – if fg_color is not None and does not contain exactly 3 values.

• ValueError – if fg_color contains a value greater than 255 or less than 0.

property bg_color

Type:

tuple[int, int, int] | None

The background color at the inspector’s pixel. The color is represented as None if transparent or a tuple of 3 integers in range [0,255], representing the color in (R, G, B) format.

For double-width characters, both cells will be set to the same color.

Raises:

• TypeError – if bg_color is not an Iterable other than str.

• ValueError – if bg_color is not None and does not contain exactly 3 values.

• ValueError – if bg_color contains a value greater than 255 or less than 0.

property raw_fg_color

Type:

int

The raw foreground color at the inspector’s pixel. The colors are -1 for transparency, a packed 8-bit RGB value (0x00RRGGBB) in truecolor mode, or the raw pen value (0-255) in indexed modes.

New in version 1.1.0.

property raw_bg_color

Type:

int

The raw background color at the inspector’s pixel. The colors are -1 for transparency, a packed 8-bit RGB value (0x00RRGGBB) in truecolor mode, or the raw pen value (0-255) in indexed modes.

New in version 1.1.0.

property char

Type:

str

The character at the inspector’s pixel. For double-width characters, the leftmost cell must contain the character and the cell to the right of it will automatically be set to 0.

Raises:

ValueError – if char is not of length 1.

remove_foreground()

A function that sets the foreground color at the inspectors pixel to be transparent.

remove_background()

A function that sets the background color at the inspectors pixel to be transparent.