Examples and use cases

Explore practical examples and use cases to effectively utilize indoor maps and venues with the HERE SDK. This section covers a range of topics to help you get the most out of our indoor mapping capabilities.

List all indoor maps

The HERE SDK for iOS (Navigate) allows you to list all private venues that are accessible for your account and the selected collection. VenueMap contains a list which holds VenueInfo elements containing venue Identifier, venue ID and venue Name.

let venueInfo:[VenueInfo]? = venueEngine?.venueMap.getVenueInfoList()
if let venueInfo = venueInfo {
  for venueInfo in venueInfo {
      print("Venue Identifier: \(venueInfo.venueIdentifier)." + " Venue Id: \(venueInfo.venueId)." + " Venue Name: \(venueInfo.venueName).")
  }
}

For maps with venue identifier as UUID, venueId would return 0.

Load and show a venue

The HERE SDK for iOS (Navigate) allows you to load and visualize venues by identifier. You must know the venue's identifier for the current set of credentials. There are several ways to load and visualize the venues.

A VenueMap has two methods to add a venue to the map: selectVenueAsync() and addVenueAsync(). Both methods use getVenueService().addVenueToLoad() to load the venue by Identifier and then add it to the map. The method selectVenueAsync() also selects the venue:

venueEngine.venueMap.selectVenueAsync(venueIdentifier: String);

venueEngine.venueMap.addVenueAsync(venueIdentifier: String);

Note

For legacy maps with an int based venue ID, VenueMap still supports selectVenueAsync(venueID: Int) and addVenueAsync(venueID: Int) to load the venue by venue ID.

Once the venue is loaded, the VenueService calls the VenueDelegate.onGetVenueCompleted() method:

// Delegate for the venue loading event.
extension ViewController: VenueDelegate {
    func onGetVenueCompleted(venueIdentifier: String, venueModel: VenueModel?, online: Bool, venueStyle: VenueStyle?) {
        if venueModel == nil {
            print("Loading of venue \(venueIdentifier) failed!")
        }
    }
}

Note

For legacy maps with an int based venue ID, VenueService calls the VenueListener.onGetVenueCompleted(venueID: Int, venueModel: VenueModel?, online: Bool, venueStyle: VenueStyle?) method.

Once the venue is loaded successfully, if you are using the addVenueAsync() method, only the VenueLifecycleDelegate.onVenueAdded() method will be triggered. If you are using the selectVenueAsync()method, the VenueSelectionDelegate.onSelectedVenueChanged() method will also be triggered.

// Delegate for the venue selection event.
extension ViewController: VenueSelectionDelegate {
    func onSelectedVenueChanged(deselectedVenue: Venue?, selectedVenue: Venue?) {
        if let venueModel = selectedVenue?.venueModel {
            if moveToVenue {
                // Move camera to the selected venue.
                let center = GeoCoordinates(latitude: venueModel.center.latitude,
                                            longitude: venueModel.center.longitude,
                                            altitude: 500.0)
                mapView.camera.lookAt(point: center)
                // This functions is used to facilitate the toggling of topology visibility.
                // Setting isTopologyVisible property to true will render the topology on scene and false will lead to hide the topology.
                selectedVenue?.isTopologyVisible = true;
            }
        }
    }
}

A Venue can also be removed from the VenueMap, which triggers the VenueLifecycleDelegate.onVenueRemoved(venueIdentifier: String) method:

venueEngine.venueMap.removeVenue(venue: venue)

Note

For legacy maps with an int based venue ID, if you are using the addVenueAsync() method, the VenueLifecycleListener.onVenueAdded() method will be triggered.
When removing an int based venue ID from VenueMap, the VenueLifecycleListener.onVenueRemoved(venueID: Int) is triggered.

Label text preference

You can override the default label text preference for a venue.

Once the VenueEngine is initialized, a callback is called. From this point on, there is access to the VenueService. The optional method setLabeltextPreference() can be called to set the label text preference during rendering. Overriding the default style label text preference provides an opportunity to set the following options as a list where the order defines the preference:

"OCCUPANT_NAMES"
"SPACE_NAME"
"INTERNAL_ADDRESS"
"SPACE_TYPE_NAME"
"SPACE_CATEGORY_NAME"

