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

mapillary_tools/geotag/image_extractors/base.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import abc
+from pathlib import Path
+
+from ... import types
+
+
+class BaseImageExtractor(abc.ABC):
+    """
+    Extracts metadata from an image file.
+    """
+
+    def __init__(self, image_path: Path):
+        self.image_path = image_path
+
+    def extract(self) -> types.ImageMetadataOrError:
+        raise NotImplementedError

mapillary_tools/geotag/image_extractors/exif.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import contextlib
+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, exif_read, geo, types, utils
+from .base import BaseImageExtractor
+
+
+class ImageEXIFExtractor(BaseImageExtractor):
+    def __init__(self, image_path: Path, skip_lonlat_error: bool = False):
+        super().__init__(image_path)
+        self.skip_lonlat_error = skip_lonlat_error
+
+    @contextlib.contextmanager
+    def _exif_context(self) -> T.Generator[exif_read.ExifReadABC, None, None]:
+        with self.image_path.open("rb") as fp:
+            yield exif_read.ExifRead(fp)
+
+    @override
+    def extract(self) -> types.ImageMetadata:
+        with self._exif_context() as exif:
+            lonlat = exif.extract_lon_lat()
+            if lonlat is None:
+                if not self.skip_lonlat_error:
+                    raise exceptions.MapillaryGeoTaggingError(
+                        "Unable to extract GPS Longitude or GPS Latitude from the image"
+                    )
+                lonlat = (0.0, 0.0)
+            lon, lat = lonlat
+
+            capture_time = exif.extract_capture_time()
+            if capture_time is None:
+                raise exceptions.MapillaryGeoTaggingError(
+                    "Unable to extract timestamp from the image"
+                )
+
+            image_metadata = types.ImageMetadata(
+                filename=self.image_path,
+                filesize=utils.get_file_size(self.image_path),
+                time=geo.as_unix_time(capture_time),
+                lat=lat,
+                lon=lon,
+                alt=exif.extract_altitude(),
+                angle=exif.extract_direction(),
+                width=exif.extract_width(),
+                height=exif.extract_height(),
+                MAPOrientation=exif.extract_orientation(),
+                MAPDeviceMake=exif.extract_make(),
+                MAPDeviceModel=exif.extract_model(),
+            )
+
+        return image_metadata

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

@@ -28,6 +28,7 @@ class SourceType(enum.Enum):
 SOURCE_TYPE_ALIAS: dict[str, SourceType] = {
     "blackvue_videos": SourceType.BLACKVUE,
     "gopro_videos": SourceType.GOPRO,
+    "exiftool": SourceType.EXIFTOOL_RUNTIME,
 }
 
 

mapillary_tools/geotag/utils.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import logging
+import typing as T
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+import gpxpy
+
+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] = []
+
+    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 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 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"
+        )

mapillary_tools/gpmf/gpmf_parser.py

@@ -39,7 +39,7 @@ class KLVDict(T.TypedDict):
     type: bytes
     structure_size: int
     repeat: int
-    data: T.List[T.Any]
+    data: list[T.Any]
 
 
 GPMFSampleData: C.GreedyRange
@@ -143,7 +143,7 @@ class GoProInfo:
 
 def extract_gopro_info(
     fp: T.BinaryIO, telemetry_only: bool = False
-) -> T.Optional[GoProInfo]:
+) -> GoProInfo | None:
     """
     Return the GoProInfo object if found. None indicates it's not a valid GoPro video.
     """
@@ -276,7 +276,7 @@ def _gps5_timestamp_to_epoch_time(dtstr: str):
 def _gps5_from_stream(
     stream: T.Sequence[KLVDict],
 ) -> T.Generator[telemetry.GPSPoint, None, None]:
