Library Documentation

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).

Contents:

• Tutorial
  • Creating an instance
  • Rendering an image
  • Drawing/Displaying an image to/in the terminal
  • Image size
  • Image scale
• Reference
  • Core Library Definitions
  • Custom Exceptions
  • Utilities
  • Top-Level Definitions
  • Render Styles
  • Auto Font Ratio
  • Image Format Specification

Known Issues

1. Drawing of images and animations doesn’t work completely well with Python for windows (tested in Windows Terminal and MinTTY).

   • Description: Some lines of the image seem to extend beyond the number of columns that they should normally occupy by one or two columns.

     This behaviour causes animations to go bizzare when lines extend beyond the width of the terminal emulator.

   • Comment: First of all, the issue seems to caused by the layer between Python and the terminal emulators (i.e the PTY implementation in use) which “consumes” the escape sequences used to display images.

     It is neither a fault of this library nor of the terminal emulators, as drawing of images and animations works properly with WSL within Windows Terminal.

   • Solution: A workaround is to leave some horizontal allowance of at least two columns to ensure the image never reaches the right edge of the terminal.

     This can be achieved in the library using the h_allow parameter of set_size().

2. Some animations with the kitty render style within the Kitty terminal emulator might be glitchy at the moment.

   • Description: When the LINES render method is used, lines of the image might intermittently disappear. When the WHOLE render method is used, the entire image might intermitently dissapear.

   • Comment: This is due to the fact that drawn each frame requires clearing the previous frame off the screen, since the terminal would otherwise blend subsequent frames. Not clearing previous frames would break transparent animations and result in a performance lag that gets worse over time.

   • Solution: Plans are in motion to implement support for native animations i.e utilizing the animation features provided by the protocol (See #40).

Planned Features

In no particular order:

• Performance improvements

• Support for more terminal graphics protocols (See #23)

• More text-based render styles (See #57)

• Support for terminal emulators with 256 colors, 8 colors and no color (See #61)

• Support for terminal emulators without Unicode support (See #58, #60)

• Support for fbTerm

• Support for open file objects and the Pathlike interface

• Determination of frame duration per frame during animations and image iteration

• Multithreaded animation

• Kitty image ID (See #40)

• Kitty native animation (See #40)

• Framing formatting option

• Image zoom and pan functionalities

• Setting images to their original size

• Key-value pair format specification

• Specifiy key to end animation

• Drawing images to an alternate output

• Use termpile for URL-sourced images

• Source images from raw pixel data

• IPython Extension

• Addition of urwid widgets for displaying images

• etc…