Package: plot

The plot package implements a bitmap-based canvas: a 2D array of bits, which can be either on or off. It contrasts with the turtle package, which is based on a vector graphics.

plot/index.js AKA plot

The plot/index.js module is the main entry point for the plot package. It exposes other modules in this directory:

• Exports the Bitmap class from plot/bitmap.js by name and as the default export.
• Augments Bitmap with line() method from plot/draw-line.js.
• Augments Bitmap with rect() method from plot/draw-rect.js.
• Augments Bitmap with toQuads() method from plot/to-quads.js.
• Augments Bitmap with toStrings() method.
• Exports drawLine(), drawRect(), and toQuads() functions.

If you don't need the whole package, you can import individual files.

import Bitmap from 'console-toolkit/plot/bitmap.js';

// extract from https://github.com/uhop/console-toolkit/blob/main/tests/test-plot.js

const bmp = new Bitmap(27, 14)
  .rect(2, 1, 24, 12)
  .rect(4, 2, 22, 11, 0)
  .rect(6, 3, 20, 10)
  .rect(8, 4, 18, 9, 0)
  .rect(10, 5, 16, 8)
  .rect(12, 6, 14, 7, 0);

for (const line of bmp.toQuads().box) console.log(line);

It produces:

 ▄▄▄▄▄▄▄▄▄▄▄▖
 █ ▄▄▄▄▄▄▄▖▐▌
 █ █ ▄▄▄▖▐▌▐▌
 █ █ █ ▐▌▐▌▐▌
 █ █ ▀▀▀▘▐▌▐▌
 █ ▀▀▀▀▀▀▀▘▐▌
 ▀▀▀▀▀▀▀▀▀▀▀▘

plot/bitmap.js

The plot/bitmap.js module is the heart of the plot package. It implements a bitmap canvas as an array of integer numbers, where each number represents a block of the bitmap. For example, by default each number uses 25 bits representing a 5 by 5 rectangular block.

Class Bitmap

The implementation is packaged as the Bitmap class with the following members:

Name	Return type	Description
constructor(width, height, blockWidth = 5, blockHeight = 5)	Bitmap	Creates a new Bitmap instance (all bits are off).
width	number	The width of the bitmap.
height	number	The height of the bitmap.
blockWidth	number	The width of each block in the bitmap.
blockHeight	number	The height of each block in the bitmap.
getBit(x, y)	number	Gets the bit at the specified position as a truthy/falsy value.
setBit(x, y, value = 1)	this	Sets the bit at the specified position. See value details below.
set(x, y, value)	this	An alias for setBit(x, y, value).
clear(value)	this	Sets all bits to the specified value.
toBox(one = fullBlock, zero = ' ')	Box	Returns a bitmap as a box.

blockWidth and blockHeight define how many bits are in each block and how they are split. In JavaScript integers can use up to 53 bits, but bitwise operators can only use up to 32 bits. It means that blockWidth * blockHeight must be less than 32 to avoid integer overflow and a possible sign extension. By default, they both are set to 5.

setBit() supports the following values:

• 0 — sets the bit to off.
• > 0 — sets the bit to on.
• < 0 — inverts the bit.

clear(value) supports zero and non-zero values to set all bits to off and on respectively.

toBox() returns a Box object with the bitmap as a box. The one and zero arguments define what symbols to use for on and off bits respectively. By default, one is set to fullBlock (█) of Module: symbols and zero is set to space ( ).

Note that visually a character is not a square but rather a rectangle roughly of 2:1 aspect ratio. Take it into account when drawing the bitmap.

Rendering one bit as a character could be wasteful. Consider using plot/to-quads.js instead, which uses quadrants instead of characters and packs four bits per character.

Exports

The Bitmap class is exported by name and as the default export.

plot/draw-line.js

The plot/draw-line.js module provides a drawLine() fiuntion to draw lines.

Function drawLine()

drawLine(bmp, x0, y0, x1, y1, value = 1) draws a line from (x0, y0) to (x1, y1) in the bitmap bmp using the specified value. By default, the value is set to 1. Internally it uses setBit() to draw pixels using the Bresenham's algorithm. See setBit() above for details on the value argument.

Exports

The drawLine() function is exported by name and as the default export.

plot/draw-rect.js

The plot/draw-rect.js module provides a drawRect() function to draw rectangles.

Function drawRect()

drawRect(bmp, x0, y0, x1, y1, value = 1) draws a rectangle in the bitmap bmp using the specified value from (x0, y0) to (x1, y1). By default, the value is set to 1. See setBit() above for details on the value argument.

Exports

The drawRect() function is exported by name and as the default export.

plot/to-quads.js

The plot/to-quads.js module provides a toQuads() function to convert a bitmap to a Box using the Unicode quadrant symbols.

Function toQuads()

toQuads(bmp) converts the bitmap bmp to a Box using the Unicode quadrant symbols. Using quadrants allows to pack four pixels per character. It makes pixels smaller and the whole picture will shrink in half in both dimensions.

See the example above.

Exports

The toQuads() function is exported by name and as the default export.