{"id":16489798,"url":"https://github.com/wookayin/python-imgcat","last_synced_at":"2025-04-04T07:08:12.713Z","repository":{"id":39617013,"uuid":"152927177","full_name":"wookayin/python-imgcat","owner":"wookayin","description":"🖼 imgcat in Python (for iTerm2)","archived":false,"fork":false,"pushed_at":"2024-07-31T15:42:25.000Z","size":635,"stargazers_count":247,"open_issues_count":10,"forks_count":20,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-10-12T13:45:19.851Z","etag":null,"topics":["imgcat","iterm2","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wookayin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-14T00:55:17.000Z","updated_at":"2024-10-10T05:01:30.000Z","dependencies_parsed_at":"2024-06-18T18:20:14.860Z","dependency_job_id":"285e3e63-6272-4214-aaf1-ede6cf671d4b","html_url":"https://github.com/wookayin/python-imgcat","commit_stats":{"total_commits":46,"total_committers":2,"mean_commits":23.0,"dds":"0.021739130434782594","last_synced_commit":"d77d57fd289dac1d486ee8ee22169844f62046bd"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wookayin%2Fpython-imgcat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wookayin%2Fpython-imgcat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wookayin%2Fpython-imgcat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wookayin%2Fpython-imgcat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wookayin","download_url":"https://codeload.github.com/wookayin/python-imgcat/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247135144,"owners_count":20889421,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["imgcat","iterm2","python"],"created_at":"2024-10-11T13:45:27.924Z","updated_at":"2025-04-04T07:08:12.686Z","avatar_url":"https://github.com/wookayin.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"`imgcat`\n========\n\n[![pypi](https://img.shields.io/pypi/v/imgcat.svg?maxAge=86400)](https://pypi.python.org/pypi/imgcat)\n[![license](https://img.shields.io/github/license/wookayin/python-imgcat.svg?maxAge=86400)](LICENSE)\n\nThe imgcat CLI, written in Python (and Python API, too).\n\n\u003cimg src=\"https://raw.githubusercontent.com/wookayin/python-imgcat/master/screenshot.png\" width=\"640\" height=\"520\" /\u003e\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\u003e\u003e\u003e from imgcat import imgcat\n\n# from the content of image (e.g. buffer in python3, str in python2)\n\u003e\u003e\u003e imgcat(open(\"./local_image.png\"))\n\n# or numpy arrays!\n\u003e\u003e\u003e im = skimage.data.chelsea()   # [300, 451, 3] ndarray, dtype=uint8\n\u003e\u003e\u003e imgcat(im, height=7)\n\n# matplotlib, PIL.Image, etc.\n\u003e\u003e\u003e imgcat(Image.fromarray(im))\n\n\u003e\u003e\u003e import matplotlib.pyplot as plt\n\u003e\u003e\u003e fig, ax = plt.subplots(); ax.plot([1, 2, 3, 4, 5])\n\u003e\u003e\u003e imgcat(fig)\n```\n\nMatplotlib Backend: `module://imgcat`\n\n```python\nMPLBACKEND=\"module://imgcat\" python draw_matplotlib.py\n```\n\n```python\n\u003e\u003e\u003e import matplotlib\n\u003e\u003e\u003e matplotlib.use(\"module://imgcat\")\n\n\u003e\u003e\u003e import matplotlib.pyplot as plt\n\u003e\u003e\u003e fig, ax = plt.subplots()\n\u003e\u003e\u003e ax.text(0.5, 0.5, \"Hello World!\");\n\u003e\u003e\u003e 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 \u003c= 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwookayin%2Fpython-imgcat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwookayin%2Fpython-imgcat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwookayin%2Fpython-imgcat/lists"}