Skip to content

Read a video's GPS clock as a straight line at the rate it fits - #889

Merged
caglarpir merged 1 commit into
mapillary:mainfrom
caglarpir:straight-video-clock
Oct 23, 2026
Merged

caglarpir merged 1 commit into
mapillary:mainfrom
caglarpir:straight-video-clock

Conversation

@caglarpir

Copy link
Copy Markdown
Contributor

Since #888, GPX sync places a track, and sampling stamps frames, through
every GPS timestamp of the video. The cameras whose timestamps leave a
straight line record in real time, so video time maps to GPS time along
a straight line, and their timestamps jitter about it. A GoPro stamps
each block of 1.001 seconds of video up to 1.7 seconds off the line
through the rest: on a GoPro MAX, the accelerometer timestamps of those
blocks advance 0.996 to 1.006 seconds each, while their GPS timestamps
advance 0 to 3.8 seconds. A PANOX V2 stamps some fixes up to 6 seconds
late.

#888 followed that jitter. It placed a GPX up to 1.4 s off the line on a
GoPro HERO7, 1.6 to 2.9 s on GoPro MAX videos with poor GPS, and 5.9 s
on a PANOX V2. It stamped interval samples 5 s apart from 3.7 to 6.3 s
apart (HERO7), and 10 s apart from 7.2 to 12.8 s apart (PANOX V2). Its
message put the move of a GPX on a GoPro MAX at up to 56 ms, and that of
GoPro interval stamps at up to 1.5 s; on these videos, both moved by up
to 2.9 s.

The LabPano Pilot One and Era, which #888 was written for, need no more
than a straight clock. Their timestamps fit one at 1.143 GPS seconds per
second of video, within 0.3 s over 14 minutes (0.7 s on the Era). The
clock was read at 1x only because any rate below the timelapse rate of
1.5 was rounded to 1.

Read the clock as the least-squares line through the timestamps, at the
rate it fits, anchored at their median as before, and use it everywhere:
GPX sync places the track by it, interval samples and distance samples
of the video's own track are stamped by it, and the geotagging stage
times the video's track at its rate. The fit leaves out the timestamps
that #888 showed to be wrong: those out of order, those before a jump of
more than a day, and stale first ones.

The rate is 1x when it is within 5% of 1x, or when it departs from 1x by
less than 2 seconds over the timestamps. On sample videos, cameras that
record in real time measure within 0.4% of 1x over 20 seconds or more,
or 1.6% for a GoPro MAX whose GPS glitches. Clips of a few seconds
measure up to 14% off 1x, a drift of at most 0.3 s. The LabPanos measure
1.093 to 1.143, a drift of at least 15 s. A rate above 1.5 must still
show in the median step between timestamps, so one timestamp far off
makes no timelapse. Timelapses get a straight clock too. Once their
stale first timestamps are left out, those of GoPro MAX, MAX 2 and Rove
timelapses lie within 0.33 GPS seconds of the line, but for one GoPro
MAX timelapse within 0.82 (55 ms of video), less than the jitter of a
normal video.

On sample videos from 9 cameras:

  • Without a GPX, process writes the same tracks for all of them.
  • A GPX made from a video's own track moves onto the straight line: by
    up to 1.4 s on the HERO7, 2.9 s and 1.6 s on GoPro MAX videos with
    poor GPS, 0.65 s on a GoPro MAX 2, 5.9 s on a PANOX V2, and up to
    0.06 s on other GoPros. Interval samples are stamped evenly, 5.000 s
    or 10.000 s apart, and those of a LabPano 11.426 s apart for 10 s of
    video. Distance samples of the video's own track are stamped by the
    clock, and their positions do not change.
  • A GPX made from a LabPano's own track lands within 0.26 s of its
    timestamps over 14 minutes, and within 0.61 s on the Era. GPX distance
    samples of the 2 fps Era are no longer dropped: Place GPX tracks and stamp samples along the GPS timestamps of a video #888 timed its frames
    alternately fast and slow, so half of them fell under the sample
    distance. One LabPano video is the exception: its GPS drops out for 6
    seconds of video, its positions jump 64 m, and its GPS time advances
    2 s over 8 seconds of video. A GPX of its own track is placed up to
    3.8 s off its timestamps, and interval samples geotagged from it up to
    65 m off its own positions.
  • GoPro MAX timelapses keep Stamp and geotag the samples of a timelapse by its GPS timestamps #852's results: their placements move by up
    to 0.05 s, and all their distance samples are described.
  • A GPX that ends exactly at a video's own first or last timestamp, as
    one made from its track does, can now miss a sample at the very start
    or end of the video, which is stamped just past it and reported as
    outside the track: 1 to 4 samples on 4 of these videos. A logger track
    that covers the video does not.
  • BlackVue, Viofo and Ricoh outputs do not change, but for 1 ms rounding
    of BlackVue GPX track times.

