mapillary-tools 0.10.6a1__tar.gz → 0.11.0b2__tar.gz

{mapillary_tools-0.10.6a1 → mapillary_tools-0.11.0b2}/PKG-INFO

@@ -1,13 +1,24 @@
 Metadata-Version: 2.1
 Name: mapillary_tools
-Version: 0.10.6a1
+Version: 0.11.0b2
 Summary: Mapillary Image/Video Import Pipeline
 Home-page: https://github.com/mapillary/mapillary_tools
 Author: Mapillary
 License: BSD
-Requires-Python: >=3.6
+Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: appdirs<2.0.0,>=1.4.4
+Requires-Dist: construct<3.0.0,>=2.10.0
+Requires-Dist: exifread==2.3.2
+Requires-Dist: piexif==1.1.3
+Requires-Dist: gpxpy<1.6.0,>=1.5.0
+Requires-Dist: pynmea2==1.12.0
+Requires-Dist: requests<3.0.0,>=2.20.0
+Requires-Dist: tqdm<5.0,>=4.0
+Requires-Dist: typing_extensions
+Requires-Dist: jsonschema~=4.17.3
+Requires-Dist: dataclasses; python_version <= "3.6"
 
 <p align="center">
   <a href="https://github.com/mapillary/mapillary_tools/">
@@ -303,6 +314,93 @@ mapillary_tools video_process MY_VIDEO_DIR \
     --video_sample_distance -1 --video_sample_interval 2
 ```
 
+## New video geotagging features (experimental)
+
+As experimental features, mapillary_tools can now:
+* Geotag videos from tracks recorded in GPX and NMEA files
+* Invoke `exiftool` internally, if available on the system. `exiftool` can extract geolocation data from a wide
+range of video formats, allowing us to support more cameras with less trouble for the end user.
+* Try several geotagging sources sequentially, until proper data is found.
+
+These features apply to the `process` command, which analyzes the video for direct upload instead of sampling it
+into images. They are experimental and will be subject to change in future releases.
+
+### Usage
+
+The new video processing is triggered with the `--video_geotag_source SOURCE` option. It can be specified multiple times:
+In this case, each source will be tried in turn, until one returns good quality data.
+
+`SOURCE` can be:
+1. the plain name of the source - one of `video, camm, gopro, blackvue, gpx, nmea, exiftool_xml, exiftool_runtime`
+2. a JSON object that includes optional parameters
+```json5
+{
+  "source": "SOURCE",
+  "pattern": "FILENAME_PATTERN" // optional
+}
+```
+
+PATTERN specifies how the data source file is named, starting from the video filename:
+* `%f`: the full video filename
+* `%g`: the video filename without extension
+* `%e`: the video filename extension
+
+Supported sources and their default pattern are:
+
+* `video`: parse the video, in order, as `camm, gopro, blackvue`. Pattern: `%f`
+* `camm`: parse the video looking for a CAMM track. Pattern: `%f`
+* `gopro`: parse the video looking for geolocation in GoPro format. Pattern: `%f`
+* `blackvue`: parse the video looking for geolocation in BlackVue format. Pattern: `%f`
+* `gpx`: external GPX file. Pattern: `%g.gpx`
+* `nmea`: external NMEA file. Pattern: `%g.nmea`
+* `exiftool_xml`: external XML file generated by exiftool. Pattern: `%g.xml`
+* `exiftool_runtime`: execute exiftool on the video file. Pattern: `%f`
+
+Notes:
+* `exiftool_runtime` only works if exiftool is installed on the system. You can find it at https://exiftool.org/ or through
+your software manager. If exiftool is installed, but is not in the default execution path, it is
+possible to specify its location by setting the environment variable `MAPILLARY_TOOLS_EXIFTOOL_PATH`.
+* Pattern are case-sensitive or not depending on the filesystem - in Windows, `%g.gpx` will match both `basename.gpx`
+and `basename.GPX`, in MacOs, Linux or other Unix systems no.
+* If both `--video_geotag_source` and `--geotag_source` are specified, `--video_geotag_source` will apply to video files
+and `--geotag_source` to image files.
+
+### Examples
+
+#### Generic supported videos
+
+Process all videos in a directory, trying to parse them as CAMM, GoPro or BlackVue:
+```sh
+mapillary_tools process --video_geotag_source video VIDEO_DIR/
+```
+
+#### External GPX
+
+Process all videos in a directory, taking geolocation data from GPX files. A video named `foo.mp4` will be associated
+with a GPX file called `foo.gpx`.
+```sh
+mapillary_tools process --video_geotag_source gpx VIDEO_DIR/
+```
+
+#### Insta360 stitched videos
+
+The videos to process have been stitched by Insta360 Studio; the geolocation data is in the original
+videos in the parent directory, and there may be GPX files alongside the stitched video.
+First look for GPX, then fallback to running exiftool against the original videos.
+```sh
+mapillary_tools process \
+--video_geotag_source gpx \
+--video_geotag_source '{"source": "exiftool_runtime", "pattern": "../%g.insv"}' \
+VIDEO_DIR/
+```
+
+### Limitations of `--video_geotag_source`
+
+**External geolocation sources will be aligned with the start of video, there is
+currently no way of applying offsets or scaling the time.** This means, for instance, that GPX tracks must begin precisely
+at the instant of the video, and that timelapse videos are supported only for sources `camm, gopro, blackvue`.
+
+
 ## Authenticate
 
 The command `authenticate` will update the user credentials stored in the config file.

mapillary_tools-0.10.6a1/mapillary_tools.egg-info/PKG-INFO → mapillary_tools-0.11.0b2/README.md

@@ -1,14 +1,3 @@
-Metadata-Version: 2.1
-Name: mapillary-tools
-Version: 0.10.6a1
-Summary: Mapillary Image/Video Import Pipeline
-Home-page: https://github.com/mapillary/mapillary_tools
-Author: Mapillary
-License: BSD
-Requires-Python: >=3.6
-Description-Content-Type: text/markdown
-License-File: LICENSE
-
 <p align="center">
   <a href="https://github.com/mapillary/mapillary_tools/">
     <img src="https://raw.githubusercontent.com/mapillary/mapillary_tools/main/docs/images/logo.png">
@@ -303,6 +292,93 @@ mapillary_tools video_process MY_VIDEO_DIR \
     --video_sample_distance -1 --video_sample_interval 2
 ```
 
