image-to-ascii

The webcam.sh script in the example folder requires streamer to capture webcam pictures.

On Ubuntu:

sudo apt-get install streamer

On CentOS / RHEL:

sudo yum install --enablerepo epel GraphicsMagick

To run the webcam script:

sh webcam.sh

The image-to-ascii library recommends installing GraphicsMagick on your system. If GraphicsMagick is not found, the library will attempt to install lwip by compiling C/C++ components automatically.

Install GraphicsMagick using your operating system's package manager:

# Ubuntu
$ sudo apt-get install graphicsmagick

# Fedora
$ sudo dnf install GraphicsMagick

# CentOS / RHEL
$ sudo yum install --enablerepo epel GraphicsMagick

# OS X
$ brew install graphicsmagick

# Windows (via Chocolatey)
# Note: Restart cmd/PowerShell after installation
$ choco install graphicsmagick

You can install the image-to-ascii Node.js module using npm or yarn.

# Using npm
npm install --save image-to-ascii

# Using yarn
yarn add image-to-ascii

If you prefer a command-line interface, you can install the CLI version globally:

npm install --global image-to-ascii-cli
# or
yarn global add image-to-ascii-cli

Once GraphicsMagick is installed on your system, you can install the image-to-ascii package via npm:

$ npm i --save image-to-ascii

The imageToAscii(source, options, callback) function converts an image into ASCII art.

Parameters

• source (String|Buffer): The path or URL to the image, or a Buffer object.
• options (Object|String): A path to an image file or an options object to configure the conversion process.
• callback (Function): The callback function executed after the conversion. It receives the resulting ASCII art.

The imageToAscii(source, options, callback) function converts an image (from a local path, URL, or Buffer) into ASCII art.

Basic usage:

const imageToAscii = require("image-to-ascii");

imageToAscii("https://example.com/image.png", (err, converted) => {
    console.log(err || converted);
});

Usage with options (e.g., disabling color):

imageToAscii("https://example.com/image.jpg", {
    colored: false
}, (err, converted) => {
    console.log(err || converted);
});

const imageToAscii = require("image-to-ascii");

imageToAscii("https://octodex.github.com/images/octofez.png", (err, converted) => {
    console.log(err || converted);
});

Control how pixels are mapped to characters and how colors are applied to the output.

Pixel Asciifier Options

• pixels (Array|String): Characters used for converting pixels (default: " .,:;i1tfLCG08@").
• reverse (Boolean): If true, creates a negative image effect (default: false).
• colored (Boolean): If true, output contains ANSI styles (default: true).
• bg (Boolean): If true, the background color is used for coloring (default: false).
• fg (Boolean): If true, the foreground color is used for coloring (default: true).
• white_bg (Boolean): Turns on white background for transparent pixels (default: true).
• px_background (Object): Custom background color using { r, g, b } values.

You can control the dimensions of the resulting ASCII art using the size and size_options properties.

Size Options

• size (Object): Interpreted by compute-size.
  • height (Number|String): The height value (default: "100%").
  • width (Number|String): The width value (default: computed value to keep aspect ratio). Optional if height is provided.

Size Configuration (size_options)

• screen_size (Object): Defaults to terminal width and height.
  • width (Number): The screen width.
  • height (Number): The screen height.
• px_size (Object): The pixel size.
  • width (Number): Default 1.
  • height (Number): Default 1.
• preserve_aspect_ratio (Boolean): If false, the aspect ratio will not be preserved (default: true).
• fit_screen (Boolean): If false, the result size will not fit to screen (default: true).

Control how the pixel matrix is processed into the final string output.

Matrix Options

• stringify (Boolean): If false, pixel objects will not be stringified (default: true).
• concat (Boolean): If false, pixel objects will not be joined together (default: true).

Stringifier Customization

• stringify_fn (Function): A custom function that receives the pixels matrix and the options object. Use this to implement your own stringification logic.
• image_type (String): Explicitly provide the image type.