Clip a GPX track to the video it geotags when a clock paces it

README.md

@@ -333,20 +333,34 @@ It is used to locate the images along the GPS tracks.
 mapillary_tools process MY_IMAGE_DIR --geotag_source "gpx" --geotag_source_path MY_EXTERNAL_GPS.gpx
 ```
 
-To geotag videos with a GPX file, video start time is required to locate the sample images along the GPS tracks.
-It is read from the video's own GPS track when it has one, and otherwise from the video creation time.
-Cameras disagree on whether the creation time marks the start or the end of the recording (most dashcams write the end),
-so mapillary_tools uses the camera model or a date and time in the file name to tell which, and assumes the start when neither says.
-Use `--video_start_time` to override it, in UTC, when the sample images end up one video duration off along the track.
+To geotag videos with a GPX file, the sample images are located along the GPS track by the time they were captured.
+A video whose own GPS records the time is synced to the track by that clock. For a video without one, specify its start
+time, in UTC, with `--video_start_time`. That start time applies to every video in the command, so to place several
+videos along one GPX file, run it once per video, each with its own start time:
 
 ```sh
-# Geotagging with GPX works with interval-based sampling only,
-# the two options --video_sample_distance -1 --video_sample_interval 2 are therefore required
-# to switch from the default distance-based sampling to the legacy interval-based sampling
-mapillary_tools video_process MY_VIDEO_DIR \
+mapillary_tools video_process MY_VIDEO.mp4 \
     --geotag_source "gpx" \
     --geotag_source_path MY_EXTERNAL_GPS.gpx \
-    --video_sample_distance -1 --video_sample_interval 2
+    --video_start_time 2025_03_14_07_00_30_000
+```
+
+Without it, distance-based sampling (the default) assumes that the track starts with the video, and refuses a track
+more than twice as long as the video. Interval-based sampling (`--video_sample_distance -1 --video_sample_interval N`)
+reads the start time from the video creation time instead. Cameras disagree on whether the creation time marks the start
+or the end of the recording (most dashcams write the end), so mapillary_tools uses the camera model or a date and time
+in the file name to tell which, and assumes the start when neither says.
+
+A timelapse video packs several seconds of capture into each second of video. Its GPS clock, if it has one, tells how
+many. If it has none, specify how many with `--video_duration_ratio`, for instance 60 for a timelapse that took a frame
+every 2 seconds and plays at 30 frames per second:
+
+```sh
+mapillary_tools video_process MY_TIMELAPSE.mp4 \
+    --geotag_source "gpx" \
+    --geotag_source_path MY_EXTERNAL_GPS.gpx \
+    --video_start_time 2025_03_14_07_00_30_000 \
+    --video_duration_ratio 60
 ```
 
 Ideally, the GPS device and the capture device should use the same clock to get the timestamps synchronized.
@@ -363,15 +377,17 @@ mapillary_tools process MY_IMAGE_DIR \
 
 Another option `--interpolation_use_gpx_start_time` moves your images to align with the beginning of the GPS track.
 This is useful when you can confirm that you start GPS recording and capturing at the same time, or with a known delay.
+For a video without a GPS clock, a track that lasts more than twice as long as the video spans at its
+`--video_duration_ratio` is then refused. If the GPS logger was left running after the video, pass the start of the
+track as `--video_start_time` instead, which places the video the same way: the error prints it.
 
 ```sh
 # Start capturing 2.5 seconds after start GPS recording
-mapillary_tools video_process MY_VIDEO_DIR \
+mapillary_tools video_process MY_VIDEO.mp4 \
     --geotag_source "gpx" \
     --geotag_source_path MY_EXTERNAL_GPS.gpx \
     --interpolation_use_gpx_start_time \
