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

mapillary_tools/geotag/image_extractors/exiftool.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import contextlib
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+from ... import exiftool_read
+from .exif import ImageEXIFExtractor
+
+
+class ImageExifToolExtractor(ImageEXIFExtractor):
+    def __init__(self, image_path: Path, element: ET.Element):
+        super().__init__(image_path)
+        self.element = element
+
+    @contextlib.contextmanager
+    def _exif_context(self):
+        yield exiftool_read.ExifToolRead(ET.ElementTree(self.element))

mapillary_tools/geotag/options.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+import dataclasses
+import enum
+import json
+import typing as T
+from pathlib import Path
+
+import jsonschema
+
+from .. import types
+
+
+class SourceType(enum.Enum):
+    NATIVE = "native"
+    GPX = "gpx"
+    NMEA = "nmea"
+    EXIFTOOL_XML = "exiftool_xml"
+    EXIFTOOL_RUNTIME = "exiftool_runtime"
+
+    # Legacy source types for images
+    GOPRO = "gopro"
+    BLACKVUE = "blackvue"
+    CAMM = "camm"
+    EXIF = "exif"
+
+
+SOURCE_TYPE_ALIAS: dict[str, SourceType] = {
+    "blackvue_videos": SourceType.BLACKVUE,
+    "gopro_videos": SourceType.GOPRO,
+    "exiftool": SourceType.EXIFTOOL_RUNTIME,
+}
+
+
+@dataclasses.dataclass
+class SourceOption:
+    # Type of the source
+    source: SourceType
+
+    # Filter by these filetypes
+    filetypes: set[types.FileType] | None = None
+
+    num_processes: int | None = None
+
+    source_path: SourcePathOption | None = None
+
+    interpolation: InterpolationOption | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, T.Any]) -> SourceOption:
+        validate_option(data)
+
+        kwargs: dict[str, T.Any] = {}
+        for k, v in data.items():
+            # None values are considered as absent and should be ignored
+            if v is None:
+                continue
+            if k == "source":
+                kwargs[k] = SourceType(SOURCE_TYPE_ALIAS.get(v, v))
+            elif k == "filetypes":
+                kwargs[k] = {types.FileType(t) for t in v}
+            elif k == "source_path":
+                kwargs.setdefault(
+                    "source_path", SourcePathOption(source_path=Path(v))
+                ).sourthe_path = Path(v)
+            elif k == "pattern":
+                kwargs.setdefault(
+                    "source_path", SourcePathOption(pattern=v)
+                ).pattern = v
+            elif k == "interpolation_offset_time":
+                kwargs.setdefault(
+                    "interpolation", InterpolationOption()
+                ).offset_time = v
+            elif k == "interpolation_use_gpx_start_time":
+                kwargs.setdefault(
+                    "interpolation", InterpolationOption()
+                ).use_gpx_start_time = v
+
+        return cls(**kwargs)
+
+
+@dataclasses.dataclass
+class SourcePathOption:
+    pattern: str | None = None
+    source_path: Path | None = None
+
+    def __post_init__(self):
+        if self.source_path is None and self.pattern is None:
+            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
+
+        assert self.pattern is not None, (
+            "either pattern or source_path must be provided"
+        )
+
+        # %f: the full video filename (foo.mp4)
+        # %g: the video filename without extension (foo)
+        # %e: the video filename extension (.mp4)
+        replaced = Path(
+            self.pattern.replace("%f", path.name)
+            .replace("%g", path.stem)
+            .replace("%e", path.suffix)
+        )
+
+        abs_path = (
+            replaced
+            if replaced.is_absolute()
+            else Path.joinpath(path.parent.resolve(), replaced)
+        ).resolve()
+
+        return abs_path
+
+
+@dataclasses.dataclass
+class InterpolationOption:
+    offset_time: float = 0.0
+    use_gpx_start_time: bool = False
+
+
+SourceOptionSchema = {
+    "type": "object",
+    "properties": {
+        "source": {
+            "type": "string",
+            "enum": [s.value for s in SourceType] + list(SOURCE_TYPE_ALIAS.keys()),
+        },
+        "filetypes": {
+            "type": "array",
+            "items": {
+                "type": "string",
+                "enum": [t.value for t in types.FileType],
+            },
+        },
+        "source_path": {
+            "type": "string",
+        },
+        "pattern": {
+            "type": "string",
+        },
+        "num_processes": {
+            "type": "integer",
+        },
+        "interpolation_offset_time": {
+            "type": "number",
+        },
+        "interpolation_use_gpx_start_time": {
+            "type": "boolean",
+        },
+    },
+    "required": ["source"],
+    "additionalProperties": False,
+}
+
+
+def validate_option(instance):
+    jsonschema.validate(instance=instance, schema=SourceOptionSchema)
+
+
+if __name__ == "__main__":
+    # python -m mapillary_tools.geotag.options > schema/geotag_source_option.json
+    print(json.dumps(SourceOptionSchema, indent=4))

