{"id":32191949,"url":"https://github.com/gered/clj-image2ascii","last_synced_at":"2025-10-22T01:54:33.689Z","repository":{"id":15651481,"uuid":"18388755","full_name":"gered/clj-image2ascii","owner":"gered","description":"Tools for turning images into ASCII equivalents.","archived":false,"fork":false,"pushed_at":"2014-04-05T20:47:36.000Z","size":164,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-10-19T23:45:37.013Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","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/gered.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}},"created_at":"2014-04-03T02:34:44.000Z","updated_at":"2023-04-01T04:42:37.000Z","dependencies_parsed_at":"2022-09-05T06:30:22.461Z","dependency_job_id":null,"html_url":"https://github.com/gered/clj-image2ascii","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/gered/clj-image2ascii","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gered%2Fclj-image2ascii","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gered%2Fclj-image2ascii/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gered%2Fclj-image2ascii/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gered%2Fclj-image2ascii/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gered","download_url":"https://codeload.github.com/gered/clj-image2ascii/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gered%2Fclj-image2ascii/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280365582,"owners_count":26318385,"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","status":"online","status_checked_at":"2025-10-21T02:00:06.614Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2025-10-22T01:54:31.318Z","updated_at":"2025-10-22T01:54:33.684Z","avatar_url":"https://github.com/gered.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# clj-image2ascii\n\nFunctions for turning images into ASCII equivalents. Largely inspired by\n[Claskii](https://github.com/LauJensen/Claskii).\n\nThe same basic algorithm to convert pixels to ASCII characters has been taken from Claskii, but a bunch of\noptimizations have been added and the code in general has been updated (Claskii was last updated ~4 years ago, Clojure\nhas evolved a bunch since then) and made a bit easier to use for general purposes and access the resulting ASCII\n\"image\" and it's properties. Additionally, support for animated GIFs has been added, where each frame of animation is\nextracted as a full image and then converted to ASCII so that rendering is dead-simple -- just flip the images, no need\nto worry about animated GIF disposal methods and such.\n\nThis library is mostly just a Clojure wrapper around the core algorithms to convert single images to ASCII and the\nanimated GIF frame extraction code which are both written in Java for performance reasons. After much benchmarking\nof a pure Clojure version of the `ImageToAscii.convert()` method and then trying out a Java equivalent out of\ncuriosity, I did find that the Java version was significantly faster, so I decided to go with it instead.\n\nAlso, credit to the Stack Overflow user SteveH for [this helpful post](http://stackoverflow.com/a/18425922) which\ncontained really great code for extracting animated GIF frames. This code is used, with a few minor tweaks, in\nclj-image2ascii.\n\n## Usage\n\n![\"clj-image2ascii version\"](https://clojars.org/clj-image2ascii/latest-version.svg)\n\n### Static Images\n\nConverting a single static image is straightforward:\n\n```clojure\n(use 'clj-image2ascii.core)\n\n(convert-image\n  (get-image-by-url (java.net.URL. \"http://i.imgur.com/KAzQTvR.png\"))\n  120\n  false)\n=\u003e {:width 120, :height 109, :color? false, :image \" \u003cbig long string of ASCII here\u003e \"}\n```\n\n`convert-image` takes a `BufferedImage` object. Two helper functions are provided to make it easy `get-image-by-url`\nand `get-image-by-file` which take a `java.net.URL` and `java.io.File` object respectively.\n\nThe optional second argument allows you to specify a new width in pixels to scale the image to before it is converted\nto ASCII. Scaling is done proportionally so the image won't be distorted. If you don't specify a new width, then no\nscaling is performed.\n\nThe last argument is always a boolean to indicate if you want color information encoded into the resulting ASCII string\nor not. Color information is added by wrapping each character in HTML `\u003cspan\u003e` tags and `\u003cbr\u003e` tags used for newlines.\nNo other HTML is added. When no color information is to be added, the resulting ASCII string will only contain ASCII\ncharacters and newlines characters.\n\nNote that converting with color will *significantly* increase the size of the returned ASCII string. Care should be\ntaken when converting large images without scaling but with color. For example, a 300x300 image converted with color\nat it's original size will result in a string that is over 3MB in size!\n\n### Animated GIFs\n\nclj-image2ascii can extract all of the frames out of an animated GIF into separate ASCII \"images.\" The return value\nwill also include the frame delay timings in milliseconds so you can easily perform your own ASCII animation by just\nswapping frames. You do not need to worry about any of the details about how animated GIFs are encoded (disposal\nmethods, frames that need to be overlaid onto the previous frame, zero-delay frames, etc), the returned ASCII images\nwill be converted from each frame's complete image.\n\n```clojure\n(use 'clj-image2ascii.core)\n\n(convert-animated-gif-frames\n  (get-image-stream-by-url (java.net.URL. \"http://i.imgur.com/DiGgmpA.gif\"))\n  120\n  false)\n=\u003e {:width 120, :height 67, :color? false, :frames [{:delay 50, :image \"...\"} {:delay 50, :image \"...\"} ... ]}\n```\n\nThe arguments to `convert-animated-gif-frames` work in exactly the same way as they do with `convert-image`.\n\nThe returned map contains all of the frames in a vector under `:frames` which are in the order they should be displayed\nto be animated. Note that each frame contains it's own delay time (in milliseconds). In animated GIFs, each frame can\nhave a different delay and this information is kept intact during conversion. The `:image` key in each frame map\nwill contain the converted ASCII \"image\" string.\n\nWith animated GIFs especially you should be careful about converting with color information, as you can end up with\n*extremely* big return values if the GIF is large.\n\n#### Streaming Frames\n\nThe `convert-animated-gif-frames` function can use excessive amounts of memory due to the fact that it holds and\nbuilds up a complete list of converted ASCII frames until the conversion process is finished for all frames and then\nthat full list is returned. This behaviour can be useful, but depending on what you need to do with these frames\nit can be wasteful. Especially so for larger GIFs that you want to convert with color information.\n\nThe `stream-animated-gif-frames!` function can be used to \"stream\" frames from the animated GIF as they are converted.\nOnce a frame has been converted, it will be passed to a function you provide to `stream-animated-gif-frames!`, then you\ncan do whatever you need to do with it. `stream-animated-gif-frames!` will not keep previously converted frames\naround and it returns nothing when conversion is complete for all frames. The arguments to `stream-animated-gif-frames!`\nare the same as to `convert-animated-gif-frames`, except that the last argument is a function that accepts a map\nwhich will contain information about the converted frame.\n\nAs an example, maybe you just want to write these frames out to a file:\n\n```clojure\n(stream-animated-gif-frames!\n  (get-image-stream-by-file (File. \"/path/to/animated.gif\"))\n  true       ; convert with color\n  (fn [{:keys [width height color? image delay]}]\n    (spit file image)))\n```\n\nNice and easy.\n\n## License\n\nDistributed under the the MIT License. See LICENSE for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgered%2Fclj-image2ascii","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgered%2Fclj-image2ascii","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgered%2Fclj-image2ascii/lists"}