Skip to content

Bundle the basemaps assets archive

This guide explains how to generate the basemaps bundled assets archive using the basemaps/cli package.

Get started

Clone the linz/basemaps-config repository to your machine.

git clone https://github.com/linz/basemaps-config.git

git clone git@github.com:linz/basemaps-config.git

gh repo clone linz/basemaps-config

Paths

This guide uses variables as shorthand to reference key directories and files. On your machine, note the following paths:

The path to the basemaps-config repository folder on your machine.

$BM_CONFIG_REPO = {path_to}/basemaps-config

The basemaps/cli package provides a bundle-assets function we can use to generate a bundled assets archive.

The path to the build folder of the basemaps/cli package.

$BM_CLI_BUILD = $BM_REPO/packages/cli/build/cli

The basemaps/sprites package provides a default function we can use to generate sprite sheets from a collection of sprite images.

The path to the bin folder of the basemaps/sprites package.

$BM_SPRITES_BIN = $BM_REPO/packages/sprites/bin

Generate the basemaps assets

1. Create local directory

To prepare for bundling the basemaps assets archive, create a local directory on your machine with the following subdirectory structure:

- assets
  - fonts
  - sprites

You can specify a location and directory name of your choice.

Path

On your machine, consider the following path:

The path to the created directory on your machine.

$ASSETS_DIR = {path_to_directory}

2. Convert fonts into .pbf (protobuf-encoded glyphs) files

To generate the basemaps .pbf files, follow the instructions described in this README.md file. Alternatively, there is a repository containing various fonts that have already been converted into the .pbf format.

Move the generated and/or downloaded collections of .pbf files into the following directory:

$ASSETS_DIR/assets/fonts

The contents of your $ASSETS_DIR/assets/fonts directory should look similar to the following:

- $ASSETS_DIR/assets/fonts
  - Noto Sans Bold
    - 0-255.pbf
    - ...
  - Open Sans Bold
    - 0-255.pbf
    - ...

3. Convert sprite files into sprite sheets

Use the following command to generate the basemaps sprite sheets from the collection of topographic sprite files:

node $BM_SPRITES_BIN/basemaps-sprites.mjs \
$BM_CONFIG_REPO/config/sprites/topographic

The above command will output the resulting sprite sheets to the location from which you executed the command. Move the outputted files into the following directory:

$ASSETS_DIR/assets/sprites

The contents of your $ASSETS_DIR/assets/sprites directory should look similar to the following:

- $ASSETS_DIR/assets/sprites
  - topographic.json
  - topographic.png
  - topographic@2x.json
  - topographic@2x.png

Run the basemaps/cli package

Command

Use the following command to bundle the basemaps assets archive:

node $BM_CLI_BUILD/bin.js bundle-assets \
    --assets $ASSETS_DIR \
    --output assets.bundle.tar.co \

Parameters

Specifies the location of the assets folder to use. This folder refers to that which contains the .pbf files and sprite sheets on your local machine.

Specifies where to save the bundled assets archive, relative to the location from which you execute the command. You can specify a location and filename of your choice.