mapillary-tools 0.13.3__py3-none-any.whl → 0.14.0__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.
-
-    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
+PointLike = T.TypeVar("PointLike", bound=Point)
 
 
-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,25 @@ 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 avg_speed(sequence: T.Sequence[PointLike]) -> float:
+    total_distance = 0.0
+    for cur, nxt in pairwise(sequence):
+        total_distance += gps_distance((cur.lat, cur.lon), (nxt.lat, nxt.lon))
+
+    if sequence:
+        time_diff = sequence[-1].time - sequence[0].time
+    else:
+        time_diff = 0.0
+
+    if time_diff == 0.0:
+        return float("inf")
+
+    return total_distance / time_diff
 
 
 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 +77,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 +116,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 +139,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 +181,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 +204,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,39 +223,52 @@ 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
 
         return interpolated
 
 
-_PointAbstract = T.TypeVar("_PointAbstract")
+_T = T.TypeVar("_T")
 
 
 def sample_points_by_distance(
-    samples: T.Iterable[_PointAbstract],
+    samples: T.Iterable[_T],
     min_distance: float,
-    point_func: T.Callable[[_PointAbstract], Point],
-) -> T.Generator[_PointAbstract, None, None]:
-    prevp: T.Optional[Point] = None
+    point_func: T.Callable[[_T], Point],
+) -> T.Generator[_T, None, None]:
+    prevp: Point | None = None
     for sample in samples:
         if prevp is None:
             yield sample
@@ -288,34 +280,82 @@ 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
+            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 _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
 
-_PointLike = T.TypeVar("_PointLike", bound=Point)
+    """
+    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 extend_deduplicate_points(
-    sequence: T.Iterable[_PointLike],
-    to_extend: T.Optional[T.List[_PointLike]] = None,
-) -> T.List[_PointLike]:
-    if to_extend is None:
-        to_extend = []
-    for point in sequence:
-        if to_extend:
-            prev = to_extend[-1].lon, to_extend[-1].lat
-            cur = (point.lon, point.lat)
-            if cur != prev:
-                to_extend.append(point)
+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:
-            to_extend.append(point)
-    return to_extend
+            # 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/__init__.py

@@ -1 +0,0 @@
-from .. import geo  # noqa: F401

mapillary_tools/geotag/base.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import abc
+import logging
+import typing as T
+from pathlib import Path
+
+from tqdm import tqdm
+
+from .. import exceptions, types, utils
+from .image_extractors.base import BaseImageExtractor
+from .video_extractors.base import BaseVideoExtractor
+
+
+LOG = logging.getLogger(__name__)
+
+
+TImageExtractor = T.TypeVar("TImageExtractor", bound=BaseImageExtractor)
+
+
+class GeotagImagesFromGeneric(abc.ABC, T.Generic[TImageExtractor]):
+    """
+    Extracts metadata from a list of image files with multiprocessing.
+    """
+
+    def __init__(self, num_processes: int | None = None) -> None:
+        self.num_processes = num_processes
+
+    def to_description(
+        self, image_paths: T.Sequence[Path]
+    ) -> list[types.ImageMetadataOrError]:
+        extractor_or_errors = self._generate_image_extractors(image_paths)
+
+        assert len(extractor_or_errors) == len(image_paths)
+
+        extractors, error_metadatas = types.separate_errors(extractor_or_errors)
+
+        map_results = utils.mp_map_maybe(
+            self.run_extraction,
+            extractors,
+            num_processes=self.num_processes,
+        )
+
+        results = list(
+            tqdm(
+                map_results,
+                desc="Extracting images",
+                unit="images",
+                disable=LOG.getEffectiveLevel() <= logging.DEBUG,
+                total=len(extractors),
+            )
+        )
+
+        return T.cast(list[types.ImageMetadataOrError], results + error_metadatas)
+
+    # This method is passed to multiprocessing
+    # so it has to be classmethod or staticmethod to avoid pickling the instance
+    @classmethod
+    def run_extraction(cls, extractor: TImageExtractor) -> types.ImageMetadataOrError:
+        image_path = extractor.image_path
+
+        try:
+            return extractor.extract()
+        except exceptions.MapillaryDescriptionError as ex:
+            return types.describe_error_metadata(
+                ex, image_path, filetype=types.FileType.IMAGE
+            )
+        except exceptions.MapillaryUserError as ex:
+            # Considered as fatal error if not MapillaryDescriptionError
+            raise ex
+        except Exception as ex:
+            # TODO: hide details if not verbose mode
+            LOG.exception("Unexpected error extracting metadata from %s", image_path)
+            return types.describe_error_metadata(
+                ex, image_path, filetype=types.FileType.IMAGE
+            )
+
+    def _generate_image_extractors(
+        self, image_paths: T.Sequence[Path]
+    ) -> T.Sequence[TImageExtractor | types.ErrorMetadata]:
+        raise NotImplementedError
+
+
+TVideoExtractor = T.TypeVar("TVideoExtractor", bound=BaseVideoExtractor)
+
+
+class GeotagVideosFromGeneric(abc.ABC, T.Generic[TVideoExtractor]):
+    """
+    Extracts metadata from a list of video files with multiprocessing.
+    """
+
+    def __init__(self, num_processes: int | None = None) -> None:
+        self.num_processes = num_processes
+
+    def to_description(
+        self, video_paths: T.Sequence[Path]
+    ) -> list[types.VideoMetadataOrError]:
+        extractor_or_errors = self._generate_video_extractors(video_paths)
+
+        assert len(extractor_or_errors) == len(video_paths)
+
+        extractors, error_metadatas = types.separate_errors(extractor_or_errors)
+
+        map_results = utils.mp_map_maybe(
+            self.run_extraction,
+            extractors,
+            num_processes=self.num_processes,
+        )
+
+        results = list(
+            tqdm(
+                map_results,
+                desc="Extracting videos",
+                unit="videos",
+                disable=LOG.getEffectiveLevel() <= logging.DEBUG,
+                total=len(extractors),
+            )
+        )
+
+        return T.cast(list[types.VideoMetadataOrError], results + error_metadatas)
+
+    # This method is passed to multiprocessing
+    # so it has to be classmethod or staticmethod to avoid pickling the instance
+    @classmethod
+    def run_extraction(cls, extractor: TVideoExtractor) -> types.VideoMetadataOrError:
+        video_path = extractor.video_path
+
+        try:
+            return extractor.extract()
+        except exceptions.MapillaryDescriptionError as ex:
+            return types.describe_error_metadata(
+                ex, video_path, filetype=types.FileType.VIDEO
+            )
+        except exceptions.MapillaryUserError as ex:
+            # Considered as fatal error if not MapillaryDescriptionError
+            raise ex
+        except Exception as ex:
+            # TODO: hide details if not verbose mode
+            LOG.exception("Unexpected error extracting metadata from %s", video_path)
+            return types.describe_error_metadata(
+                ex, video_path, filetype=types.FileType.VIDEO
+            )
+
+    def _generate_video_extractors(
+        self, video_paths: T.Sequence[Path]
+    ) -> T.Sequence[TVideoExtractor | types.ErrorMetadata]:
+        raise NotImplementedError