{"id":18074369,"url":"https://github.com/srlehn/termimg","last_synced_at":"2025-04-24T03:47:27.121Z","repository":{"id":182159780,"uuid":"668028828","full_name":"srlehn/termimg","owner":"srlehn","description":"draw images in terminals","archived":false,"fork":false,"pushed_at":"2024-10-15T21:10:51.000Z","size":56802,"stargazers_count":68,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-24T03:47:13.122Z","etag":null,"topics":["image","pseudo-terminal","pty","raster-graphics","sixel","sixel-graphics","terminal","terminal-emulator","terminal-graphics","terminal-multiplexer"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/srlehn/termimg@master","language":"Go","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/srlehn.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},"funding":{"github":["srlehn"]}},"created_at":"2023-07-18T21:16:57.000Z","updated_at":"2025-04-17T10:22:12.000Z","dependencies_parsed_at":"2023-10-11T01:58:30.122Z","dependency_job_id":"401ad813-d066-4c6f-bb66-513f7d7b4523","html_url":"https://github.com/srlehn/termimg","commit_stats":null,"previous_names":["srlehn/termimg"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srlehn%2Ftermimg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srlehn%2Ftermimg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srlehn%2Ftermimg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srlehn%2Ftermimg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/srlehn","download_url":"https://codeload.github.com/srlehn/termimg/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250560010,"owners_count":21450168,"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":["image","pseudo-terminal","pty","raster-graphics","sixel","sixel-graphics","terminal","terminal-emulator","terminal-graphics","terminal-multiplexer"],"created_at":"2024-10-31T10:12:24.594Z","updated_at":"2025-04-24T03:47:27.100Z","avatar_url":"https://github.com/srlehn.png","language":"Go","funding_links":["https://github.com/sponsors/srlehn"],"categories":["\u003ca name=\"graphics\"\u003e\u003c/a\u003eGraphics"],"sub_categories":[],"readme":"# TermImg\n\n\u003c!-- this readme is meant to be displayed in an\nHTML-capable markdown pager (github via browser, etc) --\u003e\n\n**termimg** draws images into terminals.\nThis repository includes the **termimg** library and\nthe **timg** cli tool which can be used in shell scripts.\n\n[![PkgGoDev](https://pkg.go.dev/badge/github.com/srlehn/termimg)](https://pkg.go.dev/github.com/srlehn/termimg@master)\n[![Go Report Card](https://goreportcard.com/badge/srlehn/termimg)](https://goreportcard.com/report/srlehn/termimg)\n![Lines of code](https://tokei.rs/b1/github/srlehn/termimg?type=Go\u0026category=code)\n[![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](https://lbesson.mit-license.org/)\n![experimental](https://img.shields.io/badge/status-experimental-orange.svg)\n\nThis module is still **experimental**.\nMost parts need more testing on platforms other than my own (Debian stable, X11).\nThe API of some unfinished packages will change.\nThere are still many small issues to be fixed. Please report them.\n\nImages are being placed by using **cell** not pixel **coordinates**.\n(The origin is the upper left terminal corner just like with image.Image.)\nThe latter doesn't make sense in the context of a terminal.\ntermimg is able to fit images into cell boundaries\nwhile preserving their aspect ratio.\n\ntermimg implements **several drawing methods**:\n\u003cins\u003e\n[sixel](https://en.wikipedia.org/wiki/Sixel),\n[iTerm2](https://iterm2.com/documentation-images.html),\n[kitty](https://sw.kovidgoyal.net/kitty/graphics-protocol/),\n[Terminology](https://git.enlightenment.org/enlightenment/terminology#extended-escapes-for-terminology-only),\n[DomTerm](https://domterm.org/Wire-byte-protocol.html#Miscellaneous-sequences),\n[urxvt](https://manpages.ubuntu.com/manpages/jammy/man1/urxvt-background.1.html#old%20background%20image%20settings),\nX11,\nGDI+,\nblock characters\n\u003c/ins\u003e - by default the most appropriate one will be chosen.\n\ntermimg is highly modular, most parts are exchangeable.\nMultiple term.TTY implementations exist for tty libraries used in common TUI frameworks.\n\nThe root package **\"termimg\"** contains an easy to use high-level API\nwith a lot of default dependencies.\nDirect usage of the core package **\"/term\"** is recommended\nfor more control and nearly no external dependencies.\nThe **\"/drawers/sane\"** drawer collection will only use actual drawing methods,\n**\"/drawers/all\"** will try to produce an image by any means.\n\n\u003cdetails open\u003e\u003csummary\u003e\u003ch2\u003etimg - tool for the CLI\u003c/h2\u003e\u003c/summary\u003e\n\n\u003cblockquote\u003e\u003cdetails open\u003e\n\u003csummary\u003edemo gifs\u003c/summary\u003e\n\n![demo_pic_ls.gif](https://raw.githubusercontent.com/srlehn/termimg/master/_demos/demo_pic_ls.gif)\n![demo_vid.gif](https://raw.githubusercontent.com/srlehn/termimg/master/_demos/demo_vid.gif)\n\u003c/details\u003e\n\ninstallation:\n\n```sh\nGOEXPERIMENT=rangefunc go install github.com/srlehn/termimg/cmd/timg@master\n```\n\nusage:\n\n```text\n$ timg\ntimg display terminal graphics\n\nUsage:\n  timg [flags]\n  timg [command]\n\nAvailable Commands:\n  completion  Generate the autocompletion script for the specified shell\n  help        Help about any command\n  list        list images\n  properties  list terminal properties\n  query       query terminal\n  resolution  print terminal resolution\n  scale       fit pixel area into a cell area while maintaining scale\n  show        display image\n\nFlags:\n  -d, --debug             debug errors\n  -h, --help              help for timg\n  -l, --log-file string   log file\n  -s, --silent            silence errors\n\nUse \"timg [command] --help\" for more information about a command.\n```\n\nThe `list` command displays thumbnails of previewable files\nfor a given directory similar to \"lsix\":\n\n```sh\ntimg list ~/Pictures\n```\n\nThe `show` command draws the image in the current terminal:\n\n```sh\ntimg show -p 10,10,15x15 picture.png\n```\n\nCell coordinates are optional for the show command,\nthey are passed in this format: `\u003cx\u003e,\u003cy\u003e,\u003cw\u003ex\u003ch\u003e`\nwhere x is the column, y the row, w the width and h the height.\n\nIf an error occurs the `--debug/-d` flag shows where in the code it happens.\n\nThe `runterm` command starts the terminal specified with the `-t` flag.\nIf no drawer is enforced by the optional `-d` flag, the best fitting one is used.\nThis command is meant for testing purposes.\n\n```sh\ntimg -d runterm -t mlterm -d sixel -p 10,10,15x15 picture.png\n```\n\n\u003cblockquote\u003e\u003c/details\u003e\n\n\u003cdetails open\u003e\u003csummary\u003e\u003ch2\u003eLibrary Usage\u003c/h2\u003e\u003c/summary\u003e\n\n\u003cblockquote\u003e\u003cdetails\u003e\u003csummary\u003e\u003ch3\u003eOne-Off Image Draw\u003c/h3\u003e\u003c/summary\u003e\n\n```go\nimport (\n    _ \"github.com/srlehn/termimg/drawers/all\"\n    _ \"github.com/srlehn/termimg/terminals\"\n)\n\nfunc main(){\n    defer termimg.CleanUp()\n    _ = termimg.DrawFile(`picture.png`, image.Rect(10,10,40,25))\n}\n```\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails open\u003e\u003csummary\u003e\u003ch3\u003ewith NewImage…()\u003c/h3\u003e\u003c/summary\u003e\n\nFor repeated image drawing create a term.Image via the NewImage…() functions.\nThis allows caching of the encoded image.\n\n```go\nimport (\n    _ \"github.com/srlehn/termimg/drawers/all\"\n    _ \"github.com/srlehn/termimg/terminals\"\n)\n\nfunc main(){\n    tm, _ := termimg.Terminal()\n    defer tm.Close()\n    timg := termimg.NewImageFileName(`picture.png`)\n    _ = tm.Draw(timg, image.Rect(10,10,40,25))\n}\n```\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\u003csummary\u003e\u003ch3\u003eAdvanced\u003c/h3\u003e\u003c/summary\u003e\n\n```go\nimport (\n    _ \"github.com/srlehn/termimg/drawers/sane\"\n    _ \"github.com/srlehn/termimg/terminals\"\n)\n\nfunc main(){\n    wm.SetImpl(wmimpl.Impl())\n    opts := []term.Option{\n        term.SetLogFile(`termimg.log`, true),\n        term.SetPTYName(`dev/pts/2`),\n        term.SetTTYProvider(gotty.New, false),\n        term.SetQuerier(qdefault.NewQuerier(), true),\n        term.SetWindowProvider(wm.SetImpl(wmImplementation), true),\n        term.SetResizer(\u0026rdefault.Resizer{}),\n    }\n    tm, err := term.NewTerminal(opts...)\n    if err != nil {\n        log.Fatal(err)\n    }\n    defer tm.Close()\n    var img image.Image // TODO load image\n    timg := termimg.NewImage(img)\n    if err := tm.Draw(timg, image.Rect(10,10,40,25)); err != nil {\n        log.Fatal(err)\n    }\n}\n```\n\nThe default options are packed together in `termimg.DefaultConfig`.\n\u003c/details\u003e\n\n\u003c/blockquote\u003e\u003c/details\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrlehn%2Ftermimg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsrlehn%2Ftermimg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrlehn%2Ftermimg/lists"}