Reference

Attention

🚧 Under Construction - There might be incompatible interface changes between minor versions of version zero!

If you want to use the library in a project while it’s still on version zero, ensure you pin the dependency to a specific minor version e.g >=0.4,<0.5.

On this note, you probably also want to switch to the specific documentation for the version you’re using (somewhere at the lower left corner of this page).

Sub-sections:

Top-Level Definitions

term_image.set_font_ratio(ratio)

Sets the global font ratio.

Parameters

ratio (Union[float, term_image.FontRatio]) –

Can be one of the following values.

A positive float: a fixed aspect ratio of a character cell in the terminal emulator.
FontRatio.AUTO: the ratio is immediately determined from the active terminal.
FontRatio.FULL_AUTO: the ratio is determined from the active terminal whenever get_font_ratio() is called, though with some caching involved, such that the ratio is re-determined only if the terminal size changes.

Raises

TypeError – An argument is of an inappropriate type.
ValueError – An argument is of an appropriate type but has an unexpected/invalid value.
term_image.exceptions.TermImageError – Auto font ratio is not supported in the active terminal or on the current platform.

This value is taken into consideration when setting image sizes for text-based render styles, in order to preserve the aspect ratio of images drawn to the terminal.

Note

Changing the font ratio does not automatically affect any image that already has it’s size set. For a change in font ratio to have any effect, the image’s size has to be set again.

Attention

See Auto Font Ratio for details about the auto modes.

term_image.get_font_ratio()

Returns the global font ratio.

See set_font_ratio().

class term_image.FontRatio(value)

Bases: enum.Enum

Constants for auto font ratio modes

AUTO

FULL_AUTO

class term_image.TermImageWarning

Bases: UserWarning

Package-specific warning category

Render Styles

A render style is a specific implementation of representing or drawing images in a terminal emulator and each is implemented as a class.

All render styles are designed to share a common interface (with some styles having extensions), making the usage of one class directly compatibile with another, except when using style-specific features.

Hence, the covenience functions AutoImage, from_file() and from_url() provide a means of render-style-independent usage of the library.

These functions automatically detect the best render style supported by the active terminal.

There a two categories of render styles:

Text-based Render Styles

Represent images using ASCII or Unicode symbols, and in some cases, in conjunction with ANSI colour escape codes.

Classes for render styles in this category are subclasses of TextImage. These include:

BlockImage

Graphics-based Render Styles

Represent images with actual pixels, using terminal graphics protocols.

Classes for render styles in this category are subclasses of GraphicsImage. These include:

Auto Font Ratio

When using auto font ratio (in either mode), it’s important to note that some (not all) terminal emulators (e.g VTE-based ones) might have to be queried. See Terminal Queries.

If the program will never expect any useful input, particularly while an image’s size is being set or when an image with unset size is being rendered, then using FULL_AUTO mode is OK.

Otherwise i.e if the program will be expecting input, use AUTO mode and use utils.read_tty() to read all currently unread input just before calling set_font_ratio().

Image Format Specification

[h_align] [width] [ . [v_align] [height] ] [ # [threshold | bgcolor] ] [ + {style} ]

Note

The spaces are only for clarity and not included in the syntax.
Fields within [ ] are optional.
Fields within { } are required, though subject to any enclosing [ ].
| implies mutual exclusivity.
If the . is present, then at least one of v_align and height must be present.
width and height are in units of columns and lines repectively.
If the padding width or padding height is less than or equal to the image’s rendered width or rendered height respectively, the padding has no effect.

h_align: This can be one of:
- < → left
- | → center
- > → right
- Default → center
width: padding width
- Positive integer
- Default: terminal width minus horizontal allowance
v_align: This can be one of:
- ^ → top
- - → middle
- _ → bottom
- Default → middle
height: padding height
- Positive integer
- Default: terminal height minus vertical allowance
#: Transparency setting:
- Default: transparency is enabled with the default alpha threshold.
- threshold: alpha threshold e.g .0, .325043, .99999.
  - The value must be in the range 0.0 <= threshold < 1.0.
  - Applies to only text-based render styles e.g. BlockImage.
- bgcolor: Color to replace transparent background with. Can be:
  - # -> The terminal’s default background color (or black, if undetermined) is used.
  - A hex color e.g ffffff, 7faa52.
- If neither threshold nor bgcolor is present, but # is present, transparency is disabled (alpha channel is removed).
style: Style-specific format specifier.

See each render style in Image Classes for its own specification, if it defines.

style can be broken down into [parent] [current], where current is the spec defined by a class and parent is the spec defined by a parent of that class. parent can in turn be recursively broken down as such.

See Formatted rendering for examples.