mapillary-tools 0.13.3__py3-none-any.whl → 0.14.0a1__py3-none-any.whl

mapillary_tools/geo.py

@@ -1,10 +1,12 @@
 # pyre-ignore-all-errors[4]
+from __future__ import annotations
 
 import bisect
 import dataclasses
 import datetime
 import itertools
 import math
+import sys
 import typing as T
 
 WGS84_a = 6378137.0
@@ -27,34 +29,14 @@ class Point:
     time: float
     lat: float
     lon: float
-    alt: T.Optional[float]
-    angle: T.Optional[float]
+    alt: float | None
+    angle: float | None
 
 
-def _ecef_from_lla2(lat: float, lon: float) -> T.Tuple[float, float, float]:
-    """
-    Compute ECEF XYZ from latitude, longitude and altitude.
+PointLike = T.TypeVar("PointLike", bound=Point)
 
-    All using the WGS94 model.
-    Altitude is the distance to the WGS94 ellipsoid.
-    Check results here http://www.oc.nps.edu/oc2902w/coord/llhxyz.htm
 
-    """
-    lat = math.radians(lat)
-    lon = math.radians(lon)
-    cos_lat = math.cos(lat)
-    sin_lat = math.sin(lat)
-    L = 1.0 / math.sqrt(WGS84_a_SQ * cos_lat**2 + WGS84_b_SQ * sin_lat**2)
-    K = WGS84_a_SQ * L * cos_lat
-    x = K * math.cos(lon)
-    y = K * math.sin(lon)
-    z = WGS84_b_SQ * L * sin_lat
-    return x, y, z
-
-
-def gps_distance(
-    latlon_1: T.Tuple[float, float], latlon_2: T.Tuple[float, float]
-) -> float:
+def gps_distance(latlon_1: tuple[float, float], latlon_2: tuple[float, float]) -> float:
     """
     Distance between two (lat,lon) pairs.
 
@@ -69,19 +51,9 @@ def gps_distance(
     return math.sqrt((x1 - x2) ** 2 + (y1 - y2) ** 2 + (z1 - z2) ** 2)
 
 
-def get_max_distance_from_start(latlons: T.List[T.Tuple[float, float]]) -> float:
-    """
-    Returns the radius of an entire GPS track. Used to calculate whether or not the entire sequence was just stationary video
-    Takes a sequence of points as input
-    """
-    if not latlons:
-        return 0
-    start = latlons[0]
-    return max(gps_distance(start, latlon) for latlon in latlons)
-
-
 def compute_bearing(
-    start_lat: float, start_lon: float, end_lat: float, end_lon: float
+    latlon_1: tuple[float, float],
+    latlon_2: tuple[float, float],
 ) -> float:
     """
     Get the compass bearing from start to end.
