mapillary-tools 0.14.5__py3-none-any.whl → 0.14.6__py3-none-any.whl

mapillary_tools/geotag/video_extractors/native.py

@@ -1,3 +1,8 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the BSD license found in the
+# LICENSE file in the root directory of this source tree.
+
 from __future__ import annotations
 
 import sys

mapillary_tools/gpmf/gpmf_gps_filter.py

@@ -1,3 +1,8 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the BSD license found in the
+# LICENSE file in the root directory of this source tree.
+
 import logging
 import typing as T
 

mapillary_tools/gpmf/gpmf_parser.py

@@ -1,3 +1,8 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the BSD license found in the
+# LICENSE file in the root directory of this source tree.
+
 from __future__ import annotations
 
 import dataclasses

mapillary_tools/gpmf/gps_filter.py

@@ -1,3 +1,8 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the BSD license found in the
+# LICENSE file in the root directory of this source tree.
+
 from __future__ import annotations
 
 import statistics

mapillary_tools/history.py

@@ -1,3 +1,8 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the BSD license found in the
+# LICENSE file in the root directory of this source tree.
+
 from __future__ import annotations
 
 import json

mapillary_tools/http.py

@@ -1,7 +1,11 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the BSD license found in the
+# LICENSE file in the root directory of this source tree.
+
 from __future__ import annotations
 
 import logging
-
 import ssl
 import sys
 import typing as T

mapillary_tools/ipc.py

@@ -1,3 +1,8 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the BSD license found in the
+# LICENSE file in the root directory of this source tree.
+
 import json
 import logging
 import os

mapillary_tools/mp4/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the BSD license found in the
+# LICENSE file in the root directory of this source tree.

mapillary_tools/mp4/construct_mp4_parser.py

@@ -1,3 +1,8 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the BSD license found in the
+# LICENSE file in the root directory of this source tree.
+
 # pyre-ignore-all-errors[5, 16, 21, 58]
 from __future__ import annotations
 

mapillary_tools/mp4/io_utils.py

@@ -1,3 +1,8 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the BSD license found in the
+# LICENSE file in the root directory of this source tree.
+
 import io
 import typing as T
 

mapillary_tools/mp4/mp4_sample_parser.py

@@ -1,3 +1,8 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the BSD license found in the
+# LICENSE file in the root directory of this source tree.
+
 from __future__ import annotations
 
 import datetime
@@ -7,6 +12,14 @@ from pathlib import Path
 from . import construct_mp4_parser as cparser, simple_mp4_parser as sparser
 
 
+def _convert_to_signed_int32(unsigned_int32: int) -> int:
+    """Interpret an unsigned 32-bit value as negative if high bit is set."""
+    if (unsigned_int32 & (1 << 31)) == 0:
+        return unsigned_int32
+    else:
+        return unsigned_int32 - (1 << 32)
+
+
 class RawSample(T.NamedTuple):
     # 1-based index
     description_idx: int
