The Mapillary Desktop Uploader is our desktop solution for contributing imagery to Mapillary, primarily serving those who wish to upload imagery taken from action cameras, 360° cameras, and dashboard cameras.

The Desktop Uploader has a straightforward UI, making uploading to Mapillary as easy as dragging a folder or file into the application. Both geotagged imagery and videos, spanning a number of file formats, are supported in the Desktop Uploader.

As of Fall 2024, you can also edit image positions using the Desktop Uploader, which we implemented to enable our users to correct incorrect image positions due to poor GPS.

This article will get you set up with everything you need to know about the Desktop Uploader!

📖Table of Contents

1. Getting started
2. Adding files for upload 
3. Uploading images
   1. Compass angle manipulation settings
   2. Editing image positions
4. Uploading videos
5. Upload history and retrying uploads
6. Reporting issues & Error logs

✅Getting started

To download the Desktop Uploader for Windows, MacOS, or Linux, click here. 

Once the application has finished downloading, open it. You will be prompted to sign in to your Mapillary account. You must be signed in to use the Mapillary Uploader. Once you’ve signed in, you’ll be taken to the Desktop Uploader home page. 

Take a few moments to click on some of the different elements. The best way to get comfortable with something new is to explore it! 

You'll notice that the Desktop Uploader version can be viewed in the lower right corner of the window. Additionally, A popup may sometimes appear upon startup detailing new features found in the latest release—you can close this if you'd like. 

🗂️Adding files for upload

Now that you've looked around the Desktop Uploader, you are ready to add imagery!

If you want to upload to a Mapillary Organization, you'll need to select this as your upload target before you drag & drop a folder. To do this, click on the down arrow next to 'Individual account' or anywhere on that bar to view and select the organization you'd like to upload to. If you're not part of an organization, disregard this step—the only option you'll see to upload to is your personal account.

Once you've selected your target account, you're ready to choose the imagery you'd like to upload. You can drag & drop a folder of images or videos, or can navigate to your desired files via your native file explorer by clicking 'browse.' Multiple folders and files can be selected at once!

Note that your images needs to be geotagged before you add them (i.e. have GPS information in the EXIF data, which should be added by the camera you used); you cannot add GPS data manually to images in the Desktop Uploader. However, you can add an accompanied .gpx file for videos.

After you add your files in, you'll be directed to the following view:

As you can see above, the Desktop Uploader takes several moments to pre-process your files and position them on the map—see 'Processing' in the top right corner.

Once this is complete, the map pane will automatically zoom in to where your files have been placed on the map.

If you determine that you do not want to upload the files you've added, you can click 'Discard' in the bottom-left corner to go back to the previous view and choose a different file or folder. Additionally, you can click 'Add more files' if you would like to add additional imagery to your batch.

Note that, at this point, your files have not yet been uploaded. To do so, you'll have to click the 'Upload' button, but let's take a minute to run over the differences in uploading images versus video before you do so! 

🎞️Uploading images

Depending on the type of files you've uploaded (images or video), the Desktop Uploader will have different capabilities. 

You'll notice that, when adding imagery to the Desktop Uploader, each image position corresponds to a dot on the map view. Images are connected by the order in which they were captured. The total number of images you've added can be seen under your username in the left panel. 

You can click on any image location to open a pop-up image preview window. Clicking through a handful of image previews is a good way to gauge the quality of your images: Are they oriented correctly? Is the subject matter correct? Are they good quality?

You can also view EXIF data within the Image Viewer pop-up by clicking the 'EXIF' button in the bottom-right corner of the preview window. You can view information on the image file name, capture date and time, latitude and longitude, compass angle, and camera type. 

Compass angle manipulation settings

Additionally, see the 'Image settings' bar located towards the bottom of the left pane. When you click into this, you will see there are currently two options available to adjust image properties. You may wish to use these in certain scenarios.

The first setting, 'Interpolate directions' should be used when imagery has no compass angle information, or if you feel the current compass angle is inaccurate. If you click on the button, the compass angle will automatically be reassigned to for each image, setting it to the direction of the next image location. 

Note that the Desktop Uploader will only interpolate the compass angle direction if you enable the setting; images that do not have compass angle values by default will not be auto-interpolated. 

