Skip to main content

Overlays

|

An Overlay is an additional map layer, either default or user-defined, with data stored on Magic Lane servers, accessible in online and offline modes, with few exceptions.

In order to define overlay data, you can use the Magic Lane Map Studio. It allows uploading data regarding the POIs and their corresponding categories and binary information (via GeoJSON format). An Overlay can have multiple associated categories and subcategories. A single item from an overlay is called an overlay item.

OverlayInfo​

OverlayInfo is the class that contains information about an overlay.

OverlayInfo structure​

The class that contains information about an overlay is OverlayInfo. It has the following structure:

Property / MethodDescriptionType
uidGets the unique ID of the overlay.number
categoriesGets the categories of the overlay.OverlayCategory[]
getCategory(categId: number)Gets a category by its ID.OverlayCategory | null
imgGets the Img object of the overlay.Img
imageGets the image of the overlay as Uint8Array.Uint8Array | null
nameGets the name of the overlay.string
hasCategories(categId: number)Checks if the category has subcategories.boolean

Usage​

The primary function of the OverlayInfo class is to provide the categories within an overlay. It also provides the uid of the overlay which can be used to filter the results of search and also can be used to toggle the visibility of the overlay on the map. Other fields can be displayed on the UI.

OverlayCategory​

The OverlayCategory class represents hierarchical data related to overlay categories.

OverlayCategory structure​

The OverlayCategory has the following structure:

Property / MethodDescriptionType
uidThe category ID.number
overlayuidThe parent overlay ID. Refers to the id of the OverlayInfo objectnumber
imgThe category icon as Img object.Img
imageThe category icon as Uint8Array.Uint8Array | null
nameThe category name.string
subcategoriesThe subcategories of the category.OverlayCategory[]
hasSubcategoriesChecks if the category has subcategories.boolean

Usage​

The OverlayCategory class provides the category uid, which can be utilized in various search functionalities to filter results. Additionally, the uid can be used to filter and manage overlay items that trigger alerts within the AlarmService.

OverlayItem​

An OverlayItem represents a single item within an overlay. It contains specific information about that item but also about the overlay it is part of.

OverlayItem structure​

The OverlayItem has the following structure:

Property / MethodDescriptionType
categoryIdGets the OverlayItem's category ID. May be 0 if the item does not belong to a specific category. Gives the id of the root category which may not be the direct parent category.number
coordinatesGets the coordinates of the OverlayItem.Coordinates
hasPreviewExtendedDataChecks if the OverlayItem has preview extended data (dynamic data). Available only for overlays predefined.boolean
imgGets the Img object of the OverlayItem.Img
imageGets the image of the OverlayItem as Uint8Array.Uint8Array
nameGets the name of the OverlayItem.string
uidGets the unique ID of the OverlayItem within the overlay.number
overlayInfoGets the parent OverlayInfo.OverlayInfo | null
previewDataGets the OverlayItem preview data as a parameters list.SearchableParameterList
previewDataJsonGets the OverlayItem preview data as a JSON object.any
previewUrlGets the preview URL for the item (if any).string
overlayUidGets the parent overlay UID.number
isOfType(overlayId: CommonOverlayId)Checks if the overlay is of the given type.boolean
warning

Avoid confusing the uid of OverlayInfo, OverlayCategory, and OverlayItem, as they each serve distinct purposes.

tip

To check if an OverlayItem belongs to an OverlayInfo, use the overlayUid property, or retrieve the whole OverlayInfo object via the overlayInfo property.

tip

The categoryId getter returns the ID of the root category, which may not necessarily be the direct parent category of the OverlayItem.

To obtain the direct parent category, you can access the preview data parameters and find the icon parameter which contains the category ID:

import { OverlayItem } from '@magiclane/maps-sdk';

const overlayItem: OverlayItem = // ... obtained from search or selection
const previewData = overlayItem.previewData;

// Find the icon parameter which contains the parent category ID
const iconParam = previewData.findParameter('icon');
if (iconParam) {
  const parentCategoryId: number = iconParam.value as number;
  
  // Use getCategory method from parent OverlayInfo to get the category
  const parentCategory = overlayItem.overlayInfo?.getCategory(parentCategoryId);
}