These can be set in any desired order. For example, if the label text preference does not contain "OCCUPANT_NAMES" then it will switch to "SPACE_NAME" and so on, based on the order of the list. Nothing is displayed if no preference is found.

private func onVenueEngineInit() {
    // Get VenueService and VenueMap objects.
    let venueMap = venueEngine.venueMap
    let venueService = venueEngine.venueService

    // Add needed delegates.
    venueService.addServiceDelegate(self)
    venueService.addVenueDelegate(self)
    venueMap.addVenueSelectionDelegate(self)

    // Start VenueEngine. Once authentication is done, the authentication completion handler
    // will be triggered. Afterwards VenueEngine will start VenueService. Once VenueService
    // is initialized, VenueServiceListener.onInitializationCompleted method will be called.
    venueEngine.start(callback: {
        error, data in if let error = error {
            print("Failed to authenticate, reason: " + error.localizedDescription)
        }
    })

    if (hrn != "") {
        // Set platform catalog HRN
        venueService.setHrn(hrn: hrn)
    }

    // Set label text preference
    venueService.setLabeltextPreference(labelTextPref: LabelPref)
}

Select venue drawings and levels

A Venue object allows you to control the state of the venue.

The property Venue.selectedDrawing allows you to get and set a drawing which is visible on the map. When a new drawing is selected, the VenueDrawingSelectionDelegate.onDrawingSelected() method is triggered.

The following provides an example of how to select a drawing when an item is clicked in a UITableView:

extension DrawingSwitcher: UITableViewDelegate {
    public func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) {
        let drawingIndex: Int = indexPath.row
        if let venue = venueMap?.selectedVenue {
            // Set the selected drawing when a user clicks on the item in the table view.
            let drawing: VenueDrawing = venue.venueModel.drawings[drawingIndex]
            venue.selectedDrawing = drawing
            ...
        }
    }
}

The properties Venue.selectedLevel, Venue.selectedLevelIndex and Venue.selectedLevelZIndex allow you to get and set a level which will be visible on the map. If a new level is selected, the VenueLevelSelectionDelegate.onLevelSelected() method is triggered.

The following provides an example of how to select a level based on a reversed levels list from UITableView:

extension LevelSwitcher: UITableViewDelegate {
    public func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) {
        // Rows in the LevelSwitcher's table view are presented in the reversed way
        currentLevelIndex = Int32(levels.count - indexPath.row - 1)
        updateLevel(currentLevelIndex)
    }
}

func updateLevel(_ levelIndex: Int32) {
    if let venue = venueMap?.selectedVenue {
        venue.selectedLevelIndex = currentLevelIndex
    }
}

A full example of the UI switchers to control drawings and levels is available in the "IndoorMap" example app, available on GitHub.

Customize the style of a venue

You can change the visual style of VenueGeometry objects. Geometry style and/or label style objects must be created and provided to the Venue.setCustomStyle() method:

// Create geometry and label styles for the selected geometry.
geometryStyle = VenueGeometryStyle(
    mainColor: selectedColor, outlineColor: selectedOutlineColor, outlineWidth: 1)
labelStyle = VenueLabelStyle(
    fillColor: selectedTextColor, outlineColor: selectedTextOutlineColor, outlineWidth: 1, maxFont: 28)

venue.setCustomStyle(geometries: [geometry], style: geometryStyle, labelStyle: labelStyle)

Select space by identifier

The ID of spaces, levels and drawings can be extracted using getIdentifier(), e.g. for spaces call: spaces.getIdentifier(). Then, for using those id values, a specific space can be searched in a level or a drawing with getGeometryById(id:).

var geometriesID : [String] = [];
var geometries : [VenueGeometry] = [];
for id in geometriesID
{
    VenueGeometry geometry = selectedVenue?.getSelectedDrawing().getGeometryById(id);
    geometries.append(geometry);
}
geometryStyle = VenueGeometryStyle(
    mainColor: selectedColor, outlineColor: selectedOutlineColor, outlineWidth: 1)