-    indexed: T.Dict[bytes, T.List[T.List[T.Any]]] = {
+    indexed: dict[bytes, list[list[T.Any]]] = {
         klv["key"]: klv["data"] for klv in stream
     }
 
@@ -362,7 +362,7 @@ def _gps9_from_stream(
 ) -> T.Generator[telemetry.GPSPoint, None, None]:
     NUM_VALUES = 9
 
-    indexed: T.Dict[bytes, T.List[T.List[T.Any]]] = {
+    indexed: dict[bytes, list[list[T.Any]]] = {
         klv["key"]: klv["data"] for klv in stream
     }
 
@@ -444,8 +444,8 @@ def _find_first_device_id(stream: T.Sequence[KLVDict]) -> int:
     return device_id
 
 
-def _find_first_gps_stream(stream: T.Sequence[KLVDict]) -> T.List[telemetry.GPSPoint]:
-    sample_points: T.List[telemetry.GPSPoint] = []
+def _find_first_gps_stream(stream: T.Sequence[KLVDict]) -> list[telemetry.GPSPoint]:
+    sample_points: list[telemetry.GPSPoint] = []
 
     for klv in stream:
         if klv["key"] == b"STRM":
@@ -469,7 +469,7 @@ def _is_matrix_calibration(matrix: T.Sequence[float]) -> bool:
 
 
 def _build_matrix(
-    orin: T.Union[bytes, T.Sequence[int]], orio: T.Union[bytes, T.Sequence[int]]
+    orin: bytes | T.Sequence[int], orio: bytes | T.Sequence[int]
 ) -> T.Sequence[float]:
     matrix = []
 
@@ -503,14 +503,14 @@ def _apply_matrix(
         yield sum(matrix[row_start + x] * values[x] for x in range(size))
 
 
-def _flatten(nested: T.Sequence[T.Sequence[float]]) -> T.List[float]:
-    output: T.List[float] = []
+def _flatten(nested: T.Sequence[T.Sequence[float]]) -> list[float]:
+    output: list[float] = []
     for row in nested:
         output.extend(row)
     return output
 
 
-def _get_matrix(klv: T.Dict[bytes, KLVDict]) -> T.Optional[T.Sequence[float]]:
+def _get_matrix(klv: dict[bytes, KLVDict]) -> T.Sequence[float] | None:
     mtrx = klv.get(b"MTRX")
     if mtrx is not None:
         matrix: T.Sequence[float] = _flatten(mtrx["data"])
@@ -530,7 +530,7 @@ def _get_matrix(klv: T.Dict[bytes, KLVDict]) -> T.Optional[T.Sequence[float]]:
 def _scale_and_calibrate(
     stream: T.Sequence[KLVDict], key: bytes
 ) -> T.Generator[T.Sequence[float], None, None]:
-    indexed: T.Dict[bytes, KLVDict] = {klv["key"]: klv for klv in stream}
+    indexed: dict[bytes, KLVDict] = {klv["key"]: klv for klv in stream}
 
     klv = indexed.get(key)
     if klv is None:
@@ -561,7 +561,7 @@ def _scale_and_calibrate(
 
 
 def _find_first_telemetry_stream(stream: T.Sequence[KLVDict], key: bytes):
-    values: T.List[T.Sequence[float]] = []
+    values: list[T.Sequence[float]] = []
 
     for klv in stream:
         if klv["key"] == b"STRM":
@@ -684,7 +684,7 @@ def _load_telemetry_from_samples(
     return device_found
 
 
-def _is_gpmd_description(description: T.Dict) -> bool:
+def _is_gpmd_description(description: dict) -> bool:
     return description["format"] == b"gpmd"
 
 
@@ -699,11 +699,11 @@ def _filter_gpmd_samples(track: TrackBoxParser) -> T.Generator[Sample, None, Non
             yield sample
 
 
-def _extract_camera_model_from_devices(device_names: T.Dict[int, bytes]) -> str:
+def _extract_camera_model_from_devices(device_names: dict[int, bytes]) -> str:
     if not device_names:
         return ""
 
-    unicode_names: T.List[str] = []
+    unicode_names: list[str] = []
     for name in device_names.values():
         try:
             unicode_names.append(name.decode("utf-8"))
@@ -730,7 +730,7 @@ def _extract_camera_model_from_devices(device_names: T.Dict[int, bytes]) -> str:
 
 def _iterate_read_sample_data(
     fp: T.BinaryIO, samples: T.Iterable[Sample]
-) -> T.Generator[T.Tuple[Sample, bytes], None, None]:
+) -> T.Generator[tuple[Sample, bytes], None, None]:
     for sample in samples:
         fp.seek(sample.raw_sample.offset, io.SEEK_SET)
         yield (sample, fp.read(sample.raw_sample.size))