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"

``sh


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

`sh


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.

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:

- --no-compress - disable built-in RLE compression.
- --no-prefilter - disable bitmap lines filter (XOR), used to improve
compression ratio.
- --no-kerning - drop kerning info to reduce size (not recommended).
- --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

$3

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.

$3

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
``