image to ascii

image to ascii turns any image into animated ascii, in the image’s own colours. Drop in a logo or a photo, and you get three things back: a snippet for any web page, two SVGs for a GitHub README, and a piece file. A piece is one of the library’s animations, and the file is in the library’s own format, ready to add to it.

It all happens in your browser. Your image is never uploaded.

The library’s own logos were drawn the same way, like this one:

Turn an image into ascii

1. Open image to ascii. Every page of this site links to it, as [image to ascii] next to [make a banner].
2. Give it an image, in any of these ways:
   • Drop the file anywhere on the page.
   • Press [pick a file] and choose one.
   • Copy an image, such as a screenshot, and paste it anywhere on the page.
   • Paste an SVG’s markup into the or paste an svg’s markup box, then press [draw it].
3. The art plays in the box at the top. If the image had a plain background, a message under the art says which colour it left out.
4. Under settings, type a name. Change the width, style, motion and category if you want. The art redraws as you change them.
5. Copy what you need from the three boxes at the bottom of the page: embed it, readme, and the .ts file.

The line just under the art sums it up: its size in columns by rows, how many colours it has, how often it moves, and the size of its .ts file. For example: 48×32, 8 colours, a glint every 5 s, 7.4 kB. [another image] on the same line opens a new file.

Choose a style

The style sets how each cell, one character of the art, is chosen. There are two:

The Go gopher at 32 columns, in the logo style, in one colour. Its white eyes are left out, so they show as gaps:

        __ppq8888888qq_, __
   _p88p8P"""8888P"''"888888,
  :8888P_p,   88Pqp,   88888P
   "8888/Y'  _d8b/"   _8888"
    d8888qqpp88888qqp888888,
    888888888888Y8888888888|
    8888888888qp_8888888888P
    d8888888888888888888888P
    d8888888888888888888888b
  _pp88888888888888888888888q_
  YPO88888888888888888888888Y"
    d88888888888888888888888
    d88888888888888888888888
    888888888888888888888888
    d8888888888888888888888P
    "8888888888888888888888'
     "88888888888888888888"
     _p888888888888888888q,
     O88"'""YP888PP^"" '88"

A picture of a sun over hills, in the shade style, as a dark page shows it:

  .::::::::-------=======++++++
  .::::::::-------=+***==++++++
  .::::::::------*@@@@@@*++++++
  .::::::::-----=@@@@@@@@++++++
  .::::::::------#@@@*-:==+++++
  .::::....::-----==......:-+++
  ............:::............-=
  .............................
  .............................

Each image starts in the style that suits it:

• An SVG starts in logo. So does an image with transparency, or with a plain background.
• An image with no transparency and no plain background, such as a photo, starts in shade.

Press the other style at any time to switch.

Keep or remove the background

A JPG, or any image with no transparency, usually sits on a plain background. The page takes that background out, so the logo stands on its own.

Here is how:

• It looks at the pixels round the image’s edge. If 6 in 10 of them or more are one colour, that colour is the background. If not, it takes nothing out.
• It removes that colour from the edges inwards. The same colour inside the logo, such as white letters on a shape, stays.
• It says which colour it took out, for example left out its background, #ffffff.

To put the background back, press [keep the background]. The art is drawn again from the whole image, background and all. Press [remove the background] to take it out again. Either button draws the image again in the logo style, so press shade again if you want it shaded.

The button shows only when a background was found. Nothing is taken out of:

• an SVG;
• an image with transparency of its own, such as a PNG whose edges are clear;
• an image whose border isn’t mostly one colour, such as most photos.

Change the settings

Every setting redraws the art and rewrites the snippets and the file.

Motion and category go together, as they do in the library: a distro scans, and a company or a language glints. Picking distros picks scan, and picking scan picks distros. Picking glint on a distro makes it a company.

In one colour, the art changes in two ways so it still reads:

• In the logo style, a logo with white among its colours leaves the white out. White letters on a coloured shape show as gaps.
• In the shade style, on a light page, the characters swap ends: the densest now mark the darkest parts, because dark ink on a light page reads as dark. Otherwise the picture would show as a negative.

Embed it on any web page

The embed it box holds a snippet for any HTML page. It needs no install and no build step. Press [copy], then paste it where you want the art.

The snippet is an element and a script. The script loads mount() from https://ascii.rest/mount.js and plays your piece, which is written out in full inside it. Shortened, a piece named acme looks like this:

<canvas id="ascii-acme" role="img" aria-label="acme" style="width: 100%; max-width: 480px"></canvas>
<script type="module">
import { mount } from "https://ascii.rest/mount.js";

// acme, drawn in ascii on https://ascii.rest/make/
const meta = {
  name: "acme",
  category: "companies",
  ...
};
// ... the art, its colours, and the code that draws it at each moment ...
mount(document.getElementById("ascii-acme"), { meta, default: acme });
</script>

What it does on your page:

• In colour, it draws on a <canvas>. With [mono] on, the snippet uses a <pre> in your page’s text colour instead.
• It reads your page’s text colour to tell a light page from a dark one, and uses the colours made for that page.
• It plays only while it is on screen and its tab is open. For readers who prefer reduced motion, it holds still.

To change it:

• Make it smaller or bigger: change max-width on the <canvas>. On the <pre>, change the 10px in its font.
• Put two on one page: give each its own name. The element’s id is ascii- and the name, so two with the same name clash.

If nothing shows, work through nothing shows up. If your site sends a Content-Security-Policy header, its script-src must allow https://ascii.rest and this inline script: add the script’s hash, a nonce, or 'unsafe-inline'.

Add it to a GitHub README

A README can’t run scripts, so the page makes two animated SVG files: one for GitHub’s light theme and one for its dark theme.

1. Press [light svg]. It saves <name>.svg.

2. Press [dark svg]. It saves <name>.dark.svg.

3. Put both files in your repository, next to README.md, and commit them.

4. Copy the snippet from the readme box into your README. For acme, it is:

   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="acme.dark.svg">
     <img alt="acme" src="acme.svg" width="240">
   </picture>
   

How it works:

• GitHub shows acme.dark.svg in its dark theme, and acme.svg in its light theme.
• Each SVG plays one loop of the glint or the scan, again and again, with no script. For readers who prefer reduced motion, it holds still.
• width is 5 pixels for each column. Change it to show the art bigger or smaller.
• To keep the files in another folder, change both paths, for example to .github/acme.svg and .github/acme.dark.svg.

github readme has more on images in a README.

Add it to the library

The last box holds <name>.ts: the piece in the library’s own format. It has the piece’s meta, the art, its colours, and the same glint or scan code as the library’s logos. Press [download] to save it, or [copy].

The library takes the logos of programming languages and web tools, of companies, and of Linux distributions. To add one:

1. Start from the official logo, such as an SVG from its owner’s brand page, Simple Icons or devicon.
2. Pick its category, and keep the logo style.
3. Give it a name the library doesn’t have yet. If the name is taken, the page says so: the library already has a piece called python: give this one another name to add it.
4. Download the .ts file.
5. In the comment at the top of the file, say where the logo’s artwork came from.
6. Save it in the repo as src/pieces/<name>.ts, check it, and open a pull request. Add it to the library has every step. The file already imports its types from ../types.ts, as the library’s pieces do, so skip step 3 there.

In short, with Node 23.6 or later:

git clone https://github.com/bas3line/ascii
cd ascii
npm install
# save the file as src/pieces/acme.ts, then:
npm run gen
npm run check -- acme --show
npm run typecheck

To play the file in your own app instead, change its import line to import type { Frame, Meta } from "ascii.rest";. Then use it as you would any piece you wrote: play it in React or Next.js.

Formats it takes

Any image your browser can open works. Each format is drawn like this:

• Images other than SVGs can be up to 40 MB. The page first draws every image 2400 pixels across, the longer way, so a larger image adds no detail.
• SVG markup copied out of a web page often has no xmlns. The page adds it for you.

Your image stays in your browser

The page does all of its work in your browser:

• Your image is never uploaded, and nothing about it is sent anywhere.
• The SVGs and the .ts file are made on your computer and saved from your browser.
• An SVG is drawn as an image, which runs none of its scripts and loads nothing from elsewhere.

Of what the page gives you, only the embed snippet loads anything from elsewhere: on your own page, it loads mount.js from ascii.rest.

Common problems

A message under the art says what went wrong. Each message, and the other things people run into:

Next

• github readme: more ways to put art in a README, and banners with your own text.
• your own pieces: what a piece is made of, to change the .ts file by hand.
• html: the library’s tags, for pieces on any web page.