lv_font_conv - font convertor to compact bitmap format

Converts TTF/WOFF/OTF fonts to compact format, suitable for small embedded systems. Main features are:

• Allows bitonal and anti-aliased glyphs (1-4 bits per pixel).
• Preserves kerning info.
• Compression.
• Users can select required glyphs only (subsetting).
• Multiple font sources can be merged.
• Simple CLI interface, easy to integrate into external build systems.

Install the script

node.js v14+ required.

Global install of the last version, execute as "lv_font_conv"

# install release from npm registry
npm i lv_font_conv -g
# install from github's repo, master branch
npm i lvgl/lv_font_conv -g

run via npx without install

# run from npm registry
npx lv_font_conv -h
# run from github master
npx github:lvgl/lv_font_conv -h

Note, running via npx may take some time until modules installed, be patient.

CLI params

Common:

• --bpp - bits per pixel (antialiasing).
• --size - output font size (pixels).
• -o, --output - output path (file or directory, depends on format).
• --format - output format.
  • --format dump - dump glyph images and font info, useful for debug.
  • --format bin - dump font in binary form (as described in spec).
  • --format lvgl - dump font in LVGL format.
• --force-fast-kern-format - always use more fast kering storage format, at cost of some size. If size difference appears, it will be displayed.
• --lcd - generate bitmaps with 3x horizontal resolution, for subpixel smoothing.
• --lcd-v - generate bitmaps with 3x vertical resolution, for subpixel smoothing.
• --use-color-info - try to use glyph color info from font to create grayscale icons. Since gray tones are emulated via transparency, result will be good on contrast background only.
• --lv-include - only with --format lvgl, set alternate path for lvgl.h.
• --no-compress - disable built-in RLE compression.
• --no-prefilter - disable bitmap lines filter (XOR), used to improve compression ratio.
• --byte-align - pad the line ends of the bitmaps to a whole byte (requires --no-compress and --bpp != 3)
• --no-kerning - drop kerning info to reduce size (not recommended).

Per font:

• --font - path to font file (ttf/woff/woff2/otf). May be used multiple time for merge.
• -r, --range - single glyph or range + optional mapping, belongs to previously declared --font. Can be used multiple times. Examples:
  • -r 0x1F450 - single value, dec or hex format.
  • -r 0x1F450-0x1F470 - range.
  • -r '0x1F450=>0xF005' - single glyph with mapping.
  • -r '0x1F450-0x1F470=>0xF005' - range with mapping.
  • -r 0x1F450 -r 0x1F451-0x1F470 - 2 ranges.
  • -r 0x1F450,0x1F451-0x1F470 - the same as above, but defined with single -r.
• --symbols - list of characters to copy (instead of numeric format in -r).
  • --symbols 0123456789., - extract chars to display numbers.
• --autohint-off - do not force autohinting ("light" is on by default).
• --autohint-strong - use more strong autohinting (will break kerning).

Additional debug options:

• --full-info - don't shorten 'font_info.json' (include pixels data).

Examples

Merge english from Roboto Regular and icons from Font Awesome, and show debug info:

env DEBUG=* lv_font_conv --font Roboto-Regular.ttf -r 0x20-0x7F --font FontAwesome.ttf -r 0xFE00=>0x81 --size 16 --format bin --bpp 3 --no-compress -o output.font

Merge english & russian from Roboto Regular, and show debug info:

env DEBUG=* lv_font_conv --font Roboto-Regular.ttf -r 0x20-0x7F -r 0x401,0x410-0x44F,0x451 --size 16 --format bin --bpp 3 --no-compress -o output.font

Dump all Roboto glyphs to inspect icons and font details:

lv_font_conv --font Roboto-Regular.ttf -r 0x20-0x7F --size 16 --format dump --bpp 3 -o ./dump

Note. Option --no-compress exists temporary, to avoid confusion until LVGL adds compression support.

Technical notes

Supported output formats

1. bin - universal binary format, as described in https://github.com/lvgl/lv_font_conv/tree/master/doc.
2. lvgl - format for LVGL, C file. Has minor limitations and a bit bigger size, because C does not allow to effectively define relative offsets in data blocks.
3. dump - create folder with each glyph in separate image, and other font data as json. Useful for debug.

Merged font metrics

When multiple fonts merged into one, sources can have different metrics. Result will follow principles below:

1. No scaling. Glyphs will have exactly the same size, as intended by font authors.
2. The same baseline.
3. OS/2 metrics (sTypoAscender, sTypoDescender, sTypoLineGap) will be used from the first font in list.
4. hhea metrics (ascender, descender), defined as max/min point of all font glyphs, are recalculated, according to new glyphs set.

Development

Current package includes WebAssembly build of FreeType with some helper functions. Everything is wrapped into Docker and requires zero knowledge about additional tools install. See package.json for additional commands. You may need those if decide to upgrade FreeType or update helpers.

This builds image with emscripten & freetype, usually should be done only once:

npm run build:dockerimage

This compiles helpers and creates WebAssembly files:

npm run build:freetype