Using Sprites

Map design Icons & Patterns

This collection of articles forms a suggested workflow to understanding the fundamentals of map design icons & patterns.

  1. Working with Icons
  2. Working with Patterns
  3. Using Sprites
  4. How to Add Custom Landmarks to Your Map
  5. Add custom watermark to your map

Every map can use its own set of icons for displaying points of interest, highway shields, peaks, etc. In special cases, maps can also include patterns, helping users distinguish between similar polygon features. A set of icons and patterns and a file defining which icon should be used for what purpose is called a sprite.

What is a sprite

Sprites consist of a PNG image and index JSON. Icons and patterns that can be used in a map are combined in the PNG image. A JSON file specifies the name, size, pixel ratio and position of each icon in that image.

The map JSON style loads the sprite from a URL such as this:

sprite: "https://api.maptiler.com/maps/streets-v2/sprite"

The map style can then refer to the names of the icons in the layout properties, like icon-image or fill-pattern.

Uploading sprites

To upload a sprite, choose the Raster sprites upload in MapTiler Customize.

sprite-upload.png

A Sprite typically consists of 4 files:

  • sprite.png - the image with all the icons, for example:

  • sprite.json - file describing the names and positions of the icons in the image (the names are later important when modifying the style in the Customize)
  • sprite@2x.png and sprite@2x.json - the same as above, but in higher resolution (HiDPI/retina)

You can upload these either zipped or as individual files.

Please note that to be successfully uploaded, these four files must be named precisely sprite.png, sprite.json, sprite@2x.png, and sprite@2x.json.

sprite-files.png

When you upload a new set of icons, you automatically lose the previous one. Customize currently doesn’t support multiple icon sets. 

If you need to combine your icons with the MapTiler icon set, please contact support@maptiler.com. We may be able to supply the individual SVG files for you to combine with your icons.

Generating sprites

To create a raster sprite, you can use command-line tools like Spreet.

Spreet creates sprite.png and sprite.json from SVG icons. You need to put all your icons into one folder and run Spreet with one command which is pointing to this folder. We are running it twice because of the retina version (twice magnified sprite).

spreet [input directory] sprite

spreet --retina [input directory] sprite@2x

Limits

The limit of the created output raster sprite for the map is 4000x4000px.

Uploaded raster files are restricted to the overall raster sprite limit, so there could be one image at 4000x4000px or 4 images at 1000x1000px, for example.

Next steps

Continue to How to Add Custom Landmarks to Your Map to learn how to create custom landmarks using Customize. 

Maps & styles basics
Layer styling
MapLibre style spec | Sprite