Python3 BlackVue upload

Just checking

First time I tried to use the tools to upload my Mapillary firmware equipped BlackVue vids in about a year

  • First I get an error about only supporting “Front” which it already is.
    ERROR: Currently, only front Blackvue videos are supported on this command. Please use video_process command for backwards camera videos

  • When I comment out this test in the code it fails unable to find GPS data
    Warning, could not extract gps from video 20210322_123530_NF.mp4 due to a bytes-like object is required, not ‘str’, video will be skipped…

Is anyone successfully using the firmware supplied 1CH BlackVue with the recent P3 tools?

1 Like

I guess it’s designed to work with DR900 series only. Are you trying with DR900 produced video?
Make sure you are using correct advance options, esp.
--geotag_source "blackvue_videos"

It is a DR900, supplied by Mapillary under their camera program a couple of years back, then loaded with the custom firmware.

In the past I used the now deprecated local sampling method defining the geotag source, then the Python 2 version of Direct Upload. I have had a fellow mapper uploading my mp4’s for 6 months now using doku. I have however just had the need to upload some for quick use and want to know if it is working for anyone else.

The direct upload help syntax has no gps choice function, but I will try it.

I am using a virtual environment.


Did you solve your issue? I am having similar issues. I have received no response from the Mapillary support email. Tao Peng has been helpful in responding on GitHub but I haven’t managed to successfully upload anything yet.

No not as yet. I see Tao is making many many changes/fixes with master merges, so I think it’s a case of wait.

Hey @danbjoseph @bob3bob3 would you mind send some sample blackvue video to so we can reproduce the issue? Thanks for trying out mapillary_tools.

1 Like

sent! thank you.

1 Like

Sorry @tao , my email server max’s out at 32MBytes. The vid is about 50MBytes.

Pls get from gdrive


@danbjoseph Latest version of mapillary_tools (0.8.0) supports direct Blackvue video uploads to Mapillary. Have you ever had a chance to try it? You do not need to process Blackvue videos, they will be processed on server-side.

For macOS

  • Install mapillary_tools package for macOS
  • Run below command to directly upload your Blackvue videos

find /DirectoryOftheVideos | xargs -n1 ./mapillary_tools upload

  • Ignore the RuntimeError and wait mapilary_tools to upload all files from your directory
  • Upload summary will be popped up for each uploaded sequence

Please let me know if this helps.

seems to be working. thank you.

1 Like

Awesome, thanks for the update. We’re planning to support multiple file upload with single command soon. I’ll keep you posted.

1 Like

I am writing down all of the things and code related to Python3 Blck Vue -


Process and upload imagery:

mapillary_tools process_and_upload “path/to/images/”

Upload BlackVue videos:

mapillary_tools upload_blackvue “path/to/blackvue_videos/”


User Authentication

To upload images to Mapillary, an account is required and can be created [here]. When using the tools for the first time, user authentication is required. You will be prompted to enter your account credentials.


To upload images to Mapillary, image GPS and capture time are minimally required. More information [here].


Installing via Pip

Python (3.6 and above) and git are required:

python3 -m pip install --upgrade git+

If you see “Permission Denied” error, try to run the command above with sudo , or install it in your local [virtualenv]

Installing on Android Devices

A command line program such as Termux is required. Installation can be done without root privileges. The following commands will install Python 3, pip3, git, and all required libraries for mapillary_tools on Termux:

pkg install python git build-essential libgeos openssl libjpeg-turbo python3 -m pip install --upgrade pip wheel python3 -m pip install --upgrade git+

Termux must access the device’s internal storage to process and upload images. To do this, use the following command:


Finally, on devices running Android 11, using a command line program, mapillary_tools will process images very slowly if they are in shared internal storage during processing. It is advisable to first move images to the command line program’s native directory before running mapillary_tools. For an example using Termux, if imagery is stored in the folder Internal storage/DCIM/mapillaryimages the following command will move that folder from shared storage to Termux:

mv -v storage/dcim/mapillaryimages mapillaryimages

Video Support

To [proces). Make sure it is executable and put the downloaded binaries in your $PATH . You can also install ffmpeg with your favourite package manager. For example:

On macOS, use [Homebrew]:

brew install ffmpeg

On Debian/Ubuntu:

sudo apt install ffmpeg



The process command geotags images in the given directory. It extracts the required and optional metadata from image EXIF (or the other supported geotag sources), and writes all the metadata (or process errors) in an [image description] file, which will be read during [upload].


Process all images in the directory path/to/images/ (and its sub-directories):

mapillary_tools process “path/to/images/”

Interpolate images in the directory path/to/images/ on the GPX track read from path/to/gpx_file.gpx . The images are required to contain capture time in order to sort the images and interpolate them.

mapillary_tools process “path/to/images/” \ --geotag_source “gpx” \ --geotag_source_path “path/to/gpx_file.gpx”

Process all images in the directory, specifying an angle offset of 90° for the camera direction and splitting images into sequences of images apart by less than 100 meters according to image GPS and less than 120 seconds according to image capture time.

mapillary_tools process “path/to/images/” \ --offset_angle 90 \ --cutoff_distance 100 \ --cutoff_time 120

