Dynamic Focus

Dynamic focus is currently an experimental component of the Mappedin SDK. While in this state, some features may not behave as intended and APIs may be changed. Experimental features are being tested together with early adopters to fine-tune them.

A single venue may include multiple nearby buildings scattered across an outdoor map. Dynamic focus enables seamless exploration of these buildings by revealing the contents as the camera pans over it. A venue with an outdoor base map and at least one map group is necessary to get started with this feature.

By default, showVenue will show only the first map in a venue. To enable dynamic map focus, pass an optional dynamicFocus object to showVenue and provide a value for baseMap. This map will always be visible and should represent the outdoor map for the venue.

Copy
const venue = await getVenue({
  clientId: "5eab30aa91b055001a68e996",
  clientSecret: "RJyRXKcryCMy4erZqqCbuB1NbR66QTGNXVE0x3Pg6oCIlUR1",
  venue: "mappedin-demo-campus",
});

const mapView = await showVenue(
  document.getElementById("mappedin-map")!,
  venue,
  {
    dynamicFocus: {
      baseMap: venue.maps[0],
    },
  }
);

With the correct base map set, the venue will fade in each map group when it fits within the camera. The map to show is determined by the toMap for each map group location.

The following CodeSandbox demonstrates this behavior on the Mappedin Demo Campus.

Configuration

There are a number of additional options that can be provided to dynamicFocus to configure the experience.

indoorsFullyVisibleZoomLevel - The mercator zoom level number at which the indoors should be fully visible.

buildingFullyVisibleZoomLevel - The mercator zoom level number at which the outdoor building should be fully visible

setMapAtZoomLevel - The mercator zoom level at which the current map should transition to the focused building

preloadDefaultMaps - Sets the behavior true or false to preload all the default maps for each building during the initial showVenue function call

Modifying the zoom level options enables fine-tuning of dynamic focus for a specific map. Each option accepts standard mercator zoom levels between 0 and 22.

Copy
const mapView = await showVenue(
  document.getElementById("mappedin-map")!,
  venue,
  {
    dynamicFocus: {
      baseMap: venue.maps[0],
      indoorsFullyVisibleZoomLevel: 15,
      setMapAtZoomLevel: 18,
      buildingFullyVisibleZoomLevel: 16,
    },
  }
);

Using Mercator Zoom Levels

The dynamic focus API is the first to utilize mercator zoom levels. As such, there are new convenience functions to convert between Mappedin's camera altitude and mercator zoom level.

Copy
mapView.Camera.convertZoomLevelToAltitude(zoomLevel);
mapView.Camera.convertAltitudeToZoomLevel(altitude);

To debug the current mercator zoom level, subscribe to E_CAMERA_EVENT.CHANGED and convert zoom altitude to zoom level.

Copy
mapView.Camera.on(E_CAMERA_EVENT.ZOOM_CHANGED, (zoom) => {
  console.log(mapView.Camera.convertAltitudeToZoomLevel(zoom));
});

Listening for Map Change

It may be useful to know when the map has changed due to dynamic focus. The E_SDK_EVENT.MAP_CHANGED_WITH_REASON can be used to monitor when the SDK has changed the map and why. When dynamic focus switches the map because a user has panned away, the reason will be E_MAP_CHANGED_REASON.DYNAMIC_FOCUS_USER_INTERACTION. See API Reference for E_MAP_CHANGED_REASON.

Copy
mapView.on(E_SDK_EVENT.MAP_CHANGED_WITH_REASON, ({ map, reason }) => {
  if (reason === E_MAP_CHANGED_REASON.DYNAMIC_FOCUS_USER_INTERACTION) {
    console.log("User panned to a new map");
  }
});