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).
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 wheneverget_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.
AutoImage
, from_file()
and from_url()
provide a means of render-style-independent usage of the library.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:
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 ofv_align
andheight
must be present.width
andheight
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>
→ rightDefault → center
width
: padding widthPositive integer
Default: terminal width minus horizontal allowance
v_align
: This can be one of:^
→ top-
→ middle_
→ bottomDefault → middle
height
: padding heightPositive 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
norbgcolor
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]
, wherecurrent
is the spec defined by a class andparent
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.