@xyzmaps/harp-fontcatalog-generator

This module contains the necessary scripts and resources to generate a font catalog to be used with the harp.gl renderer. It includes the NotoSans-Regular font as part of the package because the script uses a glyph from that font as a fallback, in case some glyph from the font that it processes is missing.

For information about coding style or contributing, please refer to the information main project harp.gl.

Development

Prerequisites

• Node.js - Please see nodejs.org for installation instructions
• Yarn - Please see yarnpkg.com for installation instructions.

Download dependencies

Run:

yarn install

to download and install all required packages and set up the yarn workspace.

Installation

You can install it with yarn or with npm:

yarn add @xyzmaps/harp-fontcatalog-generator

or

npm install @xyzmaps/harp-fontcatalog-generator

Run unit tests in Node.js environment

Run:

yarn test

FontCatalog Description

To generate your own FontCatalog assets to use with XYZmaps:threejsl, you need to supply a JSON file containing your FontCatalog description. This file is composed of the following paremeters:

• name: FontCatalog's name (Default: Default).
• size: FontCatalog's glyph pixel size (Default: 32).
• distance: FontCatalog's glyph pixel distance (Default: 8).
• type: FontCatalog's glyph type, which could be regular SDF or MSDF (Default: SDF).
• fontsDir: Relative path to the directory where all the .ttf font files for this FontCatalog are stored.
• fonts: Array containing all the fonts to be included in this FontCatalog. Every font entry is composed of:
  • name: Font's name.
  • bold: Font's bold variant (Optional).
  • italic: Font's italic variant (Optional).
  • boldItalic: Font's boldItalic variant (Optional).
  • blocks: Array containing the specific Unicode Blocks of this font for which we want to generate glyphs (Optional).

The size, distance and type parameters influence how SDF glyphs are rasterize, and thus, can affect the quality of the output FontCatalog. To learn more about Font SDF Rasterization, visit the msdfgen repository.

FontCatalog Generation

After installing the package, just run:

harp-fontcatalog-generator -- -i <PATH_TO_DESCRIPTION> -o <OUTPUT_PATH>

Which will output assets in the following directory structure:

├── <NAME>_Assets
│   ├── Extra
│   │   ├── Specials.json
│   │   └── Specials.png
│   ├── FontA
│   │   ├── Basic_Latin.json
│   │   ├── Basic_Latin.png
│   │   └── ...
│   ├── FontB
│   │   ├── Basic_Latin.json
│   │   ├── Basic_Latin.png
│   │   └── ...
│   └── ...
├── <NAME>_BoldAssets (if any)
│   └── ...
├── <NAME>_ItalicAssets (if any)
│   └── ...
├── <NAME>_BoldItalicAssets (if any)
│   └── ...
└── <NAME>_FontCatalog.json

To use these assets with your harp.gl theme files, copy all of them to your resources folder and reference them from the theme with a relative path:

{
  "fontCatalogs" : [
    {
      "name": "<NAME>",
      "url": "./<NAME>_FontCatalog.json"
    }
  ]
}

License

Copyright (C) 2023 XYZ maps contributors

Copyright (C) 2018-2019 HERE Europe B.V.

Unless otherwise noted in a LICENSE file for specific files or directories, the code in this repository is licensed under Apache 2.0 license.

See the LICENSE file in the root of this project for license details.