{"id":13800531,"url":"https://github.com/mjrlowe/terminal_images","last_synced_at":"2025-04-22T20:14:02.800Z","repository":{"id":40761127,"uuid":"307126625","full_name":"mjrlowe/terminal_images","owner":"mjrlowe","description":"A Deno module and CLI tool for printing images to the console. 🖼️","archived":false,"fork":false,"pushed_at":"2023-04-03T19:42:19.000Z","size":583,"stargazers_count":53,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-22T20:13:55.227Z","etag":null,"topics":["cli","deno","deno-module","image","terminal","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/mjrlowe.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":"2020-10-25T15:15:12.000Z","updated_at":"2025-04-16T22:27:54.000Z","dependencies_parsed_at":"2024-01-05T20:59:57.644Z","dependency_job_id":"6303233f-108d-48bf-b4d2-f4ea8a2b2cad","html_url":"https://github.com/mjrlowe/terminal_images","commit_stats":{"total_commits":99,"total_committers":1,"mean_commits":99.0,"dds":0.0,"last_synced_commit":"c751e15310809fdc5195a6c081f39151d4d7ee0a"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjrlowe%2Fterminal_images","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjrlowe%2Fterminal_images/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjrlowe%2Fterminal_images/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjrlowe%2Fterminal_images/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mjrlowe","download_url":"https://codeload.github.com/mjrlowe/terminal_images/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250316058,"owners_count":21410476,"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","deno","deno-module","image","terminal","typescript"],"created_at":"2024-08-04T00:01:13.461Z","updated_at":"2025-04-22T20:14:02.778Z","avatar_url":"https://github.com/mjrlowe.png","language":"TypeScript","funding_links":[],"categories":["Modules"],"sub_categories":["CLI utils"],"readme":"# terminal_images\n\n**terminal_images** is a Deno module and CLI tool, written in TypeScript, for\ndisplaying images in the terminal.\n\nIt supports PNGs, JPGs, GIFs and pixel arrays, and has support for animated GIFs\nand transparent images.\n\nTo install the CLI tool, run the following from the command line:\n\n```shell\ndeno install --allow-read --allow-net -f -n terminal_images https://deno.land/x/terminal_images@3.1.0/cli.ts\n```\n\n_Alternatively, terminal\\_images can be installed from nest.land at the URL_\n`https://x.nest.land/terminal_images@3.1.0/cli.ts`.\n\nThen run\n\n```shell\nterminal_images https://deno.land/images/artwork/hashrock_simple.png\n```\n\n...and you should see something like this:\n\n![basic terminal Deno image](./examples/basic_demo.png)\n\n_Note that the size might be different, as by default it adapts to the size of\nyour terminal._\n\nYou can also use the module, which exports two async functions:\n`getImageStrings` and `printImage`, which both take in an object with the same\nproperties.\n\nHere is an example of how you can use it:\n\n```ts\nimport { printImage } from \"https://deno.land/x/terminal_images@3.1.0/mod.ts\";\n\nprintImage({\n  // replace this with the URL or local file path of the image you want to print out\n  path: \"https://deno.land/images/artwork/deno_city.jpeg\",\n\n  // by default the size of the image is set to fit in the terminal,\n  // but you can override it with the width property\n  width: 56,\n});\n```\n\nThis should output something like this:\n\n![pixelated terminal image](./examples/color_terminal_output_example.png)\n\n## API\n\n| Property                | Type                                              | Description                                                                                                                                                                                                                                                                           | Default Value                                                             | CLI Flag                                   |\n| ----------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------ |\n| `path`                  | string                                            | The path or URL of the input image.                                                                                                                                                                                                                                                   | No default                                                                | `--file` or `-f` or the first CLI argument |\n| `rawFile`               | Uint8Array                                        | The raw data of the input image. (You can use this instead of `path`)                                                                                                                                                                                                                 | No default                                                                | [No CLI flag]                              |\n| `rawPixels`             | {data: Uint8Array; width: number; height: number} | The rgb(a) data (as well as the height and width) of the input image. (You can use this instead of `path` or `rawFile`)                                                                                                                                                               | No default                                                                | [No CLI flag]                              |\n| `color`                 | boolean                                           | Whether the output should be in color.                                                                                                                                                                                                                                                | `true`                                                                    | `--no-color` or `-n` to turn off color     |\n| `characterMap`          | string \\| string[]                                | See the section on character maps for more information.                                                                                                                                                                                                                               | By default a character map isn't used, and high-res mode is used instead. | `--character-map` or `-m`                  |\n| `inverted`              | boolean                                           | Whether the character map should be mapped from light to dark instead of dark to light. Normally you will want to set this to true if your terminal is in a dark theme.                                                                                                               | `false`                                                                   | `--inverted` or `-i`                       |\n| `width`                 | number                                            | The number of characters wide the image should be.                                                                                                                                                                                                                                    | The maximum value where all of the image is visible at once               | `--width` or `-w`                          |\n| `animationLoops`        | number                                            | The number of times the animation loops, if the image is animated.                                                                                                                                                                                                                    | 1                                                                         | `--animation-loops` or `-l`                |\n| `transparencyThreshold` | number                                            | The alpha threshold for considering a pixel transparent or opaque. Set to 0 to ignore transparency and 255 to set anything with even a little transparency to be completely transparent. Note that the terminal can only display completely transparent and completely opaque colors. | 1                                                                         | `--transparency-threshold` or `-t`         |\n\n_Because the size of the image automatically adapts to the size of your console,\nthe image produced will have a higher resolution (unless you have manually set\n`width`) if the font size is smaller and the terminal window is larger, as more\ncan fit on the screen._\n\n## Character map?\n\nThe \"character map\" is the characters that are used to display the image. _If no\ncharacter map is specified, it will default to high(er) resolution mode--see the\nmodule usage example above._\n\nThe characters at the beginning of the character map should be the darkest and\nthe ones at the end be the lightest. You can switch this around by using the\n`inverted` flag/property.\n\nIf you are using the module, you can set the character map to an array of\nstrings, where each element will be used as a pixel color (rather than each\ncharacter of the string).\n\n### Some tips for using character maps:\n\n- Simple images with recognisable shapes and high contrast work the best.\n  (Although if you aren't aiming for functionality, go wild!)\n- Normally you will want to invert the character map if your terminal is in a\n  dark theme.\n- You can generate ASCII art by using character maps such as `\"@#?)l+-. \"` and\n  blocky images using character maps like `█▓▒░`.\n- Make sure you have escaped any characters you need to with a backslash (`\\`).\n- You don't have to sort your characters from darkest to lightest or vice versa.\n  Play around with what works for specfic images, and see if you can create any\n  interesting effects.\n- Padding your character maps can be useful when brightness is not evenly\n  distributed. For example, if your image has mostly dark tones, then your\n  character map might have some extra spaces on the end, so that it is easier to\n  distinguish between darker colors than lighter ones.\n- Try to make characters next to each other in the character map similar. For\n  example, don't put a `.` after a `'` as one is displayed much lower down than\n  the other.\n\n## Required Permissions\n\n| Flag           |  R  | Reason                       |\n| :------------- | :-: | :--------------------------- |\n| `--allow-net`  |  _  | To fetch images from the web |\n| `--allow-read` |  _  | To use images stored locally |\n\nEither `--allow-net` or `--allow-read` is needed when using `path` (`--file` in\nthe CLI tool). When using `rawFile` or `rawPixels` no permission flags are\nrequired.\n\n## Examples\n\n![Inverted image loaded from unsplash](./examples/unsplash_photo_with_inverted_character_map.png)\n![Colored high-res image loaded from unsplash](./examples/small_high_res_colored_image.png)\n\nFor more example outputs, have a look at the examples folder.\n\n## Todo\n\n- [x] Add some color\n- [x] Publish to nest.land\n- [x] Add support for using images loaded from the web (rather than just\n      locally)\n- [x] Auto-detect file format (no need to rely on the file extension)\n- [x] Allow the user to input an array of strings for the character map [added,\n      but user can't do this when using the cli]\n- [x] Finish the documentation in README.md\n- [x] Add jsdoc documentation in the code\n- [x] Add support for unicode characters\n- [x] Add high(er) resolution output mode\n- [x] Correctly handle characters such as emojis that have a width that isn't 1\n- [x] Add support for GIF images\n- [x] Deal with transparency better\n- [ ] Fix some images not displaying correct colors (incorrect black and white,\n      not displaying transparent)\n- [ ] Fix some images displaying at the incorrect size (too large) by default\n- [ ] Add some tests\n- [ ] Don't count modifier characters (e.g. emoji skin tones) as separate\n      characters (unless they aren't modifying anything and are visible)\n- [ ] Option for width as a percentage of terminal screen\n- [ ] Detect whether terminal theme is light or dark automatically?\n- [ ] Better error handling (e.g. 404 when fetching image)\n- [ ] Add support for webp images\n- [ ] Add support for TIFF images\n\n## Contributions\n\nContributions are welcome and greatly appreciated! Just pick something to do\n(the todo list above is a good starting point) and let me know you want to work\non it by opening an issue or commenting on a relevant existing issue.\n\nIf you think you have found a bug, or would like to make a suggestion, please\nopen an issue (after checking for similar issues).\n\n## License\n\n**terminal_images** is under the open source MIT license. See the LICENSE file\nfor legal words.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmjrlowe%2Fterminal_images","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmjrlowe%2Fterminal_images","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmjrlowe%2Fterminal_images/lists"}