Bitmap object

Bitmap() and $Bitmap() shortcut#

Syntax#

new Bitmap(bin_bitmap_list)
// is equivalent to
$Bitmap(bin_bitmap_list)

Examples#

const bitmap_quoteright = $Bitmap([
'01110000',
'01110000',
'01110000',
'01100000',
'11100000',
'11000000',
])
const bitmap_quoteright2 = $Bitmap([
'01110',
'02110',
'01102',
'10200',
'01000',
])
// but usually you get the `Bitmap` object from a `Font` or its `Glyph`
const font = await $Font(getline('test/fonts/spec_example_fixed.bdf'))
const glyph_j = font.glyph('j')
const bitmap_j = glyph_j.draw(2)

Parameters#

NameR/OTypeDefault ValueDescription
bin_bitmap_listRequiredarray of stringsN/ABinary bitmap data, which is a array of '0'/'1'/'2' strings

Return value#

Bitmap object

Description#

Initialize a Bitmap object. Load binary bitmap data (array of strings).

The shortcut $Bitmap(bin_bitmap_list) is equivalent to new Bitmap(bin_bitmap_list), use it for convenience.

.bindata#

Syntax#

.bindata

Examples#

console.log(bitmap_quoteright2.bindata)
// ['01110',
// '02110',
// '01102',
// '10200',
// '01000']

Type#

array of strings

Description#

This attribute of a Bitmap object represents the raw binary data of the bitmap.

note

If you want to get the data, use API methods .todata() or .tobytes() instead.

.width()#

Syntax#

.width()

Examples#

bitmap_quoteright.width() // 8

Parameters#

No parameters

Return value#

(number) Width of the bitmap

Description#

Get the width of the bitmap.

.height()#

Syntax#

.height()

Examples#

bitmap_quoteright.height() // 6

Parameters#

No parameters

Return value#

(number) Height of the bitmap

Description#

Get the height of the bitmap.

.clone()#

Syntax#

.clone()

Examples#

const cloned_bitmap_quoteright = bitmap_quoteright.clone()
console.log(
cloned_bitmap_quoteright ===
bitmap_quoteright
) // false (different object)
console.log(
cloned_bitmap_quoteright.bindata ===
bitmap_quoteright.bindata
) // true (bindata also different)
console.log(
JSON.stringify(cloned_bitmap_quoteright.bindata) ===
JSON.stringify(bitmap_quoteright.bindata)
) // true (but have same value inside)

Parameters#

No parameters

Return value#

(Bitmap object) A deep copy of the original Bitmap object

Description#

Get a deep copy / clone of the Bitmap object.

.crop()#

Syntax#

.crop(w, h, xoff, yoff)

Examples#

bitmap_quoteright.crop(7, 4, -1, 1)
// .###....
// .###.... ..###..
// before: .###.... after: ..###..
// .##..... ..##...
// ###..... .###...
// ##......

Before:

After:

Parameters#

NameR/OTypeDefault ValueDescription
wRequirednumberN/AWidth of the new bitmap
hRequirednumberN/AHeight of the new bitmap
xoffOptionalnumber0Relative position in x (right) direction of the new starting (bottom-left) point from the old one
yoffOptionalnumber0Relative position in y (top) direction of the new starting (bottom-left) point from the old one

Return value#

The Bitmap object itself, which now has only the specified area as its .bindata.

(Consider to use .clone() first, if you want to maintain the original copy of the Bitmap object)

Description#

Crop and/or extend the bitmap.

.overlay()#

Syntax#

.overlay(bitmap)

Examples#

$Bitmap(['010',
'201']).overlay(
$Bitmap(['100',
'122'])).bindata
// ['110',
// '122']

Parameters#

NameR/OTypeDefault ValueDescription
bitmapRequiredBitmap objectN/AThe incoming bitmap to overlay over the current one

Return value#

The Bitmap object itself, which now has the combined bitmap as its .bindata.

Description#

Overlay another bitmap over the current one.

note

This method mutates the Bitmap object. Consider to use .clone() first, if you want to maintain the original copy of the Bitmap object.

Bitmap.concatall()#

Syntax#

Bitmap.concatall(bitmaplist, options)
// options = {direction, align, offsetlist}

Examples#

