<div align="center">
<h1><b>Term-Image</b></h1>
<p>
<img src="https://raw.githubusercontent.com/AnonymouX47/term-image/92ff4b2d2e4731be9e1b2ac7378964ebed9f10f9/docs/source/resources/logo.png" height="200">
</p>
<p>
<b>Display images in the terminal with Python</b>
</p>
<p>
📖 <a href='https://term-image.readthedocs.io'>Docs</a>
║
🏫 <a href='https://term-image.readthedocs.io/en/stable/start/tutorial.html'>Tutorial</a>
</p>
<p>
<a href='https://pypi.org/project/term-image/'>
<img src='https://img.shields.io/pypi/v/term-image.svg'>
</a>
<a href='https://pepy.tech/project/term-image'>
<img src="https://pepy.tech/badge/term-image/month">
</a>
<a href='https://pypi.org/project/term-image/'>
<img src='https://img.shields.io/pypi/pyversions/term-image.svg'>
</a>
<a href='https://github.com/psf/black'>
<img src='https://img.shields.io/badge/code%20style-black-000000.svg'>
</a>
<a href='https://github.com/AnonymouX47/term-image/actions/workflows/test.yml'>
<img src='https://github.com/AnonymouX47/term-image/actions/workflows/test.yml/badge.svg'>
</a>
<a href='https://term-image.readthedocs.io'>
<img src='https://readthedocs.org/projects/term-image/badge/?version=latest' alt='Documentation Status' />
</a>
<img src="https://img.shields.io/github/last-commit/AnonymouX47/term-image">
<a href="https://twitter.com/intent/tweet?text=Display%20images%20in%20the%20terminal%20with%20Python&url=https://github.com/AnonymouX47/term-image&hashtags=developers,images,terminal,python">
<img src="https://img.shields.io/twitter/url/http/shields.io.svg?style=social">
</a>
</p>
</div>
## Contents
- [Installation](#installation)
- [Features](#features)
- [Demo](#demo)
- [Quick Start](#library-quick-start)
- [Usage](#usage)
- [Contribution](#contribution)
- [Planned Features](#planned-features)
- [Known Issues](#known-issues)
- [FAQs](#faqs)
- [Credits](#credits)
- [Sponsor This Project](#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](https://term-image.readthedocs.io/en/stable/faqs.html))
- [Python](https://www.python.org/) >= 3.7
- A terminal emulator with **any** of the following:
- support for the [Kitty graphics protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/).
- support for the [iTerm2 inline image protocol](https://iterm2.com/documentation-images.html).
- full Unicode support and ANSI 24-bit color support
**Plans to support a wider variety of terminal emulators are in motion** (see [Planned Features](#planned-features)).
### Steps
The latest **stable** version can be installed from [PyPI](https://pypi.org/project/term-image) with:
```shell
pip install term-image
```
The **development** version can be installed with:
```shell
pip install git+https://github.com/AnonymouX47/term-image.git
```
### Supported Terminal Emulators
See [here](https://term-image.readthedocs.io/en/stable/start/installation.html#supported-terminal-emulators) 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](https://github.com/AnonymouX47/term-image/discussions/4).
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()`](https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html))
- 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](https://sw.kovidgoyal.net/kitty/graphics-protocol/), [iTerm2](https://iterm2.com/documentation-images.html)
- 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][termvisage] based on this library.
## Quick Start
### Creating an instance
1. Initialize with a file path:
```python
from term_image.image import from_file
image = from_file("path/to/image.png")
```
2. Initialize with a URL:
```python
from term_image.image import from_url
image = from_url("https://www.example.com/image.png")
```
3. Initialize with a PIL (Pillow) image instance:
```python
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:
1. Using the `draw()` method:
```python
image.draw()
```
**NOTE:** `draw()` has various parameters for render formatting.
2. Using `print()` with an image render output:
```python
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](https://term-image.readthedocs.io/en/stable/start/tutorial.html) for a more detailed introduction.
## Usage
<p align="center"><b>
🚧 Under Construction - There will most likely be incompatible changes between minor versions of
<a href='https://semver.org/spec/v2.0.0.html#spec-item-4'>version zero</a>!
</b></p>
**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](https://term-image.readthedocs.io) for the User Guide and API Reference.
## Contribution
Please read through the [guidelines](https://github.com/AnonymouX47/term-image/blob/main/CONTRIBUTING.md).
For code contributions, you should also check out the [Planned Features](#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](https://github.com/AnonymouX47/term-image/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](https://term-image.readthedocs.io/en/stable/planned.html).
## Known Issues
See [here](https://term-image.readthedocs.io/en/stable/issues.html).
## FAQs
See the [FAQs](https://term-image.readthedocs.io/en/stable/faqs.html) section of the docs.
## Credits
The following projects have been (and are still) crucial to the development of this project:
- [Pillow](https://python-pillow.org) by [Fredrik Lundh, Jeffrey A. Clark (Alex) and contributors](https://github.com/python-pillow/Pillow/graphs/contributors)
- [Requests](https://requests.readthedocs.io) by [Kenneth Reitz and others](https://requests.readthedocs.io/en/latest/dev/authors/)
The logo was composed using resource(s) from the following source(s):
- [Gallery icons created by Andrean Prabowo - Flaticon](https://www.flaticon.com/free-icons/gallery)
## Sponsor This Project
<a href="https://www.buymeacoffee.com/anonymoux47" target="_blank">
<img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" >
</a>
Any amount will go a long way in aiding the progress and development of this project.
Thank you! 💓
[termvisage]: https://github.com/AnonymouX47/termvisage
Raw data
{
"_id": null,
"home_page": "https://github.com/AnonymouX47/term-image",
"name": "term-image",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "image,terminal,viewer,PIL,Pillow,console,xterm,library,cli,tui,ANSI,ASCII-Art,kitty,iterm2,sixel,graphics",
"author": "Toluwaleke Ogundipe",
"author_email": "anonymoux47@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/8b/43/4995d07fd3e4262d9a8acc9013cda5c6b339a55892f56b027c8ac1ba1351/term-image-0.7.1.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n<h1><b>Term-Image</b></h1>\n\n<p>\n<img src=\"https://raw.githubusercontent.com/AnonymouX47/term-image/92ff4b2d2e4731be9e1b2ac7378964ebed9f10f9/docs/source/resources/logo.png\" height=\"200\">\n</p>\n\n<p>\n<b>Display images in the terminal with Python</b>\n</p>\n\n<p>\n 📖 <a href='https://term-image.readthedocs.io'>Docs</a>\n ║ \n 🏫 <a href='https://term-image.readthedocs.io/en/stable/start/tutorial.html'>Tutorial</a>\n</p>\n\n<p>\n <a href='https://pypi.org/project/term-image/'>\n <img src='https://img.shields.io/pypi/v/term-image.svg'>\n </a>\n <a href='https://pepy.tech/project/term-image'>\n <img src=\"https://pepy.tech/badge/term-image/month\">\n </a>\n <a href='https://pypi.org/project/term-image/'>\n <img src='https://img.shields.io/pypi/pyversions/term-image.svg'>\n </a>\n <a href='https://github.com/psf/black'>\n <img src='https://img.shields.io/badge/code%20style-black-000000.svg'>\n </a>\n <a href='https://github.com/AnonymouX47/term-image/actions/workflows/test.yml'>\n <img src='https://github.com/AnonymouX47/term-image/actions/workflows/test.yml/badge.svg'>\n </a>\n <a href='https://term-image.readthedocs.io'>\n <img src='https://readthedocs.org/projects/term-image/badge/?version=latest' alt='Documentation Status' />\n </a>\n <img src=\"https://img.shields.io/github/last-commit/AnonymouX47/term-image\">\n <a href=\"https://twitter.com/intent/tweet?text=Display%20images%20in%20the%20terminal%20with%20Python&url=https://github.com/AnonymouX47/term-image&hashtags=developers,images,terminal,python\">\n <img src=\"https://img.shields.io/twitter/url/http/shields.io.svg?style=social\">\n </a>\n</p>\n\n</div>\n\n\n## Contents\n- [Installation](#installation)\n- [Features](#features)\n- [Demo](#demo)\n- [Quick Start](#library-quick-start)\n- [Usage](#usage)\n- [Contribution](#contribution)\n- [Planned Features](#planned-features)\n- [Known Issues](#known-issues)\n- [FAQs](#faqs)\n- [Credits](#credits)\n- [Sponsor This Project](#sponsor-this-project)\n\n\n> ### \u26a0\ufe0f NOTICE!!! \u26a0\ufe0f\n> The image viewer (CLI and TUI) has been moved to [termvisage].\n\n\n## Installation\n\n### Requirements\n- Operating System: Unix / Linux / Mac OS X / Windows (limited support, see the [FAQs](https://term-image.readthedocs.io/en/stable/faqs.html))\n- [Python](https://www.python.org/) >= 3.7\n- A terminal emulator with **any** of the following:\n \n - support for the [Kitty graphics protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/).\n - support for the [iTerm2 inline image protocol](https://iterm2.com/documentation-images.html).\n - full Unicode support and ANSI 24-bit color support\n\n **Plans to support a wider variety of terminal emulators are in motion** (see [Planned Features](#planned-features)).\n\n### Steps\nThe latest **stable** version can be installed from [PyPI](https://pypi.org/project/term-image) with:\n\n```shell\npip install term-image\n```\n\nThe **development** version can be installed with:\n\n```shell\npip install git+https://github.com/AnonymouX47/term-image.git\n```\n\n### Supported Terminal Emulators\nSee [here](https://term-image.readthedocs.io/en/stable/start/installation.html#supported-terminal-emulators) for a list of tested terminal emulators.\n\nIf you've tested this library on any other terminal emulator that meets the requirements for any of the render styles,\nplease mention the name (and version) in a new thread under [this discussion](https://github.com/AnonymouX47/term-image/discussions/4).\n\nAlso, if you have any issue with terminal support, you may report or check information about it in the discussion linked above.\n\n\n## Features\n- Multiple image formats (basically all formats supported by [`PIL.Image.open()`](https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html))\n- Multiple image source types: PIL image instance, local file, URL\n- Multiple image render styles (with automatic support detection)\n- Support for multiple terminal graphics protocols: [Kitty](https://sw.kovidgoyal.net/kitty/graphics-protocol/), [iTerm2](https://iterm2.com/documentation-images.html)\n - Exposes various features of the protocols\n- Transparency support (with multiple options)\n- Animated image support (including transparent ones)\n - Multiple formats: GIF, WEBP, APNG (and possibly more)\n - Fully controllable iteration over rendered frames of animated images\n - Image animation with multiple parameters\n- Integration into various TUI / terminal-based output libraries.\n- Terminal size awareness\n- Automatic and manual image sizing\n- Horizontal and vertical alignment\n- Automatic and manual font ratio adjustment (to preserve image aspect ratio)\n- and more... \ud83d\ude01\n\n\n## Demo\n\nCheck out this [image viewer][termvisage] based on this library.\n\n\n## Quick Start\n\n### Creating an instance\n\n1. Initialize with a file path:\n ```python\n from term_image.image import from_file\n \n image = from_file(\"path/to/image.png\")\n ```\n\n2. Initialize with a URL:\n ```python\n from term_image.image import from_url\n \n image = from_url(\"https://www.example.com/image.png\")\n ```\n\n3. Initialize with a PIL (Pillow) image instance:\n ```python\n from PIL import Image\n from term_image.image import AutoImage\n \n img = Image.open(\"path/to/image.png\")\n image = AutoImage(img)\n ```\n\n### Drawing/Displaying an Image\n\nThere are two basic ways to draw an image to the terminal screen:\n\n1. Using the `draw()` method:\n ```python\n image.draw()\n ```\n **NOTE:** `draw()` has various parameters for render formatting.\n\n2. Using `print()` with an image render output:\n ```python\n print(image) # without formatting\n # OR\n print(f\"{image:>200.^100#ffffff}\") # with formatting\n ```\n\nFor animated images, only the former animates the output, the latter only draws the current frame.\n\nSee the [tutorial](https://term-image.readthedocs.io/en/stable/start/tutorial.html) for a more detailed introduction.\n\n\n## Usage\n\n<p align=\"center\"><b>\n \ud83d\udea7 Under Construction - There will most likely be incompatible changes between minor versions of\n <a href='https://semver.org/spec/v2.0.0.html#spec-item-4'>version zero</a>!\n</b></p>\n\n**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`.**\n\nSee the [docs](https://term-image.readthedocs.io) for the User Guide and API Reference.\n\n\n## Contribution\n\nPlease read through the [guidelines](https://github.com/AnonymouX47/term-image/blob/main/CONTRIBUTING.md).\n\nFor code contributions, you should also check out the [Planned Features](#planned-features).\nIf you wish to work on any of the listed features/improvements, please click on the linked issue or go through the [issues](https://github.com/AnonymouX47/term-image/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.\n\nHint: You can filter issues by *label* or simply *search* using the features's description.\n\nThanks! \ud83d\udc93\n\n\n## Planned Features\n\nSee [here](https://term-image.readthedocs.io/en/stable/planned.html).\n\n## Known Issues\n\nSee [here](https://term-image.readthedocs.io/en/stable/issues.html).\n\n## FAQs\n\nSee the [FAQs](https://term-image.readthedocs.io/en/stable/faqs.html) section of the docs.\n\n## Credits\n\nThe following projects have been (and are still) crucial to the development of this project:\n- [Pillow](https://python-pillow.org) by [Fredrik Lundh, Jeffrey A. Clark (Alex) and contributors](https://github.com/python-pillow/Pillow/graphs/contributors)\n- [Requests](https://requests.readthedocs.io) by [Kenneth Reitz and others](https://requests.readthedocs.io/en/latest/dev/authors/)\n\nThe logo was composed using resource(s) from the following source(s):\n- [Gallery icons created by Andrean Prabowo - Flaticon](https://www.flaticon.com/free-icons/gallery)\n\n## Sponsor This Project\n\n<a href=\"https://www.buymeacoffee.com/anonymoux47\" target=\"_blank\">\n <img src=\"https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png\" alt=\"Buy Me A Coffee\" style=\"height: 60px !important;width: 217px !important;\" >\n</a>\n\nAny amount will go a long way in aiding the progress and development of this project.\nThank you! \ud83d\udc93\n\n\n[termvisage]: https://github.com/AnonymouX47/termvisage\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Display images in the terminal",
"version": "0.7.1",
"project_urls": {
"Changelog": "https://github.com/AnonymouX47/term-image/blob/main/CHANGELOG.md",
"Documentation": "https://term-image.readthedocs.io/",
"Funding": "https://github.com/AnonymouX47/term-image#donate",
"Homepage": "https://github.com/AnonymouX47/term-image",
"Source": "https://github.com/AnonymouX47/term-image",
"Tracker": "https://github.com/AnonymouX47/term-image/issues"
},
"split_keywords": [
"image",
"terminal",
"viewer",
"pil",
"pillow",
"console",
"xterm",
"library",
"cli",
"tui",
"ansi",
"ascii-art",
"kitty",
"iterm2",
"sixel",
"graphics"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "eecd17b2d37610d0cbd698df4692a33f2cec00e805c245bfaeada870b9d42b92",
"md5": "2567ac73cc2673a1564857a7593efdd5",
"sha256": "744bc475b13e350e6d58cfec63c294f753e1514a08d3a8f015ff64440884a7f3"
},
"downloads": -1,
"filename": "term_image-0.7.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2567ac73cc2673a1564857a7593efdd5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 62130,
"upload_time": "2024-02-10T13:01:04",
"upload_time_iso_8601": "2024-02-10T13:01:04.768138Z",
"url": "https://files.pythonhosted.org/packages/ee/cd/17b2d37610d0cbd698df4692a33f2cec00e805c245bfaeada870b9d42b92/term_image-0.7.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8b434995d07fd3e4262d9a8acc9013cda5c6b339a55892f56b027c8ac1ba1351",
"md5": "7401299a6ed4a610b13bacd87696a7e1",
"sha256": "607456bd0496dc9ae4925477d239c7d012ef857a31b2317f1f5455c417190b0b"
},
"downloads": -1,
"filename": "term-image-0.7.1.tar.gz",
"has_sig": false,
"md5_digest": "7401299a6ed4a610b13bacd87696a7e1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 61191,
"upload_time": "2024-02-10T13:01:07",
"upload_time_iso_8601": "2024-02-10T13:01:07.040534Z",
"url": "https://files.pythonhosted.org/packages/8b/43/4995d07fd3e4262d9a8acc9013cda5c6b339a55892f56b027c8ac1ba1351/term-image-0.7.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-10 13:01:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AnonymouX47",
"github_project": "term-image",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "term-image"
}
JSON
