Display images in the terminal
Project description
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
Click to expand
With a local image file
term-image path/to/image.png
With an image URL
term-image https://www.example.com/image.png
With a directory, recursively (not currently supported on Windows)
term-image -r path/to/dir/
If the image is animated (GIF, WEBP), the animation is infinitely looped by default but can be stopped with Ctrl-C
.
By default, if multiple sources or at least one directory is given, the TUI (Text-based/Terminal User Interface) is launched to navigate through the images (and/or directories).
NOTE: python -m term_image
can be used as an alternative to the term-image
command (take note of the underscore VS hyphen).
Library Quick Start
Click to expand
Creating an instance
from term_image.image import from_file
image = from_file("path/to/image.png")
You can also use a URL if you don't have the file stored locally
from term_image.image import from_url
image = from_url("https://www.example.com/image.png")
The library can also be used with PIL images
from PIL import Image
from term_image.image import AutoImage
img = Image.open("path/to/image.png")
image = AutoImage(img)
Drawing/Displaying an image to/in the terminal
There are two ways to draw an image to the terminal.
1. The draw()
method
image.draw()
2. Using print()
with a rendered image
print(image) # without formatting
OR
print(f"{image:>200.^100#ffffff}") # with formatting
For animated images, only the first method can animate the output, the second only outputs the current frame.
Usage
:construction: Under Construction - There might be incompatible changes between minor versions of version zero!
If you want to use term-image
in a project while it's still on version zero, ensure you pin the dependency version to a specific minor version e.g >=0.4,<0.5
.
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:
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:
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for term_image-0.4.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 12b4083333eef3d46daf7afc39960d13eb9e117a599f8cc594a5675aa3d0ca9a |
|
MD5 | 83a66f450751256c1764f717ee234560 |
|
BLAKE2b-256 | 2cc5e37667179d6c98f522590143cb06484b6373daf742a39bddf5142951af14 |