'Compass offset angle' allows you to add an offset to the existing compass angle for all images. This is particularly useful if you have captured imagery oriented in a different direction than your direction of motion (e.g. a camera facing out the drivers side window of a moving car). 

In degrees, 0 corresponds to north, 90 to east, 180 to south, and 270 to west—these are the most common offset values. 

Editing image positions

As of Desktop Uploader v4.5, you are now able to move image positions. The best practice for moving image positions is as follows: an image should only be moved when there is probable cause that it was impacted by a poor GPS signal. It is very important to maintain the integrity of the imagery your upload.

To move an image position, you'll first want to be zoomed in enough so that you can see the individual image points. A high zoom level will make it easier to be more accurate in your adjustments. 

From there, all you'll need to do is hover over the image you'd like to move, and your cursor icon will change to reflect that you can move its position. Simply move the image to a more correct spot! 

If you mess up, or want to just delete a poor image instead before uploading, you can use the undo button and delete button, found in the top right corner of the GUI.

Before and after editing a cluster of images with poor GPS

Once you've finished making any necessary adjustments, click 'Upload' to start uploading the prepared images to Mapillary. The progress bar is an accurate reflection of where you files are at in the upload process.

You can leave your computer if you'd like; the Desktop Uploader will prevent it from going to sleep until all files have been uploaded. If your connection drops, the Uploader will retry the upload a number of times automatically. If repeatedly unsuccessful, the upload will be listed in your Upload history, as failed, so you can retry manually at a different time.

📹Uploading videos

The Desktop Uploader supports video files from many popular 360° cameras, action cameras, and dashboard cameras.

Once you add your video files, as detailed in Adding files, for upload, you'll see a preview of their GPS tracks in the map pane. Now is a good time to check that everything looks positionally accurate. 

In the above screenshot, you'll notice a red warning symbol next to one of the videos. You can hover over this warning to learn more.

In this scenario, the video did not have any GPS data. In certain use cases, you may choose to work with a non-GPS enabled camera and a separate GPS enabled device. Fortunately, the Desktop Uploader allows you to geotag imagery via the 'Add GPX file' video setting, as seen below.

You may also choose to add a separate GPS track to an already geotagged video, if you believe it to be more accurate.

Additionally, 'View details' will open a pop-up showing the video's file path and options to view the video in your device's file explorer or media player.

Once you're ready to upload, hit the 'Upload' button at the bottom left.

You can leave your computer if you'd like; the Desktop Uploader will prevent it from going to sleep until all files have been uploaded. If your connection drops, the Uploader will retry the upload a number of times automatically. If repeatedly unsuccessful, the upload will be listed in your Upload history, as failed, so you can retry manually at a different time.

After uploading, Mapillary will sample your videos for image frames. You should see your processed uploads on the platform within 24 hours, although note that processing videos takes a bit longer compared to images.

🔄Upload history and retrying uploads

At the top right of the Uploader window, you will see the 'Upload History' button. Click into this to see all of your uploads—both completed and failed. 

You can see which account you uploaded to, the number of files that were uploaded, the date the upload completed, and whether the upload was successful. For failed or canceled uploads, you can click the 'Retry upload' button right there to retry the upload.

From the three dots at the end of the row, you can access some additional options such as removing the upload from your Upload History and viewing the sum file size of your uploads.

⚠️Reporting issues & error logs

If you run into any errors with the Uploader, please create a Help Center ticket and provide the following information:

• Description of the problem 
• A detailed description of the steps taken that generated the error
• Platform (macOS or Windows)
• Version (found in lower-right corner of main page)
• Screenshots or videos illustrating the problem
• Log files

To find the log files (you may need to allow viewing hidden files, see the previous section):

• On macOS: ~/Library/Logs/<app name>/log.log
  For example: ~/Library/Logs/Mapillary\ Uploader/log.log (expanded to /Users/username/Library/Logs/Mapillary\ Uploader/log.log)
• On Windows: %USERPROFILE%\AppData\Roaming\<app name>\log.log
  For example: C:\Users\IEUser\AppData\Roaming\Mapillary Uploader\log.log

Note: If you encounter problems starting the Uploader on Linux, use the --no-sandbox flag.