binary-pixel-map

A library written in TypeScript for creating and editing a binary 2D pixel map, made for usage with small monochrome displays, for example on a Raspberry Pi or Arduino.

This library is based on oled-js and oled-font-5x7 by noopkat.

Installation

yarn add binary-pixel-map

Usage

import { PixelMap, Pixel } from 'binary-pixel-map';
 
// Create a new pixel map with a width of 54, height of 18.
const map = new PixelMap(54, 18);
 
// Draw "Hello, world!" on the map.
map.text(1, 1, 'Hello,');
map.text(1, 10, 'world!');
 
// Enable the top left and bottom right pixel.
map.set(0, 0, Pixel.ON);
map.set(53, 17, Pixel.ON);
 
console.log(map.toString());

The example above will output the following:

PixelMap { x - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
           - x - - - x - - - - - - - - - - - - x x - - - - - - x x - - - - - - - - - - - - - - - - - - - - - - - - - -
           - x - - - x - - - - - - - - - - - - - x - - - - - - - x - - - - - - - - - - - - - - - - - - - - - - - - - -
           - x - - - x - - - - x x x - - - - - - x - - - - - - - x - - - - - - x x x - - - - - - - - - - - - - - - - -
           - x x x x x - - - x - - - x - - - - - x - - - - - - - x - - - - - x - - - x - - - - - - - - - - - - - - - -
           - x - - - x - - - x x x x x - - - - - x - - - - - - - x - - - - - x - - - x - - - - x x - - - - - - - - - -
           - x - - - x - - - x - - - - - - - - - x - - - - - - - x - - - - - x - - - x - - - - - x - - - - - - - - - -
           - x - - - x - - - - x x x - - - - - x x x - - - - - x x x - - - - - x x x - - - - - x - - - - - - - - - - -
           - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
           - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
           - - - - - - - - - - - - - - - - - - - - - - - - - - x x - - - - - - - - - x - - - - - x - - - - - - - - - -
           - - - - - - - - - - - - - - - - - - - - - - - - - - - x - - - - - - - - - x - - - - - x - - - - - - - - - -
           - x - - - x - - - - x x x - - - - x - x x - - - - - - x - - - - - - x x - x - - - - - x - - - - - - - - - -
           - x - - - x - - - x - - - x - - - x x - - x - - - - - x - - - - - x - - x x - - - - - x - - - - - - - - - -
           - x - x - x - - - x - - - x - - - x - - - - - - - - - x - - - - - x - - - x - - - - - x - - - - - - - - - -
           - x - x - x - - - x - - - x - - - x - - - - - - - - - x - - - - - x - - - x - - - - - - - - - - - - - - - -
           - - x - x - - - - - x x x - - - - x - - - - - - - - x x x - - - - - x x x x - - - - - x - - - - - - - - - -
           - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - x }

API

PixelMap

new PixelMap(width: number, height: number);

get

get(x: number, y: number): PixelStatus;

Get the value of the pixel at [x, y].

getAll

getAll(): PixelStatus[][];

Get all pixels.

set

set(x: number, y: number, status: PixelStatus): void;

Set the value of the pixel at [x, y];

clear

clear(): void;

Clear the whole map.

fill

fill(status: PixelStatus): void;

Fill the map with enabled (ON) or disabled (OFF) pixels.

line

line(x0: number, y0: number, x1: number, y1: number, status: PixelStatus = Pixel.ON): void;

Draw a line from [x0, y0] to [x1, y1] using Bresenham's line algorithm.

rectangle

rectangle(x: number, y: number, width: number, height: number, outline: boolean = false, status: PixelStatus = Pixel.ON): void;

Draw a rectangle at [x, y] with the size [width, height]. If outline is set to true, only an outline will be drawn. Otherwise the rectangle will be filled.

text

text(x: number, y: number, content: string, size: number = 1, spacing: number = 2, wrap: boolean = true): void;

Draw text at [x, y] with size size. The standard size (size = 1) for letters is 5 x 7.

copy

copy(from: PixelMap, x: number = 0, y: number = 0): void;

Copy another pixel map onto the current pixel map at [x, y].

image

async image(path: string | Buffer, x: number = 0, y: number = 0, maxWidth?: number, maxHeight?: number): Promise<void>;

Copy an image onto the pixel map. path can be a file path or image buffer. Supported file types are: PNG, JPEG, WebP, GIF, SVG and TIFF.

toArray

toArray(): PixelStatus[];

Get the map as sequence of all rows. Can be useful for displaying the map on a display.

toString

toString(): string;

Get the map as string. Can be useful for debugging.

Pixel

import { Pixel } from 'binary-pixel-map';

PixelStatus

type PixelStatus = boolean;

Used as alternative to booleans. You can still use regular booleans if you prefer.

Pixel.ON

Alternative way of writing true.

Pixel.OFF

Alternative way of writing false.