term-image 0.7.2

Description:

termimage 0.7.2

Term-Image




Display images in the terminal with Python


📖 Docs
║
🏫 Tutorial


























Contents

Installation
Features
Demo
Quick Start
Usage
Contribution
Planned Features
Known Issues
FAQs
Credits
Sponsor This Project


⚠️ NOTICE!!! ⚠️
The image viewer (CLI and TUI) has been moved to termvisage.

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.
Unicode support and direct-color (truecolor) or indexed-color (256-color) support.

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


Steps
The latest stable version can be installed from PyPI with:
pip install term-image

The development version can be installed with:
pip install git+https://github.com/AnonymouX47/term-image.git

Supported Terminal Emulators
See here for a list of tested terminal emulators.
If you've tested this library 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

Multiple image formats (basically all formats supported by PIL.Image.open())
Multiple image source types: PIL image instance, local file, URL
Multiple image render styles (with automatic support detection)
Support for multiple terminal graphics protocols: Kitty, iTerm2

Exposes various features of the protocols


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


Integration into various TUI / terminal-based output libraries.
Terminal size awareness
Automatic and manual image sizing
Horizontal and vertical alignment
Automatic and manual font ratio adjustment (to preserve image aspect ratio)
and more... 😁

Demo
Check out this image viewer based on this library.
Quick Start
Creating an instance


Initialize with a file path:
from term_image.image import from_file

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



Initialize with a URL:
from term_image.image import from_url

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



Initialize with a PIL (Pillow) image instance:
from PIL import Image
from term_image.image import AutoImage

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



Drawing/Displaying an Image
There are two basic ways to draw an image to the terminal screen:


Using the draw() method:
image.draw()

NOTE: draw() has various parameters for render formatting.


Using print() with an image render output:
print(image) # without formatting
# OR
print(f"{image:>200.^100#ffffff}") # with formatting



For animated images, only the former animates the output, the latter only draws the current frame.
See the tutorial for a more detailed introduction.
Usage

🚧 Under Construction - There will most likely be incompatible changes between minor versions of
version zero!

If you want to use this 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.
See the docs for the User Guide and API Reference.
Contribution
Please read through the guidelines.
For code contributions, you should also check out the Planned Features.
If you wish to work on any of the listed features/improvements, please click on the linked issue or go through the issues section 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 features's description.
Thanks! 💓
Planned Features
See here.
Known Issues
See here.
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 by Fredrik Lundh, Jeffrey A. Clark (Alex) and contributors
Requests by Kenneth Reitz and others

The logo was composed using resource(s) from the following source(s):

Gallery icons created by Andrean Prabowo - Flaticon

Sponsor This Project



Any amount will go a long way in aiding the progress and development of this project.
Thank you! 💓