Skip to content

Stamp interval samples of a timelapse with their capture times - #852

Open
caglarpir wants to merge 1 commit into
mapillary:mainfrom
caglarpir:stamp-timelapse-samples
Open

caglarpir wants to merge 1 commit into
mapillary:mainfrom
caglarpir:stamp-timelapse-samples

Conversation

@caglarpir

@caglarpir caglarpir commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

Problem

Interval sampling stamps each frame with the video's start time plus its time in the video. Each second of a timelapse spans several seconds of capture, so its frames are stamped that many times too close together:

  • With --geotag_source gpx, the frames all land near the start of the track. A 5 s, 30x GoPro MAX timelapse, geotagged from a GPX of its own GPS track, comes out with a median error of 670 m, its frames spread over 21 m of a 1.4 km route.
  • With --geotag_source gopro, the frames are placed right but stamped 0.5 s apart for 15 s of travel, so the speed check rejects them (1,134 km/h).

Changes

  • Interval sampling reads the rate from the video's GPS clock with _read_video_clock(), as GPX sync does since Sync a GPX to the GPS clock of a timelapse, even one too noisy to publish #849, and stamps the frames at that rate. The start time is mapped back from the first GPS timestamps at the same rate.
  • --video_duration_ratio used to apply to every video. It now paces only the videos without a GPS clock, so a ratio given for those doesn't affect the other videos in a batch. A video whose clock overrides a given ratio logs a warning naming the clock's rate.
  • GeotagImagesFromVideo (the gopro, camm and blackvue image sources) times the video's track in GPS seconds at the clock's rate, to match the stamps. This also fixes distance samples of a timelapse, which were already stamped with their capture times.
  • The telemetry is read once per video. If it fails to parse, the warning is now "Unable to read the telemetry of ...".

Verification

Two GoPro MAX timelapses, remuxed to a single video stream (see the end), each geotagged from a GPX of its own GPS track, interval 0.5 s. Median error against the video's own track:

main this PR
30x, gpx 670 m 0.5 m
15x, gpx 85 m 0.1 m
30x, gopro rejected (speed) 0 m
15x, gopro 0 m 0 m
  • Distance samples with gopro: 148 of 150 and 81 of 82 frames geotagged, where main geotags 0 and 7.
  • Normal-speed videos (GoPro HERO7 and HERO8, BlackVue, Insta360 Pro), interval sampling with gpx and with their own source: output identical to main.
  • Unit: 919 passed, 18 skipped, 1 xfailed. Integration: 69 passed. Doctests, mypy, ruff check, ruff format --check and usort diff are clean.

GoPro MAX .360

Interval sampling interleaves the two video streams of a .360 file, so its frames are stamped as if twice as late (#854 fixes that). Until then, on a .360 timelapse the second half of the frames is stamped past the end of the track and fails with MapillaryOutsideGPXTrackError, where main placed every frame 127 m to 1.4 km off.

With #854: one hunk in _sample_single_video_by_interval: probe once, then this PR's telemetry and rate. With #851: the imports of sample_video.py.

Interval sampling stamped each frame with the start time of the video plus
its time in the video. A timelapse packs several seconds of capture into
each second of video, so its frames were stamped that many times too close
together. Geotagged from a GPX by those stamps, they all landed near the
start of the track. Geotagged from the video's own track, they moved so far
per second that the speed check could reject them: a 30x timelapse of a
drive read as over 1,000 km/h.

Interval sampling now reads the rate from the video's GPS clock, as GPX sync
does, and stamps the frames at it. The start time is mapped back from the
first GPS timestamps at the same rate. --video_duration_ratio, which used to
apply to every video, now paces only the videos without a GPS clock, so that
a ratio given for those leaves the other videos in the batch alone. Each
video whose clock overrides a given ratio says so in a warning.

The samples are then geotagged from the video's own track (the gopro, camm
and blackvue sources) by their time since the first sample, while the track
is timed in video seconds. It is now timed in GPS seconds, at the rate of its
clock. That also fixes distance samples of a timelapse, which were already
stamped with their capture times.
@caglarpir
caglarpir force-pushed the stamp-timelapse-samples branch from c2541c0 to 484d281 Compare October 21, 2026 09:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant