https://github.com/adamviola/textual-imageview

A simple terminal-based image viewer.
https://github.com/adamviola/textual-imageview

Last synced: 3 months ago
JSON representation

A simple terminal-based image viewer.

• Host: GitHub
• URL: https://github.com/adamviola/textual-imageview
• Owner: adamviola
• License: mit
• Created: 2023-01-02T06:31:53.000Z (about 2 years ago)
• Default Branch: main
• Last Pushed: 2023-01-08T05:18:54.000Z (about 2 years ago)
• Last Synced: 2024-05-14T01:20:43.822Z (9 months ago)
• Language: Python
• Size: 17.6 KB
• Stars: 75
• Watchers: 3
• Forks: 3
• Open Issues: 3
• Metadata Files:
  • Readme: README.md
  • License: LICENSE.txt

Awesome Lists containing this project

• awesome-textualize-projects - Imageview - A simple terminal-based image viewer. (Community / Third Party Applications)

README

        
# textual-imageview

[![PyPI - Version](https://img.shields.io/pypi/v/textual-imageview.svg)](https://pypi.org/project/textual-imageview)

[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/textual-imageview.svg)](https://pypi.org/project/textual-imageview)

![cat](https://user-images.githubusercontent.com/43352940/210931390-ad1f47fc-2340-435e-8851-234b5fa96d0f.gif)

`textual-imageview` is a both a CLI tool and [Textual](https://github.com/textualize/textual/) widget and for viewing images in the

terminal.

## Usage

Use the `vimg` CLI command to quickly view an image in the terminal.

```console

vimg 

```

Click and drag (or press W/S/A/D) to move around the image, and scroll (or press -/+) to zoom in/out of the image.

`vimg` is built on `ImageView`, a [Rich](https://github.com/textualize/rich/) renderable that renders images with padding/zoom, and `ImageViewer`, a [Textual](https://github.com/textualize/textual/) widget that adds mouse interactivity to `ImageView`. Add `textual-imageview` as a dependency to use them in your Textual app!

At the highest zoom level, each character corresponds to two image pixels. I've found that `vimg` works best with a GPU-accelerated terminal like [Alacritty](https://github.com/alacritty/alacritty).

## Installation

```console

pip install textual-imageview

```

## FAQ

**`vimg` works great locally, but colors aren't displaying correctly when using `vimg` over SSH. Why?**

Rich [determines terminal color support](https://github.com/Textualize/rich/blob/7601290c3a2f574fa29763ed5a615767494f5013/rich/console.py#L796) by checking if the `COLORTERM` environment variable is set to `truecolor` or `24bit`.

```console

echo $COLORTERM

```

If you know your terminal emulator supports truecolor - i.e., `vimg` works great locally - try setting the environment variable manually:

```console

export COLORTERM=truecolor

```

## License

`textual-imageview` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.