Feature: GPS Geotagging from GPX/KML Track Files

[jalogisch]

Summary

Add a new module (pg-geotag) that automatically sets GPS coordinates on photos by matching image timestamps against a GPX or KML track file. This enables photographers to geotag photos from cameras without built-in GPS by syncing with a GPS track recorded on a phone or dedicated GPS device.

Use Cases

• Geotagging photos from a professional camera using a GPS track from a smartphone
• Adding location data to action camera footage synced with a Garmin/Wahoo device
• Batch geotagging archived photos from a recorded route

Proposed Implementation

1. CLI Script: bin/pg-geotag

pg-geotag <files...> --track <gpx/kml file> [options]

Arguments:

• <files...> - One or more files or directories to process

Options:

• -t, --track <file> - GPX or KML track file (required)
• --tolerance <seconds> - Maximum time offset for matching (default: 30)
• --offset <seconds> - Manual time correction (camera vs GPS clock drift)
• --interpolate - Interpolate position between track points (default: on)
• --no-overwrite - Skip photos that already have GPS data
• -n, --dry-run - Show what would be done without changes
• -v, --verbose - Show detailed output

Examples:

# Geotag photos from a hike using a GPX from a phone
pg-geotag ./photos --track route.gpx

# Geotag with larger tolerance and camera offset correction
pg-geotag ./photos --track track.gpx --tolerance 60 --offset -15

# Preview without making changes
pg-geotag ./photos --track route.kml --dry-run

2. Web Module: web/modules/geotag/

module.yaml:

id: geotag
name: Geotag from Track
description: Set GPS coordinates from GPX/KML track file
icon: map-pin
order: 3

parameters:
  - id: directory
    type: positional
    label: Directory
    placeholder: ~/Pictures/PhotoLibrary/2026-01-24
    required: true
    inherit_from: target_directory
    help: "Auto-filled from previous import step if available."
    
  - id: track_file
    type: path
    label: Track File (GPX/KML)
    placeholder: ~/Downloads/route.gpx
    required: true
    cli_flag: --track
    
  - id: tolerance
    type: number
    label: Time Tolerance (seconds)
    default: 30
    cli_flag: --tolerance
    help: "Maximum time difference between photo and track point."
    
  - id: offset
    type: number
    label: Time Offset (seconds)
    default: 0
    cli_flag: --offset
    help: "Correct camera/GPS clock difference. Positive = camera ahead."
    
  - id: interpolate
    type: boolean
    label: Interpolate positions
    default: true
    cli_flag: --interpolate
    
  - id: skip_existing
    type: boolean
    label: Skip photos with GPS
    default: true
    cli_flag: --no-overwrite

outputs:
  - id: geotagged_count
    type: number
    description: Number of photos geotagged
  - id: skipped_count
    type: number
    description: Number of photos skipped (no match or already tagged)

3. Python Library: lib/gpx_utils.py

New utility for parsing GPS track files:

class GPXParser:
    """Parse GPX/KML files and match timestamps to coordinates."""
    
    def parse(self, filepath: Path) -> list[TrackPoint]
    def find_position(self, timestamp: datetime, tolerance: int = 30) -> Optional[Coordinates]
    def interpolate(self, timestamp: datetime, before: TrackPoint, after: TrackPoint) -> Coordinates

Technical Details

Track File Parsing:

• GPX: Parse <trkpt> elements with lat, lon, and <time> attributes
• KML: Parse <gx:Track> or <gx:coord> elements with associated timestamps
• Use Python's xml.etree.ElementTree (no external dependencies)

Time Matching Algorithm:

1. Read image timestamp from EXIF (DateTimeOriginal)
2. Apply manual offset correction if specified
3. Find track points within tolerance window
4. If interpolate=true and two points bracket the timestamp, calculate linear interpolation
5. If no match within tolerance, skip the image

GPS Coordinate Writing:

• Reuse existing ExifTool.write() with gps parameter
• Write standard GPS EXIF tags: GPSLatitude, GPSLongitude, GPSLatitudeRef, GPSLongitudeRef

Acceptance Criteria

• pg-geotag script works with GPX files
• pg-geotag script works with KML files
• Web module integrates with workflow planner
• Time tolerance is configurable (default: 30 seconds)
• Manual time offset correction works
• Position interpolation between track points
• Dry-run mode shows preview without changes
• Skip photos that already have GPS data (optional)
• Progress feedback for large batches

Dependencies

• exiftool (existing requirement)
• Python 3.9+ (existing requirement)
• No new external dependencies (use stdlib xml.etree.ElementTree)

Related

• Extends existing pg-exif functionality
• Integrates with workflow planner as new step type

[jalogisch]

Additional Feature: Automatic Offset Calculation

Problem

Manually determining the time offset between camera and GPS device is tedious and error-prone.

Solution: Offset Calculation Helper

Add a helper command that automatically calculates the time offset by analyzing a reference photo:

1. Take a reference photo: Photograph your phone screen showing the current time with your camera
2. Run the helper: The script compares the visible time on the screen with the camera's EXIF timestamp
3. Get the offset: Automatically calculate the difference

Proposed CLI

pg-geotag --calc-offset <reference-photo> [--manual-time "HH:MM:SS"]

Workflow:

# Option A: Manual time entry (simple, reliable)
pg-geotag --calc-offset photo_of_phone.jpg --manual-time "18:23:18"
# Output: Calculated offset: -15 seconds (camera is 15s behind)

# Option B: Use calculated offset directly
pg-geotag ./photos --track route.gpx --offset $(pg-geotag --calc-offset ref.jpg --manual-time "18:23:18")

Implementation Notes

• Phase 1: Manual time entry via --manual-time flag (user reads the time from the photo)
• Phase 2 (optional): OCR-based automatic time extraction (would require additional dependency like tesseract)

The manual approach is sufficient for most use cases and keeps the tool simple (KISS principle).

Example Reference Photo

User photographs their phone screen showing "18:23:18", the camera records EXIF timestamp "18:23:03" → offset = +15 seconds (camera is 15s behind GPS device).

[jalogisch]

Reference: Geo Tracker App

The Geo Tracker app (Android/iOS) is a good reference for GPS track recording that works well with this feature. It exports standard GPX files that can be used directly with pg-geotag.

App features relevant for photographers:

• Records GPS tracks with timestamps
• Exports to GPX format
• Shows current time prominently (useful for offset calibration photos)
• Available for both Android and iOS

Screenshots

Mobile App Interface:

Desktop/Tablet View:

The timestamp display ("25.01.2026, 18:26:10") is clearly visible, making it easy to photograph for offset calculation.