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

mapillary_tools/{geotag → gpmf}/gpmf_parser.py

@@ -1,15 +1,15 @@
+from __future__ import annotations
+
 import dataclasses
 import datetime
 import io
 import itertools
-import pathlib
 import typing as T
 
 import construct as C
 
 from .. import telemetry
 from ..mp4.mp4_sample_parser import MovieBoxParser, Sample, TrackBoxParser
-from ..telemetry import GPSFix, GPSPoint
 
 """
 Parsing GPS from GPMF data format stored in GoPros. See the GPMF spec: https://github.com/gopro/gpmf-parser
@@ -130,11 +130,103 @@ GPMFSampleData = C.GreedyRange(KLV)
 
 
 @dataclasses.dataclass
-class TelemetryData:
-    gps: T.List[GPSPoint]
-    accl: T.List[telemetry.AccelerationData]
-    gyro: T.List[telemetry.GyroscopeData]
-    magn: T.List[telemetry.MagnetometerData]
+class GoProInfo:
+    # None indicates the data has been extracted,
+    # while [] indicates extracetd but no data point found
+    gps: list[telemetry.GPSPoint] | None = None
+    accl: list[telemetry.AccelerationData] | None = None
+    gyro: list[telemetry.GyroscopeData] | None = None
+    magn: list[telemetry.MagnetometerData] | None = None
+    make: str = "GoPro"
+    model: str = ""
+
+
+def extract_gopro_info(
+    fp: T.BinaryIO, telemetry_only: bool = False
+) -> T.Optional[GoProInfo]:
+    """
+    Return the GoProInfo object if found. None indicates it's not a valid GoPro video.
+    """
+
+    moov = MovieBoxParser.parse_stream(fp)
+    for track in moov.extract_tracks():
+        if _contains_gpmd_description(track):
+            gpmd_samples = _filter_gpmd_samples(track)
+
+            if telemetry_only:
+                points_by_dvid: dict[int, list[telemetry.GPSPoint]] | None = None
+                dvnm_by_dvid: dict[int, bytes] | None = None
+                accls_by_dvid: dict[int, list[telemetry.AccelerationData]] | None = {}
+                gyros_by_dvid: dict[int, list[telemetry.GyroscopeData]] | None = {}
+                magns_by_dvid: dict[int, list[telemetry.MagnetometerData]] | None = {}
+            else:
+                points_by_dvid = {}
+                dvnm_by_dvid = {}
+                accls_by_dvid = None
+                gyros_by_dvid = None
+                magns_by_dvid = None
+
+            device_found = _load_telemetry_from_samples(
+                fp,
+                gpmd_samples,
+                points_by_dvid=points_by_dvid,
+                accls_by_dvid=accls_by_dvid,
+                gyros_by_dvid=gyros_by_dvid,
+                magns_by_dvid=magns_by_dvid,
+                dvnm_by_dvid=dvnm_by_dvid,
+            )
+            # If no device found, it's likely some other cameras using
+            # the "gpmd" container format, e.g. VANTRUE N2S 4K Dashcam
+            if not device_found:
+                return None
+
+            gopro_info = GoProInfo()
+
+            if points_by_dvid is not None:
+                gps_points = list(points_by_dvid.values())[0] if points_by_dvid else []
+                # backfill forward from the first point with epoch time
+                _backfill_gps_timestamps(gps_points)
+                # backfill backward from the first point with epoch time in reversed order
+                _backfill_gps_timestamps(reversed(gps_points))
+                gopro_info.gps = gps_points
+
+            if accls_by_dvid is not None:
+                gopro_info.accl = (
+                    list(accls_by_dvid.values())[0] if accls_by_dvid else []
+                )
+
+            if gyros_by_dvid is not None:
+                gopro_info.gyro = (
+                    list(gyros_by_dvid.values())[0] if gyros_by_dvid else []
+                )
+
+            if magns_by_dvid is not None:
+                gopro_info.magn = (
+                    list(magns_by_dvid.values())[0] if magns_by_dvid else []
+                )
+
+            if dvnm_by_dvid is not None:
+                gopro_info.model = _extract_camera_model_from_devices(dvnm_by_dvid)
+
+            return gopro_info
+
+    return None
+
+
+def extract_camera_model(fp: T.BinaryIO) -> str:
+    moov = MovieBoxParser.parse_stream(fp)
+    for track in moov.extract_tracks():
+        if _contains_gpmd_description(track):
+            gpmd_samples = _filter_gpmd_samples(track)
+            dvnm_by_dvid: dict[int, bytes] = {}
+            device_found = _load_telemetry_from_samples(
+                fp, gpmd_samples, dvnm_by_dvid=dvnm_by_dvid
+            )
+            if not device_found:
+                return ""
+            return _extract_camera_model_from_devices(dvnm_by_dvid)
+
+    return ""
 
 
 def _gps5_timestamp_to_epoch_time(dtstr: str):
@@ -181,9 +273,9 @@ def _gps5_timestamp_to_epoch_time(dtstr: str):
 #                 [378081666, -1224280064, 9621, 1492, 138],
 #                 [378081662, -1224280049, 9592, 1476, 150],
 #             ]
-def gps5_from_stream(
+def _gps5_from_stream(
     stream: T.Sequence[KLVDict],
-) -> T.Generator[GPSPoint, None, None]:
+) -> T.Generator[telemetry.GPSPoint, None, None]:
     indexed: T.Dict[bytes, T.List[T.List[T.Any]]] = {
         klv["key"]: klv["data"] for klv in stream
     }
@@ -201,7 +293,7 @@ def gps5_from_stream(
 
     gpsf = indexed.get(b"GPSF")
     if gpsf is not None:
-        gpsf_value = GPSFix(gpsf[0][0])
+        gpsf_value = telemetry.GPSFix(gpsf[0][0])
     else:
         gpsf_value = None
 
@@ -225,7 +317,7 @@ def gps5_from_stream(
         lat, lon, alt, ground_speed, _speed_3d = [
             v / s for v, s in zip(point, scal_values)
         ]
-        yield GPSPoint(
+        yield telemetry.GPSPoint(
             # will figure out the actual timestamp later
             time=0,
             lat=lat,
@@ -265,9 +357,9 @@ def _get_gps_type(input) -> bytes:
     return final
 
 
-def gps9_from_stream(
+def _gps9_from_stream(
     stream: T.Sequence[KLVDict],
-) -> T.Generator[GPSPoint, None, None]:
+) -> T.Generator[telemetry.GPSPoint, None, None]:
     NUM_VALUES = 9
 
     indexed: T.Dict[bytes, T.List[T.List[T.Any]]] = {
@@ -322,14 +414,14 @@ def gps9_from_stream(
 
         epoch_time = _gps9_timestamp_to_epoch_time(days_since_2000, secs_since_midnight)
 
-        yield GPSPoint(
+        yield telemetry.GPSPoint(
             # will figure out the actual timestamp later
             time=0,
             lat=lat,
             lon=lon,
             alt=alt,
             epoch_time=epoch_time,
-            fix=GPSFix(gps_fix),
+            fix=telemetry.GPSFix(gps_fix),
             precision=dop * 100,
             ground_speed=speed_2d,
             angle=None,
@@ -352,16 +444,16 @@ def _find_first_device_id(stream: T.Sequence[KLVDict]) -> int:
     return device_id
 
 
-def _find_first_gps_stream(stream: T.Sequence[KLVDict]) -> T.List[GPSPoint]:
-    sample_points: T.List[GPSPoint] = []
+def _find_first_gps_stream(stream: T.Sequence[KLVDict]) -> T.List[telemetry.GPSPoint]:
+    sample_points: T.List[telemetry.GPSPoint] = []
 
     for klv in stream:
         if klv["key"] == b"STRM":
-            sample_points = list(gps9_from_stream(klv["data"]))
+            sample_points = list(_gps9_from_stream(klv["data"]))
             if sample_points:
                 break
 
-            sample_points = list(gps5_from_stream(klv["data"]))
+            sample_points = list(_gps5_from_stream(klv["data"]))
             if sample_points:
                 break
 
@@ -480,30 +572,7 @@ def _find_first_telemetry_stream(stream: T.Sequence[KLVDict], key: bytes):
     return values
 
 
-def _extract_dvnm_from_samples(
-    fp: T.BinaryIO, samples: T.Iterable[Sample]
-) -> T.Dict[int, bytes]:
-    dvnm_by_dvid: T.Dict[int, bytes] = {}
-
-    for sample in samples:
-        fp.seek(sample.raw_sample.offset, io.SEEK_SET)
-        data = fp.read(sample.raw_sample.size)
-        gpmf_sample_data = T.cast(T.Dict, GPMFSampleData.parse(data))
-
-        # iterate devices
-        devices = (klv for klv in gpmf_sample_data if klv["key"] == b"DEVC")
-        for device in devices:
-            device_id = _find_first_device_id(device["data"])
-            for klv in device["data"]:
-                if klv["key"] == b"DVNM" and klv["data"]:
-                    # klv["data"] could be [b"H", b"e", b"r", b"o", b"8", b" ", b"B", b"l", b"a", b"c", b"k"]
-                    # or [b"Hero8 Black"]
-                    dvnm_by_dvid[device_id] = b"".join(klv["data"])
-
-    return dvnm_by_dvid
-
-
-def _backfill_gps_timestamps(gps_points: T.Iterable[GPSPoint]) -> None:
+def _backfill_gps_timestamps(gps_points: T.Iterable[telemetry.GPSPoint]) -> None:
     it = iter(gps_points)
 
     # find the first point with epoch time
@@ -525,91 +594,94 @@ def _backfill_gps_timestamps(gps_points: T.Iterable[GPSPoint]) -> None:
         last = point
 
 
-def _extract_points_from_samples(
-    fp: T.BinaryIO, samples: T.Iterable[Sample]
-) -> TelemetryData:
-    # To keep GPS points from different devices separated
-    points_by_dvid: T.Dict[int, T.List[GPSPoint]] = {}
-    accls_by_dvid: T.Dict[int, T.List[telemetry.AccelerationData]] = {}
-    gyros_by_dvid: T.Dict[int, T.List[telemetry.GyroscopeData]] = {}
-    magns_by_dvid: T.Dict[int, T.List[telemetry.MagnetometerData]] = {}
+# This API is designed for performance
+def _load_telemetry_from_samples(
+    fp: T.BinaryIO,
+    samples: T.Iterable[Sample],
+    points_by_dvid: dict[int, list[telemetry.GPSPoint]] | None = None,
+    accls_by_dvid: dict[int, list[telemetry.AccelerationData]] | None = None,
+    gyros_by_dvid: dict[int, list[telemetry.GyroscopeData]] | None = None,
+    magns_by_dvid: dict[int, list[telemetry.MagnetometerData]] | None = None,
+    dvnm_by_dvid: dict[int, bytes] | None = None,
+) -> bool:
+    device_found: bool = False
 
-    for sample in samples:
-        fp.seek(sample.raw_sample.offset, io.SEEK_SET)
-        data = fp.read(sample.raw_sample.size)
-        gpmf_sample_data = T.cast(T.Dict, GPMFSampleData.parse(data))
+    for sample, sample_data in _iterate_read_sample_data(fp, samples):
+        try:
+            gpmf_sample_data = T.cast(T.Dict, GPMFSampleData.parse(sample_data))
+        except C.ConstructError:
+            continue
 
         # iterate devices
         devices = (klv for klv in gpmf_sample_data if klv["key"] == b"DEVC")
         for device in devices:
+            device_found = True
             device_id = _find_first_device_id(device["data"])
 
-            sample_points = _find_first_gps_stream(device["data"])
-            if sample_points:
-                # interpolate timestamps in between
-                avg_timedelta = sample.exact_timedelta / len(sample_points)
-                for idx, point in enumerate(sample_points):
-                    point.time = sample.exact_time + avg_timedelta * idx
-
-                device_points = points_by_dvid.setdefault(device_id, [])
-                device_points.extend(sample_points)
-
-            sample_accls = _find_first_telemetry_stream(device["data"], b"ACCL")
-            if sample_accls:
-                # interpolate timestamps in between
-                avg_delta = sample.exact_timedelta / len(sample_accls)
-                accls_by_dvid.setdefault(device_id, []).extend(
-                    telemetry.AccelerationData(
-                        time=sample.exact_time + avg_delta * idx,
-                        x=x,
-                        y=y,
-                        z=z,
+            if dvnm_by_dvid is not None:
+                for klv in device["data"]:
+                    if klv["key"] == b"DVNM" and klv["data"]:
+                        # klv["data"] could be [b"H", b"e", b"r", b"o", b"8", b" ", b"B", b"l", b"a", b"c", b"k"]
+                        # or [b"Hero8 Black"]
+                        dvnm_by_dvid[device_id] = b"".join(klv["data"])
+
+            if points_by_dvid is not None:
+                sample_points = _find_first_gps_stream(device["data"])
+                if sample_points:
+                    # interpolate timestamps in between
+                    avg_timedelta = sample.exact_timedelta / len(sample_points)
+                    for idx, point in enumerate(sample_points):
+                        point.time = sample.exact_time + avg_timedelta * idx
+
+                    device_points = points_by_dvid.setdefault(device_id, [])
+                    device_points.extend(sample_points)
+
+            if accls_by_dvid is not None:
+                sample_accls = _find_first_telemetry_stream(device["data"], b"ACCL")
+                if sample_accls:
+                    # interpolate timestamps in between
+                    avg_delta = sample.exact_timedelta / len(sample_accls)
+                    accls_by_dvid.setdefault(device_id, []).extend(
+                        telemetry.AccelerationData(
+                            time=sample.exact_time + avg_delta * idx,
+                            x=x,
+                            y=y,
+                            z=z,
+                        )
+                        for idx, (z, x, y, *_) in enumerate(sample_accls)
                     )
-                    for idx, (z, x, y, *_) in enumerate(sample_accls)
-                )
 
-            sample_gyros = _find_first_telemetry_stream(device["data"], b"GYRO")
-            if sample_gyros:
-                # interpolate timestamps in between
-                avg_delta = sample.exact_timedelta / len(sample_gyros)
-                gyros_by_dvid.setdefault(device_id, []).extend(
-                    telemetry.GyroscopeData(
-                        time=sample.exact_time + avg_delta * idx,
-                        x=x,
-                        y=y,
-                        z=z,
+            if gyros_by_dvid is not None:
+                sample_gyros = _find_first_telemetry_stream(device["data"], b"GYRO")
+                if sample_gyros:
+                    # interpolate timestamps in between
+                    avg_delta = sample.exact_timedelta / len(sample_gyros)
+                    gyros_by_dvid.setdefault(device_id, []).extend(
+                        telemetry.GyroscopeData(
+                            time=sample.exact_time + avg_delta * idx,
+                            x=x,
+                            y=y,
+                            z=z,
+                        )
+                        for idx, (z, x, y, *_) in enumerate(sample_gyros)
                     )
-                    for idx, (z, x, y, *_) in enumerate(sample_gyros)
-                )
 
-            sample_magns = _find_first_telemetry_stream(device["data"], b"MAGN")
-            if sample_magns:
-                # interpolate timestamps in between
-                avg_delta = sample.exact_timedelta / len(sample_magns)
-                magns_by_dvid.setdefault(device_id, []).extend(
-                    telemetry.MagnetometerData(
-                        time=sample.exact_time + avg_delta * idx,
-                        x=x,
-                        y=y,
-                        z=z,
+            if magns_by_dvid is not None:
+                sample_magns = _find_first_telemetry_stream(device["data"], b"MAGN")
+                if sample_magns:
+                    # interpolate timestamps in between
+                    avg_delta = sample.exact_timedelta / len(sample_magns)
+                    magns_by_dvid.setdefault(device_id, []).extend(
+                        telemetry.MagnetometerData(
+                            time=sample.exact_time + avg_delta * idx,
+                            x=x,
+                            y=y,
+                            z=z,
+                        )
+                        for idx, (z, x, y, *_) in enumerate(sample_magns)
                     )
-                    for idx, (z, x, y, *_) in enumerate(sample_magns)
-                )
-
-    gps_points = list(points_by_dvid.values())[0] if points_by_dvid else []
-
-    # backfill forward from the first point with epoch time
-    _backfill_gps_timestamps(gps_points)
 
-    # backfill backward from the first point with epoch time in reversed order
-    _backfill_gps_timestamps(reversed(gps_points))
-
-    return TelemetryData(
-        gps=gps_points,
-        accl=list(accls_by_dvid.values())[0] if accls_by_dvid else [],
-        gyro=list(gyros_by_dvid.values())[0] if gyros_by_dvid else [],
-        magn=list(magns_by_dvid.values())[0] if magns_by_dvid else [],
-    )
+    return device_found
 
 
 def _is_gpmd_description(description: T.Dict) -> bool:
@@ -627,56 +699,7 @@ def _filter_gpmd_samples(track: TrackBoxParser) -> T.Generator[Sample, None, Non
             yield sample
 
 
-def extract_points(fp: T.BinaryIO) -> T.List[GPSPoint]:
-    """
-    Return a list of points (could be empty) if it is a valid GoPro video,
-    otherwise None
-    """
-    moov = MovieBoxParser.parse_stream(fp)
-    for track in moov.extract_tracks():
-        if _contains_gpmd_description(track):
-            gpmd_samples = _filter_gpmd_samples(track)
-            telemetry = _extract_points_from_samples(fp, gpmd_samples)
-            # return the firstly found non-empty points
-            if telemetry.gps:
-                return telemetry.gps
-
-    # points could be empty list or None here
-    return []
-
-
-def extract_telemetry_data(fp: T.BinaryIO) -> T.Optional[TelemetryData]:
-    """
-    Return the telemetry data from the first found GoPro GPMF track
-    """
-    moov = MovieBoxParser.parse_stream(fp)
-
-    for track in moov.extract_tracks():
-        if _contains_gpmd_description(track):
-            gpmd_samples = _filter_gpmd_samples(track)
-            telemetry = _extract_points_from_samples(fp, gpmd_samples)
-            # return the firstly found non-empty points
-            if telemetry.gps:
-                return telemetry
-
-    # points could be empty list or None here
-    return None
-
-
-def extract_all_device_names(fp: T.BinaryIO) -> T.Dict[int, bytes]:
-    moov = MovieBoxParser.parse_stream(fp)
-    for track in moov.extract_tracks():
-        if _contains_gpmd_description(track):
-            gpmd_samples = _filter_gpmd_samples(track)
-            device_names = _extract_dvnm_from_samples(fp, gpmd_samples)
-            if device_names:
-                return device_names
-    return {}
-
-
-def extract_camera_model(fp: T.BinaryIO) -> str:
-    device_names = extract_all_device_names(fp)
-
+def _extract_camera_model_from_devices(device_names: T.Dict[int, bytes]) -> str:
     if not device_names:
         return ""
 
@@ -705,9 +728,9 @@ def extract_camera_model(fp: T.BinaryIO) -> str:
     return unicode_names[0].strip()
 
 
-def parse_gpx(path: pathlib.Path) -> T.List[GPSPoint]:
-    with path.open("rb") as fp:
-        points = extract_points(fp)
-    if points is None:
-        return []
-    return points
+def _iterate_read_sample_data(
+    fp: T.BinaryIO, samples: T.Iterable[Sample]
+) -> T.Generator[T.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))

mapillary_tools/history.py

@@ -1,6 +1,5 @@
 import json
 import logging
-import os
 import string
 import typing as T
 from pathlib import Path
@@ -10,13 +9,6 @@ from . import constants, types
 JSONDict = T.Dict[str, T.Union[str, int, float, None]]
 
 LOG = logging.getLogger(__name__)
-MAPILLARY_UPLOAD_HISTORY_PATH = os.getenv(
-    "MAPILLARY_UPLOAD_HISTORY_PATH",
-    os.path.join(
-        constants.USER_DATA_DIR,
-        "upload_history",
-    ),
-)
 
 
 def _validate_hexdigits(md5sum: str):
@@ -35,14 +27,14 @@ def history_desc_path(md5sum: str) -> Path:
     basename = md5sum[2:]
     assert basename, f"Invalid md5sum {md5sum}"
     return (
-        Path(MAPILLARY_UPLOAD_HISTORY_PATH)
+        Path(constants.MAPILLARY_UPLOAD_HISTORY_PATH)
         .joinpath(subfolder)
         .joinpath(f"{basename}.json")
     )
 
 
 def is_uploaded(md5sum: str) -> bool:
-    if not MAPILLARY_UPLOAD_HISTORY_PATH:
+    if not constants.MAPILLARY_UPLOAD_HISTORY_PATH:
         return False
     return history_desc_path(md5sum).is_file()
 
@@ -53,7 +45,7 @@ def write_history(
     summary: JSONDict,
     metadatas: T.Optional[T.Sequence[types.Metadata]] = None,
 ) -> None:
-    if not MAPILLARY_UPLOAD_HISTORY_PATH:
+    if not constants.MAPILLARY_UPLOAD_HISTORY_PATH:
         return
     path = history_desc_path(md5sum)
     LOG.debug("Writing upload history: %s", path)

mapillary_tools/mp4/io_utils.py

@@ -3,7 +3,6 @@ import typing as T
 
 
 class ChainedIO(io.IOBase):
-    # is the chained stream seekable?
     _streams: T.Sequence[io.IOBase]
     # the beginning offset of the current stream
     _begin_offset: int

mapillary_tools/mp4/mp4_sample_parser.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import datetime
 import typing as T
 from pathlib import Path
@@ -278,17 +280,23 @@ class MovieBoxParser:
     def parse_file(cls, video_path: Path) -> "MovieBoxParser":
         with video_path.open("rb") as fp:
             moov = sparser.parse_box_data_firstx(fp, [b"moov"])
-        return MovieBoxParser(moov)
+        return cls(moov)
 
     @classmethod
     def parse_stream(cls, stream: T.BinaryIO) -> "MovieBoxParser":
         moov = sparser.parse_box_data_firstx(stream, [b"moov"])
-        return MovieBoxParser(moov)
+        return cls(moov)
 
     def extract_mvhd_boxdata(self) -> T.Dict:
         mvhd = cparser.find_box_at_pathx(self.moov_children, [b"mvhd"])
         return T.cast(T.Dict, mvhd["data"])
 
+    def extract_udta_boxdata(self) -> T.Dict | None:
+        box = cparser.find_box_at_path(self.moov_children, [b"udta"])
+        if box is None:
+            return None
+        return T.cast(T.Dict, box["data"])
+
     def extract_tracks(self) -> T.Generator[TrackBoxParser, None, None]:
         for box in self.moov_children:
             if box["type"] == b"trak":
@@ -312,7 +320,7 @@ class MovieBoxParser:
         return TrackBoxParser(trak_children)
 
 
-_DT_1904 = datetime.datetime.utcfromtimestamp(0).replace(year=1904)
+_DT_1904 = datetime.datetime.fromtimestamp(0, datetime.timezone.utc).replace(year=1904)
 
 
 def to_datetime(seconds_since_1904: int) -> datetime.datetime:

mapillary_tools/mp4/simple_mp4_parser.py

@@ -187,16 +187,6 @@ def _parse_path_first(
     return None
 
 
-def parse_box_path_firstx(
-    stream: T.BinaryIO, path: T.List[bytes], maxsize: int = -1
-) -> T.Tuple[Header, T.BinaryIO]:
-    # depth=1 will disable EoF extension
-    parsed = _parse_path_first(stream, path, maxsize=maxsize, depth=1)
-    if parsed is None:
-        raise BoxNotFoundError(f"unable find box at path {path}")
-    return parsed
-
-
 def parse_mp4_data_first(
     stream: T.BinaryIO, path: T.List[bytes], maxsize: int = -1
 ) -> T.Optional[bytes]: