mapillary-tools 0.14.0a2__py3-none-any.whl → 0.14.0b1__py3-none-any.whl

mapillary_tools/geotag/options.py

@@ -60,9 +60,13 @@ class SourceOption:
             elif k == "filetypes":
                 kwargs[k] = {types.FileType(t) for t in v}
             elif k == "source_path":
-                kwargs.setdefault("source_path", SourcePathOption()).source_path = v
+                kwargs.setdefault(
+                    "source_path", SourcePathOption(source_path=Path(v))
+                ).sourthe_path = Path(v)
             elif k == "pattern":
-                kwargs.setdefault("source_path", SourcePathOption()).pattern = v
+                kwargs.setdefault(
+                    "source_path", SourcePathOption(pattern=v)
+                ).pattern = v
             elif k == "interpolation_offset_time":
                 kwargs.setdefault(
                     "interpolation", InterpolationOption()
@@ -85,6 +89,24 @@ class SourcePathOption:
             raise ValueError("Either pattern or source_path must be provided")
 
     def resolve(self, path: Path) -> Path:
+        """
+        Resolve the source path or pattern against the given path.
+
+        Examples:
+            >>> from pathlib import Path
+            >>> opt = SourcePathOption(source_path=Path("/foo/bar.mp4"))
+            >>> opt.resolve(Path("/baz/qux.mp4"))
+            PosixPath('/foo/bar.mp4')
+
+            >>> opt = SourcePathOption(pattern="videos/%g_sub%e")
+            >>> opt.resolve(Path("/data/video1.mp4"))
+            PosixPath('/data/videos/video1_sub.mp4')
+
+            >>> opt = SourcePathOption(pattern="/abs/path/%f")
+            >>> opt.resolve(Path("/tmp/abc.mov"))
+            PosixPath('/abs/path/abc.mov')
+        """
+
         if self.source_path is not None:
             return self.source_path
 
@@ -140,7 +162,7 @@ SourceOptionSchema = {
             "type": "integer",
         },
         "interpolation_offset_time": {
-            "type": "float",
+            "type": "number",
         },
         "interpolation_use_gpx_start_time": {
             "type": "boolean",

mapillary_tools/geotag/video_extractors/base.py

@@ -14,5 +14,5 @@ class BaseVideoExtractor(abc.ABC):
     def __init__(self, video_path: Path):
         self.video_path = video_path
 
-    def extract(self) -> types.VideoMetadataOrError:
+    def extract(self) -> types.VideoMetadata:
         raise NotImplementedError

mapillary_tools/geotag/video_extractors/exiftool.py

@@ -21,7 +21,7 @@ class VideoExifToolExtractor(BaseVideoExtractor):
         self.element = element
 
     @override
-    def extract(self) -> types.VideoMetadataOrError:
+    def extract(self) -> types.VideoMetadata:
         exif = exiftool_read_video.ExifToolReadVideo(ET.ElementTree(self.element))
 
         make = exif.extract_make()

mapillary_tools/geotag/video_extractors/gpx.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import dataclasses
-import datetime
+import enum
 import logging
 import sys
 import typing as T
@@ -12,7 +12,7 @@ if sys.version_info >= (3, 12):
 else:
     from typing_extensions import override
 
-from ... import geo, telemetry, types
+from ... import exceptions, geo, telemetry, types
 from ..utils import parse_gpx
 from .base import BaseVideoExtractor
 from .native import NativeVideoExtractor
@@ -21,106 +21,96 @@ from .native import NativeVideoExtractor
 LOG = logging.getLogger(__name__)
 
 
+class SyncMode(enum.Enum):
+    # Sync by video GPS timestamps if found, otherwise rebase
+    SYNC = "sync"
+    # Sync by video GPS timestamps, and throw if not found
+    STRICT_SYNC = "strict_sync"
+    # Rebase all GPX timestamps to start from 0
+    REBASE = "rebase"
+
+
 class GPXVideoExtractor(BaseVideoExtractor):
-    def __init__(self, video_path: Path, gpx_path: Path):
+    def __init__(
+        self, video_path: Path, gpx_path: Path, sync_mode: SyncMode = SyncMode.SYNC
+    ):
         self.video_path = video_path
         self.gpx_path = gpx_path
+        self.sync_mode = sync_mode
 
     @override
-    def extract(self) -> types.VideoMetadataOrError:
-        try:
-            gpx_tracks = parse_gpx(self.gpx_path)
-        except Exception as ex:
-            raise RuntimeError(
-                f"Error parsing GPX {self.gpx_path}: {ex.__class__.__name__}: {ex}"
-            )
+    def extract(self) -> types.VideoMetadata:
+        gpx_tracks = parse_gpx(self.gpx_path)
 
         if 1 < len(gpx_tracks):
             LOG.warning(
-                "Found %s tracks in the GPX file %s. Will merge points in all the tracks as a single track for interpolation",
-                len(gpx_tracks),
-                self.gpx_path,
+                f"Found {len(gpx_tracks)} tracks in the GPX file {self.gpx_path}. Will merge points in all the tracks as a single track for interpolation"
             )
 
         gpx_points: T.Sequence[geo.Point] = sum(gpx_tracks, [])
 
         native_extractor = NativeVideoExtractor(self.video_path)
 
-        video_metadata_or_error = native_extractor.extract()
-
-        if isinstance(video_metadata_or_error, types.ErrorMetadata):
+        try:
+            native_video_metadata = native_extractor.extract()
+        except exceptions.MapillaryVideoGPSNotFoundError as ex:
+            if self.sync_mode is SyncMode.STRICT_SYNC:
+                raise ex
             self._rebase_times(gpx_points)
             return types.VideoMetadata(
-                filename=video_metadata_or_error.filename,
-                filetype=video_metadata_or_error.filetype or types.FileType.VIDEO,
+                filename=self.video_path,
+                filetype=types.FileType.VIDEO,
                 points=gpx_points,
             )
 
-        video_metadata = video_metadata_or_error
-
-        offset = self._synx_gpx_by_first_gps_timestamp(
-            gpx_points, video_metadata.points
-        )
-
-        self._rebase_times(gpx_points, offset=offset)
+        if self.sync_mode is SyncMode.REBASE:
+            self._rebase_times(gpx_points)
+        else:
+            offset = self._gpx_offset(gpx_points, native_video_metadata.points)
+            self._rebase_times(gpx_points, offset=offset)
 
-        return dataclasses.replace(video_metadata_or_error, points=gpx_points)
+        return dataclasses.replace(native_video_metadata, points=gpx_points)
 
-    @staticmethod
-    def _rebase_times(points: T.Sequence[geo.Point], offset: float = 0.0):
+    @classmethod
+    def _rebase_times(cls, points: T.Sequence[geo.Point], offset: float = 0.0) -> None:
         """
-        Make point times start from 0
+        Rebase point times to start from **offset**
         """
         if points:
             first_timestamp = points[0].time
             for p in points:
                 p.time = (p.time - first_timestamp) + offset
-        return points
 
-    def _synx_gpx_by_first_gps_timestamp(
-        self, gpx_points: T.Sequence[geo.Point], video_gps_points: T.Sequence[geo.Point]
+    @classmethod
+    def _gpx_offset(
+        cls, gpx_points: T.Sequence[geo.Point], video_gps_points: T.Sequence[geo.Point]
     ) -> float:
+        """
+        Calculate the offset that needs to be applied to the GPX points to sync with the video GPS points.
+
+        >>> gpx_points = [geo.Point(time=5, lat=1, lon=1, alt=None, angle=None)]
+        >>> GPXVideoExtractor._gpx_offset(gpx_points, gpx_points)
+        0.0
+        >>> GPXVideoExtractor._gpx_offset(gpx_points, [])
+        0.0
+        >>> GPXVideoExtractor._gpx_offset([], gpx_points)
+        0.0
+        """
         offset: float = 0.0
 
-        if not gpx_points:
-            return offset
-
-        first_gpx_dt = datetime.datetime.fromtimestamp(
-            gpx_points[0].time, tz=datetime.timezone.utc
-        )
-        LOG.info("First GPX timestamp: %s", first_gpx_dt)
-
-        if not video_gps_points:
-            LOG.warning(
-                "Skip GPX synchronization because no GPS found in video %s",
-                self.video_path,
-            )
+        if not gpx_points or not video_gps_points:
             return offset
 
-        first_gps_point = video_gps_points[0]
-        if isinstance(first_gps_point, telemetry.GPSPoint):
-            if first_gps_point.epoch_time is not None:
-                first_gps_dt = datetime.datetime.fromtimestamp(
-                    first_gps_point.epoch_time, tz=datetime.timezone.utc
-                )
-                LOG.info("First GPS timestamp: %s", first_gps_dt)
-                offset = gpx_points[0].time - first_gps_point.epoch_time
-                if offset:
-                    LOG.warning(
-                        "Found offset between GPX %s and video GPS timestamps %s: %s seconds",
-                        first_gpx_dt,
-                        first_gps_dt,
-                        offset,
-                    )
-                else:
-                    LOG.info(
-                        "GPX and GPS are perfectly synchronized (all starts from %s)",
-                        first_gpx_dt,
-                    )
-            else:
-                LOG.warning(
-                    "Skip GPX synchronization because no GPS epoch time found in video %s",
-                    self.video_path,
-                )
+        gps_epoch_time: float | None = None
+        gps_point = video_gps_points[0]
+        if isinstance(gps_point, telemetry.GPSPoint):
+            if gps_point.epoch_time is not None:
+                gps_epoch_time = gps_point.epoch_time
+        elif isinstance(gps_point, telemetry.CAMMGPSPoint):
+            if gps_point.time_gps_epoch is not None:
+                gps_epoch_time = gps_point.time_gps_epoch
+
+        if gps_epoch_time is not None:
+            offset = gpx_points[0].time - gps_epoch_time
 
         return offset

mapillary_tools/geotag/video_extractors/native.py

@@ -17,7 +17,7 @@ from .base import BaseVideoExtractor
 
 class GoProVideoExtractor(BaseVideoExtractor):
     @override
-    def extract(self) -> types.VideoMetadataOrError:
+    def extract(self) -> types.VideoMetadata:
         with self.video_path.open("rb") as fp:
             gopro_info = gpmf_parser.extract_gopro_info(fp)
 
@@ -29,23 +29,13 @@ class GoProVideoExtractor(BaseVideoExtractor):
         gps_points = gopro_info.gps
         assert gps_points is not None, "must have GPS data extracted"
         if not gps_points:
-            # Instead of raising an exception, return error metadata to tell the file type
-            ex: exceptions.MapillaryDescriptionError = (
-                exceptions.MapillaryGPXEmptyError("Empty GPS data found")
-            )
-            return types.describe_error_metadata(
-                ex, self.video_path, filetype=types.FileType.GOPRO
-            )
+            raise exceptions.MapillaryGPXEmptyError("Empty GPS data found")
 
         gps_points = T.cast(
             T.List[telemetry.GPSPoint], gpmf_gps_filter.remove_noisy_points(gps_points)
         )
         if not gps_points:
-            # Instead of raising an exception, return error metadata to tell the file type
-            ex = exceptions.MapillaryGPSNoiseError("GPS is too noisy")
-            return types.describe_error_metadata(
-                ex, self.video_path, filetype=types.FileType.GOPRO
-            )
+            raise exceptions.MapillaryGPSNoiseError("GPS is too noisy")
 
         video_metadata = types.VideoMetadata(
             filename=self.video_path,
@@ -61,7 +51,7 @@ class GoProVideoExtractor(BaseVideoExtractor):
 
 class CAMMVideoExtractor(BaseVideoExtractor):
     @override
-    def extract(self) -> types.VideoMetadataOrError:
+    def extract(self) -> types.VideoMetadata:
         with self.video_path.open("rb") as fp:
             camm_info = camm_parser.extract_camm_info(fp)
 
@@ -71,13 +61,7 @@ class CAMMVideoExtractor(BaseVideoExtractor):
             )
 
         if not camm_info.gps and not camm_info.mini_gps:
-            # Instead of raising an exception, return error metadata to tell the file type
-            ex: exceptions.MapillaryDescriptionError = (
-                exceptions.MapillaryGPXEmptyError("Empty GPS data found")
-            )
-            return types.describe_error_metadata(
-                ex, self.video_path, filetype=types.FileType.CAMM
-            )
+            raise exceptions.MapillaryGPXEmptyError("Empty GPS data found")
 
         return types.VideoMetadata(
             filename=self.video_path,
@@ -91,7 +75,7 @@ class CAMMVideoExtractor(BaseVideoExtractor):
 
 class BlackVueVideoExtractor(BaseVideoExtractor):
     @override
-    def extract(self) -> types.VideoMetadataOrError:
+    def extract(self) -> types.VideoMetadata:
         with self.video_path.open("rb") as fp:
             blackvue_info = blackvue_parser.extract_blackvue_info(fp)
 
@@ -101,19 +85,13 @@ class BlackVueVideoExtractor(BaseVideoExtractor):
             )
 
         if not blackvue_info.gps:
-            # Instead of raising an exception, return error metadata to tell the file type
-            ex: exceptions.MapillaryDescriptionError = (
-                exceptions.MapillaryGPXEmptyError("Empty GPS data found")
-            )
-            return types.describe_error_metadata(
-                ex, self.video_path, filetype=types.FileType.BLACKVUE
-            )
+            raise exceptions.MapillaryGPXEmptyError("Empty GPS data found")
 
         video_metadata = types.VideoMetadata(
             filename=self.video_path,
             filesize=utils.get_file_size(self.video_path),
             filetype=types.FileType.BLACKVUE,
-            points=blackvue_info.gps or [],
+            points=blackvue_info.gps,
             make=blackvue_info.make,
             model=blackvue_info.model,
         )
@@ -127,7 +105,7 @@ class NativeVideoExtractor(BaseVideoExtractor):
         self.filetypes = filetypes
 
     @override
-    def extract(self) -> types.VideoMetadataOrError:
+    def extract(self) -> types.VideoMetadata:
         ft = self.filetypes
         extractor: BaseVideoExtractor
 

mapillary_tools/history.py

@@ -7,6 +7,7 @@ import typing as T
 from pathlib import Path
 
 from . import constants, types
+from .serializer.description import DescriptionJSONSerializer
 
 JSONDict = T.Dict[str, T.Union[str, int, float, None]]
 
@@ -57,6 +58,8 @@ def write_history(
         "summary": summary,
     }
     if metadatas is not None:
-        history["descs"] = [types.as_desc(metadata) for metadata in metadatas]
+        history["descs"] = [
+            DescriptionJSONSerializer.as_desc(metadata) for metadata in metadatas
+        ]
     with open(path, "w") as fp:
         fp.write(json.dumps(history))

mapillary_tools/process_geotag_properties.py

@@ -2,7 +2,6 @@ from __future__ import annotations
 
 import collections
 import datetime
-import json
 import logging
 import typing as T
 from pathlib import Path
@@ -17,6 +16,11 @@ from .geotag.options import (
     SourcePathOption,
     SourceType,
 )
+from .serializer.description import (
+    DescriptionJSONSerializer,
+    validate_and_fail_metadata,
+)
+from .serializer.gpx import GPXSerializer
 
 LOG = logging.getLogger(__name__)
 DEFAULT_GEOTAG_SOURCE_OPTIONS = [
@@ -200,12 +204,16 @@ def _write_metadatas(
     desc_path: str,
 ) -> None:
     if desc_path == "-":
-        descs = [types.as_desc(metadata) for metadata in metadatas]
-        print(json.dumps(descs, indent=2))
+        descs = DescriptionJSONSerializer.serialize(metadatas)
+        print(descs.decode("utf-8"))
     else:
-        descs = [types.as_desc(metadata) for metadata in metadatas]
-        with open(desc_path, "w") as fp:
-            json.dump(descs, fp)
+        normalized_suffix = Path(desc_path).suffix.strip().lower()
+        if normalized_suffix in [".gpx"]:
+            descs = GPXSerializer.serialize(metadatas)
+        else:
+            descs = DescriptionJSONSerializer.serialize(metadatas)
+        with open(desc_path, "wb") as fp:
+            fp.write(descs)
         LOG.info("Check the description file for details: %s", desc_path)
 
 
@@ -293,7 +301,7 @@ def _validate_metadatas(
     # See https://stackoverflow.com/a/61432070
     good_metadatas, error_metadatas = types.separate_errors(metadatas)
     map_results = utils.mp_map_maybe(
-        types.validate_and_fail_metadata,
+        validate_and_fail_metadata,
         T.cast(T.Iterable[types.Metadata], good_metadatas),
         num_processes=num_processes,
     )
@@ -308,7 +316,7 @@ def _validate_metadatas(
         )
     )
 
-    return validated_metadatas + error_metadatas
+    return T.cast(list[types.MetadataOrError], validated_metadatas + error_metadatas)
 
 
 def process_finalize(

mapillary_tools/process_sequence_properties.py

@@ -7,6 +7,7 @@ import os
 import typing as T
 
 from . import constants, exceptions, geo, types, utils
+from .serializer.description import DescriptionJSONSerializer
 
 LOG = logging.getLogger(__name__)
 
@@ -24,24 +25,21 @@ def split_sequence_by(
     """
     output_sequences: list[list[SeqItem]] = []
 
-    seq = iter(sequence)
-
-    prev = next(seq, None)
-    if prev is None:
-        return output_sequences
-
-    output_sequences.append([prev])
+    if sequence:
+        output_sequences.append([sequence[0]])
 
-    for cur in seq:
+    for prev, cur in geo.pairwise(sequence):
         # invariant: prev is processed
         if should_split(prev, cur):
             output_sequences.append([cur])
         else:
             output_sequences[-1].append(cur)
-        prev = cur
         # invariant: cur is processed
 
-    assert sum(len(s) for s in output_sequences) == len(sequence)
+    assert sum(len(s) for s in output_sequences) == len(sequence), (
+        output_sequences,
+        sequence,
+    )
 
     return output_sequences
 
@@ -109,7 +107,7 @@ def duplication_check(
             dup = types.describe_error_metadata(
                 exceptions.MapillaryDuplicationError(
                     msg,
-                    types.as_desc(cur),
+                    DescriptionJSONSerializer.as_desc(cur),
                     distance=distance,
                     angle_diff=angle_diff,
                 ),

mapillary_tools/sample_video.py

@@ -13,6 +13,7 @@ from . import constants, exceptions, ffmpeg as ffmpeglib, geo, types, utils
 from .exif_write import ExifEdit
 from .geotag import geotag_videos_from_video
 from .mp4 import mp4_sample_parser
+from .serializer.description import parse_capture_time
 
 LOG = logging.getLogger(__name__)
 
@@ -65,7 +66,7 @@ def sample_video(
     video_start_time_dt: datetime.datetime | None = None
     if video_start_time is not None:
         try:
-            video_start_time_dt = types.map_capture_time_to_datetime(video_start_time)
+            video_start_time_dt = parse_capture_time(video_start_time)
         except ValueError as ex:
             raise exceptions.MapillaryBadParameterError(str(ex))
 
@@ -193,8 +194,8 @@ def _sample_single_video_by_interval(
             )
 
     with wip_dir_context(wip_sample_dir(sample_dir), sample_dir) as wip_dir:
-        ffmpeg.extract_frames(video_path, wip_dir, sample_interval)
-        frame_samples = ffmpeglib.sort_selected_samples(wip_dir, video_path, [None])
+        ffmpeg.extract_frames_by_interval(video_path, wip_dir, sample_interval)
+        frame_samples = ffmpeglib.FFMPEG.sort_selected_samples(wip_dir, video_path)
         for frame_idx_1based, sample_paths in frame_samples:
             assert len(sample_paths) == 1
             if sample_paths[0] is None:
@@ -321,11 +322,11 @@ def _sample_single_video_by_distance(
             video_path,
             wip_dir,
             frame_indices=set(sorted_sample_indices),
-            stream_idx=video_stream_idx,
+            stream_specifier=str(video_stream_idx),
         )
 
-        frame_samples = ffmpeglib.sort_selected_samples(
-            wip_dir, video_path, [video_stream_idx]
+        frame_samples = ffmpeglib.FFMPEG.sort_selected_samples(
+            wip_dir, video_path, selected_stream_specifiers=[str(video_stream_idx)]
         )
         if len(frame_samples) != len(sorted_sample_indices):
             raise exceptions.MapillaryVideoError(