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_cell_ratio(ratio)#

Sets the global cell ratio.

Parameters:

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

Can be one of the following values.

A positive float value.
AutoCellRatio.FIXED, the ratio is immediately determined from the active terminal.
AutoCellRatio.DYNAMIC, the ratio is determined from the active terminal whenever get_cell_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 cell 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 cell ratio does not automatically affect any image that has a fixed size. For a change in cell ratio to take effect, the image’s size has to be re-set.

Attention

See Auto Cell Ratio for details about the auto modes.

term_image.get_cell_ratio()#

Returns the global cell ratio.

See set_cell_ratio().

class term_image.AutoCellRatio(value)#

Bases: enum.Enum

Values for setting Auto Cell Ratio.

is_supported: Optional[bool] = None#

Auto cell ratio support status. Can be

None -> support status not yet determined
True -> supported
False -> not supported

Can be explicitly set when using auto cell ratio but want to avoid the support check in a situation where the support status is foreknown. Can help to avoid being wrongly detected as unsupported on a queried terminal that doesn’t respond on time.

For instance, when using multiprocessing, if the support status has been determined in the main process, this value can simply be passed on to and set within the child processes.

FIXED#

DYNAMIC#

See set_cell_ratio().

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, 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 Cell Ratio#

When using auto cell 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/calculated (for an image with dynamic size, while it’s being rendered or its rendered_size, rendered_width or rendered_height property is invoked), then using DYNAMIC mode is OK.

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

Note

This concerns text-based render styles only (see the sub-section above).

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.