{"id":21401955,"url":"https://github.com/bigjk/imeji","last_synced_at":"2026-03-27T03:09:52.712Z","repository":{"id":161759888,"uuid":"636125387","full_name":"BigJk/imeji","owner":"BigJk","description":"Images for your terminal.","archived":false,"fork":false,"pushed_at":"2024-01-09T20:04:54.000Z","size":11845,"stargazers_count":18,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-05-29T05:46:50.743Z","etag":null,"topics":["cli","console","go","golang","terminal"],"latest_commit_sha":null,"homepage":"","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/BigJk.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}},"created_at":"2023-05-04T07:18:19.000Z","updated_at":"2024-04-08T01:59:25.000Z","dependencies_parsed_at":"2024-01-09T21:57:01.165Z","dependency_job_id":null,"html_url":"https://github.com/BigJk/imeji","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BigJk%2Fimeji","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BigJk%2Fimeji/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BigJk%2Fimeji/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BigJk%2Fimeji/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BigJk","download_url":"https://codeload.github.com/BigJk/imeji/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225921289,"owners_count":17545661,"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":["cli","console","go","golang","terminal"],"created_at":"2024-11-22T15:33:53.684Z","updated_at":"2025-10-30T23:41:29.725Z","avatar_url":"https://github.com/BigJk.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# imeji\n\nイメジ ー Images for the terminal\n\n![demo](./github/screenshot.png)\n\n[![GoReportCard](https://goreportcard.com/badge/github.com/BigJk/imeji)](https://goreportcard.com/report/github.com/BigJk/imeji) [![GoDoc](https://godoc.org/github.com/golang/gddo?status.svg)](https://pkg.go.dev/github.com/BigJk/imeji)\n\nimeji is a lightweight alternative to the awesome [chafa](https://hpjansson.org/chafa/). It is written in go and can be easily embedded into tools. imeji takes a image as input and creates a sequence of characters and ansi color sequences resulting in a terminal printable images.\n\n### Why not use chafa?\n\nIf you can install chafa it should be preferred, as it is more advanced, faster and just awesome! But if you want to include terminal image output in your go application and don't want to ship chafa as external dependency imeji might be worth a try.\n\n# CLI\n\n```\nイメジ :: Images for the terminal ー by BigJk\n _                 _ _\n(_)_ __ ___   ___ (_|_)\n| | '_ ` _ \\ / _ \\| | |\n| | | | | | |  __/| | |\n|_|_| |_| |_|\\___|/ |_|\n                |__/\n_________________________________________\n\n  -font-scale float\n    \tvertical font scaling value (default: 0.8)\n  -force-full-color\n    \tforces full color output\n  -help\n    \tprint help\n  -input string\n    \tinput image path\n  -max-width int\n    \tsets the max width of the output (in cells) and keeps the aspect ratio\n  -size string\n    \tsize in terminal cells (e.g. 100x20)\n  -symbols string\n    \twhich symbole sets to use (blocks, blocks_simple, blocks_adv, ascii, misc) (default \"blocks\")\n```\n\n### Install ``imeji`` command\n\n```\ngo install github.com/BigJk/imeji/cmd/imeji@latest\n```\n\n# Go Library\n\n```\ngo get github.com/BigJk/imeji\n```\n\n### Example\n\n```go\n// Print directly to stdout and detect terminal capabilities:\nimeji.File(os.Stdout, \"./image.png\", imeji.WithMaxWidth(100))\n\n// Convert to string with full color support:\ntext, _ := imeji.FileString(\"./image.png\", imeji.WithTrueColor())\nfmt.Println(text)\n```\n\n# Technique\n\nI didn't find a good written reference on the technique used by Chafa and other tools so here is a basic overview. Its important to know that in the terminal we are limited to a single foreground and background color per character. That means for each cell in the terminal we need to find the best character and foreground, background pair with the least \"error\" (difference) to the real picture.\n\n## Pattern\n\nThe basic idea is that you can map a single character in terminal to 8x8 pixels of a real image. For each character that wants to be used in a terminal picture the pattern needs to be created. A pattern can easily be defined by an 8 line string. The pattern defines which pixels are set to the foreground color and which to the background color.\n\nSee ``/charmaps/blocks.go`` and you will quickly get the idea.\n\n**Examples**: \n\n- Char: █ (Full Block -\u003e All pixel set)\n\n```\nXXXXXXXX\nXXXXXXXX\nXXXXXXXX\nXXXXXXXX\nXXXXXXXX\nXXXXXXXX\nXXXXXXXX\nXXXXXXXX\n```\n\n- Char: !\n\n```\n________\n___X____\n___X____\n___X____\n___X____\n________\n___X____\n________\n```\n\n## Procedure\n\nNow that we know how to define the pattern for a character we can convert a image to terminal printable characters.\n\n1. Chunk the image into 8x8 pixel chunks\n2. For each pixel chunk:\n   1. Randomly select a few (foreground, background) pairs from the pixels in the chunk\n   2. For all the pairs test all characters and calculate the error to the real pixels\n   3. Return the pair and character with the least error\n3. For each chunk print the selected character with the chosen foreground and background\n\n# Further Work\n\n- [ ] Better handling of alpha channel\n- [ ] Use assembler with SIMD instructions to improve pixel to pattern diffing performance","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbigjk%2Fimeji","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbigjk%2Fimeji","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbigjk%2Fimeji/lists"}