Mapillary has integrated with Esri’s Web AppBuilder Developer Edition to allow using a Mapillary widget inside custom web applications. You can use the Mapillary widget to allow viewing street-level images alongside additional feature layers, as well as to assist in editing feature layers. You can also filter by username, date, and even your organization’s public and private imagery.
You can get the Mapillary for Web AppBuilder widget from the Esri Marketplace. If you'd like to see a preview, take a look at the live demo of the widget.
This article will go over the following sections to help you get started with the widget:
When you download the widget, it will come in a compressed zip file and include a single folder called `Mapillary`. Inside this folder are the contents of the widget. It is important not to change the name of the folder, as the code refers to this folder name when adding and deploying the widget in your web app.
Example of the widget contents
There are several different ways to add the widget to your web app, depending on your own development environment, or if you’re planning to use a server such as Portal. In Web AppBuilder (Developer Edition), the default directory for all widgets is `client\stemapp\widgets`. Assuming this matches your own environment, you’ll place the folder there. This will enable you to add the Mapillary widget to any new web app that you create.
If you’d like to add the widget to a custom or downloaded app that already exists, you’ll need to navigate to the directory for that app and place the folder inside of `stemapp\widgets`. You will also need to edit the app config file to configure the widget.
Alternative instructions from Esri with an example widget .
If you are using Portal, instructions for adding the widget are .
In order to use the Mapillary widget, you’ll need to accomplish two important tasks on the Mapillary web:
- Create an organization—the widget will be available to you and any members of your organization, and we’ll authenticate your subscription based on the organization key.
- Register your application—you will register your widget in order to receive a client ID, which is your access token.
In order to create an organization, you’ll need to follow . The most important part is simply that your organization exists, while you’ll also want to for them to be able to use the Mapillary widget in an ArcGIS environment. This also assumes you’ve already .
The client ID is separate from your organization, but instead offers a way of indicating you have a Mapillary account and therefore grants you access Mapillary from outside the website. It can be generated in your account . A client ID is inserted into the widget when you configure it and lets us know that you and your organization are actively using the widget, and have proper authentication to access your organization’s content.
When registering a client ID, the callback URL should match the URL where your web app will be hosted. This is critical for authentication of your username and organization when using the widget. You should also enable `private:read` in case you’re using Mapillary for Organizations with a private image repository, or think you may want to in the future.
In the Web AppBuilder for ArcGIS, you can create a new app then add the Mapillary Viewer widget. The Mapillary Viewer widget will appear in the alphabetically ordered list of widgets.
Adding the widget from the list of available widgets
Once you’ve added the widget to your app, you’ll be asked to review the configuration for the widget. The most important part of this is ensuring you provide a valid Mapillary client ID.
The other configuration options have explanatory text below them.
The configuration options
Sign-in, authentication, and organization filter
You may optionally sign in during the configuration, in order to authenticate your username and organization. You can then check the box titled "Hide login and registration buttons" because you or your web application users will no longer need to sign in. Instead, they will have access to the widget as part of your selected default organization. This is helpful if you want your users to not worry about signing in with their own credentials, and you instead want them to just access the widget with the privileges of your organization.
If you don’t sign in at this stage, then you should not check the box for hiding login. Users of your web application will instead need to sign into their Mapillary account and select an organization to use, which might be your same organization. This is helpful if you want many users to sign in each time they use the app, using their own credentials.
You may also check a box to hide the username filter. This means that images from all users will appear on the map, with the only customer filter being between your organization’s imagery or all global imagery.
The image transition toggles involve how the Mapillary Viewer displays transitions between images. By default, Mapillary’s 3D reconstruction () is used to create the transitions by matching common points between images. This can show a warping effect for a moment once you begin navigating but may interfere with viewing at higher playback speeds. You may opt to remove the image transitions by unchecking the first box, "Show image transitions". You can also check the second box, "Show image transition toggle", to display a toggle in the widget for the user to decide if the transitions are on or off.
There are two methods of navigating through images in the Mapillary Viewer: and . The spatial method involves using arrows that are overlaid over the bottom half of the image, some implying a discrete direction and others implying a turn or reversal motion. Navigating with these arrows will allow you to move to other images that are located near your current view, but that also may be from different users, dates, sequences, or perspectives.
The sequence method involves either a forward or backward motion that keeps your perspective in the same sequences of images, thus maintaining consistency within the direction of travel, username, and date. Sequence navigation also includes a play button, useful for automatically navigating through the sequences, as well as options to change the speed or the playback direction.
Both navigation options are enabled by default, but it may be useful to remove one or both if you wish to restrict users from navigating, and instead only be able to view the photo or sequence of photos that they’ve selected from the map.
The camera angle indicator is also visible in the widget by default, showing the current viewing direction of the photo. It is based on a 0- to 360-degree scale, with 180 degrees indicating due south, 90 degrees due east, and so on. This can help give the user an orientation in comparison to the map and its location icon but can be disabled if desired.
By default, closing the widget will remove the green Mapillary coverage layers from the map (as well as any organization layers, public or private). You can uncheck the box to allow the layers to remain on the map, even when the widget is minimized. This may be helpful if you want to know where imagery exists, but don’t necessarily want to view the images.
Once all component options have been reviewed, you may click OK and the widget configuration will be saved. Your widget is now ready to be deployed with your app. You can find detailed instructions for deploying your app in the .
Important: if you are using Portal, you’ll need to follow .
Viewing an image
The Mapillary Viewer widget can be opened by clicking the widget icon. If you haven’t signed in during the configuration of the widget, then you must sign in now before the widget will function. Either way, once authenticated the widget will add green point and line feature layers to the map, indicating Mapillary coverage. If you have applied an organization filter by default, then the green coverage layer will be off and a gold layer will represent your organization’s public imagery, and a purple layer will represent private imagery. There will also be a toggle for each layer visible below the viewer.
The viewer will be empty initially, displaying a black screen. When you click on the map, the closest image to the point of the click event will be loaded. If you click on a location with no green coverage layer, the widget will search up to 100 meters’ radius for the nearest image, but it's recommended to use the green coverage as a guide for where to click.
Once you’ve clicked, an image will load in the viewer, and an orange-yellow icon will appear on the map. This icon will indicate the camera angle of the current image and will match the camera angle indicator at the bottom-right of the image.
You can click the spatial navigation arrows to move to nearby images, and you’ll find it may show images in different perspectives, from different dates, or different users.
Contrarily, sequence navigation will maintain the direction of travel from the current sequence. Click the Vertical line at the right of the sequence menu, and you will be able to then click the rabbit icon to adjust the playback speed on the slider or click the arrows icon to reverse playback direction. Clicking the frame icon beside the rabbit icon will open the sequence timeline, allowing you to quickly jump to a different location in the current sequence.
You may also apply a username or date filter, as well as access advanced options based on your configuration. To do this, you’ll need to click the arrow by "FILTER MAP VIEW".
You may type a username into the filter box, then click that user’s name once you see it appear in the drop-down. Repeat this to filter for multiple users—their names will appear above the box, and can each be cleared by clicking the X beside the name. The date filter works by selecting a start and end date in the drop-down box.
You may clear all filters, and clear the current image as well as map location by clicking the Reset button. If you experience any problems loading an image upon click, this also can help refresh the widget.
If you need to download a JPEG of the current image, click the Download Image text at bottom right of the viewer. You may also click mapillary.com to open the image on Mapillary’s web site, or click @username to open the user’s profile page.
Minimizing and closing
To close the widget, click the X at the top right, and the Mapillary coverage and location icon will disappear from the map by default. They will also be saved and reloaded once you open the widget again.
If you logged in when loading the page, then you will see your username and avatar at the top right of the widget. If you have an organization filter preset, then you’ll see an organization name and avatar at top right. In either case, you may click the arrows beside this avatar to switch between an individual user and one or multiple organizations of which you’re a member.
When you’ve selected an organization, the green global Mapillary layer will be toggled off, and the gold or purple organizations layers will be toggled on. The gold layer is imagery from your organization which is visible to the public, while the purple layer, if it exists, is private imagery that is only available to you and other members of your organization.
When an organization is actively selected, you may also toggle the green global Mapillary coverage layer on to view images outside of your organization. However, when you click on the map, these images will not load. Clicking the map will only load images from your active public or private organization layer, and navigation in the viewer will also be limited to be between images from your organization. If you switch back to your individual user account by clicking the organization name or avatar at top right, you can once again view public imagery by clicking on the map.
Mapillary offers a free 30-day trial to any organization for trying out the widget for internal viewing in your organization as well as publicly served maps, accessible through the ArcGIS Marketplace. After the trial ends, the organization admin of ArcGIS Online needs to email firstname.lastname@example.org to purchase a license.