Bitmap.concatall([bitmap_quoteright, bitmap_j, bitmap_quoteright2])
Click to see the `.toString()` output of the result above
..............###............
..............###............
..............###............
..............###............
.............................
.............###.............
.............###.............
.............###.............
.............###.............
............###..............
............###..............
............###..............
............###..............
............###..............
...........###...............
...........###...............
.###.......###...............
.###.......###...........###.
.###......#.##...........&##.
.##......####............##.&
###.....####............#.&..
##......###..............#...
Bitmap.concatall([bitmap_quoteright, bitmap_j, bitmap_quoteright2], {offsetlist: [-3, 4]})
Click to see the `.toString()` output of the result above
...........###................
...........###................
...........###................
...........###................
..............................
..........###.................
..........###.................
..........###.................
..........###.................
.........###..................
.........###..................
.........###..................
.........###..................
.........###..................
........###...................
........###...................
.###....###...................
.###....###...............###.
.###...#.##...............&##.
.##...####................##.&
###..####................#.&..
##...###..................#...
Bitmap.concatall([bitmap_quoteright, bitmap_j, bitmap_quoteright2], {direction: 0})
Click to see the `.toString()` output of the result above
.###............
.###............
.###............
.##.............
###.............
##..............
......###.......
......###.......
......###.......
......###.......
................
.....###........
.....###........
.....###........
.....###........
....###.........
....###.........
....###.........
....###.........
....###.........
...###..........
...###..........
...###..........
...###..........
..#.##..........
.####...........
####............
###.............
.###............
.&##............
.##.&...........
#.&.............
.#..............
Bitmap.concatall([bitmap_quoteright, bitmap_j, bitmap_quoteright2], {align: 0})
Click to see the `.toString()` output of the result above
.###..........###........###.
.###..........###........&##.
.###..........###........##.&
.##...........###.......#.&..
###......................#...
##...........###.............
.............###.............
.............###.............
.............###.............
............###..............
............###..............
............###..............
............###..............
............###..............
...........###...............
...........###...............
...........###...............
...........###...............
..........#.##...............
.........####................
........####.................
........###..................
Bitmap.concatall([bitmap_quoteright, bitmap_j, bitmap_quoteright2], {direction: 0, align: 0})
Click to see the `.toString()` output of the result above
.........###....
.........###....
.........###....
.........##.....
........###.....
........##......
......###.......
......###.......
......###.......
......###.......
................
.....###........
.....###........
.....###........
.....###........
....###.........
....###.........
....###.........
....###.........
....###.........
...###..........
...###..........
...###..........
...###..........
..#.##..........
.####...........
####............
###.............
............###.
............&##.
............##.&
...........#.&..
............#...

Parameters#

NameR/OTypeDefault ValueDescription
bitmaplistRequiredarray of Bitmap objectsN/Aarray of bitmaps to concatenate
(in options) directionOptionalnumber11: right
0: down
2: left
-1: up
(in options) alignOptionalnumber1If horizontal (right (1) or left (2)) direction:
1: bottom
0: top
If vertical (down (0) or up (-1)) direction:
1: left
0: right
(in options) offsetlistOptionalarray of numbersNonearray of spacing offsets between every two glyphs: [offset_between_0_and_1, offset_between_1_and_2, ..., offset_between_2nd_last_and_last]. len(offsetlist) should be equal to len(bitmaplist)-1. If None, then all offsets are 0

Return value#

Bitmap object

Description#

Concatenate all Bitmap objects in a array.

This is a class / static method, meaning you need to call the method on the Bitmap class: Bitmap.concatall()

.concat()#

Syntax#

.concat(bitmap, options)
// options = {direction, align, offset}

Examples#

bitmap_quoteright.concat(bitmap_j)

Parameters#

NameR/OTypeDefault ValueDescription
bitmapRequiredBitmap objectN/ABitmap to concatenate
(in options) offsetRequirednumber0Spacing offset between the glyphs. See also offsetlist parameter in Bitmap.concatall()

For the rest of the parameters (direction, align in options), see Bitmap.concatall()'s "Parameters" section

Return value#

The Bitmap object itself, which now has the combined bitmap as its .bindata.

Description#

Concatenate another Bitmap objects to the current one.