mapillary_tools/geotag/utils.py

@@ -1,26 +1,62 @@
-import datetime
+from __future__ import annotations
+
+import logging
 import typing as T
+import xml.etree.ElementTree as ET
+from pathlib import Path
 
 import gpxpy
-import gpxpy.gpx
 
-from .. import geo
+from .. import exiftool_read, geo, utils
+
+Track = T.List[geo.Point]
+LOG = logging.getLogger(__name__)
+
+
+def parse_gpx(gpx_file: Path) -> list[Track]:
+    with gpx_file.open("r") as f:
+        gpx = gpxpy.parse(f)
 
+    tracks: list[Track] = []
 
-def is_video_stationary(max_distance_from_start: float) -> bool:
-    radius_threshold = 10
-    return max_distance_from_start < radius_threshold
+    for track in gpx.tracks:
+        for segment in track.segments:
+            tracks.append([])
+            for point in segment.points:
+                if point.time is not None:
+                    tracks[-1].append(
+                        geo.Point(
+                            time=geo.as_unix_time(point.time),
+                            lat=point.latitude,
+                            lon=point.longitude,
+                            alt=point.elevation,
+                            angle=None,
+                        )
+                    )
 
+    return tracks
 
-def convert_points_to_gpx_segment(points: T.Sequence[geo.Point]):
-    gpx_segment = gpxpy.gpx.GPXTrackSegment()
-    for point in points:
-        gpx_segment.points.append(
-            gpxpy.gpx.GPXTrackPoint(
-                point.lat,
-                point.lon,
-                elevation=point.alt,
-                time=datetime.datetime.utcfromtimestamp(point.time),
+
+def index_rdf_description_by_path(
+    xml_paths: T.Sequence[Path],
+) -> dict[str, ET.Element]:
+    rdf_description_by_path: dict[str, ET.Element] = {}
+
+    for xml_path in utils.find_xml_files(xml_paths):
+        try:
+            etree = ET.parse(xml_path)
+        except ET.ParseError as ex:
+            verbose = LOG.getEffectiveLevel() <= logging.DEBUG
+            if verbose:
+                LOG.warning("Failed to parse %s", xml_path, exc_info=True)
+            else:
+                LOG.warning("Failed to parse %s: %s", xml_path, ex)
+            continue
+
+        rdf_description_by_path.update(
+            exiftool_read.index_rdf_description_by_path_from_xml_element(
+                etree.getroot()
             )
         )
-    return gpx_segment
+
+    return rdf_description_by_path

mapillary_tools/geotag/video_extractors/base.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import abc
+from pathlib import Path
+
+from ... import types
+
+
+class BaseVideoExtractor(abc.ABC):
+    """
+    Extracts metadata from a video file.
+    """
+
+    def __init__(self, video_path: Path):
+        self.video_path = video_path
+
+    def extract(self) -> types.VideoMetadata:
+        raise NotImplementedError

mapillary_tools/geotag/video_extractors/exiftool.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import sys
+import typing as T
+from pathlib import Path
+from xml.etree import ElementTree as ET
+
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
+from ... import exceptions, exiftool_read_video, geo, telemetry, types, utils
+from ...gpmf import gpmf_gps_filter
+from .base import BaseVideoExtractor
+
+
+class VideoExifToolExtractor(BaseVideoExtractor):
+    def __init__(self, video_path: Path, element: ET.Element):
+        super().__init__(video_path)
+        self.element = element
+
+    @override
+    def extract(self) -> types.VideoMetadata:
+        exif = exiftool_read_video.ExifToolReadVideo(ET.ElementTree(self.element))
+
+        make = exif.extract_make()
+        model = exif.extract_model()
+
+        is_gopro = make is not None and make.upper() in ["GOPRO"]
+
+        points = exif.extract_gps_track()
+
+        # ExifTool has no idea if GPS is not found or found but empty
+        if is_gopro:
+            if not points:
+                raise exceptions.MapillaryGPXEmptyError("Empty GPS data found")
+
+            # ExifTool (since 13.04) converts GPSSpeed for GoPro to km/h, so here we convert it back to m/s
+            for p in points:
+                if isinstance(p, telemetry.GPSPoint) and p.ground_speed is not None:
+                    p.ground_speed = p.ground_speed / 3.6
+
+            if isinstance(points[0], telemetry.GPSPoint):
+                points = T.cast(
+                    T.List[geo.Point],
+                    gpmf_gps_filter.remove_noisy_points(
+                        T.cast(T.List[telemetry.GPSPoint], points)
+                    ),
+                )
+                if not points:
+                    raise exceptions.MapillaryGPSNoiseError("GPS is too noisy")
+
+        if not points:
+            raise exceptions.MapillaryVideoGPSNotFoundError(
+                "No GPS data found from the video"
+            )
+
+        filetype = types.FileType.GOPRO if is_gopro else types.FileType.VIDEO
+
+        video_metadata = types.VideoMetadata(
+            self.video_path,
+            filesize=utils.get_file_size(self.video_path),
+            filetype=filetype,
+            points=points,
+            make=make,
+            model=model,
+        )
+
+        return video_metadata

mapillary_tools/geotag/video_extractors/gpx.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import dataclasses
+import enum
+import logging
+import sys
+import typing as T
+from pathlib import Path
+
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
+from ... import exceptions, geo, telemetry, types
+from ..utils import parse_gpx
+from .base import BaseVideoExtractor
+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, 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.VideoMetadata:
+        gpx_tracks = parse_gpx(self.gpx_path)
+
+        if 1 < len(gpx_tracks):
+            LOG.warning(
+                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)
+
+        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=self.video_path,
+                filetype=types.FileType.VIDEO,
+                points=gpx_points,
+            )
+
+        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(native_video_metadata, points=gpx_points)
+
+    @classmethod
+    def _rebase_times(cls, points: T.Sequence[geo.Point], offset: float = 0.0) -> None:
+        """
+        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
+
+    @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 or not video_gps_points:
+            return offset
+
+        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

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+import sys
+import typing as T
+from pathlib import Path
+
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
+from ... import blackvue_parser, exceptions, geo, telemetry, types, utils
+from ...camm import camm_parser
+from ...gpmf import gpmf_gps_filter, gpmf_parser
+from ...mp4 import construct_mp4_parser, simple_mp4_parser
+from .base import BaseVideoExtractor
+
+
+class GoProVideoExtractor(BaseVideoExtractor):
+    @override
+    def extract(self) -> types.VideoMetadata:
+        with self.video_path.open("rb") as fp:
+            gopro_info = gpmf_parser.extract_gopro_info(fp)
+
+        if gopro_info is None:
+            raise exceptions.MapillaryVideoGPSNotFoundError(
+                "No GPS data found from the video"
+            )
+
+        gps_points = gopro_info.gps
+        assert gps_points is not None, "must have GPS data extracted"
+        if not gps_points:
+            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:
+            raise exceptions.MapillaryGPSNoiseError("GPS is too noisy")
+
+        video_metadata = types.VideoMetadata(
+            filename=self.video_path,
+            filesize=utils.get_file_size(self.video_path),
+            filetype=types.FileType.GOPRO,
+            points=T.cast(T.List[geo.Point], gps_points),
+            make=gopro_info.make,
+            model=gopro_info.model,
+        )
+
+        return video_metadata
+
+
+class CAMMVideoExtractor(BaseVideoExtractor):
+    @override
+    def extract(self) -> types.VideoMetadata:
+        with self.video_path.open("rb") as fp:
+            camm_info = camm_parser.extract_camm_info(fp)
+
+        if camm_info is None:
+            raise exceptions.MapillaryVideoGPSNotFoundError(
+                "No GPS data found from the video"
+            )
+
+        if not camm_info.gps and not camm_info.mini_gps:
+            raise exceptions.MapillaryGPXEmptyError("Empty GPS data found")
+
+        return types.VideoMetadata(
+            filename=self.video_path,
+            filesize=utils.get_file_size(self.video_path),
+            filetype=types.FileType.CAMM,
+            points=T.cast(T.List[geo.Point], camm_info.gps or camm_info.mini_gps),
+            make=camm_info.make,
+            model=camm_info.model,
+        )
+
+
+class BlackVueVideoExtractor(BaseVideoExtractor):
+    @override
+    def extract(self) -> types.VideoMetadata:
+        with self.video_path.open("rb") as fp:
+            blackvue_info = blackvue_parser.extract_blackvue_info(fp)
+
+        if blackvue_info is None:
+            raise exceptions.MapillaryVideoGPSNotFoundError(
+                "No GPS data found from the video"
+            )
+
+        if not blackvue_info.gps:
+            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,
+            make=blackvue_info.make,
+            model=blackvue_info.model,
+        )
+
+        return video_metadata
+
+
+class NativeVideoExtractor(BaseVideoExtractor):
+    def __init__(self, video_path: Path, filetypes: set[types.FileType] | None = None):
+        super().__init__(video_path)
+        self.filetypes = filetypes
+
+    @override
+    def extract(self) -> types.VideoMetadata:
+        ft = self.filetypes
+        extractor: BaseVideoExtractor
+
+        if ft is None or types.FileType.VIDEO in ft or types.FileType.GOPRO in ft:
+            extractor = GoProVideoExtractor(self.video_path)
+            try:
+                return extractor.extract()
+            except simple_mp4_parser.BoxNotFoundError as ex:
+                raise exceptions.MapillaryInvalidVideoError(
+                    f"Invalid video: {ex}"
+                ) from ex
+            except construct_mp4_parser.BoxNotFoundError as ex:
+                raise exceptions.MapillaryInvalidVideoError(
+                    f"Invalid video: {ex}"
+                ) from ex
+            except exceptions.MapillaryVideoGPSNotFoundError:
+                pass
+
+        if ft is None or types.FileType.VIDEO in ft or types.FileType.CAMM in ft:
+            extractor = CAMMVideoExtractor(self.video_path)
+            try:
+                return extractor.extract()
+            except simple_mp4_parser.BoxNotFoundError as ex:
+                raise exceptions.MapillaryInvalidVideoError(
+                    f"Invalid video: {ex}"
+                ) from ex
+            except construct_mp4_parser.BoxNotFoundError as ex:
+                raise exceptions.MapillaryInvalidVideoError(
+                    f"Invalid video: {ex}"
+                ) from ex
+            except exceptions.MapillaryVideoGPSNotFoundError:
+                pass
+
+        if ft is None or types.FileType.VIDEO in ft or types.FileType.BLACKVUE in ft:
+            extractor = BlackVueVideoExtractor(self.video_path)
+            try:
+                return extractor.extract()
+            except simple_mp4_parser.BoxNotFoundError as ex:
+                raise exceptions.MapillaryInvalidVideoError(
+                    f"Invalid video: {ex}"
+                ) from ex
+            except construct_mp4_parser.BoxNotFoundError as ex:
+                raise exceptions.MapillaryInvalidVideoError(
+                    f"Invalid video: {ex}"
+                ) from ex
+            except exceptions.MapillaryVideoGPSNotFoundError:
+                pass
+
+        raise exceptions.MapillaryVideoGPSNotFoundError(
+            "No GPS data found from the video"
+        )