Upload Images

Images that have been successfully processed can be uploaded with the upload command.


Upload all processed images in the directory path/to/images/ to user mly_user for organization mly_organization_id . It is optional to specify --user_name if you have only one user [authenticated].
mapillary_tools upload “path/to/images/” \ --user_name “mly_user” \ --organization_key “mly_organization_id”

Upload BlackVue Videos

BlackVue videos can be uploaded with the upload command and will be processed on Mapillary servers.


Upload a BlackVue video with file name video_file_name.mp4 to user mly_user for organization mly_organization_id . It is optional to specify --user_name if you have only one user [authenticated].

mapillary_tools upload_blackvue “video_file_name.mp4” \ --user_name “mly_user” \ --organization_key “mly_organization_id”

Upload all BlackVue videos (*.mp4) under the folder:

mapillary_tools upload_blackvue “path/to/blackvue_videos/”

Video Process

Video process involves two commands:

  1. sample_video : sample videos into images, and insert capture times to the image EXIF. Capture time is calculated based on the video start time and sampling interval. This is where ffmpeg is being used.
  2. process : process (geotag) the sample images with the specified source

The two commands are usually combined into a single command video_process .


Sample the videos located in path/to/videos/ at the default sampling rate 2 seconds, i.e. one video frame every two seconds. Video frames will be sampled into a sub-directory path/to/videos/mapillary_sampled_video_frames .

mapillary_tools sample_video “path/to/videos/”

Sample the videos located in path/to/videos/ to directory path/to/sample_images/ at a sampling rate 0.5 seconds, i.e. two video frames every second.

mapillary_tools sample_video “path/to/videos/” “path/to/sample_images/” \ --video_sample_interval 0.5

Sample the videos located in path/to/videos/ to the directory path/to/sample_images/ at the default sampling rate 1 second, i.e. one video frame every second, geotagging data from a gpx track stored in path/to/gpx_file.gpx video, assuming video start time can be extracted from the video file and deriving camera direction based on GPS .

mapillary_tools video_process “path/to/videos/” “path/to/sample_images/” \ --geotag_source “gpx” \ --geotag_source_path “path/to/gpx_file.gpx” \ --video_sample_interval 1 \ --interpolate_directions

GoPro videos : Sample GoPro videos in directory path/to/videos/ into import path path/to/sample_images/ at a sampling rate 0.5 seconds, i.e. two frames every second, reading geotag data from the GoPro videos in path/to/videos/ .

mapillary_tools video_process “path/to/videos/” “path/to/sample_images/” \ --geotag_source “gopro_videos” \ --interpolate_directions \ --video_sample_interval 0.5

BlackVue videos : Sample BlackVue videos in directory path/to/videos/ at a sampling rate 0.2 seconds, i.e. 5 frames every second and process resulting video frames, reading geotag data from the BlackVue videos in path/to/videos/mapillary_sampled_video_frames .

mapillary_tools video_process “path/to/videos/” \ --geotag_source “blackvue_videos”


The command authenticate will update the user credentials stored in the config file.


Authenticate new user:

mapillary_tools authenticate

Authenticate for user mly_user . If the user is already authenticated, it will update the credentials in the config:

mapillary_tools authenticate --user_name “mly_user”



process_and_upload command will run process and upload commands consecutively with combined required and optional arguments. It is equivalent to:

mapillary_tools process “path/to/images/” mapillary_tools upload “path/to/images/”


video_process command will run sample_video and process commands consecutively with combined required and optional arguments. It is equivalent to:

mapillary_tools sample_video “path/to/videos/” “path/to/images/” mapillary_tools upload “path/to/images/”


video_process_and_upload command will run sample_video and process_and_upload commands consecutively with combined required and optional arguments. It is equivalent to:

mapillary_tools sample_video “path/to/videos/” “path/to/videos/mapillary_sampled_video_frames/” mapillary_tools process_and_upload “path/to/videos/mapillary_sampled_video_frames/”

Advanced Usage

Image Description

As the output, the procss command generates mapillary_image_description.json under the image directory by default. The file contains an array of objects, each of which records the metadata of one image in the image directory. The metadata is validated by [the image description schema]. Here is a minimal example:

[ { “MAPLatitude”: 58.5927694, “MAPLongitude”: 16.1840944, “MAPCaptureTime”: “2021_02_13_13_24_41_140”, “filename”: “IMG_0291.jpg” }, { “error”: { “type”: “MapillaryGeoTaggingError”, “message”: “Unable to extract GPS Longitude or GPS Latitude from the image” }, “filename”: “IMG_0292.jpg” } ]

The upload command then takes the image description file as the input, [zip images] with the specified metadata, and then upload. The required filename property is used to associate images and metadata objects. Objects that contain error property will be ignored.


Write and read the image description file in another location. This is useful if the image directory is readonly.

mapillary_tools process “path/to/images/” --desc_path “description.json” mapillary_tools upload “path/to/images/” --desc_path “description.json” # equivalent to mapillary_tools process_and_upload “path/to/images/” --desc_path “description.json”

Edit the description file with your own scripts, e.g. filter out images outside a bounding box, or snap image locations to the nearest roads:

