`imgcat`
========
[](https://pypi.python.org/pypi/imgcat)
[](LICENSE)
The imgcat CLI, written in Python (and Python API, too).
<img src="https://raw.githubusercontent.com/wookayin/python-imgcat/master/screenshot.png" width="640" height="520" />
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)
Raw data
{
"_id": null,
"home_page": "https://github.com/wookayin/python-imgcat",
"name": "imgcat",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "imgcat iterm2 matplotlib",
"author": "Jongwook Choi",
"author_email": "wookayin@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/9c/fa/c09733cb5f8a793d2429d06c510a9eaa605fc14381de6701c2df6be69502/imgcat-0.6.0.tar.gz",
"platform": null,
"description": "`imgcat`\n========\n\n[](https://pypi.python.org/pypi/imgcat)\n[](LICENSE)\n\nThe imgcat CLI, written in Python (and Python API, too).\n\n<img src=\"https://raw.githubusercontent.com/wookayin/python-imgcat/master/screenshot.png\" width=\"640\" height=\"520\" />\n\nIt 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).\n\n\nInstallation and Usage\n----------------------\n\n```\npip install imgcat\n```\n\nCommand-line interface (similar to [iTerm2's imgcat][iTerm2_imgcat]):\n\n```bash\n$ imgcat local_image.png\n$ imgcat a.png b.png c.png\n$ cat from_stdin.gif | imgcat\n\n# height is 10 lines\n$ imgcat a.png --height 10\n```\n\nPython API:\n\n```python\n>>> from imgcat import imgcat\n\n# from the content of image (e.g. buffer in python3, str in python2)\n>>> imgcat(open(\"./local_image.png\"))\n\n# or numpy arrays!\n>>> im = skimage.data.chelsea() # [300, 451, 3] ndarray, dtype=uint8\n>>> imgcat(im, height=7)\n\n# matplotlib, PIL.Image, etc.\n>>> imgcat(Image.fromarray(im))\n\n>>> import matplotlib.pyplot as plt\n>>> fig, ax = plt.subplots(); ax.plot([1, 2, 3, 4, 5])\n>>> imgcat(fig)\n```\n\nMatplotlib Backend: `module://imgcat`\n\n```python\nMPLBACKEND=\"module://imgcat\" python draw_matplotlib.py\n```\n\n```python\n>>> import matplotlib\n>>> matplotlib.use(\"module://imgcat\")\n\n>>> import matplotlib.pyplot as plt\n>>> fig, ax = plt.subplots()\n>>> ax.text(0.5, 0.5, \"Hello World!\");\n>>> fig.show()\n# an image shall be displayed on your terminal!\n```\n\nIPython magic (works both in terminal and notebook)\n\n```\n%load_ext imgcat\n%imgcat skimage.data.chelsea()\n```\n\nNotes\n-----\n\n* [tmux 2.5+ cannot display big images][tmux_gh1502]. Use tmux <= 2.4 or run outside tmux.\n* In [tmux 3.3a or higher][tmux_33a], it is required to have `set-option -g allow-passthrough on` in `~/.tmux.conf`.\n* TODO: General platform/emulator support (introduce multiple backends) including Sixel\n\n\nRelated Projects\n----------------\n\n* Original implementation: [imgcat][iTerm2_imgcat] from iTerm2 (limited tmux support)\n * 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)\n* Node.js: [term-img](https://github.com/sindresorhus/term-img) (no tmux support)\n* Go: [iterm2-imagetools](https://github.com/olivere/iterm2-imagetools) (no tmux support)\n\n\n[iTerm2_imgcat]: https://github.com/gnachman/iTerm2/blob/master/tests/imgcat\n[tmux_gh1502]: https://github.com/tmux/tmux/issues/1502\n[tmux_33a]: https://github.com/tmux/tmux/blob/3.3a/CHANGES#L30\n[iterm_g3898]: https://gitlab.com/gnachman/iterm2/issues/3898\n\n\nLicense\n-------\n\n[MIT License](LICENSE)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "imgcat as Python API and CLI",
"version": "0.6.0",
"project_urls": {
"Homepage": "https://github.com/wookayin/python-imgcat"
},
"split_keywords": [
"imgcat",
"iterm2",
"matplotlib"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9cfac09733cb5f8a793d2429d06c510a9eaa605fc14381de6701c2df6be69502",
"md5": "b5552a75357f7fd4eddb16b066a11c1e",
"sha256": "b3547b68adb3f1f9b611390e804c94ebd464a215858543cbf97df86fbcd7935c"
},
"downloads": -1,
"filename": "imgcat-0.6.0.tar.gz",
"has_sig": false,
"md5_digest": "b5552a75357f7fd4eddb16b066a11c1e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 12681,
"upload_time": "2024-11-21T13:36:26",
"upload_time_iso_8601": "2024-11-21T13:36:26.072098Z",
"url": "https://files.pythonhosted.org/packages/9c/fa/c09733cb5f8a793d2429d06c510a9eaa605fc14381de6701c2df6be69502/imgcat-0.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-21 13:36:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wookayin",
"github_project": "python-imgcat",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"lcname": "imgcat"
}
JSON
