gps-video-sync 0.1.0__py3-none-any.whl

gps_video_sync/__init__.py

@@ -0,0 +1,63 @@
+from .models import Track, Telemetry, SyncResult
+from .plugins import (TrackReader, VideoSource, register_track, register_video,
+                      read_track, read_video)
+from .igc import IGCReader
+
+__version__ = "0.1.0"
+register_track("igc", IGCReader())
+from .gopro import GoProSource
+register_video("gopro", GoProSource())
+from .npz import NPZSource
+register_video("npz", NPZSource())
+
+def synchronize(track: Track, telemetry: Telemetry) -> SyncResult:
+    from .sync import synchronize as run
+    return run(track, telemetry)
+
+
+def match_videos(track: Track, paths, *, source: str = "gopro", hz: float = 10,
+                 cache_dir=None) -> list[SyncResult]:
+    """Match each recording independently, retaining input order and failures."""
+    import math
+    from pathlib import Path
+    import zipfile
+    from .plugins import VIDEO_SOURCES
+    from .sync import validate_track, validate_telemetry, _synchronize
+
+    validate_track(track)
+    if source not in VIDEO_SOURCES:
+        raise ValueError(f"Unknown or unavailable video source: {source}")
+    if not math.isfinite(hz) or hz <= 0:
+        raise ValueError("hz must be finite and positive")
+    if isinstance(paths, (str, Path)):
+        raise ValueError("Supply a nonempty sequence of video paths")
+    paths = list(paths)
+    if not paths or any(not isinstance(p, (str, Path)) for p in paths):
+        raise ValueError("Supply a nonempty sequence of video paths")
+    results = []
+    seen_paths = set()
+    accepted_timelines = set()
+    for path in paths:
+        identity = str(path)
+        try:
+            try:
+                identity = str(Path(path).expanduser().resolve())
+            except RuntimeError as exc:
+                raise ValueError(str(exc)) from exc
+            if identity in seen_paths:
+                raise ValueError("Duplicate input path")
+            seen_paths.add(identity)
+            telemetry = read_video(path, source=source, hz=hz, cache_dir=cache_dir)
+            validate_telemetry(telemetry)
+            timeline = (telemetry.video, telemetry.media_offset_seconds, telemetry.duration)
+            if timeline in accepted_timelines:
+                raise ValueError("Duplicate recording timeline")
+        except (OSError, ValueError, EOFError, zipfile.BadZipFile) as exc:
+            result = SyncResult("failed", video=identity, message=str(exc), date=track.date)
+        else:
+            result = _synchronize(track, telemetry)
+            if result.status != "failed":
+                accepted_timelines.add(timeline)
+        result.input_file = identity
+        results.append(result)
+    return results

gps_video_sync/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

