Create custom sprites

Overview of the tutorial

This tutorial shows you can create custom sprites for usage in your vector map styles. You will do the following:

• Create new sprites out of chosen icons
• Test new sprites

Prerequesites

• API key
• Npm and Node.js
• Git
• (Optional) Operating system with a command line compatible with POSIX standard:
  • any Linux distibution
  • MacOS
  • Windows with Cygwin or MinGW

We recommend you to have npm and Node.js already installed on your machine to quickly boot up a http server to display the page we will create.

Introduction

A sprite is an image which groups smaller icons. This technique of concatenating images into a larger one is a common solution to improve performance. In our case a sprite source defined in a style consists of two files:

• image file - it is a regular sprite file in a png format
• index file - it is a descriptor file in a json format containg information about positions of icons inside a sprite(image) file

Icons contained in a sprite may be used as values to following style properties: background-pattern, fill-pattern, line-pattern, and icon-image.

Mapbox Style Specification allows another sprites set to be defined for high-DPI devices. In that case it should consists of two files named exactly the same as sprites defined for regular-DPI devices but with a "@2x" suffix, e.g.

• regular-DPI: sprite.png, sprite.json
• high-DPI: sprite@2x.png, sprite@2x.json

If you want to know more about sprites go here.

Let's start!

Step 1. Prepare directory structure

Create a new directory which will contain all assets needed for this tutorial. I called it "sprites-tutorial" and it will be the root directory for all other directories created here. You may achieve this by typing:

mkdir sprites-tutorial

Step 2. Download sample icons

You need to download sample icons which will be part of a new sprite. Any icons would suffice but for this tutorial I suggest using the following:

• can by Natalia Matayoshi from the Noun Project
• barrel by Grant Taylor from the Noun Project

Create an "icons" directory in "sprites-tutorial" and download above icons there. Name them "can.svg" and "barrel.svg" respectively. Type following commands to do that:

mkdir icons
cd icons
wget https://thenounproject.com/term/can/38756/ -O can.svg
wget https://thenounproject.com/term/barrel/412229 -O barrel.svg

Step 3. Clone spritezero-cli tool from github

You need a tool which will combine icons into a single png file and produce a descriptor file. To achieve this, clone "spritezero-cli" repository from github by typing following in "sprites-tutorial" directory:

git clone https://github.com/mapbox/spritezero-cli

Now install all its dependencies:

npm install

Step 4. Create sprite files

Create a "sprites" directory in "sprites-tutorial" directory - it will contain our sprites files. After this use "spritezero-cli" to generate our sprites. Name result sprite files "sprite.png" and "sprite.json" respectively. You achieve these tasks by typing:

mkdir "sprites"
spritezero-cli/bin/spritezero sprites/sprite icons/

Our sprite files are ready. Now you need to test them.

Step 5. Download offline examples

In order to test our sprite files let's download offline examples of our SDK from a download page. If you need assistance with this task read this "Running examples locally" tutorial. Few things to remember:

• extract an examples app to "examples" directory under "sprites-tutorial" directory
• remember to provide API keys

Step 6. Replace old sprites by new one

After completing previous step you should end up with "examples" directory with a content similar to this one:

You see there a directory called "sdk". It contains our SDK including sprites, glyphs and styles.

Now you need to replace old sprites with new one. Old ones are in a "sprites" directory under an "sdk" directory - remove all of them. New ones are in a "sprites" directory under a "sprites-tutorial" directory - copy all of them to a "sprites" directory which stored the old ones. To achieve these tasks, type the following from "sprites-tutorial" directory:

rm examples/sdk/sprites/*
cp sprites/* examples/sdk/sprites/

Step 7. Modify a style

Since our icons names are different than those in old sprites we need to modify a style in order to use the new ones. "basic_main.json" style may be found in "styles" directory. In this file replace all "{icon}" placeholders with an icon name of your choice. It will cause that this icon will be rendered as any road shield. In our tutotial we will use the "can" icon but you are free to experiment with a "barrel".

In the "sprites-tutorial" directory create another directory called "sprites-replacer". Inside this new directory create a file called "replacer.js" and copy there the following code:

var fs = require('fs')
var path = require('path');

if (process.argv.length !== 4) {
    console.log('Expected icon name and styles file');
    process.exit(1);
}

var glyphsName = process.argv[2];
var stylesFilePath = path.resolve(process.argv[3]);

fs.readFile(stylesFilePath, 'utf8', function (err,data) {
  if (err) {
    return console.log(err);
  }
  var result = data.replace(/\{icon\}/gim, glyphsName);

  fs.writeFile(stylesFilePath, result, 'utf8', function (err) {
     if (err) return console.log(err);
  });
});

You may achieve this by typing following from "sprites-tutorial" directory:

node sprites-replacer/replacer.js can examples/sdk/styles/basic_main.json

Step 8. Run examples app

Go to an "examples" directory and type following:

npm install && npm start

Next go to http://localhost:8080/#map-vector-basic and after zooming in couple of times you may see similar picture: