machop

machop

Dependency-less Image to ASCII converter.

Installation

npm i machop

API

This API applies to machop both as a Node.js module (example) and as a CLI tool. Use the -? or --help flag to see more about the CLI tool.

path

The file path, URL, or buffer for the image you wish to machop. Currently supported formats are:

• JPG
• PNG
• GIF

options.color

Default: true

If options.color is set to true, the asciified image will be in color when printed in your terminal. If set to false, the image will be in black and white.

options.fit

Default: 'original', CLI default: 'box'

The fit to resize the image to:

• box - Resize the image such that it fits inside a bounding box defined by the specified width and height. Maintains aspect ratio.
• width - Resize the image by scaling the width to the specified width. Maintains aspect ratio.
• height - Resize the image by scaling the height to the specified height. Maintains aspect ratio.
• original - Doesn't resize the image.
• none - Scales the width and height to the specified values, ignoring original aspect ratio.

options.width

Default: original image width, CLI default: window width

The width to resize the image to. Use a percentage to set the image width to x% of the terminal window width.

options.height

Default: original image height, CLI default: window height

The height to resize the image to. Use a percentage to set the image height to x% of the terminal window height.

options.format

Default: 'string'

The format to return the asciified image in. Can be "string" or "array".

options.c_ratio

Default: 2

Since a monospace character is taller than it is wide, this property defines the integer approximation of the ratio of the width to height. You probably don't need to change this.

Examples

const machop = require('machop');

const options = {
  fit: 'box',
  width:  200,
  height: 100
}

machop('path/to/image.png', options)
  .then((asciified) => console.log(asciified))
  .catch((err) => console.error(err));

How It Works

Images are represented by pixels. This package reads each pixel as an RGBa value. Each of these values is converted into a single integer, called "intensity". A darker pixel would have a higher intensity, and a lighter pixel would have a lower intensity.

For each pixel, a character is substituted: for a light pixel, the character "," may be substituted, but for a darker pixel, the character "8" would be substituted. Since these characters are different sizes, they look lighter or darker in the big picture (pun somewhat intended).

Inspiration

At the moment, this is complete reuse of asciify-image package, but I'm planning large changes.