gps_video_sync/cli.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import subprocess
+import sys
+import zipfile
+
+import numpy as np
+
+from . import __version__, read_track, read_video, synchronize, match_videos
+from .sync import validate_telemetry
+
+
+def _json_default(value):
+    if isinstance(value, np.ndarray):
+        return value.tolist()
+    if isinstance(value, np.generic):
+        return value.item()
+    raise TypeError(f"Cannot encode {type(value).__name__}")
+
+
+def write_json(path, value):
+    Path(path).write_text(json.dumps(value, indent=2, default=_json_default,
+                                    allow_nan=False) + "\n")
+
+
+def _telemetry(args):
+    return read_video(args.videos[0], source=args.source, hz=args.hz, cache_dir=args.cache_dir)
+
+
+def _export(telemetry, path):
+    validate_telemetry(telemetry)
+    recording = dict(video=telemetry.video, duration=telemetry.duration,
+                     media_offset_seconds=telemetry.media_offset_seconds)
+    if Path(path).suffix.lower() == ".npz":
+        reserved = {"time", "gps_time", "gps_utc", "recording", "chapters", "schema_version"}
+        if reserved.intersection(telemetry.channels):
+            raise ValueError("Telemetry channel name conflicts with NPZ metadata")
+        np.savez_compressed(path, time=telemetry.time, **telemetry.channels,
+                            gps_time=telemetry.gps_time, gps_utc=telemetry.gps_utc,
+                            recording=json.dumps(recording, default=_json_default),
+                            schema_version="2.0.0")
+    elif Path(path).suffix.lower() == ".json":
+        def nullable(values):
+            values = np.asarray(values)
+            return np.where(np.isfinite(values), values, None).tolist()
+        write_json(path, dict(schema_version="2.0.0", time=nullable(telemetry.time),
+                             channels={k: nullable(v) for k, v in telemetry.channels.items()},
+                             recording=recording, gps_time=nullable(telemetry.gps_time),
+                             gps_utc=nullable(telemetry.gps_utc)))
+    else:
+        raise ValueError("--out must end in .npz or .json")
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message):
+        self.print_usage(sys.stderr)
+        self.exit(1, f"{self.prog}: error: {message}\n")
+
+
+def _parser():
+    parser = _Parser(description="Synchronize video telemetry with a GPS track")
+    parser.add_argument("--version", action="version", version=__version__)
+    commands = parser.add_subparsers(dest="command", required=True)
+    for command in ("sync", "telemetry", "verify", "info"):
+        sub = commands.add_parser(command)
+        sub.add_argument("videos", metavar="VIDEO", nargs="+" if command == "sync" else 1)
+        sub.add_argument("--source", default="gopro", help="video source plugin, or npz")
+        sub.add_argument("--cache-dir", type=Path)
+        sub.add_argument("--hz", type=float, default=10, help="telemetry sample rate (default: 10)")
+        if command in {"sync", "verify"}:
+            sub.add_argument("--track", required=True, type=Path)
+            sub.add_argument("--track-format", default="igc")
+            sub.add_argument("--altitude", choices=("auto", "gps", "pressure"), default="auto")
+        if command == "sync":
+            sub.add_argument("--json", type=Path, help="write result here instead of stdout")
+        elif command == "telemetry":
+            sub.add_argument("--out", required=True, type=Path)
+        elif command == "verify":
+            sub.add_argument("--output", required=True, type=Path)
+            sub.add_argument("--result", type=Path)
+            sub.add_argument("--frames", nargs="+", type=float, metavar="VIDEO_SECONDS")
+    return parser
+
+
+def main(argv=None):
+    args = _parser().parse_args(argv)
+    try:
+        if args.command in {"telemetry", "info"}:
+            telemetry = _telemetry(args)
+            if args.command == "telemetry":
+                _export(telemetry, args.out)
+            else:
+                print(json.dumps(dict(schema_version="2.0.0", video=telemetry.video,
+                                      input_file=str(Path(args.videos[0]).expanduser().resolve()),
+                                      duration=telemetry.duration, samples=len(telemetry.time),
+                                      start_seconds=float(telemetry.time[0]) if len(telemetry.time) else None,
+                                      end_seconds=float(telemetry.time[-1]) if len(telemetry.time) else None,
+                                      channels={k: list(v.shape) for k, v in telemetry.channels.items()},
+                                      gps_samples=len(telemetry.gps_time)),
+                                 indent=2, default=_json_default, allow_nan=False))
+            return 0
+        try:
+            track = read_track(args.track, format=args.track_format, altitude=args.altitude)
+        except KeyError as exc:
+            if exc.args == (args.track_format,):
+                raise ValueError(f"Unknown track format: {args.track_format}") from exc
+            raise
+        if args.command == "sync":
+            results = [r.to_dict() for r in match_videos(
+                track, args.videos, source=args.source, hz=args.hz, cache_dir=args.cache_dir)]
+            document = dict(schema_version="2.0.0", videos=results)
+            if args.json:
+                write_json(args.json, document)
+            else:
+                print(json.dumps(document, indent=2, default=_json_default, allow_nan=False))
+        else:
+            from .verify import plot_verification, select_result
+            telemetry = _telemetry(args)
+            result = (select_result(json.loads(args.result.read_text()), telemetry)
+                      if args.result else synchronize(track, telemetry).to_dict())
+            results = [result]
+            if result["status"] == "ok":
+                plot_verification(track, telemetry, result, args.output, args.frames or [])
+        for result in results:
+            if result["status"] != "ok":
+                print(f"{result.get('input_file') or result.get('video')}: {result['status']}: "
+                      + (result.get("message") or "No unique alignment; inspect confidence."), file=sys.stderr)
+        if any(r["status"] == "failed" for r in results):
+            return 1
+        return 2 if any(r["status"] == "ambiguous" for r in results) else 0
+    except (OSError, ValueError, KeyError, RuntimeError, ImportError, EOFError,
+            zipfile.BadZipFile, subprocess.SubprocessError) as exc:
+        detail = str(exc)
+        if isinstance(exc, subprocess.CalledProcessError) and exc.stderr:
+            detail += ": " + (exc.stderr.decode(errors="replace") if isinstance(exc.stderr, bytes) else exc.stderr).strip()
+        print(f"error: {detail}", file=sys.stderr)
+        return 1