@@ -89,7 +61,10 @@ def compute_bearing(
     Formula from
     http://www.movable-type.co.uk/scripts/latlong.html
     """
-    # make sure everything is in radians
+    start_lat, start_lon = latlon_1
+    end_lat, end_lon = latlon_2
+
+    # Make sure everything is in radians
     start_lat = math.radians(start_lat)
     start_lon = math.radians(start_lon)
     end_lat = math.radians(end_lat)
@@ -125,14 +100,14 @@ _IT = T.TypeVar("_IT")
 
 
 # http://stackoverflow.com/a/5434936
-def pairwise(iterable: T.Iterable[_IT]) -> T.Iterable[T.Tuple[_IT, _IT]]:
+def pairwise(iterable: T.Iterable[_IT]) -> T.Iterable[tuple[_IT, _IT]]:
     """s -> (s0,s1), (s1,s2), (s2, s3), ..."""
     a, b = itertools.tee(iterable)
     next(b, None)
     return zip(a, b)
 
 
-def as_unix_time(dt: T.Union[datetime.datetime, int, float]) -> float:
+def as_unix_time(dt: datetime.datetime | int | float) -> float:
     if isinstance(dt, (int, float)):
         return dt
     else:
@@ -148,59 +123,37 @@ def as_unix_time(dt: T.Union[datetime.datetime, int, float]) -> float:
                 return 0.0
 
 
-def _interpolate_segment(start: Point, end: Point, t: float) -> Point:
-    if start.time == end.time:
-        weight = 0.0
-    else:
-        weight = (t - start.time) / (end.time - start.time)
-
-    lat = start.lat + (end.lat - start.lat) * weight
-    lon = start.lon + (end.lon - start.lon) * weight
-    angle = compute_bearing(start.lat, start.lon, end.lat, end.lon)
-    alt: T.Optional[float]
-    if start.alt is not None and end.alt is not None:
-        alt = start.alt + (end.alt - start.alt) * weight
-    else:
-        alt = None
-
-    return Point(time=t, lat=lat, lon=lon, alt=alt, angle=angle)
-
+if sys.version_info < (3, 10):
 
-def _interpolate_at_index(points: T.Sequence[Point], t: float, idx: int):
-    assert points, "expect non-empty points"
-
-    # find the segment (start point, end point)
-    if len(points) == 1:
-        start, end = points[0], points[0]
-    else:
-        if 0 < idx < len(points):
-            # interpolating within the range
-            start, end = points[idx - 1], points[idx]
-        elif idx <= 0:
-            # extrapolating behind the range
-            start, end = points[0], points[1]
-        else:
-            # extrapolating beyond the range
-            assert len(points) <= idx
-            start, end = points[-2], points[-1]
+    def interpolate(points: T.Sequence[Point], t: float, lo: int = 0) -> Point:
+        """
+        Interpolate or extrapolate the point at time t along the sequence of points (sorted by time).
+        """
+        if not points:
+            raise ValueError("Expect non-empty points")
 
-    return _interpolate_segment(start, end, t)
+        # Make sure that points are sorted (disabled because the check costs O(N)):
+        # for cur, nex in pairwise(points):
+        #     assert cur.time <= nex.time, "Points not sorted"
 
+        p = Point(time=t, lat=float("-inf"), lon=float("-inf"), alt=None, angle=None)
+        idx = bisect.bisect_left(points, p, lo=lo)
+        return _interpolate_at_segment_idx(points, t, idx)
+else:
 
-def interpolate(points: T.Sequence[Point], t: float, lo: int = 0) -> Point:
-    """
-    Interpolate or extrapolate the point at time t along the sequence of points (sorted by time).
-    """
-    if not points:
-        raise ValueError("Expect non-empty points")
+    def interpolate(points: T.Sequence[Point], t: float, lo: int = 0) -> Point:
+        """
+        Interpolate or extrapolate the point at time t along the sequence of points (sorted by time).
+        """
+        if not points:
+            raise ValueError("Expect non-empty points")
 
-    # Make sure that points are sorted (disabled because the check costs O(N)):
-    # for cur, nex in pairwise(points):
-    #     assert cur.time <= nex.time, "Points not sorted"
+        # Make sure that points are sorted (disabled because the check costs O(N)):
+        # for cur, nex in pairwise(points):
+        #     assert cur.time <= nex.time, "Points not sorted"
 
-    p = Point(time=t, lat=float("-inf"), lon=float("-inf"), alt=None, angle=None)
-    idx = bisect.bisect_left(points, p, lo=lo)
-    return _interpolate_at_index(points, t, idx)
+        idx = bisect.bisect_left(points, t, lo=lo, key=lambda x: x.time)
+        return _interpolate_at_segment_idx(points, t, idx)
 
 
 class Interpolator:
@@ -212,12 +165,22 @@ class Interpolator:
     track_idx: int
     # interpolation starts from the lower bound point index in the current track
     lo: int
-    prev_time: T.Optional[float]
+    prev_time: float | None
 
     def __init__(self, tracks: T.Sequence[T.Sequence[Point]]):
+        # Remove empty tracks
         self.tracks = [track for track in tracks if track]
+
         if not self.tracks:
-            raise ValueError("Expect non-empty tracks")
+            raise ValueError("Expect at least one non-empty track")
+
+        for track in self.tracks:
+            for left, right in pairwise(track):
+                if not (left.time <= right.time):
+                    raise ValueError(
+                        "Expect points to be sorted by time, but got {left.time} then {right.time}"
+                    )
+
         self.tracks.sort(key=lambda track: track[0].time)
         self.track_idx = 0
         self.lo = 0
@@ -225,7 +188,7 @@ class Interpolator:
 
     @staticmethod
     def _lsearch_left(
-        track: T.Sequence[Point], t: float, lo: int = 0, hi: T.Optional[int] = None
+        track: T.Sequence[Point], t: float, lo: int = 0, hi: int | None = None
     ) -> int:
         """
         similar to bisect.bisect_left, but faster in the incremental search case
@@ -244,24 +207,37 @@ class Interpolator:
 
     def interpolate(self, t: float) -> Point:
         if self.prev_time is not None:
-            assert self.prev_time <= t, "requires time to be monotonically increasing"
+            if not (self.prev_time <= t):
+                raise ValueError(
+                    f"Require times to be monotonically increasing, but got {self.prev_time} then {t}"
+                )
+
+        interpolated: Point | None = None
 
         while self.track_idx < len(self.tracks):
             track = self.tracks[self.track_idx]
+            assert track, "expect non-empty track"
+
             if t < track[0].time:
-                return _interpolate_at_index(track, t, 0)
+                interpolated = _interpolate_at_segment_idx(track, t, 0)
+                break
+
             elif track[0].time <= t <= track[-1].time:
-                # similar to bisect.bisect_left(points, p, lo=lo) but faster in this case
+                # Similar to bisect.bisect_left(points, p, lo=lo) but faster in this case
                 idx = Interpolator._lsearch_left(track, t, lo=self.lo)
-                # t must sit between (track[idx - 1], track[idx]]
-                # set the lower bound to idx - 1
-                # because the next t can still be interpolated anywhere between (track[idx - 1], track[idx]]
+                # Time t must be between (track[idx - 1], track[idx]], so set the lower bound to idx - 1
+                # Because the next t can still be interpolated anywhere between (track[idx - 1], track[idx]]
                 self.lo = max(idx - 1, 0)
-                return _interpolate_at_index(track, t, idx)
+                interpolated = _interpolate_at_segment_idx(track, t, idx)
+                break
+
             self.track_idx += 1
             self.lo = 0
 
-        interpolated = _interpolate_at_index(self.tracks[-1], t, len(self.tracks[-1]))
+        if interpolated is None:
+            interpolated = _interpolate_at_segment_idx(
+                self.tracks[-1], t, len(self.tracks[-1])
+            )
 
         self.prev_time = t
 
@@ -276,7 +252,7 @@ def sample_points_by_distance(
     min_distance: float,
     point_func: T.Callable[[_PointAbstract], Point],
 ) -> T.Generator[_PointAbstract, None, None]:
-    prevp: T.Optional[Point] = None
+    prevp: Point | None = None
     for sample in samples:
         if prevp is None:
             yield sample
@@ -288,26 +264,27 @@ def sample_points_by_distance(
                 prevp = p
 
 
-def interpolate_directions_if_none(sequence: T.Sequence[Point]) -> None:
+def interpolate_directions_if_none(sequence: T.Sequence[PointLike]) -> None:
     for cur, nex in pairwise(sequence):
         if cur.angle is None:
-            cur.angle = compute_bearing(cur.lat, cur.lon, nex.lat, nex.lon)
+            cur.angle = compute_bearing((cur.lat, cur.lon), (nex.lat, nex.lon))
 
     if len(sequence) == 1:
         if sequence[-1].angle is None:
             sequence[-1].angle = 0
     elif 2 <= len(sequence):
         if sequence[-1].angle is None:
-            sequence[-1].angle = sequence[-2].angle
-
-
-_PointLike = T.TypeVar("_PointLike", bound=Point)
+            prev_angle = sequence[-2].angle
+            assert prev_angle is not None, (
+                "expect the last second point to have an interpolated angle"
+            )
+            sequence[-1].angle = prev_angle
 
 
 def extend_deduplicate_points(
-    sequence: T.Iterable[_PointLike],
-    to_extend: T.Optional[T.List[_PointLike]] = None,
-) -> T.List[_PointLike]:
+    sequence: T.Iterable[PointLike],
+    to_extend: list[PointLike] | None = None,
+) -> list[PointLike]:
     if to_extend is None:
         to_extend = []
     for point in sequence:
@@ -319,3 +296,67 @@ def extend_deduplicate_points(
         else:
             to_extend.append(point)
     return to_extend
+
+
+def _ecef_from_lla2(lat: float, lon: float) -> tuple[float, float, float]:
+    """
+    Compute ECEF XYZ from latitude and longitude.
+
+    All using the WGS94 model.
+    Altitude is the distance to the WGS94 ellipsoid.
+    Check results here http://www.oc.nps.edu/oc2902w/coord/llhxyz.htm
+
+    """
+    lat = math.radians(lat)
+    lon = math.radians(lon)
+    cos_lat = math.cos(lat)
+    sin_lat = math.sin(lat)
+    L = 1.0 / math.sqrt(WGS84_a_SQ * cos_lat**2 + WGS84_b_SQ * sin_lat**2)
+    K = WGS84_a_SQ * L * cos_lat
+    x = K * math.cos(lon)
+    y = K * math.sin(lon)
+    z = WGS84_b_SQ * L * sin_lat
+    return x, y, z
+
+
+def _interpolate_segment(start: Point, end: Point, t: float) -> Point:
+    try:
+        weight = (t - start.time) / (end.time - start.time)
+    except ZeroDivisionError:
+        weight = 0.0
+
+    lat = start.lat + (end.lat - start.lat) * weight
+    lon = start.lon + (end.lon - start.lon) * weight
+    angle = compute_bearing((start.lat, start.lon), (end.lat, end.lon))
+    alt: float | None
+    if start.alt is not None and end.alt is not None:
+        alt = start.alt + (end.alt - start.alt) * weight
+    else:
+        alt = None
+
+    return Point(time=t, lat=lat, lon=lon, alt=alt, angle=angle)
+
+
+def _interpolate_at_segment_idx(points: T.Sequence[Point], t: float, idx: int) -> Point:
+    """
+    Interpolate time t along the segment between idx - 1 and idx.
+    If idx is out of range, extrapolate it to the nearest segment (first or last).
+    """
+
+    if len(points) == 1:
+        start, end = points[0], points[0]
+    elif 2 <= len(points):
+        if 0 < idx < len(points):
+            # Normal interpolation within the range
+            start, end = points[idx - 1], points[idx]
+        elif idx <= 0:
+            # Extrapolating before the first point
+            start, end = points[0], points[1]
+        else:
+            # Extrapolating after the last point
+            assert len(points) <= idx
+            start, end = points[-2], points[-1]
+    else:
+        assert False, "expect non-empty points"
+
+    return _interpolate_segment(start, end, t)

mapillary_tools/geotag/factory.py

@@ -0,0 +1,298 @@
+from __future__ import annotations
+
+import json
+import logging
+import typing as T
+from pathlib import Path
+
+from .. import exceptions, types, utils
+from ..types import FileType
+from . import (
+    geotag_from_generic,
+    geotag_images_from_exif,
+    geotag_images_from_exiftool,
+    geotag_images_from_exiftool_both_image_and_video,
+    geotag_images_from_gpx_file,
+    geotag_images_from_nmea_file,
+    geotag_images_from_video,
+    geotag_videos_from_exiftool_video,
+    geotag_videos_from_gpx,
+    geotag_videos_from_video,
+)
+from .options import InterpolationOption, SOURCE_TYPE_ALIAS, SourceOption, SourceType
+
+
+LOG = logging.getLogger(__name__)
+
+
+def parse_source_option(source: str) -> list[SourceOption]:
+    """
+    Given a source string, parse it into a list of GeotagOptions objects.
+
+    Examples:
+        "native" -> [SourceOption(SourceType.NATIVE)]
+        "gpx,exif" -> [SourceOption(SourceType.GPX), SourceOption(SourceType.EXIF)]
+        "exif,gpx" -> [SourceOption(SourceType.EXIF), SourceOption(SourceType.GPX)]
+        '{"source": "gpx"}' -> [SourceOption(SourceType.GPX)]
+    """
+
+    try:
+        source_type = SourceType(SOURCE_TYPE_ALIAS.get(source, source))
+    except ValueError:
+        pass
+    else:
+        return [SourceOption(source_type)]
+
+    try:
+        payload = json.loads(source)
+    except json.JSONDecodeError:
+        pass
+    else:
+        return [SourceOption.from_dict(payload)]
+
+    sources = source.split(",")
+
+    return [SourceOption(SourceType(SOURCE_TYPE_ALIAS.get(s, s))) for s in sources]
+
+
+def process(
+    # Collection: ABC for sized iterable container classes
+    paths: T.Iterable[Path],
+    options: T.Collection[SourceOption],
+) -> list[types.MetadataOrError]:
+    if not options:
+        raise ValueError("No geotag options provided")
+
+    final_metadatas: list[types.MetadataOrError] = []
+
+    # Paths (image path or video path) that will be sent to the next geotag process
+    reprocessable_paths = set(paths)
+
+    for idx, option in enumerate(options):
+        LOG.debug("Processing %d files with %s", len(reprocessable_paths), option)
+
+        image_metadata_or_errors = _geotag_images(reprocessable_paths, option)
+        video_metadata_or_errors = _geotag_videos(reprocessable_paths, option)
+
+        more_option = idx < len(options) - 1
+
+        for metadata in image_metadata_or_errors + video_metadata_or_errors:
+            if more_option and _is_reprocessable(metadata):
+                # Leave what it is for the next geotag process
+                pass
+            else:
+                final_metadatas.append(metadata)
+                reprocessable_paths.remove(metadata.filename)
+
+        # Quit if no more paths to process
+        if not reprocessable_paths:
+            break
+
+    return final_metadatas
+
+
+def _is_reprocessable(metadata: types.MetadataOrError) -> bool:
+    if isinstance(metadata, types.ErrorMetadata):
+        if isinstance(
+            metadata.error,
+            (
+                exceptions.MapillaryGeoTaggingError,
+                exceptions.MapillaryVideoGPSNotFoundError,
+            ),
+        ):
+            return True
+
+    return False
+
+
+def _filter_images_and_videos(
+    file_paths: T.Iterable[Path],
+    filetypes: set[types.FileType] | None = None,
+) -> tuple[list[Path], list[Path]]:
+    image_paths = []
+    video_paths = []
+
+    ALL_VIDEO_TYPES = {types.FileType.VIDEO, *types.NATIVE_VIDEO_FILETYPES}
+
+    if filetypes is None:
+        include_images = True
+        include_videos = True
+    else:
+        include_images = types.FileType.IMAGE in filetypes
+        include_videos = bool(filetypes & ALL_VIDEO_TYPES)
+
+    for path in file_paths:
+        if utils.is_image_file(path):
+            if include_images:
+                image_paths.append(path)
+
+        elif utils.is_video_file(path):
+            if include_videos:
+                video_paths.append(path)
+
+    return image_paths, video_paths
+
+
+def _ensure_source_path(option: SourceOption) -> Path:
+    if option.source_path is None or option.source_path.source_path is None:
+        raise exceptions.MapillaryBadParameterError(
+            f"source_path must be provided for {option.source}"
+        )
+    return option.source_path.source_path
+
+
+def _geotag_images(
+    paths: T.Iterable[Path], option: SourceOption
+) -> list[types.ImageMetadataOrError]:
+    image_paths, _ = _filter_images_and_videos(paths, option.filetypes)
+
+    if not image_paths:
+        return []
+
+    if option.interpolation is None:
+        interpolation = InterpolationOption()
+    else:
+        interpolation = option.interpolation
+
+    geotag: geotag_from_generic.GeotagImagesFromGeneric
+
+    if option.source is SourceType.NATIVE:
+        geotag = geotag_images_from_exif.GeotagImagesFromEXIF(
+            image_paths, num_processes=option.num_processes
+        )
+        return geotag.to_description()
+
+    if option.source is SourceType.EXIFTOOL_RUNTIME:
+        geotag = geotag_images_from_exiftool.GeotagImagesFromExifToolRunner(
+            image_paths, num_processes=option.num_processes
+        )
+        try:
+            return geotag.to_description()
+        except exceptions.MapillaryExiftoolNotFoundError as ex:
+            LOG.warning('Skip "%s" because: %s', option.source.value, ex)
+            return []
+
+    elif option.source is SourceType.EXIFTOOL_XML:
+        # This is to ensure 'video_process --geotag={"source": "exiftool_xml", "source_path": "/tmp/xml_path"}'
+        # to work
+        geotag = geotag_images_from_exiftool_both_image_and_video.GeotagImagesFromExifToolBothImageAndVideo(
+            image_paths,
+            xml_path=_ensure_source_path(option),
+            num_processes=option.num_processes,
+        )
+        return geotag.to_description()
+
+    elif option.source is SourceType.GPX:
+        geotag = geotag_images_from_gpx_file.GeotagImagesFromGPXFile(
+            image_paths,
+            source_path=_ensure_source_path(option),
+            use_gpx_start_time=interpolation.use_gpx_start_time,
+            offset_time=interpolation.offset_time,
+            num_processes=option.num_processes,
+        )
+        return geotag.to_description()
+
+    elif option.source is SourceType.NMEA:
+        geotag = geotag_images_from_nmea_file.GeotagImagesFromNMEAFile(
+            image_paths,
+            source_path=_ensure_source_path(option),
+            use_gpx_start_time=interpolation.use_gpx_start_time,
+            offset_time=interpolation.offset_time,
+            num_processes=option.num_processes,
+        )
+
+        return geotag.to_description()
+
+    elif option.source is SourceType.EXIF:
+        geotag = geotag_images_from_exif.GeotagImagesFromEXIF(
+            image_paths, num_processes=option.num_processes
+        )
+        return geotag.to_description()
+
+    elif option.source in [
+        SourceType.GOPRO,
+        SourceType.BLACKVUE,
+        SourceType.CAMM,
+    ]:
+        map_geotag_source_to_filetype: dict[SourceType, FileType] = {
+            SourceType.GOPRO: FileType.GOPRO,
+            SourceType.BLACKVUE: FileType.BLACKVUE,
+            SourceType.CAMM: FileType.CAMM,
+        }
+        video_paths = utils.find_videos([_ensure_source_path(option)])
+        image_samples_by_video_path = utils.find_all_image_samples(
+            image_paths, video_paths
+        )
+        video_paths_with_image_samples = list(image_samples_by_video_path.keys())
+        video_metadatas = geotag_videos_from_video.GeotagVideosFromVideo(
+            video_paths_with_image_samples,
+            filetypes={map_geotag_source_to_filetype[option.source]},
+            num_processes=option.num_processes,
+        ).to_description()
+        geotag = geotag_images_from_video.GeotagImagesFromVideo(
+            image_paths,
+            video_metadatas,
+            offset_time=interpolation.offset_time,
+            num_processes=option.num_processes,
+        )
+        return geotag.to_description()
+
+    else:
+        raise ValueError(f"Invalid geotag source {option.source}")
+
+
+def _geotag_videos(
+    paths: T.Iterable[Path], option: SourceOption
+) -> list[types.VideoMetadataOrError]:
+    _, video_paths = _filter_images_and_videos(paths, option.filetypes)
+
+    if not video_paths:
+        return []
+
+    geotag: geotag_from_generic.GeotagVideosFromGeneric
+
+    if option.source is SourceType.NATIVE:
+        geotag = geotag_videos_from_video.GeotagVideosFromVideo(
+            video_paths, num_processes=option.num_processes, filetypes=option.filetypes
+        )
+        return geotag.to_description()
+
+    if option.source is SourceType.EXIFTOOL_RUNTIME:
+        geotag = geotag_videos_from_exiftool_video.GeotagVideosFromExifToolRunner(
+            video_paths, num_processes=option.num_processes
+        )
+        try:
+            return geotag.to_description()
+        except exceptions.MapillaryExiftoolNotFoundError as ex:
+            LOG.warning('Skip "%s" because: %s', option.source.value, ex)
+            return []
+
+    elif option.source is SourceType.EXIFTOOL_XML:
+        geotag = geotag_videos_from_exiftool_video.GeotagVideosFromExifToolVideo(
+            video_paths,
+            xml_path=_ensure_source_path(option),
+        )
+        return geotag.to_description()
+
+    elif option.source is SourceType.GPX:
+        geotag = geotag_videos_from_gpx.GeotagVideosFromGPX(video_paths)
+        return geotag.to_description()
+
+    elif option.source is SourceType.NMEA:
+        # TODO: geotag videos from NMEA
+        return []
+
+    elif option.source is SourceType.EXIF:
+        # Legacy image-specific geotag types
+        return []
+
+    elif option.source in [
+        SourceType.GOPRO,
+        SourceType.BLACKVUE,
+        SourceType.CAMM,
+    ]:
+        # Legacy image-specific geotag types
+        return []
+
+    else:
+        raise ValueError(f"Invalid geotag source {option.source}")