-    --interpolation_offset_time 2.5 \
-    --video_sample_distance -1 --video_sample_interval 2
+    --interpolation_offset_time 2.5
 ```
 
 ## New video geotagging features (experimental)

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,8 @@
 
 from __future__ import annotations
 
+import bisect
+import dataclasses
 import logging
 import sys
 import typing as T
@@ -15,15 +17,78 @@
 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__)
 
 
+@dataclasses.dataclass(frozen=True)
+class GPSTimeline:
+    """
+    The Unix time of the video's GPS clock along the video: interpolated
+    between its GPS timestamps, and extrapolated beyond them at the clock's
+    rate. A timelapse captured its frames at those times, which one rate from
+    one of them does not follow: the rate drifts from them over the video, and
+    the first timestamp of a GoPro MAX timelapse can be seconds early.
+
+    >>> timeline = GPSTimeline((0.0, 1.0, 2.0), (100.0, 104.0, 114.0), rate=10.0)
+    >>> timeline.to_unix_time(0.5)
+    102.0
+    >>> timeline.to_unix_time(3.0)
+    124.0
+    """
+
+    video_times: tuple[float, ...]
+    unix_times: tuple[float, ...]
+    # GPS seconds per video second beyond the timestamps
+    rate: float
+
+    @classmethod
+    def read(cls, points: T.Sequence[geo.Point], rate: float) -> GPSTimeline | None:
+        """
+        Read the timeline from the GPS timestamps of the points, or None if they
+        have none
+        """
+        pairs: list[tuple[float, float]] = []
+        for p in points:
+            unix_time = p.get_unix_time()
+            if unix_time is None:
+                continue
+            if pairs and unix_time == pairs[-1][1]:
+                # GoPro GPS5 stamps a whole block (~1s) of points with one
+                # timestamp. Keep the first point of the block
+                continue
+            pairs.append((p.time, unix_time))
+
+        if not pairs:
+            return None
+
+        return cls(
+            video_times=tuple(v for v, _ in pairs),
+            unix_times=tuple(u for _, u in pairs),
+            rate=rate,
+        )
+
+    def to_unix_time(self, video_time: float) -> float:
+        idx = bisect.bisect_right(self.video_times, video_time)
+        if 0 < idx < len(self.video_times):
+            v0, v1 = self.video_times[idx - 1], self.video_times[idx]
+            u0, u1 = self.unix_times[idx - 1], self.unix_times[idx]
+            return u0 + (u1 - u0) * (video_time - v0) / (v1 - v0)
+
+        # Before the first timestamp or after the last
+        anchor = 0 if idx == 0 else -1
+        return (
+            self.unix_times[anchor]
+            + (video_time - self.video_times[anchor]) * self.rate
+        )
+
+
 class GeotagImagesFromVideo(GeotagImagesFromGeneric):
     def __init__(
         self,
@@ -74,7 +139,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 +163,28 @@ 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. A
+        timelapse packs several into each second of video, as many as its GPS
+        timestamps tell.
+        """
+        clock = GPXVideoExtractor._read_video_clock(points)
+        if clock is None or clock.rate == 1.0:
+            return points
+
+        timeline = GPSTimeline.read(points, clock.rate)
+        assert timeline is not None, "a GPS clock is read from GPS timestamps"
+        start = timeline.to_unix_time(0.0)
+        return [
+            dataclasses.replace(p, time=timeline.to_unix_time(p.time) - start)
+            for p in points
+        ]
+
 
 class GeotagImageSamplesFromVideo(GeotagImagesFromGeneric):
     def __init__(

mapillary_tools/geotag/geotag_videos_from_gpx.py

@@ -47,7 +47,12 @@ def _generate_video_extractors(
             if source_path.is_file():
                 results.append(
                     GPXVideoExtractor(
-                        video_path, source_path, video_sync=self.video_sync
+                        video_path,
+                        source_path,
+                        video_sync=self.video_sync,
+                        # The track that process uploads with the video.
+                        # Sampling reads its track only within the video
+                        clip_to_video=self.video_sync is None,
                     )
                 )
             else:

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",