Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/AnonymouX47/termvisage
Browse and view images in the terminal (mostly a front-end to https://github.com/AnonymouX47/term-image)
https://github.com/AnonymouX47/termvisage
cli curses image image-viewer images python term-image terminal tui urwid viewer
Last synced: 11 days ago
JSON representation
Browse and view images in the terminal (mostly a front-end to https://github.com/AnonymouX47/term-image)
- Host: GitHub
- URL: https://github.com/AnonymouX47/termvisage
- Owner: AnonymouX47
- License: mit
- Created: 2023-03-28T13:06:01.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-05-28T22:11:57.000Z (6 months ago)
- Last Synced: 2024-05-29T13:10:25.556Z (6 months ago)
- Topics: cli, curses, image, image-viewer, images, python, term-image, terminal, tui, urwid, viewer
- Language: Python
- Homepage: http://termvisage.readthedocs.io
- Size: 677 KB
- Stars: 32
- Watchers: 3
- Forks: 1
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
## 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.8
- 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)
- Unicode and direct-color (truecolor) 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.
See the [installation docs](https://termvisage.readthedocs.io/en/stable/installation.html) for info about optional features and more.
## Features
- Almost everything the [term-image] library supports
- Display individual images
- Browse multiple images and directories (recursively)
- Efficient and configurable thumbnailing
- 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
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
