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.
Learn more about:
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.
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
andsprite@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.
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.
Useful links
Maps & styles basics
Layer styling
MapLibre style spec | Sprite
Comments
0 comments
Please sign in to leave a comment.