labelStyle = VenueLabelStyle(
    fillColor: selectedTextColor, outlineColor: selectedTextOutlineColor, outlineWidth: 1, maxFont: 28)
selectedVenue.setCustomStyle(geometries: geometries, style: geometryStyle, labelStyle: labelStyle)

Handle tap gestures on a venue

You can select a venue object by tapping it. First, set the tap delegate:

// Create a venue tap handler and set it as default tap delegate.
mapView.gestures.tapDelegate = VenueTapHandler(venueEngine: venueEngine,
                                               mapView: mapView,
                                               geometryLabel: geometryNameLabel)

Inside the tap delegate, you can use the tapped geographic coordinates as parameter for the VenueMap.getGeometry() and VenueMap.getVenue() methods:

public func onTap(origin: Point2D) {
    deselectGeometry()

    let venueMap = venueEngine.venueMap
    // Get geo coordinates of the tapped point.
    if let position = mapView.viewToGeoCoordinates(viewCoordinates: origin) {
        // If the tap point was inside a selected venue, try to pick a geometry inside.
        // Otherwise try to select an another venue, if the tap point was on top of one of them.
        if let selectedVenue = venueMap.selectedVenue, let geometry = venueMap.getGeometry(position: position) {
            onGeometryPicked(venue: selectedVenue, geometry: geometry)
        } else if let venue = venueMap.getVenue(position: position) {
            venueMap.selectedVenue = venue
        }
    }
}

func deselectGeometry() {
    // If a map marker is already on the screen, remove it.
    if let currentMarker = marker {
        mapView.mapScene.removeMapMarker(currentMarker)
    }
}

func onGeometryPicked(venue: Venue,
                      geometry: VenueGeometry) {
    // If the geomtry has an icon, add a map marker on top of the geometry.
    if geometry.lookupType == .icon {
        if let image = getMarkerImage() {
            marker = MapMarker(at: geometry.center,
                               image: image,
                               anchor: Anchor2D(horizontal: 0.5, vertical: 1.0))
            if let marker = marker {
                mapView.mapScene.addMapMarker(marker)
            }
        }
    }
}

HERE recommends that you deselect the tapped geometry when the selected venue, drawing, or level has changed:

public init(venueEngine: VenueEngine, mapView: MapView, geometryLabel: UILabel) {
    ...
    let venueMap = venueEngine.venueMap
    venueMap.addVenueSelectionDelegate(self)
    venueMap.addDrawingSelectionDelegate(self)
    venueMap.addLevelSelectionDelegate(self)
}

deinit {
    let venueMap = venueEngine.venueMap
    venueMap.removeVenueSelectionDelegate(self)
    venueMap.removeDrawingSelectionDelegate(self)
    venueMap.removeLevelSelectionDelegate(self)
}

extension VenueTapHandler: VenueSelectionDelegate {
    public func onSelectedVenueChanged(deselectedVenue: Venue?, selectedVenue: Venue?) {
        self.deselectGeometry()
    }
}

extension VenueTapHandler: VenueDrawingSelectionDelegate {
    public func onDrawingSelected(venue: Venue, deselectedDrawing: VenueDrawing?, selectedDrawing: VenueDrawing) {
        self.deselectGeometry()
    }
}

extension VenueTapHandler: VenueLevelSelectionDelegate {
    public func onLevelSelected(venue: Venue, drawing: VenueDrawing, deselectedLevel: VenueLevel?, selectedLevel: VenueLevel) {
        self.deselectGeometry()
    }
}

A full example showing usage of the map tap event with venues is available in the "IndoorMap" example app, available on GitHub.

Indoor Routing

The HERE SDK for iOS (Navigate) provides comprehensive indoor routing capabilities, allowing you to calculate and visualize routes within venues. This section covers how to set up and use indoor routing features.

Indoor route at HERE Berlin office.

Indoor Route calculation

To calculate an indoor route, you need to create an IndoorRoutingEngine and specify waypoints with venue and level information. A waypoint would be created for each departure and arrival locations.

First, create the routing engine:

let routingEngine = IndoorRoutingEngine(_: venueService)

Create waypoints for the start and destination locations. For indoor locations, specify the venue ID and level ID:

