Term-Image

Display Images in the terminal

Contents

• Installation
• Features
• Demo
• CLI/TUI Quick Start
• Library Quick Start
• Usage
• Contribution
• Planned Features
• Known Issues
• FAQs
• Credits
• Donate

Installation

Requirements

• Operating System: Unix / Linux / Mac OS X / Windows (limited support, see the FAQs)

• Python >= 3.7

• A terminal emulator with any of the following:

  • support for the Kitty graphics protocol.
  • support for the iTerm2 inline image protocol.
  • full Unicode support and ANSI 24-bit color support

  Plans to support a wider variety of terminal emulators are in motion (see here).

Steps

The latest stable version can be installed from PyPI using pip:

pip install term-image

The development version can be installed thus:

NOTE: it's recommended to install in an isolated virtual environment which can be created by any means.

Clone this repository from within a terminal

git clone https://github.com/AnonymouX47/term-image.git

then navigate into the local repository

cd term-image

and run

pip install .

Supported Terminal Emulators

See here for a list of tested terminal emulators.

If you've tested term-image on any other terminal emulator that meets the requirements for any of the render styles, please mention the name (and version) in a new thread under this discussion.

Also, if you have any issue with terminal support, you may report or check information about it in the discussion linked above.

Features

Library features

• Multiple image formats (basically all formats supported by PIL.Image.open())
• Multiple image source types: PIL image instance, local file, URL
  • Exposes various features of the protocols
• Multiple image render styles (with automatic support detection)
• Support for multiple terminal graphics protocols: Kitty, iTerm2
• Transparency support (with multiple options)
• Animated image support (including transparent ones)
  • Multiple formats: GIF, WEBP, APNG (and possibly more)
  • Fully controllable iteration over rendered frames of animated images
  • Image animation with multiple parameters
• Terminal size awareness
• Automatic and manual image sizing
• Horizontal and vertical alignment
• Automatic and manual font ratio adjustment (to preserve image aspect ratio)
• Well-documented
• and more... :grin:

CLI/TUI features

• Almost everything the library supports
• Individual/Multiple image display [CLI]
• Browse multiple images and directories (recursively) [TUI]
• Adjustable image grids [TUI]
• Context-based controls [TUI]
• Customizable controls and configuration options
• Smooth and performant experience
• and more... :grin:

How does this project compare with similar ones?

As far as I know, the only aspect of this project that any other currently existing project can be compared with is the CLI.

I prefer to leave comparisons to the users.

Demo

Check out the gallery.

CLI/TUI Quick Start

term-image path/to/image.png

term-image https://www.example.com/image.png

term-image -r path/to/dir/

Library Quick Start

from term_image.image import from_file

image = from_file("path/to/image.png")

from term_image.image import from_url

image = from_url("https://www.example.com/image.png")

from PIL import Image
from term_image.image import AutoImage

img = Image.open("path/to/image.png")
image = AutoImage(img)

image.draw()

print(image)  # without formatting

print(f"{image:>200.^100#ffffff}")  # with formatting

Usage

Library

See the tutorial for a more detailed introduction and the reference for full descriptions and details of the available features.

CLI (Command-Line Interface)

Run term-image --help to see the full usage info and list of options.

TUI (Text-based/Terminal User Interface)

The controls are context-based and displayed at the bottom of the terminal window. Pressing the F1 key (in most contexts) brings up a help menu describing the available controls (called actions) in that context.

The TUI can be configured by modifying the config file ~/.term_image/config.json. See the Configuration section of the docs.

Here is a config file with Vim-style key-bindings (majorly navigation). Remember to rename the file to config.json.

Contribution

If you've found any bug or want to suggest a new feature, please open a new issue with proper description, after browsing/searching through the existing issues and making sure you won't create a duplicate.

For code contributions, please read through the guidelines.

Also, check out the Planned Features section below. If you wish to work on any of the listed tasks, please click on the linked issue or go through the issues tab and join in on an ongoing discussion about the task or create a new issue if one hasn't been created yet, so that the implementation can be discussed.

Hint: You can filter issues by label or simply search using the task's name or description.

For anything other than the above (such as questions or anything that would fit under the term "discussion"), please open a new discussion instead.

Thanks! :heart:

Planned Features

Check here for the library and here for the image viewer.

Known Issues

Check here for the library and here for the image viewer.

FAQs

See the FAQs section of the docs.

Credits

The following projects have been (and are still) crucial to the development of this project:

• Pillow
• Urwid

Donate

Your donation will go a long way in aiding the progress and development of this project.

USDT Address: TKP6d3hLcs7i5R18WRFxLe3zsPQcCBS1Ro
Network: TRC20

I'm sincerly sorry for any inconviences that may result from the means of donation.

Please bare with me, as usual means of accepting donations are not available in the region of the world where I reside.

Thank you! :heart: