This library converts images and movies to ASCII art.
It is written entirely in JavaScript and is intended to use in web browsers.
- Mona (original)
- Lenna (original)
- Marylin (original)
- Evangeline (original)
- Monica (original)
- Big Buck Bunny
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 globalaalib
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
:
These are objects which read from various sources and write to a processing stream.
Exposed in aalib.read.image
and as a default export in aalib.js/lib/readers/ImageReader
.
Factory methods:
fromURL(url:string)
- createsImageReader
reading from given URL and returns observable.fromHTMLImage(img:HTMLImageElement)
- createsImageReader
reading givenHTMLImageElement
and returns observable.
Exposed in aalib.read.video
and as a default export in aalib.js/lib/readers/VideoReader
.
Factory methods:
fromVideoElement(video:HTMLVideoElement, options:object)
- createsVideoReader
reading from givenHTMLVideoElement
and returns observable.
options
accepts the following options:
autoplay:boolean
- Iftrue
, starts playing video automatically, default:false
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 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.
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
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
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
.
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
.
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.
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
- iftrue
, 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 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
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 bytagName
.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 (seecolored
in AA options), default:#000
.
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.
Options:
fontSize:number
- font size of the rendered text, default:7px
.fontFamily:string
- font being used while rendering, default:monospace
.lineHeight:number
- defines line height, default: 7px.charWidth:number
- defines the width of the characters, default: 4.2px.width:number
- defines canvas width in pixels, default: 400.height:number
- defines canvas height in pixels, default: 300.el:HTMLElement
- if defined, use this element as render target. Otherwise create a new canvas.charset:string[]
- a list of characters being used while rendering, default: printable ASCII characters (range <32, 127>).background:string
- background color of canvas, default#FFF
.color:string
- color of the text. Ignored if output image is not monochrome (seecolored
in AA options), default:#000
.
The MIT License (MIT). Copyright (c) 2017 mirz ([email protected])