Canvas Configuration

import chafa

config = chafa.CanvasConfig()

config.height = 10
config.width  = 10

config.fg_color = (255, 0, 255)

CanvasConfig

A CanvasConfig describes a set of parameters for Canvas, such as its geometry, color space and other output characteristics.

To create a new CanvasConfig, simply initialise that class. You can then modify it changing it’s properties (which are inherited from it’s base class ReadOnlyCanvasConfig) and via it’s setter functions e.g. CanvasConfig.set_symbol_map() before using it to initialise a Canvas.

Note that it is not possible to change a canvas’ configuration after the canvas is created.

class chafa.CanvasConfig
Bases:

ReadOnlyCanvasConfig

copy()

Creates a new CanvasConfig that’s a copy of this one.

Return type:

CanvasConfig

set_symbol_map(symbol_map: SymbolMap)

Assigns a copy of symbol_map to config.

Parameters:

symbol_map (SymbolMap) – The symbol_map.

calc_canvas_geometry(src_width: int, src_height: int, font_ratio: float, zoom: bool = False, stretch: bool = False)

Calculates an optimal geometry for a Canvas given the width and height of an input image, font ratio, zoom and stretch preferences. This will then set the config’s width and height to the calculated values.

Parameters:

  • src_width (int) – Width of the input image in pixels.

  • src_height (int) – Height of the input image in pixels.

  • font_ratio (float) – The font’s width divided by its height.

  • zoom (bool) – Upscale the image to fit the canvas.

  • stretch (bool) – Ignore the aspect ratio of source.

Raises:

  • ValueError – if src_width src_height or font_ratio are <= 0

  • TypeError – if zoom or stretch are None

set_fill_symbol_map(fill_symbol_map: SymbolMap)

Assigns a copy of fill_symbol_map to config.

Fill symbols are assigned according to their overall foreground to background coverage, disregarding shape.

Parameters:

fill_symbol_map (SymbolMap) – The fill symbol map.

ReadOnlyCanvasConfig

This class describes a read only CanvasConfig. This is returned from e.g. Canvas.peek_config().

The properties of a ReadOnlyCanvasConfig become editable when inherited by a CanvasConfig.

Attention

All properties of ReadOnlyCanvasConfig can be inspected but not changed!

class chafa.ReadOnlyCanvasConfig
property width
Type:

int

The config’s width in character cells.

property height
Type:

int

The config’s height in character cells.

property cell_width
Type:

int

The config’s cell width in pixels.

property cell_height
Type:

int

The config’s cell height in pixels.

property pixel_mode
Type:

PixelMode

The config’s stored PixelMode. This determines how pixel graphics are rendered in the output.

property canvas_mode
Type:

CanvasMode

The config’s stored CanvasMode. This determines how colours (and colour control codes) are used in the output.

property color_extractor
Type:

ColorExtractor

The config’s stored ColorExtractor. This determines how colours are approximated in character symbol output e.g. PixelMode.CHAFA_PIXEL_MODE_SYMBOLS.

property color_space
Type:

ColorSpace

The config’s stored ColorSpace.

property dither_mode
Type:

DitherMode

The config’s stored DitherMode.

property dither_intensity
Type:

float

The relative intensity of the dithering pattern applied during image conversion. 1.0 is the default, corresponding to a moderate intensity.

property dither_width
Type:

int

The config’s stored dither grain width in pixels. These values can be 1, 2, 4 or 8. 8 corresponds to the size of an entire character cell. The default is 4 pixels.

property dither_height
Type:

int

The config’s stored dither grain width in pixels. These values can be 1, 2, 4 or 8. 8 corresponds to the size of an entire character cell. The default is 4 pixels.

property transparency_threshold
Type:

float

The threshold above which full transparency will be used.

property fg_only
Type:

bool

Queries whether to use foreground colors only, leaving the background unmodified in the canvas output. When this is set, the canvas will emit escape codes to set the foreground color only.

Note

This is relevant only when the pixel_mode is set to PixelMode.CHAFA_PIXEL_MODE_SYMBOLS.

property fg_color
Type:

tuple[int, int, int]

The assumed foreground color of the output device. This is used to determine how to apply the foreground pen in FGBG modes like CanvasMode.CHAFA_CANVAS_MODE_FGBG.

The color is a tuple containing 3 integers in range [0,255] corresponding to red, green and blue respectively.

property bg_color
Type:

tuple[int, int, int]

The assumed background color of the output device. This is used to determine how to apply the background pen in FGBG modes like CanvasMode.CHAFA_CANVAS_MODE_FGBG.

The color is a tuple containing 3 integers in range [0,255] corresponding to red, green and blue respectively.

property preprocessing
Type:

bool

Indicates whether automatic image preprocessing should be enabled. This allows Chafa to boost contrast and saturation in an attempt to improve legibility.

Note

The type of preprocessing applied (if any) depends on the canvas_mode.

property work_factor
Type:

float

Gets the work/quality tradeoff factor. A higher value means more time and memory will be spent towards a higher quality output.

property optimizations
Type:

tuple[Optimizations, …]

The config’s optimization flags. When enabled, these may produce more compact output at the cost of reduced compatibility and increased CPU use.

The config’s optimizations are a tuple containing all enabled flags.

Note

Output quality is unaffected by optimizations.

get_geometry()

Get the config’s canvas geometry in character cells. This is the same as inspecting width and height

Return type:

tuple[int, int] of width and height.

peek_symbol_map()

Returns a read only version of the SymbolMap belonging to the config.

Note

There are currently no implemented attributes or getter functions for ReadOnlySymbolMap.

Return type:

ReadOnlySymbolMap