mapillary_tools process “path/to/images/” --desc_path - \ | ./ 5.9559,45.818,10.4921,47.8084 \ | ./ > “description.json” mapillary_tools upload “path/to/images/” --desc_path “description.json”

Geotag from a custom CSV format.

./ special.csv | mapillary_tools upload “path/to/images/” --desc_path -

Geotag from a custom video format.

sample with ffmpeg ffmpeg -i “path/to/video.mp4” -vf fps=1/1 -qscale 1 -nostdin “path/to/images/video_%06d.jpg” # extract geotags from the videos (or other sources) ./ “path/to/video.mp4” > “description.json” # upload mapillary_tools upload “path/to/images/” --desc_path “description.json”

Zip Images

When [uploading] an image directory, internally the upload command will zip sequences in the temporary directory ( TMPDIR ) and then upload these zip files.

Mapillary Tools provides zip command that allows users to specify where to store the zip files, usually somewhere with faster IO or more free space.


Zip processed images in path/to/images/ and write zip files in path/to/zipped_images/ :

mapillary_tools zip “path/to/images/” “path/to/zipped_images/”

Upload all the zip files (*.zip) under the folder:

mapillary_tools upload_zip “path/to/zipped_images/”

Upload API

mapillary_tools provides a simple Upload API interface:

class Uploader: def init(self, user_items: UserItem, emitter: EventEmitter = None, dry_run=False): … def upload_zipfile(self, zip_path: str) → Optional[int]: … def upload_blackvue(self, blackvue_path: str) → Optional[int]: … def upload_images(self, descs: List[ImageDescriptionFile]) → Dict[str, int]: …


import os from mapillary_tools import uploader # To obtain your user access token, check /#authentication user_item = { “user_upload_token”: “YOUR_USER_ACCESS_TOKEN”, “MAPOrganizationKey”: 1234, } mly_uploader = uploader.Uploader(user_item) descs = [ { “MAPLatitude”: 58.5927694, “MAPLongitude”: 16.1840944, “MAPCaptureTime”: “2021_02_13_13_24_41_140”, “filename”: “path/to/IMG_0291.jpg”, “MAPSequenceUUID”: “sequence_1”, }, { “MAPLatitude”: 58.5927694, “MAPLongitude”: 16.1840944, “MAPCaptureTime”: “2021_02_13_13_24_41_140”, “filename”: “path/to/IMG_0292.jpg”, “MAPSequenceUUID”: “sequence_2”, }, ] # Upload images as 2 sequences mly_uploader.upload_images(descs) # Zip images uploader.zip_images(descs, “path/to/zip_dir”) # Upload zip files for zip_path in os.listdir(“path/to/zip_dir”): if zip_path.endswith(".zip"): mly_uploader.upload_zipfile(zip_path) # Upload blackvue videos directly mly_uploader.upload_blackvue(“path/to/blackvue.mp4”)


In case of any issues with the installation and usage of mapillary_tools , check this section in case it has already been addressed, otherwise, open an issue on GitHub.


  • In case of any issues, it is always safe to try and rerun the failing command while specifying --verbose to see more information printed out. Basically, I have used BlackVue to upload automated payroll software and related things. Uploaded images should not get uploaded more than once and should not be processed after uploading. mapillary_tools should take care of that, if it occurs otherwise, please open an issue on GitHub.
  • Make sure you run the latest version of mapillary_tools , which you can check with mapillary_tools --version . When installing the latest version, don’t forget you need to specify --upgrade .
  • Advanced user are encouraged to explore the processed data and the image description file in the path/to/images/mapillary_image_description.json to get more insight in the failure.

Run time issues

  • HTTP Errors can occur due to poor network connection or high load on the import pipeline. In most cases the images eventually get uploaded regardless. But in some cases HTTP Errors can occur due to authentication issues, which can be resolved by either removing the config file with the users credentials, located in ~/.config/mapillary/config or running mapillary_tools authenticate .
  • Missing required data is often the reason for failed uploads, especially if the processing included parsing external data like a gps trace. Images are aligned with a gps trace based on the image capture time and gps time, where the default assumption is that both are in UTC. Check the beginning and end date of your capture and the beginning and end date of the gps trace to make sure that the image capture time is in the scope of the gps trace. To correct any offset between the two capture times, you can specify --offset_time "offset time" .

Upload quality issues

  • Some devices do not store the camera direction properly, often storing only 0. Camera direction will get derived based on latitude and longitude only if the camera direction is not set or --interpolate_directions is specified. Before processing and uploading images, make sure that the camera direction is either correct or missing and in case it is present but incorrect, you specify --interpolate_directions .


Clone the repository:

Set up the virtual environment. It is optional but recommended:

python3 -m venv venv source venv/bin/activate # For Windows, run: .\venv\Scripts\activate # verify if the venv is activated which python3

Install dependencies:

python3 -m pip install -r requirements.txt -r requirements-dev.txt

Run the code from the repository:

python3 -m mapillary_tools.commands --version

Run tests:

pytest tests

Run linting:

black mapillary_tools tests

Hope this thing will help everyone properly.