Use the getCategory method from the parent OverlayInfo class to retrieve the OverlayCategory object corresponding to this ID.

Usage​

OverlayItems can be selected from the map or be provided by the AlarmService on approach. Other fields and information can be displayed on the UI.

Classification​

There are a few types of predefined overlays:

  • Safety overlay
  • Public transport overlay
  • Social reports overlay

The CommonOverlayId enum contains information about the ids of the predefined overlay categories.

import { CommonOverlayId } from '@magiclane/maps-sdk';

// Predefined overlay IDs
const safetyId = CommonOverlayId.Safety;           // 0x8100
const publicTransportId = CommonOverlayId.PublicTransport; // 0x2EEFAA
const socialLabelsId = CommonOverlayId.SocialLabels;    // 0xA200
const socialReportsId = CommonOverlayId.SocialReports;   // 0xA300

Safety Overlay​

These overlays represent speed limit cameras, red light controls and so on.

For a speed limit, previewData might include information searchable by keys like:

  • eStrDrivingDirection: the driving direction on which the overlay item applies as string, e.g. "Both Ways"
  • speedValue: value of maximum allowed speed as number, e.g. 50
  • speedUnit: unit of measurement for speed as string, e.g "km/h"
  • Country: country name where the overlay is reported as string, e.g "FRA"
import { OverlayItem, CommonOverlayId } from '@magiclane/maps-sdk';

const overlayItem: OverlayItem = // ... obtained from search or selection

if (overlayItem.isOfType(CommonOverlayId.Safety)) {
  const previewData = overlayItem.previewData;
  
  const direction = previewData.findParameter('eStrDrivingDirection')?.value as string;
  const speedValue = previewData.findParameter('speedValue')?.value as number;
  const speedUnit = previewData.findParameter('speedUnit')?.value as string;
  const country = previewData.findParameter('Country')?.value as string;
  
  console.log(`Speed limit: ${speedValue} ${speedUnit} (${direction}) in ${country}`);
}

Public Transport Overlay​

This overlay is responsible for displaying public transport stations.

For a bus station, previewData might include information searchable by keys like:

  • id: unique overlay id as number
  • create_stamp_utc: unix epoch time when overlay has been created as number
  • icon: category icon id as number
  • name: name of bus station as string
import { OverlayItem, CommonOverlayId } from '@magiclane/maps-sdk';

const overlayItem: OverlayItem = // ... obtained from search or selection

if (overlayItem.isOfType(CommonOverlayId.PublicTransport)) {
  const previewData = overlayItem.previewData;
  
  const id = previewData.findParameter('id')?.value as number;
  const createStamp = previewData.findParameter('create_stamp_utc')?.value as number;
  const iconId = previewData.findParameter('icon')?.value as number;
  const name = previewData.findParameter('name')?.value as string;
  
  // Convert Unix timestamp to Date
  const createDate = new Date(createStamp * 1000);
  
  console.log(`Bus station: ${name} (created: ${createDate.toLocaleString()})`);
}
warning

There are two types of public transport stops available on the map:

  • Bus station with schedule information, available on the map as overlay items.
  • Bus station without schedule information, available on the map as landmarks.

Social Reports Overlay​

This overlay is responsible for displaying fixed cameras, construction sites and more.

For a construction report, previewData includes information searchable by keys like:

  • longitude: value for longitude coordinate as number
  • latitude: value for latitude coordinates as number
  • owner_name: user's name that reported the event as string
  • score: likes (confirmations) offered by other users as number
  • location_address: address of reported location as string, it contains street, city and country
import { OverlayItem, CommonOverlayId } from '@magiclane/maps-sdk';

const overlayItem: OverlayItem = // ... obtained from search or selection

if (overlayItem.isOfType(CommonOverlayId.SocialReports)) {
  const previewData = overlayItem.previewData;
  
  const longitude = previewData.findParameter('longitude')?.value as number;
  const latitude = previewData.findParameter('latitude')?.value as number;
  const ownerName = previewData.findParameter('owner_name')?.value as string;
  const score = previewData.findParameter('score')?.value as number;
  const address = previewData.findParameter('location_address')?.value as string;
  
  console.log(`Report by ${ownerName} at ${address} (score: ${score})`);
}

