Skip to main content

Display landmarks

|

Filter landmarks by category

When displaying the map, we can choose what types of landmarks we want to display. Each landmark can have one or more LandmarkCategory. To selectively display specific categories of landmarks programmatically, you can use the addStoreCategoryId method provided by the LandmarkStoresCollection class:

// Get MapView from GemSurfaceView
val gemSurfaceView = findViewById<GemSurfaceView>(R.id.gem_surface)
val mapView = gemSurfaceView.mapView

// Get the landmark store service to access map POIs
val landmarkStoreService = LandmarkStoreService()
val mapPoisStoreId = landmarkStoreService.mapPoisLandmarkStoreId

// Clear all the landmark types on the map
mapView?.preferences?.landmarkStores?.removeAllStoreCategories(mapPoisStoreId)

// Display only gas stations
mapView?.preferences?.landmarkStores?.addStoreCategoryId(
    mapPoisStoreId,
    EGenericCategoriesIDs.GasStation.value
)

This allows filtering the default map data. Next, we might want to also add custom landmarks to the map (see the next section).

Display custom landmarks​

Landmarks can be added to the map by storing them in a LandmarkStore. Next, the LandmarkStore is added to the LandmarkStoresCollection within MapViewPreferences. The following code demonstrates all these steps: first, creating custom landmarks, then adding them to a store, and finally adding the store to the collection of stores.

// Get MapView from GemSurfaceView
val gemSurfaceView = findViewById<GemSurfaceView>(R.id.gem_surface)
val mapView = gemSurfaceView.mapView

val landmarksToAdd = arrayListOf<Landmark>()

// Load image from assets
val imageData = Image.fromFile("assets/poi83.png")

val landmark1 = Landmark().apply {
    name = "Added landmark1"
    coordinates = Coordinates(51.509865, -0.118092)
    image = imageData
}
landmarksToAdd.add(landmark1)

val landmark2 = Landmark().apply {
    name = "Added landmark2"
    coordinates = Coordinates(51.505165, -0.112992)
    image = imageData
}
landmarksToAdd.add(landmark2)

// Create landmark store
val landmarkStoreService = LandmarkStoreService()
val (landmarkStore, errorCode) = landmarkStoreService.createLandmarkStore("landmarks")

if (errorCode == GemError.NoError && landmarkStore != null) {
    // Add landmarks to the store
    for (landmark in landmarksToAdd) {
        landmarkStore.addLandmark(landmark)
    }

    // Add the store to the map view preferences
    mapView?.preferences?.landmarkStores?.add(landmarkStore)
}
Landmarks displayed

Some methods of LandmarkStoresCollection class are explained below:

  • add(LandmarkStore lms): add a new store to be displayed on map. All the landmarks from the store will be displayed, regardless of the category provided.
  • addAllStoreCategories(Int storeId): does the same thing as add but uses the storeId, not the LandmarkStore instance.
  • addStoreCategoryId(Int storeId, Int categoryId): adds the landmarks with the specified category from the landmark store on the map.
  • removeAllStoreCategories(Int storeId): removes all landmark stores from the map.
  • contains(Int storeId, Int categoryId): check if the specified category ID from the specified store ID was already added.
  • containsStore(LandmarkStore lms): check if the specified store has any categories of landmarks shown on the map.

Highlight landmarks​

Highlights allow customizing a list of landmarks, making them more visible and providing options to customize the render settings. Highlights can only be used upon Landmarks. By default, highlighted landmarks are not selectable but can be made selectable if necessary.

Highlighting a landmark allows:

  • Customizing its appearance.
  • Temporarily isolating it from standard interactions - it cannot be selected (default behavior, can be modified for each highlight).
Tip

Landmarks retrieved through search or other means can be highlighted to enhance their prominence and customize their appearance. Additionally, custom landmarks can be highlighted, but they have to be added to a LandmarkStore first.

Activate highlights​

Highlights can be displayed on map by using MapView.activateHighlightLandmarks. For demonstration purposes, a new Landmark object will be instantiated and filled with specifications using available setters. Next, the created landmark needs to be added to a List<Landmark> and a HighlightRenderSettings needs to be provided in order to enable desired customizations. Then activateHighlightLandmarks can be called with a unique highlightId.

// Get MapView from GemSurfaceView
val gemSurfaceView = findViewById<GemSurfaceView>(R.id.gem_surface)
val mapView = gemSurfaceView.mapView