@@ -192,7 +205,13 @@ def extract_raw_samples_from_stbl_data(
             composition_offsets = []
             for entry in data["entries"]:
                 for _ in range(entry["sample_count"]):
-                    composition_offsets.append(entry["sample_offset"])
+                    # Some encodings like H.264 and H.265 support negative offsets.
+                    # We cannot rely on the version field since some encoders incorrectly set
+                    # ctts version to 0 instead of 1 even when using signed offsets.
+                    # Leigitimate positive values are relatively small so we can assume the value is signed.
+                    composition_offsets.append(
+                        _convert_to_signed_int32(entry["sample_offset"])
+                    )
         elif box["type"] == b"stss":
             syncs = set(data["entries"])
 

mapillary_tools/mp4/simple_mp4_builder.py

@@ -1,3 +1,8 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the BSD license found in the
+# LICENSE file in the root directory of this source tree.
+
 from __future__ import annotations
 
 import dataclasses

mapillary_tools/mp4/simple_mp4_parser.py

@@ -1,3 +1,8 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the BSD license found in the
+# LICENSE file in the root directory of this source tree.
+
 # pyre-ignore-all-errors[5, 16, 21, 24, 58]
 from __future__ import annotations
 

mapillary_tools/process_geotag_properties.py

@@ -1,3 +1,8 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the BSD license found in the
+# LICENSE file in the root directory of this source tree.
+
 from __future__ import annotations
 
 import datetime

mapillary_tools/process_sequence_properties.py

@@ -1,3 +1,8 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the BSD license found in the
+# LICENSE file in the root directory of this source tree.
+
 from __future__ import annotations
 
 import functools
@@ -141,6 +146,55 @@ def duplication_check(
     return dedups, dups
 
 
+def _check_null_island(
+    sequence: PointSequence,
+) -> tuple[PointSequence, list[types.ErrorMetadata]]:
+    """
+    Filter out images with null island (0, 0) GPS coordinates.
+
+    Returns:
+        Tuple of (valid images, error metadatas for null island images)
+    """
+    valid: PointSequence = []
+    errors: list[types.ErrorMetadata] = []
+
+    for image in sequence:
+        if image.lat == 0 and image.lon == 0:
+            ex = exceptions.MapillaryNullIslandError(
+                "GPS coordinates in Null Island (0, 0)"
+            )
+            errors.append(
+                types.describe_error_metadata(
+                    exc=ex, filename=image.filename, filetype=types.FileType.IMAGE
+                )
+            )
+        else:
+            valid.append(image)
+
+    return valid, errors
+
+
+def _check_sequences_null_island(
+    input_sequences: T.Sequence[PointSequence],
+) -> tuple[list[PointSequence], list[types.ErrorMetadata]]:
+    """Apply null island check to all sequences."""
+    output_sequences: list[PointSequence] = []
+    output_errors: list[types.ErrorMetadata] = []
+
+    for sequence in input_sequences:
+        output_sequence, errors = _check_null_island(sequence)
+        if output_sequence:
+            output_sequences.append(output_sequence)
+        output_errors.extend(errors)
+
+    if output_errors:
+        LOG.info(
+            f"Null island check: {len(output_errors)} images removed with (0, 0) coordinates"
+        )
+
+    return output_sequences, output_errors
+
+
 def _group_images_by(
     image_metadatas: T.Iterable[types.ImageMetadata],
     group_key_func: T.Callable[[types.ImageMetadata], T.Hashable],
@@ -283,49 +337,28 @@ def _video_name(video_metadata: types.VideoMetadata) -> str:
 
 def _check_sequences_by_limits(
     input_sequences: T.Sequence[PointSequence],
-    max_sequence_filesize_in_bytes: int | None,
     max_capture_speed_kmh: float,
 ) -> tuple[list[PointSequence], list[types.ErrorMetadata]]:
     output_sequences: list[PointSequence] = []
     output_errors: list[types.ErrorMetadata] = []
 
     for sequence in input_sequences:
-        try:
-            if max_sequence_filesize_in_bytes is not None:
-                sequence_filesize = sum(
-                    utils.get_file_size(image.filename)
-                    if image.filesize is None
-                    else image.filesize
-                    for image in sequence
-                )
-                if sequence_filesize > max_sequence_filesize_in_bytes:
-                    raise exceptions.MapillaryFileTooLargeError(
-                        f"Sequence file size {humanize.naturalsize(sequence_filesize)} exceeds max allowed {humanize.naturalsize(max_sequence_filesize_in_bytes)}",
-                    )
+        avg_speed_kmh = geo.avg_speed(sequence) * 3.6  # Convert m/s to km/h
+        too_fast = len(sequence) >= 2 and avg_speed_kmh > max_capture_speed_kmh
 
-            contains_null_island = any(
-                image.lat == 0 and image.lon == 0 for image in sequence
+        if too_fast:
+            error = exceptions.MapillaryCaptureSpeedTooFastError(
+                f"Capture speed {avg_speed_kmh:.3f} km/h exceeds max allowed {max_capture_speed_kmh:.3f} km/h",
             )
-            if contains_null_island:
-                raise exceptions.MapillaryNullIslandError(
-                    "GPS coordinates in Null Island (0, 0)"
-                )
-
-            avg_speed_kmh = geo.avg_speed(sequence) * 3.6  # Convert m/s to km/h
-            too_fast = len(sequence) >= 2 and avg_speed_kmh > max_capture_speed_kmh
-            if too_fast:
-                raise exceptions.MapillaryCaptureSpeedTooFastError(
-                    f"Capture speed {avg_speed_kmh:.3f} km/h exceeds max allowed {max_capture_speed_kmh:.3f} km/h",
-                )
-        except exceptions.MapillaryDescriptionError as ex:
-            LOG.error(f"{_sequence_name(sequence)}: {ex}")
+            LOG.error(f"{_sequence_name(sequence)}: {error}")
             for image in sequence:
                 output_errors.append(
                     types.describe_error_metadata(
-                        exc=ex, filename=image.filename, filetype=types.FileType.IMAGE
+                        exc=error,
+                        filename=image.filename,
+                        filetype=types.FileType.IMAGE,
                     )
                 )
-
         else:
             output_sequences.append(sequence)
 
@@ -350,6 +383,7 @@ def _group_by_folder_and_camera(
         image_metadatas,
         lambda metadata: (
             str(metadata.filename.parent),
+            metadata.MAPCameraUUID,
             metadata.MAPDeviceMake,
             metadata.MAPDeviceModel,
             metadata.width,
@@ -397,6 +431,138 @@ def _check_sequences_duplication(
     return output_sequences, output_errors
 
 
+def _check_sequences_zigzag(
+    input_sequences: T.Sequence[PointSequence],
+    window_size: int = 5,
+    deviation_threshold: float = 0.8,
+    min_deviations: int = 1,
+    min_distance: float = 50.0,
+) -> tuple[list[PointSequence], list[types.ErrorMetadata]]:
+    """
+    Check for zig-zag GPS patterns where images jump back and forth between locations.
+
+    Detects spatial deviations - when an image returns closer to earlier images
+    than the previous image was. This catches zig-zag patterns where the sequence
+    jumps to a different location and then returns.
+
+    Only marks deviation points as errors, keeping the main path intact.
+
+    Args:
+        input_sequences: List of image sequences to check
+        window_size: Number of images to look back when checking for deviations
+        deviation_threshold: Ratio threshold - if dist_curr < dist_prev * threshold,
+                            it's considered a deviation
+        min_deviations: Minimum number of deviation events to mark errors
+        min_distance: Minimum distance (in meters) between consecutive images (prev to curr)
+                     to consider for deviation detection. This filters out small-scale
+                     movements like U-turns.
+    """
+    output_sequences: list[PointSequence] = []
+    output_errors: list[types.ErrorMetadata] = []
+
+    for sequence in input_sequences:
+        if len(sequence) < window_size + 1:
+            # Sequence too short to detect pattern
+            output_sequences.append(sequence)
+            continue
+
+        # Track which indices are detected as deviations
+        deviation_indices: set[int] = set()
+
+        for i in range(window_size, len(sequence)):
+            curr = sequence[i]
+            prev = sequence[i - 1]
+            ref = sequence[i - window_size]
+
+            # Distance between consecutive images (prev to curr)
+            dist_prev_curr = geo.gps_distance(
+                (prev.lat, prev.lon), (curr.lat, curr.lon)
+            )
+            # Distance from current image back to reference
+            dist_curr = geo.gps_distance((curr.lat, curr.lon), (ref.lat, ref.lon))
+            # Distance from previous image to reference
+            dist_prev = geo.gps_distance((prev.lat, prev.lon), (ref.lat, ref.lon))
+
+            # Deviation: current is closer to reference than previous was
+            # Only check if the jump between prev and curr is above min_distance
+            if (
+                dist_prev_curr > min_distance
+                and dist_curr < dist_prev * deviation_threshold
+            ):
+                LOG.debug(
+                    f"Zigzag detected at {prev.filename.name}: "
+                    f"dist_curr={dist_curr:.1f}m < dist_prev={dist_prev:.1f}m * {deviation_threshold}, "
+                    f"jump={dist_prev_curr:.1f}m"
+                )
+
+                # Mark prev as deviation (it's the point that jumped away)
+                deviation_indices.add(i - 1)
+
+                # Walk backwards from prev to ref+1 to find more deviation points
+                # We're looking for deviations between prev and ref
+                # Use the same check as above: compare distance to ref and jump to curr
+                for j in range(i - 2, i - window_size, -1):  # Stop at ref+1
+                    point_j = sequence[j]
+
+                    # Distance from j to ref
+                    dist_j_to_ref = geo.gps_distance(
+                        (point_j.lat, point_j.lon), (ref.lat, ref.lon)
+                    )
+                    # Distance from j to curr
+                    dist_j_to_curr = geo.gps_distance(
+                        (point_j.lat, point_j.lon), (curr.lat, curr.lon)
+                    )
+
+                    # Same check as original: j is a deviation if it's farther from ref
+                    # than curr is, and the jump from j to curr is significant
+                    if (
+                        dist_j_to_curr > min_distance
+                        and dist_curr < dist_j_to_ref * deviation_threshold
+                    ):
+                        deviation_indices.add(j)
+                        LOG.debug(
+                            f"Backwards walk: {point_j.filename.name} also marked as deviation"
+                        )
+                    else:
+                        # j is on the normal path, stop walking backwards
+                        break
+
+        if len(deviation_indices) >= min_deviations:
+            # Create errors only for deviation points
+            for idx in sorted(deviation_indices):
+                image = sequence[idx]
+                ex = exceptions.MapillaryZigZagError("GPS zig-zag deviation detected")
+                LOG.error(f"{image.filename.name}: {ex}")
+                output_errors.append(
+                    types.describe_error_metadata(
+                        exc=ex, filename=image.filename, filetype=types.FileType.IMAGE
+                    )
+                )
+
+            # Keep non-deviation points in output sequence
+            non_deviation_points = [
+                sequence[idx]
+                for idx in range(len(sequence))
+                if idx not in deviation_indices
+            ]
+            if non_deviation_points:
+                output_sequences.append(non_deviation_points)
+        else:
+            output_sequences.append(sequence)
+
+    # Assertion to ensure all images accounted for
+    assert sum(len(s) for s in output_sequences) + len(output_errors) == sum(
+        len(s) for s in input_sequences
+    )
+
+    if output_errors:
+        LOG.info(
+            f"Zig-zag check: {len(output_errors)} images rejected due to GPS zig-zag patterns"
+        )
+
+    return output_sequences, output_errors
+
+
 class SplitState(T.TypedDict, total=False):
     sequence_images: int
     sequence_file_size: int
@@ -604,6 +770,7 @@ def process_sequence_properties(
     duplicate_distance: float = constants.DUPLICATE_DISTANCE,
     duplicate_angle: float = constants.DUPLICATE_ANGLE,
     max_capture_speed_kmh: float = constants.MAX_CAPTURE_SPEED_KMH,
+    skip_zigzag_check: bool = False,
 ) -> list[types.MetadataOrError]:
     LOG.info("==> Processing sequences...")
 
@@ -660,6 +827,10 @@ def process_sequence_properties(
             cutoff_time=cutoff_time,
         )
 
+        # Null island check
+        sequences, errors = _check_sequences_null_island(sequences)
+        error_metadatas.extend(errors)
+
         # Duplication check
         sequences, errors = _check_sequences_duplication(
             sequences,
@@ -678,11 +849,22 @@ def process_sequence_properties(
         # Check limits for sequences
         sequences, errors = _check_sequences_by_limits(
             sequences,
-            max_sequence_filesize_in_bytes=max_sequence_filesize_in_bytes,
             max_capture_speed_kmh=max_capture_speed_kmh,
         )
         error_metadatas.extend(errors)
 
+        # Check for zig-zag GPS patterns
+        # NOTE: This is done after _check_sequences_null_island to filter zero coordinates
+        if not skip_zigzag_check:
+            sequences, errors = _check_sequences_zigzag(
+                sequences,
+                window_size=constants.ZIGZAG_WINDOW_SIZE,
+                deviation_threshold=constants.ZIGZAG_DEVIATION_THRESHOLD,
+                min_deviations=constants.ZIGZAG_MIN_DEVIATIONS,
+                min_distance=constants.ZIGZAG_MIN_DISTANCE,
+            )
+            error_metadatas.extend(errors)
+
         # Split sequences by cutoff distance
         # NOTE: The speed limit check probably rejects most anomalies
         sequences = _split_sequences_by_limits(

mapillary_tools/sample_video.py

@@ -1,3 +1,8 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the BSD license found in the
+# LICENSE file in the root directory of this source tree.
+
 from __future__ import annotations
 
 import datetime
@@ -349,7 +354,14 @@ def _sample_single_video_by_distance(
                 f"interpolated time {interp.time} should match the video sample time {video_sample.exact_composition_time}"
             )
 
-            timestamp = start_time + datetime.timedelta(seconds=interp.time)
+            # Try to use GPS epoch time if available (for timelapse videos)
+            gps_epoch_time = interp.get_gps_epoch_time()
+            if gps_epoch_time is not None:
+                timestamp = datetime.datetime.fromtimestamp(
+                    gps_epoch_time, tz=datetime.timezone.utc
+                )
+            else:
+                timestamp = start_time + datetime.timedelta(seconds=interp.time)
             exif_edit = ExifEdit(sample_paths[0])
             exif_edit.add_date_time_original(timestamp)
             exif_edit.add_gps_datetime(timestamp)

mapillary_tools/serializer/description.py

@@ -1,3 +1,8 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the BSD license found in the
+# LICENSE file in the root directory of this source tree.
+
 from __future__ import annotations
 
 import dataclasses
@@ -84,6 +89,7 @@ class VideoDescription(_SharedDescription, total=False):
     MAPGPSTrack: Required[list[T.Sequence[float | int | None]]]
     MAPDeviceMake: str
     MAPDeviceModel: str
+    MAPCameraUUID: str
 
 
 class _ErrorObject(TypedDict, total=False):
@@ -201,6 +207,10 @@ VideoDescriptionSchema = {
             "type": "string",
             "description": "Device model, e.g. HERO10 Black, DR900S-1CH, Insta360 Titan",
         },
+        "MAPCameraUUID": {
+            "type": "string",
+            "description": "Camera unique identifier, typically derived from camera serial number",
+        },
     },
     "required": [
         "MAPGPSTrack",
@@ -397,6 +407,8 @@ class DescriptionJSONSerializer(BaseSerializer):
             desc["MAPDeviceMake"] = metadata.make
         if metadata.model:
             desc["MAPDeviceModel"] = metadata.model
+        if metadata.camera_uuid:
+            desc["MAPCameraUUID"] = metadata.camera_uuid
         return desc
 
     @classmethod
@@ -490,6 +502,7 @@ class DescriptionJSONSerializer(BaseSerializer):
             points=[PointEncoder.decode(entry) for entry in desc["MAPGPSTrack"]],
             make=desc.get("MAPDeviceMake"),
             model=desc.get("MAPDeviceModel"),
+            camera_uuid=desc.get("MAPCameraUUID"),
         )
 
 

mapillary_tools/serializer/gpx.py

@@ -1,3 +1,8 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the BSD license found in the
+# LICENSE file in the root directory of this source tree.
+
 import datetime
 import json
 import sys
@@ -12,7 +17,6 @@ import gpxpy
 import gpxpy.gpx
 
 from .. import geo, types
-
 from ..telemetry import CAMMGPSPoint, GPSPoint
 from ..types import (
     BaseSerializer,

mapillary_tools/store.py

@@ -1,3 +1,8 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the BSD license found in the
+# LICENSE file in the root directory of this source tree.
+
 """
 This module provides a persistent key-value store based on SQLite.