Camera

To create rich experiences on top of the Mappedin Web SDK, it's useful to be able to control the map view programmatically. This guide shows how to focus the map view on targets, how to listen to camera events and how to control the camera.

Demo keys are available on the Trial API Keys page with Terms and Conditions for their use

The CodeSandbox sample below demonstrates the concepts outlined below. Clicking a polygon will focus on that polygon and clicking outside of interactive polygons on the map will reset the camera to a set orientation. The camera event listeners are printing debug messages to the console on every camera-related user interaction.

Focus the camera to targets

To focus on a polygon after it has been clicked, we add a E_SDK_EVENT.POLYGON_CLICKED event handler. In this case, we are targeting only the clicked polygon. However, we can also give coordinates or nodes as TFocusOnTargets.

import {
  getVenue,
  showVenue,
  E_SDK_EVENT
} from "@mappedin/mappedin-js";

const options = {
  venue: "mappedin-demo-mall",
  clientId: "<MAPPEDIN_CLIENT_ID>",
  clientSecret: "<MAPPEDIN_CLIENT_SECRET>",
};

async function init() {
  const venue = await getVenue(options);
  const mapView = await showVenue(document.getElementById("app")!, venue);

  mapView.addInteractivePolygonsForAllLocations();
  mapView.labelAllLocations({ flatLabels: true });

  mapView.on(E_SDK_EVENT.POLYGON_CLICKED, (polygon) => {
    mapView.Camera.focusOn({
      targets: {
        polygons: [polygon]
      }
    });
  });
}

init();

Listening to camera events

There are 5 camera events that can be acted on by setting a listener with mapView.Camera.on(). Rotation, tilt and zoom events have access to the newly changed value in the handler.

mapView.Camera.on(E_CAMERA_EVENT.USER_INTERACTION_START, () => {
	console.log('USER_INTERACTION_START');
});

mapView.Camera.on(E_CAMERA_EVENT.USER_INTERACTION_END, () => {
	console.log('USER_INTERACTION_END');
});

mapView.Camera.on(E_CAMERA_EVENT.ROTATION_CHANGED, (payload) => {
	console.log('ROTATION_CHANGED', payload);
});

mapView.Camera.on(E_CAMERA_EVENT.TILT_CHANGED, (payload) => {
	console.log('TILT_CHANGED', payload);
});

mapView.Camera.on(E_CAMERA_EVENT.ZOOM_CHANGED, (payload) => {
	console.log('ZOOM_CHANGED', payload);
});

Controlling the camera

Controlling the camera to set it to a specific tilt, rotation or zoom can be done with mapView.Camera.set(). Tilt and rotation are set as radians, where as zoom is in the camera distance in meters from the target.

mapView.Camera.set({
	rotation: 1.5,
	tilt: 0.3,
	zoom: 1234,
});

It is possible to limit the tilting of the camera by listening to the change event and setting it to a desired value in the callback.

mapView.Camera.on(E_CAMERA_EVENT.TILT_CHANGED, (_payload) => {
	mapView.Camera.set({
		tilt: 0.0,
	});
});

If you want to be able to zoom in closer than the default limit, use the setter Camera.minZoom = 200.

Animation

The camera can also be animated to perform some or a combination of the transforms explained above. More about how to set the animation in the API reference.

await mapView.Camera.animate({
	positionOptions: {
		tilt: 0,
		rotation: 1,
		zoom: 6000,
	},
	animationOptions: {
		duration: 3000,
		easing: CAMERA_EASING_MODE.EASE_OUT,
	},
});

Reset camera

The following code sample shows how to reset the camera to its initial position. It focuses on a location when clicked and when clicking outside of interactive polygons, it resets the camera. If two polygons are clicked, it will draw a route between them and focus on the route. To test it, pan and rotate the map and then select two locations by clicking on them. Then reset the camera by clicking outside of interactive polygons to reset the camera to the initial state.

The camera movements are slower than usual, as we've set custom animation durations for this example.