val landmarksToHighlight = arrayListOf<Landmark>()

// Load image from assets
val imageData = Image.fromFile("assets/poi83.png")

val landmark = Landmark().apply {
    name = "New Landmark"
    coordinates = Coordinates(52.48209, -2.48888)
    image = imageData
    extraImage = imageData
}
landmarksToHighlight.add(landmark)

// Configure highlight render settings
val settings = HighlightRenderSettings(
    options = EHighlightOptions.ShowLandmark,
    innerColor = Rgba(255, 98, 0, 255),
    outerColor = Rgba(255, 98, 0, 255),
    innerSize = 1.5,
    outerSize = 0.0
)

// Apply additional options using bitwise OR
settings.setOptions(
    EHighlightOptions.ShowLandmark.value or
    EHighlightOptions.NoFading.value or
    EHighlightOptions.Overlap.value
)

// First add landmark to a store
val landmarkStoreService = LandmarkStoreService()
val (landmarkStore, errorCode) = landmarkStoreService.createLandmarkStore("landmarks")

if (errorCode == GemError.NoError && landmarkStore != null) {
    landmarkStore.addLandmark(landmark)
    mapView?.preferences?.landmarkStores?.add(landmarkStore)

    // Activate highlight
    mapView?.activateHighlightLandmarks(
        landmarksToHighlight,
        settings,
        highlightId = 2
    )

    // Center on the landmark
    mapView?.centerOnCoordinates(Coordinates(52.48209, -2.48888), zoomLevel = 40)
}

Hightlight options​

The EHighlightOptions enum provides several options to customize the behavior of highlighted landmarks:

OptionDescription
ShowLandmarkShows the landmark icon & text. By default is enabled.
ShowContourShows the landmark contour area if available. By default, this option is enabled.
GroupGroups landmarks when many are present in close proximity. Available only with ShowLandmark. By default it is disabled.
OverlapOverlap highlight over existing map data. Available only with ShowLandmark. By default, disabled.
NoFadingDisable highlight fading in/out. Available only with ShowLandmark. By default, disabled.
BubbleDisplays highlights in a bubble with custom icon placement inside the text. Available only with ShowLandmark. Automatically invalidates Group. By default, disabled.
SelectableThe highlights are selectable using setCursorScreenPosition.This option is available only in conjunction with ShowLandmark By default, the option is true
danger

When showing bubble highlights, if the whole bubble does not fit on the screen, it will not be displayed at all. Make sure to truncate the text if the text length is very long.

danger

For a landmark contour to be displayed, the landmark must have a valid contour area. Landmarks which have a polygon representation on OpenStreetMap will have a contour area.

Make sure the contour geographic related fields from the extraInfo property of the Landmark are not removed or altered.

Deactivate highlights​

To remove a displayed landmark from the map, use MapView.deactivateHighlight(id) to selectively remove a specific landmark, or MapView.deactivateAllHighlights() to clear all displayed landmarks at once.

// Get MapView from GemSurfaceView
val gemSurfaceView = findViewById<GemSurfaceView>(R.id.gem_surface)
val mapView = gemSurfaceView.mapView

mapView?.deactivateHighlight(highlightId = 2)

Get highlighted landmarks​

To get the highlighted landmarks based on a particular highlight id, you can use the geographic area of the highlight:

// Get MapView from GemSurfaceView
val gemSurfaceView = findViewById<GemSurfaceView>(R.id.gem_surface)
val mapView = gemSurfaceView.mapView

val highlightArea = mapView?.getHighlightArea(highlightId = 2)
info

The Android SDK provides getHighlightArea() instead of getHighlight() to retrieve information about highlights.

Tip

Overlay items can also be highlighted using the activateOverlayItemsHighlight method in a similar way.

Disabling landmarks​

Removing all presented landmarks can be done by calling removeAllStoreCategories(storeId) method of LandmarkStoresCollection class. The following code does just that:

// Get MapView from GemSurfaceView
val gemSurfaceView = findViewById<GemSurfaceView>(R.id.gem_surface)
val mapView = gemSurfaceView.mapView

// Get the landmark store service to access map POIs
val landmarkStoreService = LandmarkStoreService()
val mapPoisStoreId = landmarkStoreService.mapPoisLandmarkStoreId

mapView?.preferences?.landmarkStores?.removeAllStoreCategories(mapPoisStoreId)
Last updated on