Integrate Indoor Maps
The HERE Indoor Map feature provides the possibility to load, show and interact with private venues on the map.
It provides a wealth of hyperlocal information about indoor spaces, including building geometry and points of interest, spanning across multiple floors. HERE has mapped thousands of buildings globally, including, shopping malls, airports, train stations, parking garages, corporate campuses, factories, warehouses and many other types of buildings.
If you are a venue owner and are interested in leveraging HERE Indoor Map with the HERE SDK, contact us at: venues.support@here.com.
Screenshot: Showing an airport venue with a customized floor switcher.
Note that as of now the HERE SDK provides only support for private venues: This means, that your venue data will be shown only in your app. By default, no venues are visible on the map. Each of your venues will get a uniquie venue ID that is tied to your HERE SDK credentials.
Initialize the VenueEngine
Before you start using the Indoor Map API, the VenueEngine
instance should be created and started. This can be done after a map initialization. The best point to create the VenueEngine
is after the map loads a scene.
private void loadMapScene() {
private func onLoadScene(mapError: MapError?) {
guard mapError == nil else {
print("Error: Map scene not loaded, \(String(describing: mapError))")
return
}
mapView.mapScene.setLayerState(layerName: MapScene.Layers.extrudedBuildings,
newState: MapScene.LayerState.hidden)
venueEngine = VenueEngine { [weak self] in self?.onVenueEngineInit() }
}
}
Once the VenueEngine
has been initialized, a completion handler will be called. From this point, there is access to the VenueService
and the VenueMap
. A VenueService
is used for loading venues and a VenueMap
controls the venues on the map. Inside the completion handler all needed delegates can be added. Afterwards, the VenueEngine
needs to be started.
private func onVenueEngineInit() {
let venueMap = venueEngine.venueMap
let venueService = venueEngine.venueService
venueService.addServiceDelegate(self)
venueService.addVenueDelegate(self)
venueMap.addVenueSelectionDelegate(self)
venueEngine.start(callback: {
error, data in if let error = error {
print("Failed to authenticate, reason: " + error.localizedDescription)
}
})
}
After the VenueEngine
is started, it authenticates using the current credentials. If authentication is successful, the VenueEngine
will start the VenueService
. Once the VenueService
is initialized, the VenueServiceDelegate.onInitializationCompleted()
method will be called.
extension ViewController: VenueServiceDelegate {
func onInitializationCompleted(result: VenueServiceInitStatus) {
if (result == .onlineSuccess) {
print("Venue Service initialize successfully.")
} else {
print("Venue Service failed to initialize!")
}
}
func onVenueServiceStopped() {
print("Venue Service has stopped.")
}
}
Load and Show a Venue
The Indoor Map API allows to load and visualize venues by ID's. You should know the venue ID's available for the current credentials beforehand. There are several ways to load and visualize the venues. In the VenueService
there is a method to start a new venues loading queue:
venueEngine.venueService.startLoading(venueIds: )
Also, there is a method to add a venue ID to the existing loading queue:
venueEngine.venueService.addVenueToLoad(venueId: );
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 ID and then add it to the map. The method selectVenueAsync()
also selects the venue.
venueEngine.venueMap.selectVenueAsync(venueId:);
venueEngine.venueMap.addVenueAsync(venueId:);
Once the venue is loaded, the VenueService
calls the VenueDelegate.onGetVenueCompleted()
method.
extension ViewController: VenueDelegate {
func onGetVenueCompleted(venueId: Int32, venueModel: VenueModel?, online: Bool, venueStyle: VenueStyle?) {
if venueModel == nil {
print("Loading of venue \(venueId) failed!")
}
}
}
If the venue is loaded successfully, in case of the method addVenueAsync()
, only the VenueLifecycleDelegate.onVenueAdded()
method will be triggered. In case of the method selectVenueAsync()
, VenueSelectionDelegate.onSelectedVenueChanged()
method will be triggered as well.
extension ViewController: VenueSelectionDelegate {
func onSelectedVenueChanged(deselectedVenue: Venue?, selectedVenue: Venue?) {
if let venueModel = selectedVenue?.venueModel {
if moveToVenue {
let center = GeoCoordinates(latitude: venueModel.center.latitude,
longitude: venueModel.center.longitude,
altitude: 500.0)
mapView.camera.lookAt(point: center)
}
}
}
}
A Venue
can be removed from the VenueMap
. In this case, the VenueLifecycleDelegate.onVenueRemoved()
method will be triggered.
venueEngine.venueMap.removeVenue(venue: venue)
Select Venue Drawings and Levels
A Venue
object allows to control a state of the venue.
The property Venue.selectedDrawing
allows to get and set a drawing which will be visible on the map. If a new drawing is selected, the VenueDrawingSelectionDelegate.onDrawingSelected()
method will be triggered. See an example of how to select a drawing when an item is clicked in an UITableView
:
extension DrawingSwitcher: UITableViewDelegate {
public func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) {
let drawingIndex: Int = indexPath.row
if let venue = venueMap?.selectedVenue {
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 will be triggered. See 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) {
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 indoor-map example app you can find on GitHub.
Customize the Style of a Venue
It is possible to change the visual style of the VenueGeometry
objects. Geometry style and/or label style objects need to be created and provided to the Venue.setCustomStyle()
method.
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)
Handle Tap Gestures on a Venue
You can select a venue object by performing a tap gesture on it. First, set the 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
if let position = mapView.viewToGeoCoordinates(viewCoordinates: origin) {
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 let currentMarker = marker {
mapView.mapScene.removeMapMarker(currentMarker)
}
}
func onGeometryPicked(venue: Venue,
geometry: VenueGeometry) {
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)
}
}
}
}
It is good practice to 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 of the usage of the map tap event with venues is available in the indoor-map example app you can find on GitHub.
Indoor Routing
The HERE Indoor Routing API (beta) allows calculating routes inside venues, from outside to a position inside a venue, from a position inside a venue to outside. API also allows showing the result routes on the map.
Screenshot: Showing an airport venue with an indoor route inside it.
Note: This feature is in beta state and thus there can be bugs and unexpected behavior. Related APIs may change for new releases without a deprecation process. Currently, the indoor route calculation may not be accurate so that e.g. a pedestrian end user might be routed via a vehicle access and route or similar. Therefore end users must use this feature with caution and always be aware of the surroundings. The signs and instructions given at the premises must be observed. You are required to inform the end user about this in an appropriate manner, whether in the UI of your application, your end user terms or similar.
To calculate indoor routes and render them on the map, we need to initialize IndoorRoutingEngine
, IndoorRoutingController
, IndoorRouteOptions
and IndoorRouteStyle
objects inside a new class which will control indoor routing API and UI related to it:
public class IndoorRoutingUI: UIView {
...
private weak var venueService: VenueService?
private weak var venueMap: VenueMap?
private weak var mapView: MapView?
private var routingEngine: IndoorRoutingEngine?
private var routingController: IndoorRoutingController?
private var routeOptions: IndoorRouteOptions = IndoorRouteOptions()
private var routeStyle: IndoorRouteStyle = IndoorRouteStyle()
...
public func setup(_ venueEngine: VenueEngine?, mapView: MapView?, heightConstraint: NSLayoutConstraint!) {
self.mapView = mapView
if let venueService = venueEngine?.venueService {
self.venueService = venueService
}
if let venueMap = venueEngine?.venueMap {
self.venueMap = venueMap
}
self.heightConstraint = heightConstraint
initRouting()
}
private func initRouting() {
if let venueMap = venueMap, let venueService = venueService, let mapView = mapView {
routingEngine = IndoorRoutingEngine(_: venueService)
routingController = IndoorRoutingController(_: venueMap, mapScene: mapView.mapScene)
...
}
}
}
A start and destination point can be created by listening for the tap and long press events, for example:
public func onTap(origin: Point2D) {
if let waypoint = getIndoorWaypoint(origin: origin) {
arrival = waypoint
updateLabelText(arrivalLabel, waypoint: waypoint)
}
}
extension IndoorRoutingUI: LongPressDelegate {
public func onLongPress(state: GestureState, origin: Point2D) {
if state != .end {
return;
}
if let waypoint = getIndoorWaypoint(origin: origin) {
departure = waypoint
updateLabelText(departureLabel, waypoint: waypoint)
}
}
}
Check if the tap point is inside or outside a venue to find the type of IndoorWaypoint
object to create:
private func getIndoorWaypoint(origin: Point2D) -> IndoorWaypoint? {
if let venueMap = venueMap, let position = mapView?.viewToGeoCoordinates(viewCoordinates: origin) {
if let venue = venueMap.getVenue(position: position) {
let venueModel = venue.venueModel
if venueModel.id == venueMap.selectedVenue?.venueModel.id {
return IndoorWaypoint(coordinates: position, venueId: String(venueModel.id), levelId: String(venue.selectedLevel.id))
} else {
venueMap.selectedVenue = venue
return nil
}
}
return IndoorWaypoint(coordinates: position)
}
return nil
}
Calculate an indoor route using IndoorRoutingEngine.calculateRoute()
method. Show the result indoor route with IndoorRoutingController.showRoute()
method:
@IBAction private func onRouteButton(_ sender: Any) {
if let departure = departure, let arrival = arrival {
routingEngine?.calculateRoute(from: departure, to: arrival, routeOptions: routeOptions) { error, routes in
self.routingController?.hideRoute()
if error == nil, let routes = routes {
self.routingController?.showRoute(route: routes[0], style: self.routeStyle)
} else {
let alert = UIAlertController(title: "Indoor Routing", message: "Failed to calculate a route.", preferredStyle: .alert)
alert.addAction(UIAlertAction(title: "OK", style: .default, handler: nil))
self.window?.rootViewController?.present(alert, animated: true, completion: nil)
}
}
}
}
A full example of IndoorRoutingUI
with a custom indoor route style and the ability to change the indoor route settings through the UI is available in the indoor-map example app you can find on GitHub.