let startWaypoint = IndoorWaypoint(
    coordinates: position,
    venueId: String(venueModel.identifier),
    levelId: String(venue.selectedLevel.identifier))

let destinationWaypoint = IndoorWaypoint(
    coordinates: position,
    venueId: String(venueModel.identifier),
    levelId: String(venue.selectedLevel.identifier))

Calculate the route using the routingEngine:

let routeOptions = IndoorRouteOptions()
routingEngine?.calculateRoute(
    from: startWaypoint,
    to: destinationWaypoint,
    routeOptions: routeOptions) { error, routes in
        if error == nil, let routes = routes {
            let route = routes[0]
            // Use the calculated route
        }
    }

Multilevel route calculation

Indoor routes can span multiple levels within a venue. The SDK automatically handles level transitions and provides information about level changes in the route.

To access indoor section details and level information:

for section in route.sections {
    // Check if section has indoor details
    if let indoorDetails = section.indoorSectionDetails {
        print("Indoor Section - Departure: \(indoorDetails.departurePlace.venueId ?? "")")
        print("Indoor Section - Arrival: \(indoorDetails.arrivalPlace.venueId ?? "")")
        
        // Iterate through indoor maneuvers
        for indoorManeuver in indoorDetails.indoorManeuvers {
            if let action = indoorManeuver.action {
                print("IndoorManeuver Action: \(action)")
            }
            print("IndoorManeuver Location Info: Level_Z_Index: \(indoorManeuver.levelZIndex)")
            
            // Check for level change data
            if let levelChangeData = indoorManeuver.indoorLevelChangeData {
                print("IndoorManeuver Level change using: \(levelChangeData.connector)")
                print("changeInLevel: \(levelChangeData.deltaZ)")
            }
        }
    }
}

The IndoorLevelChangeData provides information about:

connector: The type of level connector used (elevator, stairs, escalator, ramp, etc.)
deltaZ: The change in level (positive for going up, negative for going down)

Errors while route calculation

The routing callback provides an IndoorRoutingError parameter to handle various error scenarios. During route calculation, certain issues are reported as route notices, which are then converted to IndoorRoutingError objects. The following notice types are supported:

noRouteFound: No route found between selected waypoints
couldNotMatchOrigin: Origin could not be matched
couldNotMatchDestination: Destination could not be matched

Other errors include network connectivity issues, service errors, and request validation problems:

routingEngine?.calculateRoute(
    from: startWaypoint,
    to: destinationWaypoint,
    routeOptions: routeOptions) { error, routes in
        if error == nil, let routes = routes {
            let route = routes[0]
            // Process the route
        } else {
            var errorMessage: String
            switch error {
                // Route notice errors - converted from route notices
                case .noRouteFound:
                    errorMessage = "No route found between selected waypoints"
                case .couldNotMatchOrigin:
                    errorMessage = "Origin could not be matched"
                case .couldNotMatchDestination:
                    errorMessage = "Destination could not be matched"
                case .mapNotFound:
                    errorMessage = "Requested map not found"
                case .parsingError:
                    errorMessage = "Routing response not in correct format"
                case .unknownError:
                    errorMessage = "Unknown error encountered"
                default:
                    errorMessage = "Unknown error encountered"
            }
            // Handle the error appropriately
            print(errorMessage)
        }
    }

Avoidance option for level connector

You can configure the routing engine to avoid specific types of level connectors based on user preferences or accessibility requirements when calculating the Indoor Route.

let routeOptions = IndoorRouteOptions()

// Add features to avoid
routeOptions.indoorAvoidanceOptions.indoorFeatures.append(.elevator)
routeOptions.indoorAvoidanceOptions.indoorFeatures.append(.escalator)
routeOptions.indoorAvoidanceOptions.indoorFeatures.append(.stairs)

Available level connector types that can be avoided:

.elevator: Elevators
.escalator: Escalators
.stairs: Stairs
.ramp: General ramps
.pedestrianRamp: Pedestrian-specific ramps
.driveRamp: Drive ramps
.carLift: Car lifts
.elevatorBank: Elevator banks
.connector: Generic connectors

