mapillary-tools 0.13.3a1__py3-none-any.whl → 0.14.0__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
@@ -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
@@ -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
+) -> GoProInfo | None:
+    """
+    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,10 +273,10 @@ 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]:
-    indexed: T.Dict[bytes, T.List[T.List[T.Any]]] = {
+) -> T.Generator[telemetry.GPSPoint, None, None]:
+    indexed: dict[bytes, list[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,12 +357,12 @@ 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]]] = {
+    indexed: dict[bytes, list[list[T.Any]]] = {
         klv["key"]: klv["data"] for klv in stream
     }
 
@@ -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]) -> list[telemetry.GPSPoint]:
+    sample_points: 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
 
@@ -377,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 = []
 
@@ -411,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"])
@@ -438,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:
@@ -469,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":
@@ -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,94 +594,97 @@ 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:
+def _is_gpmd_description(description: dict) -> bool:
     return description["format"] == b"gpmd"
 
 
@@ -627,60 +699,11 @@ 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: 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"))
@@ -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[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/{geotag → gpmf}/gps_filter.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import statistics
 import typing as T
 
@@ -96,7 +98,7 @@ def both(
 def dbscan(
     sequences: T.Sequence[PointSequence],
     merge_or_not: Decider,
-) -> T.Dict[int, PointSequence]:
+) -> dict[int, PointSequence]:
     """
     One-dimension DBSCAN clustering: https://en.wikipedia.org/wiki/DBSCAN
     The input is a list of sequences, and it is guaranteed that all sequences are sorted by time.
@@ -107,7 +109,7 @@ def dbscan(
     """
 
     # find which sequences (keys) should be merged to which sequences (values)
-    mergeto: T.Dict[int, int] = {}
+    mergeto: dict[int, int] = {}
     for left in range(len(sequences)):
         mergeto.setdefault(left, left)
         # find the first sequence to merge with
@@ -119,7 +121,7 @@ def dbscan(
                 break
 
     # merge
-    merged: T.Dict[int, PointSequence] = {}
+    merged: dict[int, PointSequence] = {}
     for idx, s in enumerate(sequences):
         merged.setdefault(mergeto[idx], []).extend(s)