+## New video geotagging features (experimental)
+
+As experimental features, mapillary_tools can now:
+* Geotag videos from tracks recorded in GPX and NMEA files
+* Invoke `exiftool` internally, if available on the system. `exiftool` can extract geolocation data from a wide
+range of video formats, allowing us to support more cameras with less trouble for the end user.
+* Try several geotagging sources sequentially, until proper data is found.
+
+These features apply to the `process` command, which analyzes the video for direct upload instead of sampling it
+into images. They are experimental and will be subject to change in future releases.
+
+### Usage
+
+The new video processing is triggered with the `--video_geotag_source SOURCE` option. It can be specified multiple times:
+In this case, each source will be tried in turn, until one returns good quality data.
+
+`SOURCE` can be:
+1. the plain name of the source - one of `video, camm, gopro, blackvue, gpx, nmea, exiftool_xml, exiftool_runtime`
+2. a JSON object that includes optional parameters
+```json5
+{
+  "source": "SOURCE",
+  "pattern": "FILENAME_PATTERN" // optional
+}
+```
+
+PATTERN specifies how the data source file is named, starting from the video filename:
+* `%f`: the full video filename
+* `%g`: the video filename without extension
+* `%e`: the video filename extension
+
+Supported sources and their default pattern are:
+
+* `video`: parse the video, in order, as `camm, gopro, blackvue`. Pattern: `%f`
+* `camm`: parse the video looking for a CAMM track. Pattern: `%f`
+* `gopro`: parse the video looking for geolocation in GoPro format. Pattern: `%f`
+* `blackvue`: parse the video looking for geolocation in BlackVue format. Pattern: `%f`
+* `gpx`: external GPX file. Pattern: `%g.gpx`
+* `nmea`: external NMEA file. Pattern: `%g.nmea`
+* `exiftool_xml`: external XML file generated by exiftool. Pattern: `%g.xml`
+* `exiftool_runtime`: execute exiftool on the video file. Pattern: `%f`
+
+Notes:
+* `exiftool_runtime` only works if exiftool is installed on the system. You can find it at https://exiftool.org/ or through
+your software manager. If exiftool is installed, but is not in the default execution path, it is
+possible to specify its location by setting the environment variable `MAPILLARY_TOOLS_EXIFTOOL_PATH`.
+* Pattern are case-sensitive or not depending on the filesystem - in Windows, `%g.gpx` will match both `basename.gpx`
+and `basename.GPX`, in MacOs, Linux or other Unix systems no.
+* If both `--video_geotag_source` and `--geotag_source` are specified, `--video_geotag_source` will apply to video files
+and `--geotag_source` to image files.
+
+### Examples
+
+#### Generic supported videos
+
+Process all videos in a directory, trying to parse them as CAMM, GoPro or BlackVue:
+```sh
+mapillary_tools process --video_geotag_source video VIDEO_DIR/
+```
+
+#### External GPX
+
+Process all videos in a directory, taking geolocation data from GPX files. A video named `foo.mp4` will be associated
+with a GPX file called `foo.gpx`.
+```sh
+mapillary_tools process --video_geotag_source gpx VIDEO_DIR/
+```
+
+#### Insta360 stitched videos
+
+The videos to process have been stitched by Insta360 Studio; the geolocation data is in the original
+videos in the parent directory, and there may be GPX files alongside the stitched video.
+First look for GPX, then fallback to running exiftool against the original videos.
+```sh
+mapillary_tools process \
+--video_geotag_source gpx \
+--video_geotag_source '{"source": "exiftool_runtime", "pattern": "../%g.insv"}' \
+VIDEO_DIR/
+```
+
+### Limitations of `--video_geotag_source`
+
+**External geolocation sources will be aligned with the start of video, there is
+currently no way of applying offsets or scaling the time.** This means, for instance, that GPX tracks must begin precisely
+at the instant of the video, and that timelapse videos are supported only for sources `camm, gopro, blackvue`.
+
+
 ## Authenticate
 
 The command `authenticate` will update the user credentials stored in the config file.