To remove an avoidance option:

if let index = routeOptions.indoorAvoidanceOptions.indoorFeatures.firstIndex(of: .elevator) {
    routeOptions.indoorAvoidanceOptions.indoorFeatures.remove(at: index)
}

Route Preferences

Configure route calculation preferences using the IndoorRouteOptions object.

Route Optimization Mode

Choose between fastest and shortest route:

let routeOptions = IndoorRouteOptions()

// For fastest route
routeOptions.routeOptions.optimizationMode = OptimizationMode.fastest

// For shortest route
routeOptions.routeOptions.optimizationMode = OptimizationMode.shortest

Walk Speed for Pedestrian

You can customize the walking speed for pedestrian routes, which affects the estimated travel time. The speed is specified in meters per second, with a valid range between 0.5 and 2.0 m/s.

let routeOptions = IndoorRouteOptions()

// Set walk speed (in meters per second)
// Valid range: 0.5 to 2.0 m/s
// Default is typically 1.0 m/s
routeOptions.speedInMetersPerSecond = 1.5

Example with validation:

var speed: Double = 1.2 // User input

// Validate and clamp the speed
if speed < 0.5 {
    speed = 0.5
} else if speed > 2.0 {
    speed = 2.0
}

routeOptions.speedInMetersPerSecond = speed

Turn by turn actions

Indoor routes provide detailed turn-by-turn maneuver information through the IndoorManeuver class.

for section in route.sections {
    if let indoorDetails = section.indoorSectionDetails {
        for indoorManeuver in indoorDetails.indoorManeuvers {
            // Get the maneuver action
            if let action = indoorManeuver.action {
                print("Action: \(action)")
            }
            
            // Get the level information
            print("Level Z-Index: \(indoorManeuver.levelZIndex)")
            
            // Check for level change information
            if let levelChangeData = indoorManeuver.indoorLevelChangeData {
                print("Level change via: \(levelChangeData.connector)")
                print("Change in levels: \(levelChangeData.deltaZ)")
            }
            
            // Get space information (room/area details)
            if let spaceData = indoorManeuver.indoorSpaceData {
                print("Space Category: \(spaceData.spaceCategory)")
                print("Space Type: \(spaceData.spaceType)")
            }
        }
    }
}

The IndoorManeuver provides:

Action: The type of maneuver to perform
Level Z-Index: The vertical level of the maneuver
Indoor Level Change Data: Information about level transitions including the connector type and change in level
Indoor Space Data: Details about the space being entered or traversed, including category and type

Route ETA and distance covered

You can retrieve the estimated time of arrival (ETA) and total distance from the calculated route.

let route = routes[0]

// Get the total duration in seconds
let durationInSeconds = route.duration.seconds

// Get the total length in meters
let lengthInMeters = route.lengthInMeters

// Format for display
print("Route duration: \(durationInSeconds) seconds")
print("Route distance: \(lengthInMeters) meters")

// Convert to more readable format
let minutes = durationInSeconds / 60
let seconds = durationInSeconds % 60
let kilometers = Double(lengthInMeters) / 1000.0

print(String(format: "ETA: %d min %d sec", minutes, seconds))
print(String(format: "Distance: %.2f km", kilometers))

For section-level details:

for section in route.sections {
    let sectionDuration = section.duration.seconds
    let sectionLength = section.lengthInMeters
    
    print("Section duration: \(sectionDuration) seconds")
    print("Section distance: \(sectionLength) meters")
}

Route rendering

The IndoorRoutingController handles the visualization of indoor routes on the map.

First, create the controller:

let routingController = IndoorRoutingController(_: venueMap, mapView: mapView)

Polyline rendering

To display a route on the map, use the showRoute() method.

// Create route style
let routeStyle = IndoorRouteStyle()

// Show the route
routingController?.showRoute(route: route, style: routeStyle)

To hide the route:

routingController?.hideRoute()

Level change icons placing

Configure custom markers for different route elements and level change indicators:

let routeStyle = IndoorRouteStyle()

// Set start and destination markers
let middleBottomAnchor = Anchor2D(horizontal: 0.5, vertical: 1.0)

