<div align="center">
<h1><b>TermVisage</b></h1>
<p>
<img src="https://raw.githubusercontent.com/AnonymouX47/termvisage/23b8b4612e0ac4a167fa92630be63766f7f56e29/docs/source/resources/logo.png" height="200">
</p>
<p>
<b>Browse and view images in the terminal</b>
</p>
<p>
📖 <a href='https://termvisage.readthedocs.io'>Manual</a>
║
🖼 <a href='https://termvisage.readthedocs.io/en/latest/gallery.html'>Gallery</a>
</p>
<p>
<a href='https://pypi.org/project/termvisage/'>
<img src='https://img.shields.io/pypi/v/termvisage.svg'/>
</a>
<img src="https://static.pepy.tech/badge/termvisage"/>
<a href='https://pypi.org/project/termvisage/'>
<img src='https://img.shields.io/pypi/pyversions/termvisage.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://termvisage.readthedocs.io/en/latest/?badge=latest'>
<img src='https://readthedocs.org/projects/termvisage/badge/?version=latest' alt='Documentation Status'/>
</a>
<img src="https://img.shields.io/github/last-commit/AnonymouX47/termvisage"/>
<a href="https://twitter.com/intent/tweet?text=Browse%20and%20view%20images%20in%20the%20terminal&url=https://github.com/AnonymouX47/termvisage&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](#quick-start)
- [Usage](#usage)
- [Contribution](#contribution)
- [Planned Features](#planned-features)
- [Known Issues](#known-issues)
- [FAQs](#faqs)
- [Credits](#credits)
- [Sponsor This Project](#sponsor-this-project)
## Installation
### Requirements
- Operating System: Unix / Linux / Mac OS X / Windows (limited support, see the [FAQs](https://termvisage.readthedocs.io/en/latest/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 the [library][term-image]'s planned features).
### Steps
The latest version can be installed from [PyPI](https://pypi.org/project/termvisage) using [`pipx`](https://pypa.github.io/pipx/) with:
```shell
pipx install termvisage
```
and upgraded with:
```shell
pipx upgrade termvisage
```
**NOTE:** [`pip`](https://pip.pypa.io/en/stable/) can also be used but `pipx` is recommended.
## Features
- Almost everything the [term-image] library supports
- Display individual images
- Browse multiple images and directories (recursively)
- Adjustable image grids
- Context-based controls
- Customizable controls and configuration options
- Smooth and performant experience
- Shell completion for command-line arguments
- and more... 😁
## Demo
### Multiple Render Styles
| block | iterm2 | kitty |
|:-----:|:------:|:-----:|
|  |  |  |
### High-Resolution Images
|  |  |
|:---:|:---:|
### Video Demo
[Demo Video](https://user-images.githubusercontent.com/61663146/235648854-dcccd260-c463-4692-bd01-f51c099613cf.mp4)
### Gallery
Check out the [Gallery](https://termvisage.readthedocs.io/en/latest/gallery.html) for more.
## Quick Start
With a file path:
```shell
termvisage path/to/image.png
```
With a URL:
```shell
termvisage https://www.example.com/image.png
```
With a directory, recursively (not currently supported on Windows):
```shell
termvisage -r path/to/dir/
```
If a single source is given and it's animated (GIF, APNG, Animated WebP), the animation is infinitely looped by **default** and can be stopped with `Ctrl-C` (`SIGINT`).
By **default**, if multiple sources or at least one directory source is given, the TUI (Terminal User Interface) is launched to navigate through the images and/or directories.
## Usage
### CLI (Command-Line Interface)
Run ``termvisage --help`` to see the basic help message or ``termvisage --long-help`` for the full help message.
See the [CLI manual](https://termvisage.readthedocs.io/en/latest/cli.html).
### TUI (Terminal User Interface)
The controls are **context-based** and always displayed at the bottom of the screen.
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 using a config file. See the [Configuration](https://termvisage.readthedocs.io/en/latest/config.html) section of the docs.
[Here](https://github.com/AnonymouX47/termvisage/blob/main/vim_style-termvisage.json) is a config file with Vim-style key-bindings (majorly navigation).
See the [TUI manual](https://termvisage.readthedocs.io/en/latest/tui.html).
## Contribution
If you've found any bug or want to suggest a new feature, please open a new [issue](https://github.com/AnonymouX47/termvisage/issues) 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](https://github.com/AnonymouX47/termvisage/blob/main/CONTRIBUTING.md).
Also, check out the [Planned Features](#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](https://github.com/AnonymouX47/termvisage/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](https://github.com/AnonymouX47/termvisage/discussions) instead.
Thanks! 💓
## Planned Features
See [here](https://termvisage.readthedocs.io/en/latest/planned.html).
## Known Issues
See [here](https://termvisage.readthedocs.io/en/latest/issues.html).
## FAQs
See the [FAQs](https://termvisage.readthedocs.io/en/latest/faqs.html) section of the docs.
## Credits
The following projects have been (and are still) crucial to the development of this project:
- [term-image] by [@AnonymouX47](https://github.com/AnonymouX47)
- [Pillow](https://python-pillow.org) by [Fredrik Lundh, Jeffrey A. Clark (Alex) and contributors](https://github.com/python-pillow/Pillow/graphs/contributors)
- [Urwid](https://urwid.org) by [Ian Ward et al](https://github.com/urwid/urwid/graphs/contributors)
- [argcomplete](https://github.com/kislyuk/argcomplete) by [Andrey Kislyuk](https://github.com/kislyuk)
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)
Thanks to [@digitallyserviced](https://github.com/digitallyserviced) for the project name and logo concept.
## 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! 💓
[term-image]: https://github.com/AnonymouX47/term-image
Raw data
{
"_id": null,
"home_page": "https://github.com/AnonymouX47/termvisage",
"name": "termvisage",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "image,terminal,viewer,PIL,Pillow,console,xterm,cli,tui,ANSI,ASCII-Art,kitty,iterm2,sixel,graphics",
"author": "Toluwaleke Ogundipe",
"author_email": "anonymoux47@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/7a/60/71ddd8201f14e3160b1b3778114c00f129875af69f335e91877ea07795e3/termvisage-0.1.0.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n<h1><b>TermVisage</b></h1>\n\n<p>\n<img src=\"https://raw.githubusercontent.com/AnonymouX47/termvisage/23b8b4612e0ac4a167fa92630be63766f7f56e29/docs/source/resources/logo.png\" height=\"200\">\n</p>\n\n<p>\n<b>Browse and view images in the terminal</b>\n</p>\n\n<p>\n 📖 <a href='https://termvisage.readthedocs.io'>Manual</a>\n ║ \n 🖼 <a href='https://termvisage.readthedocs.io/en/latest/gallery.html'>Gallery</a>\n</p>\n\n<p>\n <a href='https://pypi.org/project/termvisage/'>\n <img src='https://img.shields.io/pypi/v/termvisage.svg'/>\n </a>\n <img src=\"https://static.pepy.tech/badge/termvisage\"/>\n <a href='https://pypi.org/project/termvisage/'>\n <img src='https://img.shields.io/pypi/pyversions/termvisage.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://termvisage.readthedocs.io/en/latest/?badge=latest'>\n <img src='https://readthedocs.org/projects/termvisage/badge/?version=latest' alt='Documentation Status'/>\n </a>\n <img src=\"https://img.shields.io/github/last-commit/AnonymouX47/termvisage\"/>\n <a href=\"https://twitter.com/intent/tweet?text=Browse%20and%20view%20images%20in%20the%20terminal&url=https://github.com/AnonymouX47/termvisage&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](#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## Installation\n\n### Requirements\n- Operating System: Unix / Linux / Mac OS X / Windows (limited support, see the [FAQs](https://termvisage.readthedocs.io/en/latest/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 the [library][term-image]'s planned features).\n\n### Steps\nThe latest version can be installed from [PyPI](https://pypi.org/project/termvisage) using [`pipx`](https://pypa.github.io/pipx/) with:\n\n```shell\npipx install termvisage\n```\n\nand upgraded with:\n\n```shell\npipx upgrade termvisage\n```\n\n**NOTE:** [`pip`](https://pip.pypa.io/en/stable/) can also be used but `pipx` is recommended.\n\n\n## Features\n\n- Almost everything the [term-image] library supports\n- Display individual images\n- Browse multiple images and directories (recursively)\n- Adjustable image grids\n- Context-based controls\n- Customizable controls and configuration options\n- Smooth and performant experience\n- Shell completion for command-line arguments\n- and more... \ud83d\ude01\n\n\n## Demo\n\n\n\n### Multiple Render Styles\n| block | iterm2 | kitty |\n|:-----:|:------:|:-----:|\n|  |  |  |\n\n### High-Resolution Images\n|  |  |\n|:---:|:---:|\n\n### Video Demo\n[Demo Video](https://user-images.githubusercontent.com/61663146/235648854-dcccd260-c463-4692-bd01-f51c099613cf.mp4)\n\n### Gallery\nCheck out the [Gallery](https://termvisage.readthedocs.io/en/latest/gallery.html) for more.\n\n\n## Quick Start\n\nWith a file path:\n```shell\ntermvisage path/to/image.png\n```\n\nWith a URL:\n```shell\ntermvisage https://www.example.com/image.png\n```\n\nWith a directory, recursively (not currently supported on Windows):\n```shell\ntermvisage -r path/to/dir/\n```\n\nIf a single source is given and it's animated (GIF, APNG, Animated WebP), the animation is infinitely looped by **default** and can be stopped with `Ctrl-C` (`SIGINT`).\n\nBy **default**, if multiple sources or at least one directory source is given, the TUI (Terminal User Interface) is launched to navigate through the images and/or directories.\n\n\n## Usage\n\n### CLI (Command-Line Interface)\nRun ``termvisage --help`` to see the basic help message or ``termvisage --long-help`` for the full help message.\n\nSee the [CLI manual](https://termvisage.readthedocs.io/en/latest/cli.html).\n\n### TUI (Terminal User Interface)\nThe controls are **context-based** and always displayed at the bottom of the screen.\nPressing the `F1` key (in most contexts) brings up a **help** menu describing the available controls (called *actions*) in that context.\n\nThe TUI can be configured using a config file. See the [Configuration](https://termvisage.readthedocs.io/en/latest/config.html) section of the docs.\n\n[Here](https://github.com/AnonymouX47/termvisage/blob/main/vim_style-termvisage.json) is a config file with Vim-style key-bindings (majorly navigation).\n\nSee the [TUI manual](https://termvisage.readthedocs.io/en/latest/tui.html).\n\n\n## Contribution\n\nIf you've found any bug or want to suggest a new feature, please open a new [issue](https://github.com/AnonymouX47/termvisage/issues) with proper description, after browsing/searching through the existing issues and making sure you won't create a duplicate.\n\nFor code contributions, please read through the [guidelines](https://github.com/AnonymouX47/termvisage/blob/main/CONTRIBUTING.md).\n\nAlso, check out the [Planned Features](#planned-features) section below.\nIf you wish to work on any of the listed tasks, please click on the linked issue or go through the [issues](https://github.com/AnonymouX47/termvisage/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.\n\nHint: You can filter issues by *label* or simply *search* using the task's name or description.\n\nFor anything other than the above (such as questions or anything that would fit under the term \"discussion\"), please open a new [discussion](https://github.com/AnonymouX47/termvisage/discussions) instead.\n\nThanks! \ud83d\udc93\n\n\n## Planned Features\n\nSee [here](https://termvisage.readthedocs.io/en/latest/planned.html).\n\n## Known Issues\n\nSee [here](https://termvisage.readthedocs.io/en/latest/issues.html).\n\n## FAQs\n\nSee the [FAQs](https://termvisage.readthedocs.io/en/latest/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- [term-image] by [@AnonymouX47](https://github.com/AnonymouX47)\n- [Pillow](https://python-pillow.org) by [Fredrik Lundh, Jeffrey A. Clark (Alex) and contributors](https://github.com/python-pillow/Pillow/graphs/contributors)\n- [Urwid](https://urwid.org) by [Ian Ward et al](https://github.com/urwid/urwid/graphs/contributors)\n- [argcomplete](https://github.com/kislyuk/argcomplete) by [Andrey Kislyuk](https://github.com/kislyuk)\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\nThanks to [@digitallyserviced](https://github.com/digitallyserviced) for the project name and logo concept.\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[term-image]: https://github.com/AnonymouX47/term-image\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Display and browse images in the terminal",
"version": "0.1.0",
"project_urls": {
"Changelog": "https://github.com/AnonymouX47/termvisage/blob/main/CHANGELOG.md",
"Documentation": "https://termvisage.readthedocs.io/",
"Funding": "https://github.com/AnonymouX47/termvisage#donate",
"Homepage": "https://github.com/AnonymouX47/termvisage",
"Source": "https://github.com/AnonymouX47/termvisage",
"Tracker": "https://github.com/AnonymouX47/termvisage/issues"
},
"split_keywords": [
"image",
"terminal",
"viewer",
"pil",
"pillow",
"console",
"xterm",
"cli",
"tui",
"ansi",
"ascii-art",
"kitty",
"iterm2",
"sixel",
"graphics"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2880a7cc667b7e15e05bffbc73e37e0eca90e6812c01c502e783c5b18eaf02a3",
"md5": "ff97081a5b74f4fc0b31f5622410db7f",
"sha256": "757e5ad689d89be5dd434c069ea206c97e0fe60e006d21505a85015bddc25897"
},
"downloads": -1,
"filename": "termvisage-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ff97081a5b74f4fc0b31f5622410db7f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 62887,
"upload_time": "2023-06-03T00:13:58",
"upload_time_iso_8601": "2023-06-03T00:13:58.272570Z",
"url": "https://files.pythonhosted.org/packages/28/80/a7cc667b7e15e05bffbc73e37e0eca90e6812c01c502e783c5b18eaf02a3/termvisage-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7a6071ddd8201f14e3160b1b3778114c00f129875af69f335e91877ea07795e3",
"md5": "28e90f1c1d3e1ca4d55dec3defac254c",
"sha256": "4149dfd16d98a6fc38dfb5515fe9553fabf41fb1493ea41cad52b982595b5a9e"
},
"downloads": -1,
"filename": "termvisage-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "28e90f1c1d3e1ca4d55dec3defac254c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 59676,
"upload_time": "2023-06-03T00:14:00",
"upload_time_iso_8601": "2023-06-03T00:14:00.925212Z",
"url": "https://files.pythonhosted.org/packages/7a/60/71ddd8201f14e3160b1b3778114c00f129875af69f335e91877ea07795e3/termvisage-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-03 00:14:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AnonymouX47",
"github_project": "termvisage",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "termvisage"
}
JSON
