How to use image templates

Article
08/30/2024

Images can be used with HTML markers and various layers within the Azure Maps web SDK:

Symbol layers can render points on the map with an image icon. Symbols can also be rendered along a lines path.
Polygon layers can be rendered with a fill pattern image.
HTML markers can render points using images and other HTML elements.

In order to ensure good performance with layers, load the images into the map image sprite resource before rendering. The IconOptions, of the SymbolLayer, preloads a couple of marker images in a handful of colors into the map image sprite, by default. These marker images and more are available as SVG templates. They can be used to create images with custom scales, or used as a customer primary and secondary color. In total there are 42 image templates provided: 27 symbol icons and 15 polygon fill patterns.

Image templates can be added to the map image sprite resources by using the map.imageSprite.createFromTemplate function. This function allows up to five parameters to be passed in;

createFromTemplate(id: string, templateName: string, color?: string, secondaryColor?: string, scale?: number): Promise<void>

The id is a unique identifier you create. The id is assigned to the image when it's added to the maps image sprite. Use this identifier in the layers to specify which image resource to render. The templateName specifies which image template to use. The color option sets the primary color of the image and the secondaryColor options sets the secondary color of the image. The scale option scales the image template before applying it to the image sprite. When the image is applied to the image sprite, it converts into a PNG. To ensure crisp rendering, it's better to scale up the image template before adding it to the sprite, than to scale it up in a layer.

This function asynchronously loads the image into the image sprite. Thus, it returns a Promise that you can wait for this function to complete.

The following code shows how to create an image from one of the built-in templates, then use it with a symbol layer.

map.imageSprite.createFromTemplate('myTemplatedIcon', 'marker-flat', 'teal', '#fff').then(function () {

   //Add a symbol layer that uses the custom created icon.
   map.layers.add(new atlas.layer.SymbolLayer(datasource, null, {
      iconOptions: {
         image: 'myTemplatedIcon'
      }
   }));
});

Use an image template with a symbol layer

Once an image template is loaded into the map image sprite, it can be rendered as a symbol in a symbol layer by referencing the image resource ID in the image option of the iconOptions.

The Symbol layer with built-in icon template sample demonstrates how to do this by rendering a symbol layer using the marker-flat image template with a teal primary color and a white secondary color, as shown in the following screenshot.

For the source code for this sample, see Symbol layer with built-in icon template sample code.

Use an image template along a lines path

Once an image template is loaded into the map image sprite, it can be rendered along the path of a line by adding a LineString to a data source and using a symbol layer with a lineSpacingoption and by referencing the ID of the image resource in the image option of the iconOptions.

The Line layer with built-in icon template demonstrates how to do this. As show in the following screenshot, it renders a red line on the map and uses a symbol layer using the car image template with a dodger blue primary color and a white secondary color. For the source code for this sample, see Line layer with built-in icon template sample code.

Tip

If the image template points up, set the rotation icon option of the symbol layer to 90 if you want it to point in the same direction as the line.

Use an image template with a polygon layer

Once an image template is loaded into the map image sprite, it can be rendered as a fill pattern in a polygon layer by referencing the image resource ID in the fillPattern option of the layer.

The Fill polygon with built-in icon template sample demonstrates how to render a polygon layer using the dot image template with a red primary color and a transparent secondary color, as shown in the following screenshot. For the source code for this sample, see Fill polygon with built-in icon template sample code.

Tip

Setting the secondary color of fill patterns makes it easier to see the underlying map will still providing the primary pattern.

Use an image template with an HTML marker

An image template can be retrieved using the atlas.getImageTemplate function and used as the content of an HTML marker. The template can be passed into the htmlContent option of the marker, and then customized using the color, secondaryColor, and text options.

The HTML Marker with built-in icon template sample demonstrates this using the marker-arrow template with a red primary color, a pink secondary color, and a text value of "00", as shown in the following screenshot. For the source code for this sample, see HTML Marker with built-in icon template sample code.

Tip

Image templates can be used outside of the map too. The getImageTemplate function returns an SVG string that has placeholders; {color}, {secondaryColor}, {scale}, {text}. Replace these placeholder values to create a valid SVG string. You can then either add the SVG string directly to the HTML DOM or convert it into a data URI and insert it into an image tag. For example:

//Retrieve an SVG template and replace the placeholder values.
var svg = atlas.getImageTemplate('marker').replace(/{color}/, 'red').replace(/{secondaryColor}/, 'white').replace(/{text}/, '').replace(/{scale}/, 1);

//Convert to data URI for use in image tags.
var dataUri = 'data:image/svg+xml;base64,' + btoa(svg);

Create custom reusable templates

If your application uses the same icon within different modules or if you're creating a module that adds more image templates, you can easily add and retrieve these icons from the Azure Maps web SDK. Use the following static functions on the atlas namespace.

Name	Return Type	Description
`addImageTemplate(templateName: string, template: string, override: boolean)`		Adds a custom SVG image template to the atlas namespace.
`getImageTemplate(templateName: string, scale?: number)`	string	Retrieves an SVG template by name.
`getAllImageTemplateNames()`	string[]	Retrieves an SVG template by name.

SVG image templates support the following placeholder values:

Placeholder	Description
`{color}`	The primary color.
`{secondaryColor}`	The secondary color.
`{scale}`	The SVG image is converted to an png image when added to the map image sprite. This placeholder can be used to scale a template before it's converted to ensure it renders clearly.
`{text}`	The location to render text when used with an HTML Marker.

The Add custom icon template to atlas namespace sample demonstrates how to take an SVG template, and add it to the Azure Maps web SDK as a reusable icon template, as shown in the following screenshot. For the source code for this sample, see Add custom icon template to atlas namespace sample code.

List of image templates

This table lists all image templates currently available within the Azure Maps web SDK. The template name is above each image. By default, the primary color is blue and the secondary color is white. To make the secondary color easier to see on a white background, the following images have the secondary color set to black.

Symbol icon templates

marker

marker-thick

marker-circle

marker-flat

marker icon

marker-thick icon

marker-circle icon

marker-flat icon

marker-square

marker-square-cluster

marker-arrow

marker-ball-pin

marker-square icon

marker-square-cluster icon

marker-ball-pin icon

marker-square-rounded

marker-square-rounded-cluster

flag

flag-triangle

marker-square-rounded icon

marker-square-rounded-cluster icon

triangle

triangle-thick

triangle-arrow-up

triangle-arrow-left

triangle icon

triangle-thick icon

hexagon

hexagon-thick

hexagon-rounded

hexagon-rounded-thick

hexagon icon

hexagon-thick icon

hexagon-rounded icon

hexagon-rounded-thick icon

pin-round

rounded-square

rounded-square-thick

pin icon

pin-round icon

rounded-square icon

rounded-square-thick icon

arrow-up

arrow-up-thin

car

car icon

Polygon fill pattern templates

checker

checker-rotated

circles

circles-spaced

checker icon

checker-rotated icon

circles icon

circles-spaced icon

diagonal-lines-up

diagonal-lines-down

diagonal-stripes-up

diagonal-stripes-down

diagonal-lines-up icon

diagonal-lines-down icon

diagonal-stripes-up icon

diagonal-stripes-down icon

grid-lines

rotated-grid-lines

rotated-grid-stripes

x-fill

grid-lines icon

rotated-grid-lines icon

rotated-grid-stripes icon

x-fill icon

zig-zag

zig-zag-vertical

dots

zig-zag icon

zig-zag-vertical icon

dots icon

Preloaded image icons

The map preloads a set of icons into the maps image sprite using the marker, pin, and pin-round templates. These icon names and their color values are listed in the following table.

icon name	color	secondaryColor
`marker-black`	`#231f20`	`#ffffff`
`marker-blue`	`#1a73aa`	`#ffffff`
`marker-darkblue`	`#003963`	`#ffffff`
`marker-red`	`#ef4c4c`	`#ffffff`
`marker-yellow`	`#f2c851`	`#ffffff`
`pin-blue`	`#2072b8`	`#ffffff`
`pin-darkblue`	`#003963`	`#ffffff`
`pin-red`	`#ef4c4c`	`#ffffff`
`pin-round-blue`	`#2072b8`	`#ffffff`
`pin-round-darkblue`	`#003963`	`#ffffff`
`pin-round-red`	`#ef4c4c`	`#ffffff`

Try it now tool

With the following tool, you can render the different built-in image templates in various ways and customize the primary and secondary colors and scale.