Sync a GPX to a video without a GPS clock at --video_duration_ratio

mapillary_tools/commands/sample_video.py

@@ -34,7 +34,7 @@ def add_basic_arguments(self, parser: argparse.ArgumentParser):
         )
         group.add_argument(
             "--video_duration_ratio",
-            help="[DEPRECATED since v0.10.0] Real time video duration ratio of the under or oversampled video duration. [default: %(default)s]",
+            help="Seconds of real time per second of video, for videos without a GPS clock of their own to tell, such as 60 for a timelapse that took a frame every 2 seconds and plays at 30 frames per second. A timelapse needs it to be synced to a GPX track. The GPS clock of a video, if it has one, wins. [default: %(default)s]",
             type=float,
             default=constants.VIDEO_DURATION_RATIO,
             required=False,

mapillary_tools/exceptions.py

@@ -91,8 +91,9 @@ class MapillaryStationaryVideoError(MapillaryDescriptionError):
 
 class MapillaryGPXVideoStartUnknownError(MapillaryDescriptionError):
     """
-    Nothing says where along a GPX track a video without GPS starts, and the
-    track is too long to assume that it starts with the video.
+    Nothing says how a GPX track lines up with a video without a GPS clock:
+    the track is too long either to assume that it starts with the video, or,
+    when it is said to, to end with it at the rate the video is said to run.
     """
 
 

mapillary_tools/geotag/geotag_images_from_video.py

@@ -5,6 +5,7 @@
 
 from __future__ import annotations
 
+import dataclasses
 import logging
 import sys
 import typing as T
@@ -15,10 +16,11 @@
 else:
     from typing_extensions import override
 
-from .. import types, utils
+from .. import geo, types, utils
 from .base import GeotagImagesFromGeneric
 from .geotag_images_from_gpx import GeotagImagesFromGPX
 from .geotag_videos_from_video import GeotagVideosFromVideo
+from .video_extractors.gpx import GPXVideoExtractor
 
 
 LOG = logging.getLogger(__name__)
@@ -74,7 +76,7 @@ def to_description(
             )
 
             geotag = GeotagImagesFromGPX(
-                video_metadata.points,
+                self._on_capture_timeline(video_metadata.points),
                 use_gpx_start_time=False,
                 use_image_start_time=True,
                 offset_time=self.offset_time,
@@ -98,6 +100,21 @@ def to_description(
 
         return final_image_metadatas
 
+    @classmethod
+    def _on_capture_timeline(
+        cls, points: T.Sequence[geo.Point]
+    ) -> T.Sequence[geo.Point]:
+        """
+        Time the video's GPS points in GPS seconds from the start of the video,
+        like the samples, which are stamped with their capture times. Each
+        second of a timelapse spans as many as its GPS clock runs faster.
+        """
+        clock = GPXVideoExtractor._read_video_clock(points)
+        if clock is None or clock.rate == 1.0:
+            return points
+
+        return [dataclasses.replace(p, time=p.time * clock.rate) for p in points]
+
 
 class GeotagImageSamplesFromVideo(GeotagImagesFromGeneric):
     def __init__(

mapillary_tools/geotag/options.py

@@ -166,6 +166,10 @@ class VideoSyncOption:
     # frame at the start of the GPX
     use_gpx_start_time: bool = False
 
+    # --video_duration_ratio: GPS seconds per second of a video without a GPS
+    # clock of its own to tell, such as a timelapse
+    duration_ratio: float = 1.0
+
 
 SourceOptionSchema = {
     "type": "object",