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

mapillary_tools/geotag/options.py

@@ -0,0 +1,160 @@
+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 = v
+            elif k == "pattern":
+                kwargs.setdefault("source_path", SourcePathOption()).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:
+        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": "float",
+        },
+        "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.VideoMetadataOrError:
+        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.VideoMetadataOrError:
+        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/{video_data_extraction/extractors/gpx_parser.py → geotag/video_extractors/gpx.py}

@@ -1,51 +1,84 @@
+from __future__ import annotations
+
+import dataclasses
 import datetime
 import logging
+import sys
 import typing as T
+from pathlib import Path
 
-from ... import geo, telemetry
-from ...geotag import geotag_images_from_gpx_file
-from .base_parser import BaseParser
-from .generic_video_parser import GenericVideoParser
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
 
+from ... import geo, telemetry, types
+from ..utils import parse_gpx
+from .base import BaseVideoExtractor
+from .native import NativeVideoExtractor
 
-LOG = logging.getLogger(__name__)
 
+LOG = logging.getLogger(__name__)
 
-class GpxParser(BaseParser):
-    default_source_pattern = "%g.gpx"
-    parser_label = "gpx"
 
-    def extract_points(self) -> T.Sequence[geo.Point]:
-        path = self.geotag_source_path
-        if not path:
-            return []
+class GPXVideoExtractor(BaseVideoExtractor):
+    def __init__(self, video_path: Path, gpx_path: Path):
+        self.video_path = video_path
+        self.gpx_path = gpx_path
 
+    @override
+    def extract(self) -> types.VideoMetadataOrError:
         try:
-            gpx_tracks = geotag_images_from_gpx_file.parse_gpx(path)
+            gpx_tracks = parse_gpx(self.gpx_path)
         except Exception as ex:
             raise RuntimeError(
-                f"Error parsing GPX {path}: {ex.__class__.__name__}: {ex}"
+                f"Error parsing GPX {self.gpx_path}: {ex.__class__.__name__}: {ex}"
             )
 
         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.videoPath,
+                self.gpx_path,
             )
 
         gpx_points: T.Sequence[geo.Point] = sum(gpx_tracks, [])
-        if not gpx_points:
-            return gpx_points
 
-        offset = self._synx_gpx_by_first_gps_timestamp(gpx_points)
+        native_extractor = NativeVideoExtractor(self.video_path)
+
+        video_metadata_or_error = native_extractor.extract()
+
+        if isinstance(video_metadata_or_error, types.ErrorMetadata):
+            self._rebase_times(gpx_points)
+            return types.VideoMetadata(
+                filename=video_metadata_or_error.filename,
+                filetype=video_metadata_or_error.filetype or 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)
 
-        return gpx_points
+        return dataclasses.replace(video_metadata_or_error, points=gpx_points)
+
+    @staticmethod
+    def _rebase_times(points: T.Sequence[geo.Point], offset: float = 0.0):
+        """
+        Make point times start from 0
+        """
+        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]
+        self, gpx_points: T.Sequence[geo.Point], video_gps_points: T.Sequence[geo.Point]
     ) -> float:
         offset: float = 0.0
 
@@ -57,19 +90,14 @@ class GpxParser(BaseParser):
         )
         LOG.info("First GPX timestamp: %s", first_gpx_dt)
 
-        # Extract first GPS timestamp (if found) for synchronization
-        # Use an empty dictionary to force video parsers to extract make/model from the video metadata itself
-        parser = GenericVideoParser(self.videoPath, self.options, {})
-        gps_points = parser.extract_points()
-
-        if not gps_points:
+        if not video_gps_points:
             LOG.warning(
                 "Skip GPX synchronization because no GPS found in video %s",
-                self.videoPath,
+                self.video_path,
             )
             return offset
 
-        first_gps_point = gps_points[0]
+        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(
@@ -92,17 +120,7 @@ class GpxParser(BaseParser):
             else:
                 LOG.warning(
                     "Skip GPX synchronization because no GPS epoch time found in video %s",
-                    self.videoPath,
+                    self.video_path,
                 )
 
         return offset
-
-    def extract_make(self) -> T.Optional[str]:
-        # Use an empty dictionary to force video parsers to extract make/model from the video metadata itself
-        parser = GenericVideoParser(self.videoPath, self.options, {})
-        return parser.extract_make()
-
-    def extract_model(self) -> T.Optional[str]:
-        # Use an empty dictionary to force video parsers to extract make/model from the video metadata itself
-        parser = GenericVideoParser(self.videoPath, self.options, {})
-        return parser.extract_model()

mapillary_tools/geotag/video_extractors/native.py

@@ -0,0 +1,157 @@
+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 .base import BaseVideoExtractor
+
+
+class GoProVideoExtractor(BaseVideoExtractor):
+    @override
+    def extract(self) -> types.VideoMetadataOrError:
+        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:
+            # 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
+            )
+
+        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
+            )
+
+        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.VideoMetadataOrError:
+        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:
+            # 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
+            )
+
+        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.VideoMetadataOrError:
+        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:
+            # 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
+            )
+
+        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 [],
+            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.VideoMetadataOrError:
+        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 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 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 exceptions.MapillaryVideoGPSNotFoundError:
+                pass
+
+        raise exceptions.MapillaryVideoGPSNotFoundError(
+            "No GPS data found from the video"
+        )