It is similar to Bitmap.concatall([bitmap1, bitmap2]), but update the current Bitmap object and return it, instead of creating a new one like the other two methods.

note

This method mutates the Bitmap object. If you want to maintain the original copy of the Bitmap object, consider to use Bitmap.concatall() or .clone() first.

.enlarge()#

Syntax#

.enlarge(x, y)

Examples#

bitmap_quoteright.enlarge(3, 1)
// .###.... ...#########............
// .###.... ...#########............
// before: .###.... after: ...#########............
// .##..... ...######...............
// ###..... #########...............
// ##...... ######..................

Before:

After:

Parameters#

NameR/OTypeDefault ValueDescription
xOptionalnumber1Multiplier in x (right) direction
yOptionalnumber1Multiplier in y (top) direction

Return value#

The Bitmap object itself, which now has the enlarged bitmap as its .bindata.

Description#

Enlarge a Bitmap object, by multiplying every pixel in x (right) direction and in y (top) direction.

.replace()#

Syntax#

.replace(substr, newsubstr)

Examples#

$Bitmap(['0121',
'2200']).replace(2, 1).bindata
// ['0111',
// '1100']

Parameters#

NameR/OTypeDefault ValueDescription
substrRequiredstringsN/ASubstring to be replaced
newsubstrRequiredstringsN/ANew substring as the replacement

Return value#

The Bitmap object itself, which now has the altered bitmap as its .bindata.

Description#

Replace a string by another in the bitmap. Because the bitmap's data is stored as a array of '0'/'1'/'2' strings (e.g. ['0211','1010','0200']), you can replace a substring (e.g. '2' by '1') in it.

.shadow()#

Syntax#

.shadow(xoff, yoff)

Examples#

bitmap_quoteright.shadow(2, -1)
// .###.... .###......
// .###.... .###&&....
// .###.... .###&&....
// before: .##..... after: .##&&&....
// ###..... ###&&.....
// ##...... ##&&&.....
// ..&&......

Before:

After:

Parameters#

NameR/OTypeDefault ValueDescription
xoffOptionalnumber1Shadow's offset in x (right) direction
yoffOptionalnumber-1Shadow's offset in y (top) direction

Return value#

The Bitmap object itself, which now has a bitmap of the original shape with its shadow as the Bitmap object's .bindata.

Description#

Add shadow to the shape in the bitmap.

The shadow will be filled by '2's.

Default parameters (xoff=1, yoff=-1) mean add a shadow which is 1 pixel right and 1 pixel bottom to the original shape.

.glow()#

Syntax#

.glow()

Examples#

bitmap_quoteright.glow()
// ..&&&.....
// .###.... .&###&....
// .###.... .&###&....
// .###.... .&###&....
// before: .##..... after (default mode 0): .&##&.....
// ###..... &###&.....
// ##...... &##&......
// .&&.......
bitmap_quoteright.glow(1)
// .&&&&&....
// .&###&....
// .&###&....
// .&###&....
// after (mode 1): &&##&&....
// &###&.....
// &##&&.....
// &&&&......

Before:

After (default mode 0):

After (mode 1):

Parameters#

NameR/OTypeDefault ValueDescription
modeOptionalinteger0Mode. Corner pixels will not be filled in default mode 0 but will in mode 1

Return value#

The Bitmap object itself, which now has a bitmap of the original shape with glow effect as the Bitmap object's .bindata.

Description#

Add glow effect to the shape in the bitmap.

The glowing area is one pixel up, right, bottom and left to the original pixels (corners will not be filled in default mode 0 but will in mode 1), and will be filled by '2's.

.bytepad()#

Syntax#

.bytepad(bits)

Examples#

bitmap_quoteright2.bytepad().bindata
// ['01110', ['01110000',
// '02110', '02110000',
// before: '01102', after: '01102000',
// '10200', '10200000',
// '01000'] '01000000']

Parameters#

NameR/OTypeDefault ValueDescription
bitsOptionalnumber8Each line should be padded to multiple of how many bits/pixels

Return value#

The Bitmap object itself, which now has the altered bitmap as its .bindata.

Description#

Pad each line (row) to multiple of 8 (or other numbers) bits/pixels, with '0's.

