braille-image

Convert images to Unicode braille text art.

Install

npm i braille-image

CLI

npx braille-image <input> [options]

Option	Description
-w, --width <cells>	Output width in braille cells (default: auto)
--height <cells>	Output height in braille cells (default: auto)
-t, --threshold <n>	Brightness threshold 0–255 (default: 128)
-i, --invert	Invert luminance before thresholding
-h, --help	Show usage

Examples:

# Auto-sized output
npx braille-image photo.jpg

# Fixed 40-cell wide output
npx braille-image photo.jpg --width 40

# Inverted with custom threshold
npx braille-image photo.jpg --invert --threshold 200

Library API

import { imageToBraille } from 'braille-image';

const art = await imageToBraille('./photo.jpg', {
  width: 40,
  invert: true,
});

console.log(art);

imageToBraille(input, options?)

Param	Type	Description
input	string | Buffer | Uint8Array	File path or image buffer
options.threshold	number (0–255)	Brightness cutoff. Default: 128
options.width	number	Target width in braille cells
options.height	number	Target height in braille cells
options.invert	boolean	Invert luminance. Default: false

Returns: Promise<string> — braille text with \n-separated rows.

Throws: TypeError on invalid options, Error on image processing failures.

How it works

1. Grayscale — the input image is converted to single-channel luminance via sharp.

2. Resize — if width / height are specified, the image is scaled to (width × 2) × (height × 4) pixels so each braille cell maps to exactly one 4×2 pixel block.

3. Threshold — each pixel is compared against the threshold value. Brighter pixels are "raised dots"; darker pixels are left empty.

4. Braille encoding — every 4×2 block is packed into one Unicode braille character using the standard dot layout:

   Physical      Bit
    1 .  4      0 .  3
    2 .  5      1 .  4
    3 .  6      2 .  5
    7 .  8      6 .  7
   

Development

This project was built collaboratively with Reasonix Code.

Quick start

git clone https://github.com/PuppyOne/braille-image.git
cd braille-image
npm i
npm run build
npm test

Stack

Layer	Tool
Runtime	Node.js ≥ 18, ESM
Image processing	sharp
Build	tsdown
Test	vitest
Language	TypeScript 6

License

Apache-2.0