Interaction with Overlays​

OverlayService​

The OverlayService is a key component for managing overlays in the Maps SDK. It provides methods to retrieve, enable, disable, and manage overlay data, both online and offline.

Retrieving overlay info with OverlayService​

You can retrieve the list of all available overlays for the current map style using the getAvailableOverlays method from the OverlayService. This method returns a Pair<OverlayCollection, boolean>. The OverlayCollection object contains the available overlays, and the boolean indicates that some information is not available and will be downloaded when network is available. If not all overlay information is available onboard, a notification will be sent when it will be downloaded via a call to the callback provided as a parameter to the onCompleteDownload option.

import { OverlayService, GemError } from '@magiclane/maps-sdk';

// Get available overlays
const result = OverlayService.getAvailableOverlays({
  onCompleteDownload: (error: GemError) => {
    if (error === GemError.success) {
      console.log('Overlay data download complete');
    } else {
      console.error('Error downloading overlay data:', error);
    }
  }
});

const overlayCollection = result.first;
const needsDownload = result.second;

console.log(`Found ${overlayCollection.size} overlays`);
console.log(`Needs download: ${needsDownload}`);

The OverlayCollection class contains methods and getters such as:

  • size: returns the size of the collection.
  • getOverlayAt(index: number): returns the OverlayInfo at a specified index and null if it doesn't exist.
  • getOverlayByUId(overlayUid: number): returns an OverlayInfo by a given id.
  • overlayInfos: returns all overlay infos in the collection.
import { OverlayService, OverlayInfo } from '@magiclane/maps-sdk';

const result = OverlayService.getAvailableOverlays();
const overlayCollection = result.first;

// Iterate through all overlays
for (let i = 0; i < overlayCollection.size; i++) {
  const overlayInfo = overlayCollection.getOverlayAt(i);
  if (overlayInfo) {
    console.log(`Overlay: ${overlayInfo.name} (UID: ${overlayInfo.uid})`);
    
    // Get categories
    const categories = overlayInfo.categories;
    categories.forEach(category => {
      console.log(`  Category: ${category.name} (UID: ${category.uid})`);
    });
  }
}

// Get specific overlay by ID
const safetyOverlay = overlayCollection.getOverlayByUId(CommonOverlayId.Safety);
if (safetyOverlay) {
  console.log(`Safety overlay found: ${safetyOverlay.name}`);
}

Enabling and disabling overlays​

You can enable or disable overlays on the map using the enableOverlay and disableOverlay methods from the OverlayService. Check whether an overlay is enabled or disabled using the isOverlayEnabled method.

import { OverlayService, CommonOverlayId, GemError } from '@magiclane/maps-sdk';

const overlayUid = CommonOverlayId.Safety;

// Enable overlay
const errorWhileEnabling: GemError = OverlayService.enableOverlay(overlayUid);
if (errorWhileEnabling === GemError.success) {
  console.log('Safety overlay enabled');
}

// Disable overlay
const errorWhileDisabling: GemError = OverlayService.disableOverlay(overlayUid);
if (errorWhileDisabling === GemError.success) {
  console.log('Safety overlay disabled');
}

// Check if overlay is enabled
const isEnabled: boolean = OverlayService.isOverlayEnabled(overlayUid);
console.log(`Safety overlay is ${isEnabled ? 'enabled' : 'disabled'}`);

The enableOverlay, disableOverlay, and isOverlayEnabled methods can also take an optional categUid parameter to enable, disable, or check the status of a specific category within an overlay. By default, if no category ID is provided (or set to -1), the entire overlay is affected.

import { OverlayService, CommonOverlayId } from '@magiclane/maps-sdk';

const overlayUid = CommonOverlayId.Safety;
const categoryId = 123; // Specific category ID

// Enable specific category
OverlayService.enableOverlay(overlayUid, categoryId);

// Disable specific category
OverlayService.disableOverlay(overlayUid, categoryId);