Do this before using the bitmap for a glyph in a BDF font: per BDF spec, if the bit/pixel count in a line is not multiple of 8, the line needs to be padded on the right with 0s to the nearest byte (that is, multiple of 8).

Parameter bits is 8 by default because 1 byte = 8 bits, you can change it if you want to use other unconventional, off-spec values, such as 4 (half a byte).

.todata()#

Syntax#

.todata(datatype)

Examples#

const bitmap1 = $Bitmap(['00010', '11010', '00201'])
const bitmap2 = $Bitmap(['00010', '11010'])
bitmap1.todata(0) // '00010\n11010\n00201'
bitmap1.todata() // ['00010', '11010', '00201']
bitmap1.todata(2) // [[0, 0, 0, 1, 0], [1, 1, 0, 1, 0], [0, 0, 2, 0, 1]]
bitmap1.todata(3) // [0, 0, 0, 1, 0, 1, 1, 0, 1, 0, 0, 0, 2, 0, 1]
bitmap2.todata(4) // ['02', '1a']
bitmap2.todata(5) // [2, 26]

Parameters#

NameR/OTypeDefault ValueDescription
datatypeOptionalSee below1Output data type. See below

datatype: output data type:

  • 0: binary-encoded multi-line string. e.g. '00010\n11010\n00201'
  • 1: array of binary-encoded strings. e.g. ['00010','11010','00201']
  • 2: array of arrays of numbers 0 or 1 (or 2 sometimes). e.g. [[0,0,0,1,0],[1,1,0,1,0],[0,0,2,0,1]]
  • 3: array of numbers 0 or 1 (or 2 sometimes) (to be used with .width() and .height()). e.g. [0,0,0,1,0,1,1,0,1,0,0,0,2,0,1]
  • 4: array of lowercase hexadecimal-encoded strings (without '0x', padded with leading '0's according to width). e.g. ['02','1a']
  • 5: array of numbers. e.g. [2,26]
note

You can't have '2's when using datatype 4 or 5.

Return value#

Bitmap data in the specified type (array or string) and format

Description#

Get the bitmap's data in the specified type and format.

.draw2canvas()#

Syntax#

.draw2canvas(context, pixelcolors)

Examples#

// <canvas id="mycanvas"></canvas> in HTML
const canvas = document.getElementById('mycanvas')
const context = canvas.getContext('2d')
const glowing_bitmap_quoteright = bitmap_quoteright.glow(1)
glowing_bitmap_quoteright.draw2canvas(context)

Parameters#

NameR/OTypeDefault ValueDescription
contextRequiredCanvasContextN/ACanvas context, see above example
pixelcolorsOptionalobjectsee belowPixel color map

By default, parameter pixelcolors is set to:

{
'0': null,
'1': 'black',
'2': 'red',
}

'0' defines background color, '1' defines foreground color, '2' defines shadow or glowing effect color. The color can be hex color value (e.g. #000000), CSS color keyword or anything CanvasRenderingContext2D.fillStyle accepts.

Return value#

The Bitmap object itself.

Description#

Draw the bitmap to HTML <canvas> element.

.toString()#

Syntax#

.toString()

Examples#

const font = await $Font(getline('test/fonts/unifont-13.0.04.bdf'))
const c_glyph = font.glyph("c")
const c_bitmap = c.draw().crop(6, 8, 1, 2).shadow()
console.log(c_bitmap.toString())
// .####..
// #.&&&#.
// #&....&
// #&.....
// output: #&.....
// #&.....
// #&...#.
// .####.&
// ..&&&&.

Description#

(string) .toString() gets a human-readable (multi-line) string representation of the Bitmap object.

The following digits in the bitmap's binary-encoded string array data are replaced in .toString()'s output:

  • '0's are replaced by #
  • '1's are replaced by .
  • '2's are replaced by &

.repr()#

Syntax#

.repr()

Examples#

// use `c_bitmap` again in the last example
console.log(c_bitmap.repr())
// Bitmap([
// "0111100",
// "1022210",
// "1200002",
// output: "1200000",
// "1200000",
// "1200000",
// "1200010",
// "0111102",
// "0022220"
// ])

Description#

(string) It gets a programmer-readable (multi-line) string representation of the Bitmap object.

Edit this page