Skip to main content

Event Handling

Viewer and other MapillaryJS classes emit events in response to user interactions or changes in state. You can listen to these events and use the event data to make decisions relevant to your application. In this guide we will register event handler to Viewer event types and act upon these events.

You will learn
  • How to listen to Viewer events
  • What types of events the viewer emits
  • How to retrieve additional information from the viewer when handling state events

Register Handlers#

Viewer is an event emitter. As such, it exposes the Viewer.on method which can be called to register event handlers. Each event handler is registered to a specific ViewerEventType.

Let's start by registering an event handler for the load event. The load event is fired immediately after all necessary resources have been downloaded and the first visually complete rendering of the viewer has occurred. We can listen to it to initialize application specific functionality and resources on Viewer load.

const viewer = new Viewer({accessToken, container});
viewer.on('load', (event) => console.log(`'${event.type}'`));

The load event is state event that emits an object with two properties, the type and the target. The target is the object instance that emitted the event, in this case the viewer.

We can listen to other state events too. Let's take a look at the position event. It is fired when the viewer's position changes. We can use the Viewer.getPosition to get the position and use it in our application.

const viewer = new Viewer({accessToken, container});
viewer.on('position', async (event) => {  const position = await viewer.getPosition();
  const lng = position.lngLat.lng;  const lat = position.lngLat.lat;  console.log(`id: ${imageId}', lng: ${lng}, lat: ${lat}`);});

We can also listen to the dataloading event to understand if the Viewer is currently loading data for a navigation request.

const viewer = new Viewer({accessToken, container});
viewer.on('dataloading', (event) => {  console.log(`'${event.type}' - loading: ${event.loading}`);});

We can also listen to viewpoint events that give us information about the viewer camera. The bearing event is fired when the viewing direction of the camera changes. We can use the ViewerBearingEvent.bearing property directly to update our application state.

const viewer = new Viewer({accessToken, container});
viewer.on('bearing', (event) => {  console.log(`'${event.type}' - bearing: ${event.bearing}`);});

Image Event#

The Image class is an important entity in MapillaryJS. Whenever we navigate in the viewer, images are used to represent the current position and visual appearance. We can listen to the image event and use the ViewerImageEvent object to display information about the current image.

Live Editor
Result
SyntaxError: Unexpected token (1:8)
1 : return ()
            ^

Pointer Events#

We can listen to a number of pointer events. These events are fired when users move or use their mouse in the viewer HTML container. All pointer events emit ViewerPointerEvent objects.

const viewer = new Viewer({accessToken, container});
const onPointerEvent = (event) => {  const lng = event.lngLat ? event.lngLat.lng : null;  const lat = event.lngLat ? event.lngLat.lat : null;  console.log(`'${event.type}' - lng: ${lng}, lat: ${lat}`);};
viewer.on('dblclick', onPointerEvent);viewer.on('mousemove', onPointerEvent);

The pointer event objects have three coordinate properties that we can use.

  1. ViewerPointerEvent.pixelPoint - The pixel coordinates in the viewer container of the mouse event target
  2. ViewerPointerEvent.basicPoint - The geodetic location in the viewer of the mouse event target
  3. ViewerPointerEvent.lngLat - The basic image coordinates in the current image of the mouse event target

In the live example we will use the pixel coordinates to show a box with the basic coordinates.

tip

Try to pan the view and click outside the image.

Can you display the lngLat instead of the basicPoint in the coordinate container on click?

Live Editor
Result
SyntaxError: Unexpected token (1:8)
1 : return ()
            ^

Camera Pose Events#

When users interact with the viewer, for example by panning, zooming, or navigating, the viewpoint, position, and other camera pose properties changes. We can register event handlers to listen and act on these changes. For the live example below we will listen to the pov event and use the Viewer bearing to update a compass north indicator.

We call the Viewer.getPointOfView method in our event handler and use the PointOfView.bearing property to rotate our north indicator.

tip

Can you use the tilt property of the PointOfView object to rotate the north indicator around another axis?

Live Editor
Result
SyntaxError: Unexpected token (1:8)
1 : return ()
            ^

Remove Handlers#

When we do not need to listen to a specific event type any more, we call the Viewer.off method to remove our event handler.

const viewer = new Viewer({accessToken, container});
const onImage = (event) {  const imageId = event.image.id;  console.log(`id: ${imageId}'`);};
viewer.on('image', onImage);
// ...// Remove event handler at a later timeviewer.off('image', onImage);
info

You can view more event handling code in the Viewer Events example.

Recap#

Now you know how to:

  • Register event handlers to listen to Viewer events
  • Use the properties of the event objects
  • Retrieve additional data by calling the Viewer methods for state events
  • Remove your event handlers when you do not need to listen anymore