gps_video_sync/gopro.py

@@ -0,0 +1,243 @@
+"""Motion retains native camera axes. GPS times are Unix UTC seconds."""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+import hashlib
+import json
+import math
+import os
+from pathlib import Path
+import tempfile
+from dataclasses import dataclass
+import zipfile
+
+import numpy as np
+from scipy.ndimage import uniform_filter1d
+
+from . import mp4
+from .gpmf import number, scaled, streams
+from .models import Telemetry
+from .sync import validate_telemetry
+
+KEYS = ("ACCL", "GYRO", "GRAV", "CORI", "IORI")
+QUATERNIONS = ("CORI", "IORI")
+CACHE_VERSION = "2.0.0"
+MAX_GRID_SAMPLES = 1_000_000
+GPS_EPOCH = datetime(2000, 1, 1, tzinfo=timezone.utc).timestamp()
+
+
+def _gps(fields: dict, times: np.ndarray, key: str) -> tuple[np.ndarray, np.ndarray]:
+    values = scaled(fields[key], fields)
+    if key == "GPS9":
+        if values.shape[1] != 9:
+            raise ValueError("GPS9 requires nine columns")
+        utc = GPS_EPOCH + values[:, 5] * 86400 + values[:, 6]
+        good = ((values[:, 8] >= 3) & (values[:, 5] >= 0)
+                & (values[:, 6] >= 0) & (values[:, 6] < 86401))
+    else:
+        if values.shape[1] != 5:
+            raise ValueError("GPS5 requires five columns")
+        if "GPSU" not in fields or "GPSF" not in fields:
+            return np.empty(0), np.empty(0)
+        try:
+            stamp = fields["GPSU"].data.decode("ascii").rstrip("\0")
+            fmt = "%y%m%d%H%M%S.%f" if "." in stamp else "%y%m%d%H%M%S"
+            epoch = datetime.strptime(stamp, fmt).replace(tzinfo=timezone.utc).timestamp()
+        except (UnicodeDecodeError, ValueError):
+            return np.empty(0), np.empty(0)
+        utc = epoch + (times - times[0])
+        good = np.ones(len(values), dtype=bool)
+    # GPSF, when present, must also report a 3D fix. GPS9 carries its own fix.
+    if "GPSF" in fields:
+        fix = number(fields["GPSF"]).ravel()
+        if len(fix) not in (1, len(values)):
+            raise ValueError("GPSF does not match GPS samples")
+        good &= fix >= 3
+    good &= np.isfinite(values).all(axis=1) & np.isfinite(utc)
+    good &= (np.abs(values[:, 0]) <= 90) & (np.abs(values[:, 1]) <= 180)
+    return times[good], utc[good]
+
+
+@dataclass
+class Recording:
+    duration: float
+    packets: int
+    motion: dict
+    gps: list
+
+
+def _recording(path: Path) -> Recording:
+    timeline = mp4.read_timeline(path)
+    duration = timeline.duration
+    data = {key: [] for key in KEYS}
+    gps5, gps9 = [], []
+    with path.open("rb") as handle:
+        for sample in timeline.samples:
+            pts, interval = sample.time, sample.duration
+            handle.seek(sample.offset)
+            buf = handle.read(sample.size)
+            if len(buf) != sample.size:
+                raise ValueError("Truncated GPMF packet in video file")
+            packet_gps5, packet_gps9 = [], []
+            has_gps9 = False
+            for stream in streams(buf):
+                fields = {r.key: r for r in stream}
+                for key in KEYS:
+                    if key not in fields:
+                        continue
+                    values = scaled(fields[key], fields)
+                    expected = 4 if key in QUATERNIONS else 3
+                    if values.shape[1] != expected:
+                        raise ValueError(f"{key} requires {expected} columns")
+                    if not len(values):
+                        continue
+                    t = pts + np.arange(len(values)) * interval / len(values)
+                    mask = (t >= 0) & (t < duration)
+                    data[key].append(np.column_stack((t[mask], values[mask])))
+                for key, target in (("GPS9", packet_gps9), ("GPS5", packet_gps5)):
+                    if key not in fields:
+                        continue
+                    has_gps9 |= key == "GPS9"
+                    count = fields[key].count
+                    if not count:
+                        continue
+                    t = pts + np.arange(count) * interval / count
+                    gt, utc = _gps(fields, t, key)
+                    mask = (gt >= 0) & (gt < duration)
+                    if mask.any():
+                        target.append((gt[mask], utc[mask]))
+            # Do not replace rejected GPS9 fixes with a second GPS5 observation.
+            if has_gps9:
+                gps9.extend(packet_gps9)
+            else:
+                gps5.extend(packet_gps5)
+    return Recording(duration, len(timeline.samples), data, gps5 + gps9)
+
+
+def _resample(blocks: list, grid: np.ndarray, key: str, hz: float) -> np.ndarray | None:
+    if not blocks or not len(grid):
+        return None
+    raw = np.concatenate(blocks)
+    raw = raw[np.isfinite(raw).all(axis=1)]
+    if key in QUATERNIONS:
+        raw = raw[np.linalg.norm(raw[:, 1:], axis=1) > 0]
+    if not len(raw):
+        return None
+    raw = raw[np.argsort(raw[:, 0], kind="stable")]
+    raw = raw[np.r_[np.diff(raw[:, 0]) > 0, True]]
+    if key in QUATERNIONS:
+        values = raw[:, 1:]
+        values /= np.linalg.norm(values, axis=1)[:, None]
+        flip = np.r_[1, np.cumprod(np.where(np.sum(values[1:] * values[:-1], axis=1) < 0, -1, 1))]
+        raw[:, 1:] = values * flip[:, None]
+    elif len(raw) > 1:
+        width = max(1, min(len(raw), round(1 / np.median(np.diff(raw[:, 0])) / hz)))
+        raw[:, 1:] = uniform_filter1d(raw[:, 1:], width, axis=0, mode="nearest")
+    result = np.column_stack([np.interp(grid, raw[:, 0], raw[:, i]) for i in range(1, raw.shape[1])])
+    if key in QUATERNIONS:
+        result /= np.linalg.norm(result, axis=1)[:, None]
+    if len(raw) > 1:
+        step = float(np.median(np.diff(raw[:, 0])))
+        right = np.searchsorted(raw[:, 0], grid).clip(1, len(raw)-1)
+        gap = (raw[right, 0]-raw[right-1, 0]) > max(.5, 3*step)
+        outside = (grid < raw[0, 0]) | (grid > raw[-1, 0]+step)
+        result[gap | outside] = np.nan
+    return result
+
+
+def _cache_path(path: Path, hz: float, directory: Path) -> Path:
+    stat = path.stat()
+    identity = {"version": CACHE_VERSION, "hz": hz, "file":
+                [str(path), stat.st_size, stat.st_mtime_ns]}
+    digest = hashlib.sha256(json.dumps(identity, sort_keys=True).encode()).hexdigest()
+    return directory / f"gopro-{digest}.npz"
+
+
+def _grid_samples(duration: float, hz: float) -> int:
+    try:
+        samples = duration * hz
+    except OverflowError:
+        samples = math.inf
+    if not math.isfinite(samples) or samples > MAX_GRID_SAMPLES:
+        raise ValueError(f"GoPro resampling exceeds {MAX_GRID_SAMPLES:,} samples; lower hz")
+    return math.ceil(samples)
+
+
+def _load_cache(path: Path, hz: float) -> Telemetry | None:
+    try:
+        with np.load(path, allow_pickle=False) as saved:
+            meta = json.loads(str(saved["metadata"].item()))
+            if meta["version"] != CACHE_VERSION or any(k not in KEYS for k in meta["channels"]):
+                return None
+            _grid_samples(meta["duration"], hz)
+            result = Telemetry(saved["time"], {k: saved[k] for k in meta["channels"]},
+                               meta["video"], meta["duration"], saved["gps_time"], saved["gps_utc"])
+            if result.time.ndim != 1 or result.gps_time.ndim != 1 or result.gps_utc.shape != result.gps_time.shape:
+                return None
+            if any(v.shape != (len(result.time), 4 if k in QUATERNIONS else 3)
+                   for k, v in result.channels.items()):
+                return None
+            validate_telemetry(result)
+            return result
+    except (OSError, ValueError, KeyError, TypeError, EOFError, zipfile.BadZipFile):
+        return None
+
+
+def _save_cache(path: Path, result: Telemetry) -> None:
+    temporary = None
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with tempfile.NamedTemporaryFile(dir=path.parent, suffix=".npz", delete=False) as handle:
+            temporary = handle.name
+            metadata = {"version": CACHE_VERSION, "channels": list(result.channels),
+                        "video": result.video, "duration": result.duration}
+            np.savez_compressed(handle, metadata=json.dumps(metadata), time=result.time,
+                                gps_time=result.gps_time, gps_utc=result.gps_utc, **result.channels)
+        os.replace(temporary, path)
+    except OSError:
+        # A read-only cache must not make extraction fail.
+        pass
+    finally:
+        if temporary is not None:
+            try:
+                os.unlink(temporary)
+            except FileNotFoundError:
+                pass
+
+
+class GoProSource:
+    """Extract one MP4 recording with file-local sample times."""
+
+    def read(self, path: str | Path, *, hz: float = 10,
+             cache_dir: str | Path | None = None) -> Telemetry:
+        hz = float(hz)
+        if not math.isfinite(hz) or hz <= 0:
+            raise ValueError("hz must be finite and positive")
+        if not isinstance(path, (str, Path)):
+            raise ValueError("Supply one video path")
+        path = Path(path).expanduser().resolve()
+        directory = Path(cache_dir).expanduser() if cache_dir is not None else Path.home() / ".cache" / "gps-video-sync"
+        cache = _cache_path(path, hz, directory)
+        saved = _load_cache(cache, hz)
+        if saved is not None and saved.video == str(path) and saved.duration is not None:
+            return saved
+        local = _recording(path)
+        if not local.packets:
+            raise ValueError(f"No GoPro telemetry (gpmd) track found in: {path.name}")
+        grid = np.arange(_grid_samples(local.duration, hz)) / hz
+        grid = grid[grid < local.duration]
+        channels = {}
+        for key in KEYS:
+            values = _resample(local.motion[key], grid, key, hz)
+            if values is not None:
+                channels[key] = values
+        if local.gps:
+            pairs = np.concatenate([np.column_stack(pair) for pair in local.gps])
+            pairs = pairs[np.argsort(pairs[:, 0], kind="stable")]
+            pairs = pairs[np.r_[True, np.diff(pairs[:, 0]) > 0]]
+            gps_time, gps_utc = pairs.T
+        else:
+            gps_time, gps_utc = np.empty(0), np.empty(0)
+        result = Telemetry(grid, channels, str(path), local.duration, gps_time, gps_utc)
+        _save_cache(cache, result)
+        return result

