An API to convert any image into ASCII

 

Who doesn’t love ASCII art?

There are the true artists who create art themselves, a character at a time. For the rest of us, there are lots of great ASCII art generators, for instance Picascii or Text Image.  One thing they are missing though is an API to handle the image-to-ASCII conversion.  When we were building our API for image transformations, we had to include things like resize, compress, and crop but we wanted to include ASCII because it’s just awesome. This post is about this cool feature. As you’ll see, with this online tool that works as a png converter, modifying image files has never  been easier.

This blog will convert an jpg to ASCII in the example, but you can also automatically convert the following file types to ASCII using our API: png, ai, psd, tiff, bmp.

Let’s go!

The Filestack transformation API

The Filestack transformation API is really simple to use.  Basically, you send a request to our transformation endpoint along with your API key and task.  You can programmatically interact with our API, but in these examples, I’ll just show you how to convert to ASCII by adding conversion tasks to at URL.

Here is how the Transformation URL is structured for an image hosted on some server or object store like Amazon S3.

You can see there are three parts: your API key, the conversion task (in our case convert-to-ascii), and the url of the image we want to convert.

How to convert any image into an HTML file of ASCII Art

Ok, with the basics out of the way, let’s see how the Filestack transformation engine can take any image file and turn it into an HTML file of ASCII Art by simply passing these few url parameters to the Filestack API.

Here is the structure of the Image to ASCII task.

Image to ASCII Task URL Format:

https://process.filestackapi.com/<API_KEY>/ascii=[options]/File_URL

File_URL is the url of the image that you want to convert.  This could be any image hosted on any server, but most commonly will be something stored on an object store like S3, Azure Blob store or Google Storage.

The options are:

ascii=background:white or #FF0000

where you specify a background color for the HTML file from our list of accepted color names or a hex color code. You can even opt for a transparent background if that is what you like.

Same thing goes for the foreground color.

ascii=foreground:red or #FF0000

This is the font color that will make up the image.  Specifying the foreground option will create a single color image.

If you want a multi-color image, you can use the colored option.

ascii=colored:true

When set to true, this reproduces the colors in the original image. This works best with a dark HMTL background as you’ll see below.

You can also use the size attribute to specify the size of the returned file as a percentage of the original. The parameter must be an integer between 10 and 100. The default is 100. This online tools makes it easier for you to format image files to your own needs and expectations.

ascii=size:10 to 100

You can also reverse the character set used to generate the ASCII output. This works well with dark backgrounds and requires color:true

ascii=reverse:true

With the details out of the way.  Let’s look at some of the world’s most famous paintings as ASCII art!

In no particular order, here are some of the world’s most famous paintings in ASCII.  If you don’t see the ones you would have picked, give it a try and Tweet us a link via Twitter.

(BTW, for display purposes on the blog, I’ve included the ASCII as images, but if you click on each image itself, you’ll get the full HTML page with the ASCII art.  For comparison, you can click on the hyperlink to see the original.)

 

 

 

 

 

 

 

 

What else can I do?

Filestack does a lot of other image transformations, using the same patterns as above. Here is a complete list of all the transformations that Filestack can do, with a link to the relevant page in documentation:

Compress
Watermark
Facial Detection
Crop
Rotate
Border and Effects
Filters
Collage
Image Enhancements
URL Screenshot
Image to ASCII
File type conversions
Zip

I hope that this has given you a taste of some fun, and sometimes even useful, things Filestack can do.  Till next time.

Michael @ Filestack