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.
API keys
To get an API key:
- Register/Sign in to TomTom Developer Portal.
- Request an evaluation API key to access the service you want to use the SDK with.
Note - It is possible to have a single key(app) for all TomTom services, but you can also choose to have individual keys for the different services.
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:
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: