Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/wookayin/python-imgcat
🖼 imgcat in Python (for iTerm2)
https://github.com/wookayin/python-imgcat
imgcat iterm2 python
Last synced: 12 days ago
JSON representation
🖼 imgcat in Python (for iTerm2)
- Host: GitHub
- URL: https://github.com/wookayin/python-imgcat
- Owner: wookayin
- License: mit
- Created: 2018-10-14T00:55:17.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2024-07-31T15:42:25.000Z (3 months ago)
- Last Synced: 2024-10-12T13:45:19.851Z (about 1 month ago)
- Topics: imgcat, iterm2, python
- Language: Python
- Homepage:
- Size: 620 KB
- Stars: 247
- Watchers: 10
- Forks: 20
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
`imgcat`
========
[](https://pypi.python.org/pypi/imgcat)
[](LICENSE)
The imgcat CLI, written in Python (and Python API, too).
It works with [iTerm2](https://www.iterm2.com/documentation-images.html) and [WezTerm](https://wezfurlong.org/wezterm/imgcat.html), and [even inside tmux][iterm_g3898] (for tmux, see [Notes](#notes) below).
Installation and Usage
----------------------
```
pip install imgcat
```
Command-line interface (similar to [iTerm2's imgcat][iTerm2_imgcat]):
```bash
$ imgcat local_image.png
$ imgcat a.png b.png c.png
$ cat from_stdin.gif | imgcat
# height is 10 lines
$ imgcat a.png --height 10
```
Python API:
```python
>>> from imgcat import imgcat
# from the content of image (e.g. buffer in python3, str in python2)
>>> imgcat(open("./local_image.png"))
# or numpy arrays!
>>> im = skimage.data.chelsea() # [300, 451, 3] ndarray, dtype=uint8
>>> imgcat(im, height=7)
# matplotlib, PIL.Image, etc.
>>> imgcat(Image.fromarray(im))
>>> import matplotlib.pyplot as plt
>>> fig, ax = plt.subplots(); ax.plot([1, 2, 3, 4, 5])
>>> imgcat(fig)
```
Matplotlib Backend: `module://imgcat`
```python
MPLBACKEND="module://imgcat" python draw_matplotlib.py
```
```python
>>> import matplotlib
>>> matplotlib.use("module://imgcat")
>>> import matplotlib.pyplot as plt
>>> fig, ax = plt.subplots()
>>> ax.text(0.5, 0.5, "Hello World!");
>>> fig.show()
# an image shall be displayed on your terminal!
```
IPython magic (works both in terminal and notebook)
```
%load_ext imgcat
%imgcat skimage.data.chelsea()
```
Notes
-----
* [tmux 2.5+ cannot display big images][tmux_gh1502]. Use tmux <= 2.4 or run outside tmux.
* In [tmux 3.3a or higher][tmux_33a], it is required to have `set-option -g allow-passthrough on` in `~/.tmux.conf`.
* TODO: General platform/emulator support (introduce multiple backends) including Sixel
Related Projects
----------------
* Original implementation: [imgcat][iTerm2_imgcat] from iTerm2 (limited tmux support)
* There are modified versions with better tmux support by [Eric Dobson](https://gitlab.com/gnachman/iterm2/issues/3898#note_14097715) and by [@krtx](https://gist.github.com/krtx/533d33d6cc49ecbbb8fab0ae871059ec)
* Node.js: [term-img](https://github.com/sindresorhus/term-img) (no tmux support)
* Go: [iterm2-imagetools](https://github.com/olivere/iterm2-imagetools) (no tmux support)
[iTerm2_imgcat]: https://github.com/gnachman/iTerm2/blob/master/tests/imgcat
[tmux_gh1502]: https://github.com/tmux/tmux/issues/1502
[tmux_33a]: https://github.com/tmux/tmux/blob/3.3a/CHANGES#L30
[iterm_g3898]: https://gitlab.com/gnachman/iterm2/issues/3898
License
-------
[MIT License](LICENSE)