aalib.js

ASCII art library in JavaScript

Download as .zip Download as .tar.gz View on GitHub

This library allows to automatically convert images and movies to ASCII art.

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

Examples

Usage

The library uses streams to process images. This means that an image is firstly read and then passed through a stream. A stream consists of processors which can read data from its input, process, and write to output. Chaining processors together makes a series of transformations which eventually lead to ASCII art.

In general the stream has the following form:

Reader >> Filter >> AA >> Filter >> Renderer

This means what follows:

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

That is how it looks expressed in a code:

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

See API section for more details on how processors work.

API

Readers

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

ImageReader

Exposed in aalib.read.image

It has two handy factory methods:

VideoReader

Exposed in aalib.read.video

It has two handy factory methods:

Both methods accepts following options:

Filters

Filters are processors which changes every 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

aalib.filter.inverse()

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

linear

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

It applies linear transformation to every image component. The linear transformation is a function: f(x) = ax + b

brightness

aalib.filter.brightness(value:number)

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

contrast

aalib.filter.contrast(value:number)

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

AA

This processor handles actual conversion to ASCII art image.

aalib.aa(options:object)

It accepts the following options:

Renderers

Renderers are used to output ASCII art image. They can render using different characters set. By default two charsets are defined and exposed under CHARSET property of every renderer:

HTMLRenderer

aalib.render.html(options:object)

Renders ASCII art image as HTML element.

Options:

CanvasRenderer

aalib.render.canvas(options:object)

Renders ASCII art image as Canvas element.

Options:

License

The MIT License (MIT). Copyright (c) 2015 mirz (mirz.hq@gmail.com)