gps_video_sync/gpmf.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import re
+import struct
+from typing import Iterator, NamedTuple
+
+import numpy as np
+
+
+class Record(NamedTuple):
+    key: str
+    typ: str
+    size: int
+    count: int
+    data: bytes
+
+
+DTYPES = {
+    "b": ">i1", "B": ">u1", "s": ">i2", "S": ">u2",
+    "l": ">i4", "L": ">u4", "j": ">i8", "J": ">u8",
+    "f": ">f4", "d": ">f8", "q": ">i4", "Q": ">i8",
+}
+
+
+MAX_DEPTH = 8
+
+
+def records(buf: bytes) -> Iterator[Record]:
+    for record in _records(memoryview(buf)):
+        yield record._replace(data=bytes(record.data))
+
+
+def _records(buf: memoryview) -> Iterator[Record]:
+    offset = 0
+    while offset < len(buf):
+        if len(buf) - offset < 8:
+            raise ValueError("Truncated GPMF header")
+        key, typ, size, count = struct.unpack_from(">4sBBH", buf, offset)
+        length = size * count
+        end = offset + 8 + length
+        padded_end = offset + 8 + ((length + 3) // 4) * 4
+        if padded_end > len(buf):
+            raise ValueError("Truncated GPMF payload or padding")
+        try:
+            name = key.decode("ascii")
+        except UnicodeDecodeError as exc:
+            raise ValueError("Invalid GPMF key") from exc
+        yield Record(name, chr(typ), size, count, buf[offset + 8:end])
+        offset = padded_end
+
+
+def streams(buf: bytes, _depth: int = 0) -> Iterator[list[Record]]:
+    """Yield STRM records. Nesting is limited to MAX_DEPTH containers, and
+    payload bytes are not copied between levels, so work is linear in size."""
+    if _depth > MAX_DEPTH:
+        raise ValueError("GPMF container nesting is too deep")
+    view = buf if isinstance(buf, memoryview) else memoryview(buf)
+    for record in _records(view):
+        if record.key == "STRM":
+            yield [r._replace(data=bytes(r.data)) for r in _records(record.data)]
+        elif record.typ == "\0":
+            yield from streams(record.data, _depth + 1)
+
+
+def _types(description: str, size: int) -> list[str]:
+    types: list[str] = []
+    offset = 0
+    while offset < len(description):
+        match = re.match(r"([bBsSlLjJfdqQ])(?:\[(\d+)\])?", description[offset:])
+        if match is None:
+            raise ValueError(f"Unsupported GPMF TYPE: {description!r}")
+        count = int(match[2]) if match[2] else 1
+        if count < 1 or count > size:
+            raise ValueError("Invalid GPMF TYPE array size")
+        types.extend([match[1]] * count)
+        offset += len(match[0])
+        if len(types) > size:
+            raise ValueError("GPMF TYPE exceeds row size")
+    if not types or sum(np.dtype(DTYPES[t]).itemsize for t in types) != size:
+        raise ValueError("GPMF TYPE does not match row size")
+    return types
+
+
+def number(record: Record, type_hint: str | Record | None = None) -> np.ndarray:
+    _, typ, size, count, data = record
+    if len(data) != size * count or size == 0:
+        raise ValueError("Invalid GPMF numeric payload size")
+    if typ == "?":
+        if isinstance(type_hint, Record):
+            try:
+                type_hint = type_hint.data.decode("ascii").rstrip("\0")
+            except UnicodeDecodeError as exc:
+                raise ValueError("Invalid GPMF TYPE text") from exc
+        if not isinstance(type_hint, str):
+            raise ValueError("Complex GPMF data requires TYPE")
+        types = _types(type_hint, size)
+        dtype = np.dtype([(f"f{i}", DTYPES[t]) for i, t in enumerate(types)])
+        rows = np.frombuffer(data, dtype=dtype, count=count)
+        values = np.column_stack([rows[f"f{i}"] for i in range(len(types))]).astype(float)
+        for i, t in enumerate(types):
+            if t in ("q", "Q"):
+                values[:, i] /= 2 ** (16 if t == "q" else 32)
+        return values
+    if typ not in DTYPES:
+        raise ValueError(f"Unsupported GPMF numeric type: {typ!r}")
+    dtype = np.dtype(DTYPES[typ])
+    if size % dtype.itemsize:
+        raise ValueError("GPMF row size is not a multiple of its numeric type")
+    values = np.frombuffer(data, dtype=dtype).astype(float).reshape(count, size // dtype.itemsize)
+    if typ in ("q", "Q"):
+        values /= 2 ** (16 if typ == "q" else 32)
+    return values
+
+
+def scaled(record: Record, fields: dict[str, Record]) -> np.ndarray:
+    values = number(record, fields.get("TYPE"))
+    if "SCAL" in fields:
+        scale = number(fields["SCAL"]).ravel()
+        if len(scale) not in (1, values.shape[1]):
+            raise ValueError("GPMF SCAL does not match data columns")
+        if not np.all(np.isfinite(scale)) or np.any(scale == 0):
+            raise ValueError("GPMF SCAL must be finite and nonzero")
+        values /= scale
+    return values

gps_video_sync/igc.py

@@ -0,0 +1,57 @@
+from datetime import datetime
+from pathlib import Path
+import re
+import numpy as np
+from .models import Track
+
+class IGCReader:
+    def read(self, path: str | Path, *, altitude: str = "auto") -> Track:
+        if altitude not in {"auto", "gps", "pressure"}:
+            raise ValueError("altitude must be auto, gps, or pressure")
+        rows = []
+        day = None
+        last_clock = None
+        rollover = 0
+        for line in Path(path).read_text(errors="replace").splitlines():
+            match = re.match(r"H[FO]DTE\s*(?:DATE:)?\s*(\d{6})", line)
+            if match and day is None:
+                try:
+                    day = datetime.strptime(match[1], "%d%m%y").date()
+                except ValueError:
+                    pass
+            if not line.startswith("B") or len(line) < 35:
+                continue
+            if not (line[1:14].isascii() and line[1:14].isdigit()
+                    and line[15:23].isascii() and line[15:23].isdigit()):
+                continue
+            try:
+                h, m, s = int(line[1:3]), int(line[3:5]), int(line[5:7])
+                if h > 23 or m > 59 or s > 59:
+                    continue
+                clock = h * 3600 + m * 60 + s
+                if line[24] != "A" or line[14] not in "NS" or line[23] not in "EW":
+                    continue
+                lat = (int(line[7:9]) + int(line[9:14]) / 60000) * (1 if line[14] == "N" else -1)
+                lon = (int(line[15:18]) + int(line[18:23]) / 60000) * (1 if line[23] == "E" else -1)
+                pressure, gps = int(line[25:30]), int(line[30:35])
+                if abs(lat) > 90 or abs(lon) > 180:
+                    continue
+                if last_clock is not None and rollover and clock > last_clock + 43200:
+                    continue
+                t = clock + rollover
+                if last_clock is not None and clock < last_clock - 43200:
+                    t += 86400
+                if rows and t <= rows[-1][0]:
+                    continue
+                rollover = t - clock
+                last_clock = clock
+                rows.append((t, lat, lon, pressure, gps))
+            except ValueError:
+                continue
+        if len(rows) < 2:
+            raise ValueError("IGC needs at least two valid increasing fixes")
+        a = np.asarray(rows, dtype=float)
+        choice = altitude
+        if choice == "auto":
+            choice = "pressure" if np.ptp(a[:, 3]) > 0 and np.any(a[:, 3] != 0) else "gps"
+        return Track(a[:, 0], a[:, 1], a[:, 2], a[:, 3 if choice == "pressure" else 4], day, choice)