img-using-text

Utility to help process an image into a string (mostly for ASCII art) in the browser. Use a File or url. Also exposes an API to retrieve rgba values for a pixel at any position. See example in index.html.

npm install --save img-using-text

Usage

Simple example

import { fileToText } from 'img-using-text';
// File input change handler. Has to be an image upload. 
const handleFileChange = function(e)  {
  const file = this.files[0];
  fileToText(file).then((text) => {
    console.log(text);
  })  
}

More advanced example

import { fileToText, isWhiteOrTransparent } from 'img-using-text';

const text = 'foobar';
const charForPixel = (pixel, pixelIndex) => {
   const { r, g, b, a } = pixel;
   if (!isWhiteOrTransparent(r, g, b, a)) {
     return text[pixelIndex % text.length];
     } else {
        return ' ';
     }
};
// File input change handler. Has to be an image upload. 
const handleFileChange = function (e) {
  const file = this.files[0];
  const width = 300;
  const stretch = 0.6;
  fileToText(file, width, stretch, {
    charForPixel,
    async: true
  })
  .then((formattedText) => {
    const content = document.getElementById('content');
    content.innerHTML = formattedText;
  });
};

API

isWhiteOrTransparent

Simple estimation for whether an rgba value is white or transparent

Parameters

• r number red
• g number green
• b number blue
• a number alpha

Returns boolean

pixelsToText

Convert from ImagePixels to text

Parameters

• imgPixels ImagePixels instance of ImagePixels containing image information
• options Object options object
  • options.async boolean whether to wrap the work for every row in a setTimeout (optional, default false)
  • options.charForPixel function the function to call to convert from an {r, g, b, a} object to a character or text. (optional, default return'x'if!isWhiteOrTransparentelse' ')

Returns (string | Promise) the resulting text if not async, a Promise otherwise

imageFromFile

Create an Image object from a File object

Parameters

• file File the file (from an for example)

Returns Image

fileToPixels

Given a File it returns an ImagePixels Promise

Parameters

• file File
• width number width value if you want to resize the image (optional, default imagewidth)
• stretch number how much you would like to stretch the height compared to the width (optional, default 1)

Returns Promise a bluebird promise

urlToPixels

Given a URL it returns an ImagePixels Promise

Parameters

• url string url of the image (needs to allows CORS)
• width number width value if you want to resize the image (optional, default imagewidth)
• stretch number how much you would like to stretch the height compared to the width (optional, default 1)

Returns Promise a bluebird promise

fileToText

Given a File containing an image, convert it to a text representation.

Parameters

• file File
• width number width value if you want to resize the image (optional, default imagewidth)
• stretch number how much you would like to stretch the height compared to the width (optional, default 1)
• options Object options object
  • options.async boolean whether to wrap the work for every row in a setTimeout (optional, default false)
  • options.charForPixel function the function to call to convert from an {r, g, b, a} object to a character or text. (optional, default return'x'if!isWhiteOrTransparentelse' ')

Returns Promise a promise that resolves to an ImagePixels instance

urlToText

Given a File containing an image, convert it to a text representation.

Parameters

• url string url of the image (needs to allows CORS)
• width number width value if you want to resize the image (optional, default imagewidth)
• stretch number how much you would like to stretch the height compared to the width (optional, default 1)
• options Object options object
  • options.async boolean whether to wrap the work for every row in a setTimeout (optional, default false)
  • options.charForPixel function the function to call to convert from an {r, g, b, a} object to a character or text. (optional, default return'x'if!isWhiteOrTransparentelse' ')

Returns Promise a promise that resolves to an ImagePixels instance

ImagePixels

A class that wraps a canvas context and allows you to read individual pixels as rgba values.

constructor

Parameters

• img Image
• width number width value if you want to resize the image (optional, default imagewidth)
• yStretch number how much you would like to stretch the height compared to the width (optional, default 1)
• mockCanvas Canvas mock canvas used only for testing with 'canvas-prebuilt' (optional, default test-only)

get

Get an Object with keys r, g, b, a representing the pixel at point i, j

Parameters

• i number
• j number

Returns Object with r, g, b, a values

Contributing

Features

• Build with webpack 2 and babel
• Test with jest
• Lint with eslint (air-bnb config)
• Document with documentation

  Commands

npm run clean

Delete all cache and output files

npm run dev

Build your library in development mode

npm run build

Build your library in production mode

npm run documentation

Automatically generate documentation from JSDoc strings and insert them in README.

npm run test

Run tests

npm run lint

Check your code for errors and code styles

npm run prepublish

Hook for npm, that executes when you publishing package in npm repository.

Lint

This project uses air-bnb code style conventions, .eslintrc config file:

{
  //...
  
  "extends": "airbnb"
}