// Check if specific category is enabled
const isCategoryEnabled = OverlayService.isOverlayEnabled(overlayUid, categoryId);

Selecting overlay items​

Overlay items are selectable. When user taps or clicks, you can identify specific overlay items programmatically (e.g., through the function cursorSelectionOverlayItems()). Please refer to the Map Selection Functionality guide for more details.

Searching overlay items​

Overlays are searchable. This can be done in multiple ways, the most common being to set the right properties in the search preferences when performing a regular search. More details can be found within the Get started with Search guide.

Calculating route with overlay items​

Overlay items are not designed for route calculation and navigation.

tip

Create a new landmark using the overlay item's relevant coordinates and a representative name, then utilize this object for routing purposes.

Displaying overlay item information​

Overlay items can contain additional information that can be displayed to the user. This information can be accessed using the previewData getter, the previewDataJson getter, or accessing the previewUrl getter that returns a URL that can be opened in a web browser to present more details about the item.

The previewData getter provides more information structured inside a SearchableParameterList, information which depend on the overlay type. We can iterate through all the parameters within a SearchableParameterList in the following way:

import { OverlayItem, SearchableParameterList } from '@magiclane/maps-sdk';

const overlayItem: OverlayItem = // ... obtained from search or selection
const parameters: SearchableParameterList = overlayItem.previewData;

// Iterate through parameters
for (let i = 0; i < parameters.size; i++) {
  const param = parameters.at(i);
  if (param) {
    // Unique for every parameter
    const key = param.key;
    
    // Used for display on UI - might change depending on language
    const name = param.name;
    
    // The type of param.value
    const valueType = param.type;
    
    // The parameter value
    const value = param.value;
    
    console.log(`${name} (${key}): ${value} [${valueType}]`);
  }
}
warning

The previewData returned is not available if the parent map tile is disposed. Please get the preview data before further interactions with the map.

In order to obtain preview data in a more structured way, you can use the previewDataJson getter, which returns the data as a JSON object:

import { OverlayItem, CommonOverlayId } from '@magiclane/maps-sdk';

const overlayItem: OverlayItem = // ... obtained from search or selection

if (overlayItem.isOfType(CommonOverlayId.PublicTransport)) {
  const data = overlayItem.previewDataJson;
  
  const name = data.name as string;
  const createStamp = data.create_stamp_utc as number;
  const iconId = data.icon as number;
  
  console.log(`Bus station: ${name}`);
}

if (overlayItem.isOfType(CommonOverlayId.Safety)) {
  const data = overlayItem.previewDataJson;
  
  const country = data.Country as string;
  const speedValue = data.speedValue as number;
  const speedUnit = data.speedUnit as string;
  
  console.log(`Speed limit: ${speedValue} ${speedUnit} in ${country}`);
}

if (overlayItem.isOfType(CommonOverlayId.SocialReports)) {
  const data = overlayItem.previewDataJson;
  
  const score = data.score as number;
  const description = data.description as string;
  const createStamp = data.create_stamp_utc as number;
  const ownerName = data.owner_name as string;
  
  const createDate = new Date(createStamp * 1000);
  console.log(`Report by ${ownerName}: ${description} (score: ${score})`);
}

In order to retrieve the image associated with an overlay item, you can use the img property (for the Img object) or the image property (for Uint8Array) of the OverlayItem class:

import { OverlayItem } from '@magiclane/maps-sdk';

const overlayItem: OverlayItem = // ... obtained from search or selection

// Get image as Uint8Array
const imageBytes: Uint8Array = overlayItem.image;

// Create a blob and object URL for display in browser
const blob = new Blob([imageBytes], { type: 'image/png' });
const imageUrl = URL.createObjectURL(blob);

// Use in an img element
const imgElement = document.createElement('img');
imgElement.src = imageUrl;
document.body.appendChild(imgElement);

// Clean up when done
// URL.revokeObjectURL(imageUrl);

Get notifications when approaching overlay items​

Alarms can be configured to notify users when they approach specific overlay items from selected overlays.

Activate highlights​

Overlay Items can be highlighted using the activateHighlightOverlayItems method provided by the GemMapController class.

Last updated on