FontPixel: Opensource Pixel Fonts
bdfparser (JS/TS)
On this page

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)
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'))
if (!font) {
  throw new Error("Can't find font")
}
const glyph_j = font.glyph('j')
if (!glyph_j) {
  throw new Error("Can't find glyph")
}
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']
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
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
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)
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: ..###..
//         .##.....         ..##...
//         ###.....         .###...
//         ##......
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']
$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 numbersempty/undefinedarray 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 empty/undefined, 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)
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: ...#########............
//         .##.....        ...######...............
//         ###.....        #########...............
//         ##......        ######..................
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']
$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: .##&&&....
//         ###.....        ###&&.....
//         ##......        ##&&&.....
//                         ..&&......
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): &&##&&....
//                                          &###&.....
//                                          &##&&.....
//                                          &&&&......
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']
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]
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, xoff, yoff)

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)
// <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
xoffOptionalnumber0X position of top left corner
yoffOptionalnumber0Y position of top left corner

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: #&.....
//         #&.....
//         #&...#.
//         .####.&
//         ..&&&&.
const font = await $Font(getline('test/fonts/unifont-13.0.04.bdf'))
if (!font) {
  throw new Error('Can\'t find font')
}
const c_glyph = font.glyph("c")
if (!c_glyph) {
  throw new Error('Can\'t find glyph')
}
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"
//        ])
// 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.