if let startImage = UIImage(named: "ic_route_start.png"),
   let startPngData = startImage.pngData() {
    let markerImage = MapImage(pixelData: startPngData, imageFormat: .png)
    let startMarker = MapMarker(
        at: GeoCoordinates(latitude: 0.0, longitude: 0.0),
        image: markerImage,
        anchor: middleBottomAnchor)
    routeStyle.startMarker = startMarker
}

if let endImage = UIImage(named: "ic_route_end.png"),
   let endPngData = endImage.pngData() {
    let markerImage = MapImage(pixelData: endPngData, imageFormat: .png)
    let endMarker = MapMarker(
        at: GeoCoordinates(latitude: 0.0, longitude: 0.0),
        image: markerImage,
        anchor: middleBottomAnchor)
    routeStyle.destinationMarker = endMarker
}

// Set transport mode markers
if let walkImage = UIImage(named: "indoor_walk.png"),
   let walkPngData = walkImage.pngData() {
    let markerImage = MapImage(pixelData: walkPngData, imageFormat: .png)
    let walkMarker = MapMarker(
        at: GeoCoordinates(latitude: 0.0, longitude: 0.0),
        image: markerImage,
        anchor: Anchor2D(horizontal: 0.5, vertical: 0.5))
    routeStyle.walkMarker = walkMarker
}

if let driveImage = UIImage(named: "indoor_drive.png"),
   let drivePngData = driveImage.pngData() {
    let markerImage = MapImage(pixelData: drivePngData, imageFormat: .png)
    let driveMarker = MapMarker(
        at: GeoCoordinates(latitude: 0.0, longitude: 0.0),
        image: markerImage,
        anchor: Anchor2D(horizontal: 0.5, vertical: 0.5))
    routeStyle.driveMarker = driveMarker
}

Configure markers for level change features with directional indicators:

// Configure markers for each level change feature
let features: [IndoorLevelChangeFeatures] = [
    .elevator,
    .escalator,
    .stairs,
    .ramp
]

for feature in features {
    // Create markers for up, down, and neutral directions
    let upMarker = createMarker(for: feature, deltaZ: 1)       // Going up
    let downMarker = createMarker(for: feature, deltaZ: -1)    // Going down
    let neutralMarker = createMarker(for: feature, deltaZ: 0)  // No vertical change
    
    routeStyle.setIndoorMarkersFor(
        feature: feature,
        upMarker: upMarker,
        downMarker: downMarker,
        exitMarker: neutralMarker)
}

Helper method to create markers based on feature type and direction:

private func createMarker(for feature: IndoorLevelChangeFeatures, deltaZ: Int) -> MapMarker? {
    let imageName = getImageName(for: feature, deltaZ: deltaZ)
    
    guard let image = UIImage(named: imageName),
          let pngData = image.pngData() else {
        return nil
    }
    
    let markerImage = MapImage(pixelData: pngData, imageFormat: .png)
    return MapMarker(
        at: GeoCoordinates(latitude: 0.0, longitude: 0.0),
        image: markerImage,
        anchor: Anchor2D(horizontal: 0.5, vertical: 0.5))
}

private func getImageName(for feature: IndoorLevelChangeFeatures, deltaZ: Int) -> String {
    var baseName: String
    
    switch feature {
    case .elevator:
        baseName = "indoor_elevator"
    case .escalator:
        baseName = "indoor_escalator"
    case .stairs:
        baseName = "indoor_stairs"
    case .ramp:
        baseName = "indoor_ramp"
    default:
        return ""
    }
    
    if deltaZ > 0 {
        return "\(baseName)_up.png"
    } else if deltaZ < 0 {
        return "\(baseName)_down.png"
    } else {
        return "\(baseName).png"
    }
}

The deltaZ parameter indicates the direction:

1 (positive): Going up to a higher level
-1 (negative): Going down to a lower level
0: No vertical level change

The showRoute() method only supports limited customization for rendering a route, if you wish to apply advanced level customization you can do so by using a MapPolyline that is drawn between each coordinate of the route; refer to Show the route on the map.

A full example showing usage of indoor routing with venues is available in the "IndoorMap" example app, available on GitHub.