Metadata-Version: 2.1
Name: mapillary-tools
Version: 0.0.4
Summary: Mapillary Commandline Image Uploader
Home-page: https://github.com/MarcelloPerathoner/mapillary-tools
Author: Marcello Perathoner
Author-email: marcello@perathoner.de
License: GPL3
Keywords: mapillary commandline console image upload
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Utilities
Requires-Python: >=3.5.0
Description-Content-Type: text/x-rst
Requires-Dist: piexif
Requires-Dist: requests
Requires-Dist: tqdm
Requires-Dist: urllib3

======================================
 Mapillary Commandline Image Uploader
======================================


Commandline tools to upload discrete images to Mapillary.
Does not support videos.


Rewrite
=======

This is a rewrite of a portion of the official Mapillary tools found at:
https://github.com/mapillary/mapillary_tools

The official Mapillary tools are broken because Python 2 is dead.  Major
distributions have already removed Python 2 from their standard installation.
An official Python 3 port has been requested in May 2018 but has not
materialized so far.

A quick look at the official code shows that it is not worth porting anyway.
That code was obviously written by lots of different people with varying
understanding of Python and then duct-taped together to make it look like one
application.  It also pulls in way too many dependencies, like a full image
manipulation library, 2 different Exif libraries (one of them custom patched)
and an advanced keystore.

The rewritten code uses Python 3 and only a few external libraries.

This code does not change your image files, neither does it copy them around.
All data and housekeeping information is kept in small sidecar files, one file
per image.  This keeps your disk lean and your backups small.  The sidecar files
contain JSON, so debugging is easy.


Usage
=====

0. Install:

   .. code-block:: shell

      pip install mapillary-tools


1. Authorize: This will prompt for your Mapillary password:

   .. code-block:: shell

      mapillary_auth.py --user_name <your_username> --user_email <your_email>

   This step is needed only once.  Your credentials are now stored in the file
   :code:`~/.config/mapillary/configs/<CLIENT_ID>`.  Keep this file secret.
   Mapillary credentials do not expire.


2. Pre-process the images:

   .. code-block:: shell

      mapillary_process.py ~/Pictures/Mapillary/*.jpg

   This step extracts GPS data from your images and stores it in sidecar files.


3. Upload the images:

   .. code-block:: shell

      mapillary_upload.py ~/Pictures/Mapillary/*.jpg

   The script remembers which images were successfully uploaded.  If you run the
   upload script on the same images again, the ones already uploaded will not be
   uploaded again.

4. Cleanup:

   .. code-block:: shell

      mapillary_process.py --clean ~/Pictures/Mapillary/*.jpg

   Delete all sidecar files.  Caution: This will erase all memory about which
   files where already uploaded.

Run the scripts with '-h' to see more options.


Videos
======

This software has no support for videos.

To split a video file into images use ffmpeg, then use exiftool to set the exif
timestamp.

Proposed workflow:

.. code-block:: shell

   mkdir -p /tmp/frames
   # extract I-frames for better clarity
   ffmpeg -i ~/Videos/dash.mp4 -vf "select='eq(pict_type,PICT_TYPE_I)'" -vsync vfr -frame_pts true /tmp/frames/%08d.jpg
   # figure out the start time and frame rate
   ffprobe -v quiet ~/Videos/dash.mp4 -print_format json -show_streams
   # set the same start time on all files
   exiftool '-AllDates=2020:01:01 00:00:00' /tmp/frames/
   # increment time according to frame number
   exiftool '-AllDates+<0:0:${FileName;$_=substr($_,0,8)/30}' /tmp/frames/

See:

- https://trac.ffmpeg.org/wiki/Create%20a%20thumbnail%20image%20every%20X%20seconds%20of%20the%20video
- https://exiftool.org/Shift.html


GPS Tracks
==========

This software has no support for syncronizing to GPS tracks.

To syncronize your images to a GPS track use you can use exiftool.

Proposed workflow:

.. code-block:: shell

   exiftool -geotag=track.gpx /tmp/frames

See: https://exiftool.org/geotag.html