mapillary_tools-0.11.0b2/mapillary_tools/__init__.py

@@ -0,0 +1 @@
+VERSION = "0.11.0b2"

{mapillary_tools-0.10.6a1 → mapillary_tools-0.11.0b2}/mapillary_tools/api_v4.py

@@ -1,15 +1,8 @@
 import os
-import sys
 import typing as T
-from typing import Union
 
 import requests
 
-if sys.version_info >= (3, 8):
-    from typing import Literal  # pylint: disable=no-name-in-module
-else:
-    from typing_extensions import Literal
-
 MAPILLARY_CLIENT_TOKEN = os.getenv(
     "MAPILLARY_CLIENT_TOKEN", "MLY|5675152195860640|6b02c72e6e3c801e5603ab0495623282"
 )
@@ -31,7 +24,7 @@ def get_upload_token(email: str, password: str) -> requests.Response:
 
 
 def fetch_organization(
-    user_access_token: str, organization_id: Union[int, str]
+    user_access_token: str, organization_id: T.Union[int, str]
 ) -> requests.Response:
     resp = requests.get(
         f"{MAPILLARY_GRAPH_API_ENDPOINT}/{organization_id}",
@@ -47,7 +40,7 @@ def fetch_organization(
     return resp
 
 
-ActionType = Literal[
+ActionType = T.Literal[
     "upload_started_upload", "upload_finished_upload", "upload_failed_upload"
 ]
 

{mapillary_tools-0.10.6a1 → mapillary_tools-0.11.0b2}/mapillary_tools/commands/__main__.py

@@ -63,14 +63,14 @@ def add_general_arguments(parser, command):
     elif command in ["upload"]:
         parser.add_argument(
             "import_path",
-            help="Path to your images.",
+            help="Paths to your images or videos.",
             nargs="+",
             type=Path,
         )
     elif command in ["process", "process_and_upload"]:
         parser.add_argument(
             "import_path",
-            help="Path to your images.",
+            help="Paths to your images or videos.",
             nargs="+",
             type=Path,
         )
@@ -167,7 +167,9 @@ def main():
     try:
         args.func(argvars)
     except exceptions.MapillaryUserError as exc:
-        LOG.error("%s: %s", exc.__class__.__name__, exc)
+        LOG.error(
+            "%s: %s", exc.__class__.__name__, exc, exc_info=log_level == logging.DEBUG
+        )
         sys.exit(exc.exit_code)
 
 

{mapillary_tools-0.10.6a1 → mapillary_tools-0.11.0b2}/mapillary_tools/commands/process.py

@@ -171,6 +171,13 @@ class Command:
             required=False,
             type=Path,
         )
+        group_geotagging.add_argument(
+            "--video_geotag_source",
+            help="Name of the video data extractor and optional arguments. Can be specified multiple times. See the documentation for details. [Experimental, subject to change]",
+            action="append",
+            default=[],
+            required=False,
+        )
         group_geotagging.add_argument(
             "--interpolation_use_gpx_start_time",
             help=f"If supplied, the first image will use the first GPX point time for interpolation, which means the image location will be interpolated to the first GPX point too. Only works for geotagging from {', '.join(geotag_gpx_based_sources)}.",
@@ -261,13 +268,14 @@ class Command:
             vars_args["duplicate_angle"] = 360
 
         metadatas = process_geotag_properties(
+            vars_args=vars_args,
             **(
                 {
                     k: v
                     for k, v in vars_args.items()
                     if k in inspect.getfullargspec(process_geotag_properties).args
                 }
-            )
+            ),
         )
 
         metadatas = process_import_meta_properties(

{mapillary_tools-0.10.6a1 → mapillary_tools-0.11.0b2}/mapillary_tools/constants.py

@@ -18,6 +18,7 @@ VIDEO_SAMPLE_DISTANCE = float(os.getenv(_ENV_PREFIX + "VIDEO_SAMPLE_DISTANCE", 3
 VIDEO_DURATION_RATIO = float(os.getenv(_ENV_PREFIX + "VIDEO_DURATION_RATIO", 1))
 FFPROBE_PATH: str = os.getenv(_ENV_PREFIX + "FFPROBE_PATH", "ffprobe")
 FFMPEG_PATH: str = os.getenv(_ENV_PREFIX + "FFMPEG_PATH", "ffmpeg")
+EXIFTOOL_PATH: str = os.getenv(_ENV_PREFIX + "EXIFTOOL_PATH", "exiftool")
 IMAGE_DESCRIPTION_FILENAME = os.getenv(
     _ENV_PREFIX + "IMAGE_DESCRIPTION_FILENAME", "mapillary_image_description.json"
 )

{mapillary_tools-0.10.6a1 → mapillary_tools-0.11.0b2}/mapillary_tools/exceptions.py

@@ -34,6 +34,10 @@ class MapillaryFFmpegNotFoundError(MapillaryUserError):
     help = "https://github.com/mapillary/mapillary_tools#video-support"
 
 
+class MapillaryExiftoolNotFoundError(MapillaryUserError):
+    exit_code = 8
+
+
 class MapillaryDescriptionError(Exception):
     pass
 

{mapillary_tools-0.10.6a1 → mapillary_tools-0.11.0b2}/mapillary_tools/exif_read.py

@@ -1,8 +1,10 @@
 import abc
 import datetime
 import logging
+import re
 import typing as T
 import xml.etree.ElementTree as et
+from fractions import Fraction
 from pathlib import Path
 
 import exifread
@@ -21,6 +23,8 @@ XMP_NAMESPACES = {
 # https://github.com/ianare/exif-py/issues/167
 EXIFREAD_LOG = logging.getLogger("exifread")
 EXIFREAD_LOG.setLevel(logging.ERROR)
+SIGN_BY_DIRECTION = {None: 1, "N": 1, "S": -1, "E": 1, "W": -1}
+ADOBE_FORMAT_REGEX = re.compile(r"(\d+),(\d{1,3}\.?\d*)([NSWE])")
 
 
 def eval_frac(value: Ratio) -> float:
@@ -47,6 +51,38 @@ def gps_to_decimal(values: T.Tuple[Ratio, Ratio, Ratio]) -> T.Optional[float]:
     return degrees + minutes / 60 + seconds / 3600
 
 
+def _parse_coord_numeric(coord: str, ref: T.Optional[str]) -> T.Optional[float]:
+    try:
+        return float(coord) * SIGN_BY_DIRECTION[ref]
+    except (ValueError, KeyError):
+        return None
+
+
+def _parse_coord_adobe(coord: str) -> T.Optional[float]:
+    """
+    Parse Adobe coordinate format: <degrees,fractionalminutes[NSEW]>
+    """
+    matches = ADOBE_FORMAT_REGEX.match(coord)
+    if matches:
+        deg = Ratio(int(matches.group(1)), 1)
+        min_frac = Fraction.from_float(float(matches.group(2)))
+        min = Ratio(min_frac.numerator, min_frac.denominator)
+        sec = Ratio(0, 1)
+        converted = gps_to_decimal((deg, min, sec))
+        if converted is not None:
+            return converted * SIGN_BY_DIRECTION[matches.group(3)]
+    return None
+
+
+def _parse_coord(coord: T.Optional[str], ref: T.Optional[str]) -> T.Optional[float]:
+    if coord is None:
+        return None
+    parsed = _parse_coord_numeric(coord, ref)
+    if parsed is None:
+        parsed = _parse_coord_adobe(coord)
+    return parsed
+
+
 def _parse_iso(dtstr: str) -> T.Optional[datetime.datetime]:
     try:
         return datetime.datetime.fromisoformat(dtstr)
@@ -378,22 +414,22 @@ class ExifReadFromXMP(ExifReadABC):
         )
 
     def extract_lon_lat(self) -> T.Optional[T.Tuple[float, float]]:
-        lat = self._extract_alternative_fields(["exif:GPSLatitude"], float)
+        lat_ref = self._extract_alternative_fields(["exif:GPSLatitudeRef"], str)
+        lat_str: T.Optional[str] = self._extract_alternative_fields(
+            ["exif:GPSLatitude"], str
+        )
+        lat: T.Optional[float] = _parse_coord(lat_str, lat_ref)
         if lat is None:
             return None
 
-        lon = self._extract_alternative_fields(["exif:GPSLongitude"], float)
+        lon_ref = self._extract_alternative_fields(["exif:GPSLongitudeRef"], str)
+        lon_str: T.Optional[str] = self._extract_alternative_fields(
+            ["exif:GPSLongitude"], str
+        )
+        lon = _parse_coord(lon_str, lon_ref)
         if lon is None:
             return None
 
-        ref = self._extract_alternative_fields(["exif:GPSLongitudeRef"], str)
-        if ref and ref.upper() == "W":
-            lon = -1 * lon
-
-        ref = self._extract_alternative_fields(["exif:GPSLatitudeRef"], str)
-        if ref and ref.upper() == "S":
-            lat = -1 * lat
-
         return lon, lat
 
     def extract_make(self) -> T.Optional[str]:

{mapillary_tools-0.10.6a1 → mapillary_tools-0.11.0b2}/mapillary_tools/exiftool_read.py

@@ -310,6 +310,10 @@ class ExifToolRead(exif_read.ExifReadABC):
         if lon_lat is not None:
             return lon_lat
 
+        lon_lat = self._extract_lon_lat("XMP-exif:GPSLongitude", "XMP-exif:GPSLatitude")
+        if lon_lat is not None:
+            return lon_lat
+
         return None
 
     def _extract_lon_lat(

{mapillary_tools-0.10.6a1 → mapillary_tools-0.11.0b2}/mapillary_tools/ffmpeg.py

@@ -11,22 +11,17 @@ import tempfile
 import typing as T
 from pathlib import Path
 
-if sys.version_info >= (3, 8):
-    from typing import TypedDict  # pylint: disable=no-name-in-module
-else:
-    from typing_extensions import TypedDict
-
 LOG = logging.getLogger(__name__)
 FRAME_EXT = ".jpg"
 NA_STREAM_IDX = "NA"
 
 
-class StreamTag(TypedDict):
+class StreamTag(T.TypedDict):
     creation_time: str
     language: str
 
 
-class Stream(TypedDict):
+class Stream(T.TypedDict):
     codec_name: str
     codec_tag_string: str
     codec_type: str
@@ -37,7 +32,7 @@ class Stream(TypedDict):
     width: int
 
 
-class ProbeOutput(TypedDict):
+class ProbeOutput(T.TypedDict):
     streams: T.List[Stream]
 
 

{mapillary_tools-0.10.6a1 → mapillary_tools-0.11.0b2}/mapillary_tools/geotag/construct_mp4_parser.py

@@ -1,17 +1,11 @@
 # pyre-ignore-all-errors[5, 16, 21, 58]
 
-import sys
 import typing as T
 
-if sys.version_info >= (3, 8):
-    from typing import Literal, TypedDict  # pylint: disable=no-name-in-module
-else:
-    from typing_extensions import Literal, TypedDict
-
 import construct as C
 
 
-BoxType = Literal[
+BoxType = T.Literal[
     b"@mak",
     b"@mod",
     b"co64",
@@ -46,7 +40,7 @@ BoxType = Literal[
 ]
 
 
-class BoxDict(TypedDict, total=True):
+class BoxDict(T.TypedDict, total=True):
     type: BoxType
     data: T.Union[T.Sequence["BoxDict"], T.Dict[str, T.Any], bytes]
 

{mapillary_tools-0.10.6a1 → mapillary_tools-0.11.0b2}/mapillary_tools/geotag/gpmf_parser.py

@@ -1,13 +1,7 @@
 import io
 import pathlib
-import sys
 import typing as T
 
-if sys.version_info >= (3, 8):
-    from typing import TypedDict  # pylint: disable=no-name-in-module
-else:
-    from typing_extensions import TypedDict
-
 import construct as C
 
 from .. import geo
@@ -35,7 +29,7 @@ NOTE:
 """
 
 
-class KLVDict(TypedDict):
+class KLVDict(T.TypedDict):
     key: bytes
     type: bytes
     structure_size: int