Term-Image

Display Images in the terminal

Contents

• Installation
• Features
• Demo
• CLI/TUI Quick Start
• Library Quick Start
• Usage
• Contribution
• WIP
• TODO
• Known Issues
• FAQs

Installation

Requirements

• Operating System: Unix / Linux / MacOS X / Windows (partial support, see the FAQs)
• Python >= 3.7
• A Terminal emulator with full Unicode support and ANSI 24-bit color support
  • Plans are in place to support a wider variety of terminal emulators, whether not meeting or surpassing these requirements (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: Clone this repository, then navigate into the project directory in a terminal 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 all requirements, please mention the name in a new thread under this discussion. Also, if you're having an issue with terminal support, you may report or view information about it in the discussion linked above.

Features

Library features

• Multiple image format support
  • Basically supports all formats supported by PIL.Image.open()
• Multiple image sources (PIL image, local file, URL)
• Transparency support (with multiple options)
• Animated image support (including transparent ones)
  • Fully controllable and efficient iteration over frames of animated images
  • Image animation with controllable parameters
• Terminal size awareness
• Variable image size
• Automatic image sizing; best fit within the terminal window or a given size
• Variable image scale
• Horizontal and vertical alignment/padding
• Font-ratio adjustment
• and more... :grin:

CLI/TUI features

• Basically everything the library supports
• Individual image display
• Browse multiple images
• Browse directories (recursively) [TUI]
• Image grids [TUI]
• Context-based controls [TUI]
• Dynamic controls (context actions are disabled and enabled dynamically) [TUI]
• Customizable controls and configuration options
• Automatic adjustment upon terminal resize [TUI]
• Image deletion [TUI]
• Smooth and fairly performant experience
• Takes advantage of both concurrency and parallelism
• Notification system
• Detailed logging system
• and more... :grin:

Demo

CLI/TUI Quick Start

term-image path/to/image.png

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

Library Quick Start

Creating an instance

from term_image.image import TermImage

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

from term_image.image import TermImage

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

from PIL import Image
from term_image.image import TermImage

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

Rendering an image

str(image)

format(image, "|200.^100#ffffff")

f"{image:>._#.5}"

"{:1.1#}".format(image)

Drawing/Displaying an image to/in the terminal

image.draw()

print(image)  # Uses str()

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

Usage

Library

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

PLEASE NOTE: This project is currently at a stage where the public API might change without warning but significant changes will always be specified in the changelog.

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 controls can be configured by modifying the config file ~/.term_image/config.json. See the Configuration section.

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 make sure you read through the guidelines.

Also, check out the WIP and TODO sections below. If you wish to work on any of the listed tasks, please 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:

WIP

• Support for terminal graphics protocols (See #23)
• Performace Improvements

TODO

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.