Mapillary_tools usage for GoPro Max

Contributing and equipment Command line tools
1

I have *.360 files from GoPro Max and want to process using mapillary_tools to upload rectilinear 360 images that are spaced with GPS distance three meters. I am on Windows 10 so i cant generate rectilinear mp4 with embedded GPMF metadata as this option only works in Mac version of GoPro Player.

Currently i am only able to sample rectilinear 360 images with time interval, not GPS distance.

Following workflow:

  1. Convert *.360 file to rectilinear *.mp4 (without GPMF metadata as i am on Windows 10)

  2. run mapillary_tools sample_video --video_sample_distance -1 --video_sample_interval 2 E:\GoPro\GS010603.mp4

  3. Rename folder with sampled images from
    E:\GoPro\mapillary_sampled_video_frames\GS010603.mp4 to GS010603.360

  4. run mapillary_tools process --geotag_source gopro_videos --filetypes image --geotag_source_path E:\ORIGINALS\GS010603.360 E:\GoPro\mapillary_sampled_video_frames\GS010603.360

  5. run mapillary_tools upload --user_name <***> --organization_key <***> E:\GoPro\mapillary_sampled_video_frames\GS010603.360

2

You can ignore my previous post as after several days of looking i found a better way of dealing with GoPro Max metadata.

I duplicate here what i posed on gopro forum just in case, obviously you don’t need the audio part for mapillary.

  1. Export video using GoPro Player into MP4 format

  2. Download FFMpeg

  3. Use either of this commands

    for GPMF metadata only

    ffmpeg -i "C:\GoPro\GS010603.360" -map 0:3 -c copy "C:\GoPro\GS010603_gpmf.mov"

    for 360 audio only

    ffmpeg -i "C:\GoPro\GS010603.360" -map 0:6 -c copy "C:\GoPro\GS010603_pcm.mov"

    for both GPMF metadata and 360 audio

    ffmpeg -i "C:\GoPro\GS010603.360" -map 0:3 -map 0:6 -c copy "C:\GoPro\GS010603_gpmf_and_pcm.mov"

    this will export data from original .360 container

  4. Add it to MP4 that created by GoPro Player (keep in mind MP4 should be same length timewise as original video for everything to work smoothly, otherwise you can edit as you wish)

    (first input file depends on your choice in step 3)

    ffmpeg -i "C:\GoPro\GS010603_gpmf_and_pcm.mov" -i "C:\GoPro\GS010603.mp4" -map 0 -map 1 -c copy "C:\GoPro\GS010603_gpmf_and_pcm_final.mov"

    Your final output file has to be .mov, can not use .mp4

  5. If you really want to get an MP4 instead of MOV then download MP4Box and use command

    (input file depends on your choice in step 4)

    MP4Box -add "C:\GoPro\GS010603_gpmf_and_pcm_final.mov" -new "C:\GoPro\GS010603_gpmf_and_pcm_final.mp4"

  6. Might need to update timestamps in MP4 using ExifTool

    exiftool -TagsFromFile "E:\GoPro\GS010603.360" "-time:all>time:all" -overwrite_original "E:\GoPro\GS010603_gpmf_and_pcm_final.mp4"

Now you can use MOV or MP4 (depending on your choice) in any program that supports metadata or upload straight to mapillary or google street view.

As a bonus if you want to export 360 audio from original .360 file use this command

ffmpeg -i "C:\GoPro\GS010603.360" -map 0:6 -c:a pcm_s32le "C:\GoPro\GS010603_4ch.wav"

then you can mix it in Adobe Audition for example and export as stereo.

Only benefit i found of 360 audio is that if you use noise reduction in GoPro Max options (i recommend to set Noise Reduction to Auto, really all it does it makes microphone volume lower if camera thinks its too loud?, having it ON all the time just makes microphone volume too low) then wav file is unprocessed audio that will have full volume and better quality, you can save it to stereo and use it instead if noise reduction messes up your audio too much.

1 Like
3

@MapMan - what is the benefit of this approach vs uploading the .360 to mapillary directly? (both mapillary_tools and desktop uploader support .360 videos natively, and they will get sampled to one image every 3 meters by the mapillary server, no processing required by users)

4

If the same data is used for Google Streetview, Google can’t process the .360 files directly.

1 Like
5

To clarify mapillary_tools supports .360 files, but only if end user wants to upload the whole videos + JSON. However for extracting JPG stills from video mapillary_tools only support getting front camera stream from .360 file, for whole 360 image got to convert video to mp4 using GoPro Player which on Windows does not include GPMF in final 360 video.

In situations like mine (and others) where i record about 50 GB of 360 videos at a time and want to upload only JPG’s while having control of the distance between images in meters.
360 JPG generation using mapillary_tools only works from MP4 that has GPMF embedded.

This is mappilary_tools approach i come up with so far.

Export GPMF from .360 file

ffmpeg -i "E:\GoPro\GS010603.360" -map 0:3 -c copy "E:\GoPro\GS010603_gpmf.mov"

Embed GPMF to MP4. Important specify GPMF stream as second option so it will append at the end of the video container, otherwise there is a bug in current version of mapillary_tools that outputs low quality JPG’s.

