Honour --geotag_source in distance-based sampling

[caglarpir]

#839 has landed, so the diff against main is this PR's own. Its commits start at fff6550; the merges bring in #839 and main (last at fd742c1), and 2fb6b22 re-applies this PR to the GPXVideoExtractor that #831, #847 and #849 reworked.

Problem

Distance sampling called GeotagVideosFromVideo() directly, bypassing the geotag factory, so --geotag_source never reached it. Attaching a GPX is the documented answer for a camera whose embedded GPS is unusable — but the sampler needs positions just as much as geotagging does, and it only ever looked at the video's own telemetry. The GPX was read, announced in the log, then ignored:

video_process V.mp4 OUT --video_sample_distance 3 \
    --geotag_source gpx --geotag_source_path V.gpx
-> 0 frames

Fix

Go through factory.process() (fff6550). The consumer was already generic — _sample_video_stream_by_distance() takes a plain Sequence[geo.Point] and doesn't care about provenance. Only the producer was hardcoded.

Routing rather than adding a fallback keeps the source-selection policy in one place: sample_video.py has no business re-deciding which source may rescue a file, _build_video_geotag() stays the only map from source to extractor, and chaining (native,gpx) comes for free.

Sampling defaults to NATIVE alone, not DEFAULT_GEOTAG_SOURCE_OPTIONS, which continues on to exiftool_runtime. That reader cannot see every field the noise filter rejects on (see #840), so defaulting to the full chain would make sampling accept tracks the native parser refuses. NATIVE-only is also exactly today's behaviour.

_parse_source_options() moves from process_geotag_properties to geotag.factory, next to parse_source_option(), so both callers share one implementation instead of the sampler reaching for a private helper.

commands/sample_video.py needs no change: it splats vars_args filtered by the signature of sample_video(), so the new parameters flow through from video_process, which registers the process command's arguments into the same parser. The standalone sample_video command doesn't register them, so they stay absent and the defaults apply.

Picking frames where the geotagging stage will put them

Routing alone was not enough. The sampler now picks frames by positions from the GPX, and the geotagging stage of video_process then places each frame along the same GPX by the timestamp the sampler stamped it with. Unless the two line up the GPX with the video the same way, frames are picked by positions they do not end up at. Five follow-ups:

• Place the GPX by --video_start_time (c599ddb, and for GPS without a clock 2fb6b22). For a video with no GPS of its own, GPXVideoExtractor assumed the track starts with the video, and --video_start_time never reached it. The frames were stamped with the GPX start plus their own time, and the geotagging stage agreed, so the result exited 0, looked consistent, and was wrong whenever the track did not start with the video: two clips of one drive, recorded hours apart and each given its own --video_start_time, came out as the same frames, from the first minutes of the drive's GPX.
  Distance sampling now hands the extractor a VideoSyncOption carrying the start time the user gave. Only a given one: the probed start time is creation_time - duration, a whole video length early on cameras whose creation_time marks the start (Read a video's start time from its GPS clock, and tell whether creation_time marks the start or the end #832). A video with GPS is still synced by its own GPS clock.
  • Without a start time, the track is still assumed to start with the video, but that is now checked. A track lasting more than twice as long as the video fails the sample and asks for --video_start_time, or --interpolation_use_gpx_start_time if the GPX was started with the video. MapillaryGPXVideoStartUnknownError is not reprocessable, so a source after the GPX in the chain cannot hide it behind "no GPS found". A track more than 2 s longer than the video warns.
  • A track that misses the video selected no frames and left an empty sample directory with exit 0. That fails the sample now. Fail the sample instead of silently producing no frames #839 adds the same check; the merge keeps this one, whose message says where the track lies relative to the video.
• Apply the interpolation options (61b2a6a). video_process registers --interpolation_offset_time and --interpolation_use_gpx_start_time for its geotagging stage, and the README documents both for lining up a GPX with a video. Sampling ignored them: with an offset, frames near the end of the track were pushed past it and rejected, failing the command. The extractor now applies both, and shifts the absolute times with the track, so that a frame is stamped with its capture time and the geotagging stage, adding the offset back, finds the position the frame was picked by.
• Sources that cannot read videos (641ba60). exif, nmea and the legacy gopro/blackvue/camm sources have no video extractor, so process() returned nothing for the video and the sampler failed an assert, for videos it used to sample fine. Sampling now uses the requested sources that can read videos, or the video's own GPS, as before, when none can.
• Drop GPX points timestamped before 1980, and sort the rest (544b21e). A GPX converted from a dashcam's log listed its 42 tracks out of time order, and 26 of them carried 1969-12-31T15:59:59Z on every point. GPXVideoExtractor merged the tracks as they came, and distance sampling, which now reads the GPX, crashed in the interpolator with ValueError: Expect points to be sorted by time. No GPS fix can predate the GPS epoch, so those points are dropped, with a warning, and the rest sorted. Sorting alone would have left the junk at the start of the track, where --interpolation_use_gpx_start_time would pin the video.
• Sidecar comment (a0ef901). A comment and a test claimed that a GPX beside the video is found without --geotag_source_path. It is not: every source gets the video import path, which is how exiftool_xml finds XML files in the video directory. A GPX needs --geotag_source_path, which the geotagging stage needs as well.

process is unchanged, except for untidy GPX files. It passes no VideoSyncOption, so it places a GPX on a video as before, and keeps ignoring the interpolation options for videos: it sets them on every source for the images, and applying them to a video there would change the track uploaded with it, which is a separate decision. The one change it shares is 544b21e: for the GPX above it uploaded all 29,440 points out of order, 25,250 of them some 55 years before the video, and now uploads the 4,190 real ones in order. A GPX whose points are in order and after 1980 gives the same track as before.

Verification

Against main:

scenario	before	after
no-GPS video + overlapping GPX	0 frames	86 frames
noisy GoPro + overlapping GPX	0 frames	299 frames (with #831)
noisy GoPro, no GPX	rejected	rejected

The noisy-GoPro row needs #831 as well: without it GPXVideoExtractor still lets MapillaryGPSNoiseError escape before the GPX is consulted.

The follow-ups, against fff6550:

scenario	before	after
no-GPS clip + GPX of a whole drive, --video_start_time given	frames from the start of the GPX, stamped with its times, exit 0	frames from the given start time
the same, with a start time outside the GPX	the same wrong frames, exit 0	exit 7: none of its frames falls within its GPS track
the same, without a start time	the same wrong frames, exit 0	exit 7: asks for --video_start_time
no-GPS clip + GPX recorded with it	sampled	sampled, unchanged
clip at the end of its GPX, --interpolation_offset_time 2	5 of 15 frames rejected, exit 6; frames picked 16.7 m from where they are placed	none rejected; picked where they are placed
--geotag_source exif, video with good GPS	AssertionError	sampled by its own GPS
no-GPS clip + GPX with tracks out of order and points timestamped 1969, --video_start_time given	ValueError traceback, exit 1	sampled; junk points dropped with a warning

The default paths are untouched: bare video_process and sample_video, and process on a video with a GPX, with and without the interpolation options, give the same descriptions and byte-identical frames as fff6550. Every new test fails without its fix, except the two that pin behaviour that stays the same: process, and the default source path.

Full suite passes, mypy, ruff and usort clean. (test_persistent_cache::test_multiprocess_shared_cache_comprehensive is flaky under parallel load on this machine — passes in isolation, with and without this change.)

Not fixed here

• Timelapses: Sync a GPX to the GPS clock of a timelapse, even one too noisy to publish #849, now on main, syncs a GPX to the GPS clock of a timelapse. Merging it in, this PR applies --interpolation_offset_time in GPS seconds, which a timelapse packs several of into each second of video. A timelapse without a GPS clock is still placed as if its video ran in real time.
• With --interpolation_use_gpx_start_time, the geotagging stage puts the first sampled frame at the start of the GPX, while sampling puts video time 0 there. They differ by the composition time of the first frame, under a metre on the test clip; it cannot push frames off the track.
• A video without creation_time still needs --video_start_time, even with --interpolation_use_gpx_start_time: the start-time check runs before the GPX is read.
• _video_duration() in gpx.py duplicates the one Fix CAMM GPS epoch follow-ups from #828 #842 adds; whichever lands second should keep one.