Unit and integration tests, doctests, mypy --python-version 3.9, ruff check, ruff format --check and usort diff are clean.

Since mapillary#888, GPX sync places a track, and sampling stamps frames, through
every GPS timestamp of the video. The cameras whose timestamps leave a
straight line record in real time, so video time maps to GPS time along
a straight line, and their timestamps jitter about it. A GoPro stamps
each block of 1.001 seconds of video up to 1.7 seconds off the line
through the rest: on a GoPro MAX, the accelerometer timestamps of those
blocks advance 0.996 to 1.006 seconds each, while their GPS timestamps
advance 0 to 3.8 seconds. A PANOX V2 stamps some fixes up to 6 seconds
late.

mapillary#888 followed that jitter. It placed a GPX up to 1.4 s off the line on a
GoPro HERO7, 1.6 to 2.9 s on GoPro MAX videos with poor GPS, and 5.9 s
on a PANOX V2. It stamped interval samples 5 s apart from 3.7 to 6.3 s
apart (HERO7), and 10 s apart from 7.2 to 12.8 s apart (PANOX V2). Its
message put the move of a GPX on a GoPro MAX at up to 56 ms, and that of
GoPro interval stamps at up to 1.5 s; on these videos, both moved by up
to 2.9 s.

The LabPano Pilot One and Era, which mapillary#888 was written for, need no more
than a straight clock. Their timestamps fit one at 1.143 GPS seconds per
second of video, within 0.3 s over 14 minutes (0.7 s on the Era). The
clock was read at 1x only because any rate below the timelapse rate of
1.5 was rounded to 1.

Read the clock as the least-squares line through the timestamps, at the
rate it fits, anchored at their median as before, and use it everywhere:
GPX sync places the track by it, interval samples and distance samples
of the video's own track are stamped by it, and the geotagging stage
times the video's track at its rate. The fit leaves out the timestamps
that mapillary#888 showed to be wrong: those out of order, those before a jump of
more than a day, and stale first ones.

The rate is 1x when it is within 5% of 1x, or when it departs from 1x by
less than 2 seconds over the timestamps. On sample videos, cameras that
record in real time measure within 0.4% of 1x over 20 seconds or more,
or 1.6% for a GoPro MAX whose GPS glitches. Clips of a few seconds
measure up to 14% off 1x, a drift of at most 0.3 s. The LabPanos measure
1.093 to 1.143, a drift of at least 15 s. A rate above 1.5 must still
show in the median step between timestamps, so one timestamp far off
makes no timelapse. Timelapses get a straight clock too. Once their
stale first timestamps are left out, those of GoPro MAX, MAX 2 and Rove
timelapses lie within 0.33 GPS seconds of the line, but for one GoPro
MAX timelapse within 0.82 (55 ms of video), less than the jitter of a
normal video.

On sample videos from 9 cameras:

- Without a GPX, process writes the same tracks for all of them.
- A GPX made from a video's own track moves onto the straight line: by
  up to 1.4 s on the HERO7, 2.9 s and 1.6 s on GoPro MAX videos with
  poor GPS, 0.65 s on a GoPro MAX 2, 5.9 s on a PANOX V2, and up to
  0.06 s on other GoPros. Interval samples are stamped evenly, 5.000 s
  or 10.000 s apart, and those of a LabPano 11.426 s apart for 10 s of
  video. Distance samples of the video's own track are stamped by the
  clock, and their positions do not change.
- A GPX made from a LabPano's own track lands within 0.26 s of its
  timestamps over 14 minutes, and within 0.61 s on the Era. GPX distance
  samples of the 2 fps Era are no longer dropped: mapillary#888 timed its frames
  alternately fast and slow, so half of them fell under the sample
  distance. One LabPano video is the exception: its GPS drops out for 6
  seconds of video, its positions jump 64 m, and its GPS time advances
  2 s over 8 seconds of video. A GPX of its own track is placed up to
  3.8 s off its timestamps, and interval samples geotagged from it up to
  65 m off its own positions.
- GoPro MAX timelapses keep mapillary#852's results: their placements move by up
  to 0.05 s, and all their distance samples are described.
- A GPX that ends exactly at a video's own first or last timestamp, as
  one made from its track does, can now miss a sample at the very start
  or end of the video, which is stamped just past it and reported as
  outside the track: 1 to 4 samples on 4 of these videos. A logger track
  that covers the video does not.
- BlackVue, Viofo and Ricoh outputs do not change, but for 1 ms rounding
  of BlackVue GPX track times.
@meta-cla meta-cla Bot added the cla signed label Oct 23, 2026
@caglarpir
caglarpir merged commit e6f1ccd into mapillary:main Oct 23, 2026
16 checks passed
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