Hotspot layer
Hotspot technology is designed to load and display a large number of objects on raster layers.
When using hotspots, instead of showing thousands of individual objects, a single layer containing images of all these objects is displayed. On top of the layer with images of objects, there is another invisible layer with information about these objects and their boundaries. It allows you to make objects interactive, that is, to program the object's reaction to user actions.
The advantage of this method is that information about objects is loaded from the server only for the tile on which the mouse pointer is located.
Hotspot technology
The layer containing images of objects is called the picture layer and is formed, like any layer, from tiles. To create this layer, you need to create images of the tiles that the objects fall into when displayed on the map. The background of the tiles should be transparent.
In order for objects to become interactive, that is, they can interact with the user, a hotspot layer is drawn on top of the image layer on the map. It provides the API with information about which sections of the map should be interactive.
The interactive section of the map is called the hotspot and is represented by one or more simple geometric shapes. The hotspot is an abstract concept, it is not visible on the map.
The hotspot layer contains information about the hotspots — their position, types of their geometries, as well as some properties. This information is provided in JSON format.
To store hotspot layer data, the same tile technologies are used as for regular map layers. This means that the data is decomposed into 256x256 pixel squares, sliced for all zoom levels. Hotspot data is stored on the server.
The hotspot layer communicates with the server using MMapTileDataSource. In the settings of the data source, you can implement the fetchHotspots callback function, which sends a request for information about hotspots of the desired tile and returns data to the layer.
The layer stores hotspot data only for the tile on which the mouse pointer is located. When the user moves the mouse pointer to another tile, the layer calls fetchHotspots for data for the new tile. As soon as the function returns new data, the layer deletes the data from the previous tile. Thus, the layer does not store the previously uploaded data.
Hotspot descriptions
Hotspot descriptions should be generated separately for each tile and for all zoom levels.
The position of the shape is set in pixel coordinates relative to the upper-left corner of the corresponding tile.
There are situations when a hotspot falls into several tiles at once. When forming a description of such an area, it is not necessary to divide it into shapes along tile borders. The description is set for the entire figure. This means that the hotspot description must specify the same identifier for each tile. In this case, the coordinates of the vertices of the shape must be specified relative to the tile for which the description is being formed.
Storing hotspot data
The API does not have strict conditions on how to store hotspot data. In the fetchHotspots callback function, you can implement your own logic for receiving this data.
Usually, the description of hotspots for each tile can be stored in a separate file and placed on the server, and accessed each time it is necessary to obtain data for the desired tile:
fetchHotspots: async (x, y, zoom) => {
// form a URL to request data about hotspots in the selected tile
const url = `http://server.domain/${zoom}/${x}/${y}`;
// get data about hotspots in the selected tile as an array
const hotspotTileData = await (await fetch(url)).json();
// return data in the format expected by the hotspot layer
return hotspotTileData.map((data) => {
return {
// Hotspot type. Type 'renderer' means that pixel coordinates are used
type: 'rendered',
feature: {
// Hotspot identifier
id: data.id,
type: 'Feature',
// Hotspot properties. Can contain arbitrary data
properties: data.properties,
// Hotspot geometry in LngLat coordinates. Format is similar to geojson geometry
geometry: data.geometry
},
// Hotspot geometry in pixel coordinates. Format is similar to geojson geometry
geometry: {
// Type of pixel geometry
type: data.pixelGeometry.type,
// Pixel coordinates of the geometry
coordinates: data.pixelGeometry.coordinates
}
};
});
};
A detailed example can be found at the link.