ffmpeg -i "E:\GoPro\GS010603.mp4" -i "E:\GoPro\GS010603_gpmf.mov" -map 0 -map 1 -c copy "E:\GoPro\GS010603_gpmf_final.mov"

copy timestamps from 360 file

exiftool -TagsFromFile "E:\GoPro\GS010603.360" "-time:all>time:all" -overwrite_original "E:\GoPro\GS010603_gpmf_final.mov"

extract JPG’s

mapillary_tools sample_video --video_sample_distance 3 "E:\GoPro\GS010603_gpmf_final.mov"

generate JSON

mapillary_tools process --filetypes image "E:\GoPro\mapillary_sampled_video_frames\GS010603_gpmf_final.mov"

Upload to Mapillary

mapillary_tools upload --user_name <...> --organization_key <...> E:\GoPro\mapillary_sampled_video_frames\GS010603_gpmf_final.mov

Can be split into less commands if needed, but this is for someone who wants to make their own script for batch processing, so they probably know how to do it.

2 Likes
6

Gotcha, thank you for the clarification!

7

What settings do you use for the 360 to mp4 conversion in Go Pro Player?

8

FYI I am doing this with a GoPro Max Video Time Lapse video. So in that case the line to extract the GPS data is:

ffmpeg -i "C:\GoPro\GS010603.360" -map 0:2 -c copy "C:\GoPro\GS010603_gpmf.mov"

You can examine the results of ffprobe myfile.360 to figure out what -map value to use. The GPS data stream will have something like “Data: bin_data (gpmd / 0x646D7067)” and “GoPro MET”, like this:

  Stream #0:2[0x3](eng): Data: bin_data (gpmd / 0x646D7067), 348 kb/s (default)
      Metadata:
        creation_time   : 2025-07-11T20:33:02.000000Z
        handler_name    : GoPro MET

The Stream #0:2 is what tells you to use -map 2.

The Video Time Lapse doesn’t have an audio track so it makes sense that the stream -map number is one off from a normal video file.

Altogether my .bat file to process/upload a Video Time Lapse .360 file is:

ffmpeg -i "U:\mapillary\gopro_downloads2\GS010183.360" -map 0:2 -c copy "U:\mapillary\gopro_downloads2\GS010183_gpmf.mov"

ffmpeg -i "U:\mapillary\gopro_downloads2\GS010183.mp4" -i "U:\mapillary\gopro_downloads2\GS010183_gpmf.mov" -map 0 -map 1 -c copy "U:\mapillary\gopro_downloads2\GS010183_final.mov"

exiftool -TagsFromFile "U:\mapillary\gopro_downloads2\GS010183.360" "-time:all>time:all" -overwrite_original "U:\mapillary\gopro_downloads2\GS010183_final.mov"

mapillary_tools.exe video_process "U:\mapillary\gopro_downloads2\GS010183_final.mov" "U:\mapillary\gopro_samples3" --video_sample_distance 1.5

Also important: The initial .mp4 file (GS010183.mp4 in my example above) is obtained by exporting from GoPro Player with these settings:

  • CODEC: HVEC
  • Resolution: 5.6K
  • Bitrate: Max
  • World Lock & Horizon Level checked (not sure if those are the best settings, but what I used)
  • Hardware Encoding checked (on my machine the export would not process without this checked)

I am just uploading the first results from doing this right now, but I think the end result of this will be an upload from a 360 video/Time Lapse Video that will be very noticeably of higher quality than what both default mapillary_tools and the desktop uploader achieve with that same file right now.

1 Like
9

When I have tried uploading .360 files directly using either mapillary_tools or the desktop uploader, they do upload and process but the result is strange to me.

Like, the 360 shots are missing both the stop and the bottom, and the mapping is all distorted - like the project hasn’t been handled correctly, or at all. And in addition to that, the smoothing & matching that GoPro does to blend the images from the two lenses together seamlessly, is missing. It is just the right image and left image plopped together with an ugly un-matched seam.

My impression is, .360 files have 3 streams for the video: top cap, bottom cap, and a 360 degree panorama for the center (around the horizon). It looked to me like Mapillary was just grabbing the 360 degree panorama portion and discarding the top & bottom caps altogether.

When you, instead, use the GoPro Player to export the .360 video to .mp4, it does a bunch of processing and converts the video to a normal equirectangular style 360 video file.

(I confess I haven’t tried to just upload that file raw to see what happens - that might work just fine. But . . . as mentioned elsewhere on the thread, for GoPro player/windows that .mp4 file is missing all the GPS data. So, not much use for Mapillary purposes.)

10

No, there are just 2 videostreams. Please use my program to upload the .360 footage to Mapillary. Dropbox

It will extract the GPMF data from the 360 files and uses the exported mp4 files (from the GoPro player app) to make a file that Mapillary Tools can use for the extraction. Please give it a try, all the necessary apps are already inside this program.

11

@flug32 - are you uploading .360 files from the GoPro MAX (fully supported, should work well), or the GoPro MAX 2 (not yet supported, you will need to stitch the .360 as .mp4 using GoPro Player). We are working on adding GoPro MAX 2 support, but its not yet available.