Skip to main content

sprite

A sprite is a single image that contains all the icons and style images on the map.

Images can be used to render the following style attributes: background-pattern, fill-pattern, line-pattern, fill-extrusion-pattern and icon-image.

It is defined in the style as follows:

"http://***/vt_map/sprite/sprite"

The Mapmost SDK for WebGL will use this URL template to request two sprite files to render the icons and patterns on the map.

Sprite files​

A valid sprite source must provide two types of files: index files and image files.

Index file​

The index file of the sprite map is a JSON file that contains a description of each image in the sprite map, including the image size (width and height attributes) and pixel ratio (pixelRatio) and its position (x, y) in the sprite map.

For example, a sprite containing a single image might contain the following index file content:

{
    "poi": {
        "width": 32,
        "height": 32,
        "x": 0,
        "y": 0,
        "pixelRatio": 1
    }
}

Based on the data in the sprite index file, the style can reference the image in the sprite by creating a symbol layer with the layout attribute "icon-image":"poi" or with the tag value "icon-image":"{icon}" and a vector map function with the icon attribute value poi.

In addition to the required properties width, height, x, y and pixelRatio, the following optional properties are supported:

  • content: an array composed of 4 numbers, the first two numbers specify the upper left corner, and the last two numbers specify the lower right corner. If present, and the image uses icon-text-fit, the symbol’s text will fit within the content box.
  • stretchX: a two-element array consisting of two numbers, representing the starting position and ending position of the stretchable area.
  • stretchY: Same as stretchX, but works in the vertical dimension.

Image file​

The image file for a sprite is a PNG image containing an icon.

The maximum size of a sprite is limited by WebGL MAX_TEXTURE_SIZE, which depends on the client’s GPU, but is usually at least 4096×4096 pixels.

How to create a sprite file​

You can use the [Icon Generation] function in the Mapmost Studio mapping platform to upload svg to generate the required files.

Load sprite file​

Mapmost SDK for WebGL will use the sprite property value in the style as a URL template and generate the complete URL based on these two sprite files:

  • First, for index and image files, they will have @2x appended to the URL on high dpi devices.
  • Second, they append file extensions: .json for index files and .png for image files.

For example, if you specify "sprite" in your style: "http://***/vt_map/sprite/sprite" the renderer will load the following:

  • http:///vt_map/sprite/sprite.json and http:///vt_map/sprite/sprite.png or
  • http:///vt_map/sprite/sprite@2x.json and http:///vt_map/sprite/sprite@2x.png