HERE iOS SDK Developer's Guide

Venue Zoom

Certain 3D venues may have fine details that are not visible even at the maximum map zoom level. The HERE SDK offers a way to activate a venue-focused extended zoom mode to show a venue in a closer view. Note that fine details are not available for all venues.

Figure 1. A venue at the max zoom level
Figure 2. A venue with Venue Zoom enabled

To enable this extended Venue Zoom feature, use an NMAVenue3dMapLayer object and call the enableVenueZoom method. For example:

/// Get an instance of NMAVenue3dMapLayer
_venueMapLayer = self.mainVC.activeMapView.venue3dMapLayer

// To activate Venue Zoom:
[_venueMapLayer enableVenueZoom:YES];

// To deactivate Venue Zoom:
[_venueMapLayer enableVenueZoom:NO];

After enabling Venue Zoom, you can use one of the recommended ways to activate the feature. If the application input is based on gestures, the most convenient way is to add the application as a NMAVenue3dVenueZoomDelegate to NMAVenue3dMapLayer and use NMAVenue3dGestureHandler to receive zoom gesture events. When the map gets zoomed in up to the maximum available map zoom level and Venue Zoom is enabled, 3D venues are shown in enlarged mode. Note that NMAVenue3dGestureHandler handles only the gesture events that cause zooming and only in case when operating in Venue Zoom area.

The example code below shows how a gesture handler can be used with Venue Zoom. In this example, zooming in beyond the maximum map zoom level initiates Venue Zoom and shows the venue in enlarged mode.

#import "NMAVenue3dGestureHandler.h"
//...
gestureHandler = [NMAVenue3dGestureHandler
  gestureHandlerWithVenueMapLayer:venueMapLayer];

// Add gesture handler as NMAMapGestureDelegate to NMAMapView object
mapView.gestureDelegate = gestureHandler;

// Enable Venue Zoom
[_venueMapLayer enableVenueZoom:YES];

If the application needs to perform some part of zoom handling itself, it can register itself as NMAVenue3dGestureHandler and forward relevant events to NMAVenue3dGestureHandler object when needed:

@interface Venue3dMapsMode()<NMAVenue3dMapLayerDelegate, NMAMapGestureDelegate, NMAVenue3dServiceListener>

....
gestureHandler = [NMAVenue3dGestureHandler
  gestureHandlerWithVenueMapLayer:venueMapLayer];

// Enable Venue Zoom
[_venueMapLayer enableVenueZoom:YES];

....

// NMAMapGestureDelegate functions that cause zooming
- (void)mapView:(NMAMapView *)mapView didReceivePinch:(float)pinch
                       atLocation:(CGPoint)location
{
  // This example assumes handleInApp defines which handler handles the events
  if (handleInApp){
    // pinch handling
  } else {
    [_gestureHandler mapView:mapView didReceivePinch:pinch
                        atLocation:location];
  }
}

- (void)mapView:(NMAMapView*)mapView
  didReceiveTwoFingerTapAtLocation:(CGPoint)location
{
  if (handleInApp){
    // two finger tap handling
  } else {
    [_gestureHandler mapView:mapView
      didReceiveTwoFingerTapAtLocation:location];
  }
}

- (void)mapView:(NMAMapView*)mapView
  didReceiveDoubleTapAtLocation:(CGPoint)location
{
  if (handleInApp){
    // double tap handling
  } else {
    [_gestureHandler mapView:mapView
      didReceiveDoubleTapAtLocation:location];
  }
}

Another way to activate Venue Zoom is to use the useVenueZoom: method of NMAVenue3dController to immediately and activate Venue Zoom.


// Get VenueController:
NMAVenue3dController* venueController = venueMapLayer.venueController;

// To move to Venue Zoom area:
[venueController useVenueZoom:YES];
// To return to normal zoom area:
[venueController useVenueZoom:NO];

While venue zoom is activated, only 3D Venues are shown, and the base map becomes hidden. If venue zoom is activated while a venue route is being displayed, only the indoor portions of the routes are shown.

Note: You can also use NMAVenue3dVenueZoomDelegate to determine whether the Venue Zoom feature was successfully activated.

Once activated, the visible map becomes two zoom levels larger than they would appear without Venue Zoom. For example, if Venue Zoom is activated at map zoom level 18, the venues are shown as if the map is at zoom level 20. Note that this behavior only occurs when the map is at zoom level 18 or higher.

Scaling Custom Map Objects

For custom polygon-based map objects, the HERE SDK offers scaling methods to scale them to be used with Venue Zoom. Each point of the polygon need to be scaled to be used in Venue Zoom using the getScaledGeoCoordinatesFromNormal method in NMAVenue3dController. If the reverse operation is desired, where the starting point is a scaled polygon or geolocation, the getNormalGeoCoordinatesFromScaled method returns geocoordinates for a non-scaled geolocation.

Note: While both NMAMapGeoModel and NMAMapLocalModel can be scaled by these scaling methods, it is recommended to use NMAMapGeoModel, since only the anchor point location can be scaled in a NMAMapLocalModel .

In most cases it makes most sense to create two map objects, one for used in normal zoom mode and one used in Venue Zoom mode. Use addMapObject: and removeMapObject: from NMAMapView to swap between objects when changing between normal and Venue Zoom mode.

Enlarged 3D Models and Venue Zoom

Venue Zoom displays enlarged venue models that are automatically generated. Model generation happens in the following situations:

  • Venue Zoom is enabled and a venue is downloaded from the backend.
  • Venue Zoom is enabled and a venue is opened, and there is no enlarged model generated yet.

Note that if a venue is opened in 3D mode and then Venue Zoom is enabled, Venue Zoom would not successfully activate if the enlarged venue model has not been generated. In this case, the Venue Zoom can be used after the venue is closed and then opened again. If an enlarged model has already been generated earlier, then Venue Zoom can be used immediately after it has been enabled.