MapillaryJS Tagging

The latest component in a growing list extending the functionality of MapillaryJS exposes an API and functionality for photo tagging. With the tagging component we are adding support for displaying, creating and editing tags.

A tag is defined by a category, a geometry, and the position of the geometry in the photo. The MapillaryJS tagging API lets the library user decide what type of tags to show, where to show them and how they should be rendered on top of the photo. Currently there is support for rendering points and bounding boxes. Along with the tagging functionality we have also added sprite support in MapillaryJS. Sprite sheet icons provided to the library can be used instead of text to visualize categories.

Below is a video showing the tagging functionality in the MapillaryJS 1.3.0 release.

Regular photos

The video starts by showing tagging in a regular photo. Tags are created, moved and resized. A few things can be noted about the behavior:

  • Vertices are set by static clicks when creating tags.
  • Vertex positions are changed by dragging when editing tags.
  • Bounding boxes are always created by setting the top left corner first and then the bottom right corner. Clicks on top or to the left of the top left corner will be ignored.
  • It is possible to abort the creation of a bounding box by clicking the first vertex again.
  • It is not possible to set the first vertex of a tag outside of the photo.
  • It is not possible to move or resize a tag so that any of the vertices are outside of the photo.

The library will enforce these rules automatically and the API user does not need to handle any logic regarding keeping tag geometry vertices inside the photo boundaries.


After the regular photo, tagging in a panorama is shown. There is more freedom of movement when entering a panorama, you can pan and tilt and in the latest MapillaryJS release it is also possible to zoom. Zooming is done by using the scroll wheel when working with a mouse or by pinching on touch devices. A few things can also be noted regarding the panorama tagging:

  • When creating bounding boxes it is possible to pan, tilt and zoom after creating the top left corner. By dragging, the field of view will change. This can ease the tagging if the whole object is not in view initially.
  • Bounding boxes will not be rendered as rectangles for every point of view because of the perspective distortion.
  • Zooming does not zoom towards the center of view but instead towards the position of the mouse.

Try it out

You can try the new tagging functionality yourself below by creating, resizing, and moving points and bounding boxes. Everything shown in the video above can also be done in the demo. The demo does not save any tags to a server and the viewer will be cleared of tags when you move to another photo.

Things to come

As mentioned above there is currently support for points and bounding boxes. Moving forward we will add more geometry types like lines and polygons. In the demo above there is also experimental support for creating tags on touch devices. We will refine the touch behavior for creating tags and add support for editing tags on touch devices in later releases.

The tagging functionality will be integrated into the new version of the website. It can also be used in any other web application because of the fact that MapillaryJS is a standalone library.

If you have any feedback on the tagging functionality, the API or other parts of MapillaryJS, let us know through Github issues. If you have any general feedback let us know through Twitter or on the Forum.


Continue the conversation