aalib.js

This library converts images and movies to ASCII art.

It is written entirely in JavaScript and is intended to use in web browsers.

Examples

Interactive demo

Usage

Converting to ASCII art is performed by reading an image (or a video) then processing it by a series of processors and finally rendering the output.

In general it has the following form:

Reader >> Pre-Filter >> AA >> Post-Filter >> Renderer

This means what follows:

Reader reads image (static or moving) and converts it to internal representation.
(Optional) Pre-Filter (e.g. brightness or contrast) can be applied to the image from the 1st step.
AA transforms image from the 2nd step to ASCII art.
(Optional) Another Post-Filter can be applied but in this step it is applied to ASCII art image.
Renderer renders image from the 4th step to a given output.

That is how it looks expressed in a code:

aalib.read.image.fromURL("marylin.jpg")
    .map(aalib.filter.contrast(0.9))
    .map(aalib.aa({ width: 530, height: 160 }))
    .map(aalib.filter.brightness(10))
    .map(aalib.render.html({ el: document.querySelector(".aa-image") }))
    .subscribe();

See API section for more details on how the processors work.

The library is using RxJS under the hood. Every reader actually returns an Observable so processing is not started until subscribe method is called. Data emitted by observables may be transformed by map operator, or you are allowed to perform any operation (like logging or side-effects) by using do operator.

The library is distributed as:

a standalone UMD library (see dist directory) - exposed as a global aalib namespace. Dedicated for use in browsers.

<script type="text/javascript" src="dist/aalib.js"></script>

ES6 modules (see lib directory) - for node.js

const aalib = require("aalib.js");

// or

import aalib from "aalib.js";

You may also want to load separate files by importing/requiring directly from aalib.js/lib:

API

Readers

These are objects which read from various sources and write to a processing stream.

ImageReader

Exposed in aalib.read.image and as a default export in aalib.js/lib/readers/ImageReader.

Factory methods:

fromURL(url:string) - creates ImageReader reading from given URL and returns observable.
fromHTMLImage(img:HTMLImageElement) - creates ImageReader reading given HTMLImageElement and returns observable.

VideoReader

Exposed in aalib.read.video and as a default export in aalib.js/lib/readers/VideoReader.

Factory methods:

fromVideoElement(video:HTMLVideoElement, options:object) - creates VideoReader reading from given HTMLVideoElement and returns observable.

options accepts the following options:

autoplay:boolean - If true, starts playing video automatically, default: false

ImageDataReader

Exposed as aalib.read.imageData or as a default export in aalib.js/lib/readers/ImageDataReader.

Use the fromImageData factory method to create observable from an image data object. An image data object contains three mandatory fields; width, height, and data. The first two describe the dimensions of the image data, while the third is an array of width * height * 4 elements, where each pixels is represented as r, g, b, alpha. ImageData object are returned for example when getting pixel data from a canvas, or when rendering to an offscreen buffer using WebGL.

Filters

Filters are processors changing each component of an image. When a filter is applied to a regular image it changes a RGB value. When a filter is applied to ASCII art image it changes the only component the image has - intensity. Intensity is a value which tells whether part of an image should be rendered as a "dark" or "light" character.

inverse

Exposed as aalib.filter.inverse or as a default export in aalib.js/lib/filters/inverse.

aalib.filter.inverse()

This filter inverses each component of an image. By inversion I mean the function: f(x) = 255 - x

linear

Exposed as aalib.filter.linear or as a default export in aalib.js/lib/filters/linear.

aalib.filter.linear(a:number, b:number)

It applies the linear transformation: f(x) = ax + b

brightness

Exposed as aalib.filter.brightness or as a default export in aalib.js/lib/filters/brightness.

aalib.filter.brightness(value:number)

It changes the brightness of an image. This is the special case of the linear filter where a = 1.

contrast

Exposed as aalib.filter.contrast or as a default export in aalib.js/lib/filters/contrast.

aalib.filter.contrast(value:number)

It changes the contrast of an image. This is the special case of the linear filter where b = 0.

desaturate

Exposed as aalib.filter.desaturate or as a default export in aalib.js/lib/filters/desaturate.

aalib.filter.desaturate()

It desaturates (converts to a grayscale) an image.

AA

This processor handles actual conversion to ASCII art image.

Exposed as aalib.aa or as a default export in lib/aa.

aalib.aa(options:object)

It accepts the following options:

width:number - width (in characters) of target ASCII art image.
height:number - height (in characters) of target ASCII art image.
colored:boolean - if true, the colors of the original image are preserved. Every character in a target image has a mean color of area it represents in the original image.

Renderers

Renderers outputs ASCII art image. They can render using different characters set. By default two charsets are defined are defined:

ASCII_CHARSET - printable ASCII characters - range: <32, 127>. This is the default one.
SIMPLE_CHARSET - characters from list ['.', ':', '*', 'I', '$', 'V', 'F', 'N', 'M'].

They are exposed in each renderer as named export:

import { ASCII_CHARSET, SIMPLE_CHARSET } from "lib/renderers/HTMLRenderer";

or as

aalib.charset

HTMLRenderer

Exposed as aalib.render.html or as a default export in aalib.js/lib/renderers/HTMLRenderer.

aalib.render.html(options:object)

Renders ASCII art image as HTML element.

Options:

tagName:string - tag name of the rendered HTML element, default: pre.
el:HTMLElement - if defined, use this element as render target. Otherwise create a new element defined by tagName.
fontFamily:string - font being used while rendering, default: monospace.
fontSize:number - font size of the rendered text, default: 7px.
charset:string[] - a list of characters being used while rendering, default: printable ASCII characters (range <32, 127>).
background:string - background color of target HTML element, default #FFF.
color:string - color of the text. Ignored if output image is not monochrome (see colored in AA options), default: #000.

CanvasRenderer

Exposed as aalib.render.canvas or as a default export in aalib.js/lib/renderers/CanvasRenderer.

aalib.render.canvas(options:object)

Renders ASCII art image as Canvas element.