chore: upgrade to pyproject.toml

.github/workflows/python-package.yml

@@ -16,7 +16,7 @@ jobs:
   build:
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
         platform: ["ubuntu-latest", "macos-latest", "windows-latest"]
         # https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
         # Optional - x64 or x86 architecture, defaults to x64
@@ -44,7 +44,7 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           python -m pip install .
-          python -m pip install -r requirements-dev.txt
+          python -m pip install --group dev
 
       - name: Lint with ruff
         run: |
@@ -56,7 +56,7 @@ jobs:
 
       - name: Sort imports with usort
         run: |
-          usort diff mapillary_tools/
+          usort diff mapillary_tools
 
       - name: Type check with mypy
         run: |

.github/workflows/release.yml

@@ -92,7 +92,7 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           python -m pip install .
-          python -m pip install -r requirements-dev.txt
+          python -m pip install --group dev
 
       - name: Validate version
         run: |

README.md

@@ -28,18 +28,40 @@ mapillary_tools --help
 <!--ts-->
 
 - [Supported File Formats](#supported-file-formats)
+  - [Image Formats](#image-formats)
+  - [Video Formats](#video-formats)
 - [Installation](#installation)
+  - [Standalone Executable](#standalone-executable)
+  - [Installing via pip](#installing-via-pip)
+    - [Installing on Android Devices](#installing-on-android-devices)
 - [Usage](#usage)
   - [Process and Upload](#process-and-upload)
   - [Process](#process)
   - [Upload](#upload)
 - [Advanced Usage](#advanced-usage)
   - [Local Video Processing](#local-video-processing)
+    - [Install FFmpeg](#install-ffmpeg)
+    - [Video Processing](#video-processing)
   - [Geotagging with GPX](#geotagging-with-gpx)
+  - [New video geotagging features (experimental)](#new-video-geotagging-features-experimental)
+    - [Usage](#usage-1)
+    - [Examples](#examples)
+      - [Generic supported videos](#generic-supported-videos)
+      - [External GPX](#external-gpx)
+      - [Insta360 stitched videos](#insta360-stitched-videos)
+    - [Limitations of `--video_geotag_source`](#limitations-of---video_geotag_source)
   - [Authenticate](#authenticate)
+    - [Examples](#examples-1)
   - [Image Description](#image-description)
   - [Zip Images](#zip-images)
 - [Development](#development)
+  - [Setup](#setup)
+    - [Option 1: Using uv (Recommended)](#option-1-using-uv-recommended)
+    - [Option 2: Using pip with virtual environment](#option-2-using-pip-with-virtual-environment)
+  - [Running the code](#running-the-code)
+  - [Tests](#tests)
+  - [Code Quality](#code-quality)
+  - [Release and Build](#release-and-build)
 
 <!--te-->
 
@@ -465,49 +487,78 @@ git clone [email protected]:mapillary/mapillary_tools.git
 cd mapillary_tools
 ```
 
-Set up the virtual environment. It is optional but recommended:
+### Option 1: Using uv (Recommended)
+
+Use [uv](https://docs.astral.sh/uv/) - a fast Python package manager.
+
+Install the project in development mode with all dependencies:
 
 ```sh
-pip install pipenv
+# Install the project and development dependencies
+uv sync --group dev
+
+# Activate the virtual environment
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 ```
 
-Install dependencies:
+### Option 2: Using pip with virtual environment
+
+Set up a virtual environment (recommended):
 
 ```sh
-pipenv install -r requirements.txt
-pipenv install -r requirements-dev.txt
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 ```
 
-Enter the virtualenv shell:
+Install the project in development mode:
 
 ```sh
-pipenv shell
+# Install the project and all dependencies in editable mode
+pip install -e .
+
+# Install development dependencies
+pip install --group dev
 ```
 
+## Running the code
+
 Run the code from the repository:
 
 ```sh
-python3 -m mapillary_tools.commands --version
+# If you have mapillary_tools installed in editable mode
+mapillary_tools --version
+
+# Alternatively
+python -m mapillary_tools.commands --version
 ```
 
 ## Tests
 
 Run tests:
 
 ```sh
-# test all cases
-python3 -m pytest -s -vv tests
-# or test a single case specifically
-python3 -m pytest -s -vv tests/unit/test_camm_parser.py::test_build_and_parse
+# Test all cases
+pytest -s -vv tests
+# Or test a single case specifically
+pytest -s -vv tests/unit/test_camm_parser.py::test_build_and_parse
 ```
 
-Run linting:
+## Code Quality
+
+Run code formatting and linting:
 
 ```sh
-# format code
-black mapillary_tools tests
-# sort imports
+# Format code with ruff
+ruff format mapillary_tools tests
+
+# Lint code with ruff
+ruff check mapillary_tools tests
+
+# Sort imports with usort
 usort format mapillary_tools tests
+
+# Type checking with mypy
+mypy mapillary_tools
 ```
 
 ## Release and Build

mapillary_tools/geotag/base.py

@@ -51,7 +51,7 @@ def to_description(
             )
         )
 
-        return results + error_metadatas
+        return T.cast(list[types.ImageMetadataOrError], results + error_metadatas)
 
     # This method is passed to multiprocessing
     # so it has to be classmethod or staticmethod to avoid pickling the instance
@@ -117,7 +117,7 @@ def to_description(
             )
         )
 
-        return results + error_metadatas
+        return T.cast(list[types.VideoMetadataOrError], results + error_metadatas)
 
     # This method is passed to multiprocessing
     # so it has to be classmethod or staticmethod to avoid pickling the instance

mapillary_tools/process_geotag_properties.py

@@ -308,7 +308,7 @@ def _validate_metadatas(
         )
     )
 
-    return validated_metadatas + error_metadatas
+    return T.cast(list[types.MetadataOrError], validated_metadatas + error_metadatas)
 
 
 def process_finalize(

mapillary_tools.spec → pyinstaller/mapillary_tools.spec

@@ -5,7 +5,7 @@ block_cipher = None
 options = [("u", None, "OPTION")]
 
 a = Analysis(
-    ["./pyinstaller/main.py"],
+    ["./main.py"],
     pathex=[SPECPATH],
     binaries=[],
     datas=[],

mapillary_tools_folder.spec → pyinstaller/mapillary_tools_folder.spec

@@ -4,7 +4,7 @@
 block_cipher = None
 
 
-a = Analysis(["./pyinstaller/main.py"],
+a = Analysis(["./main.py"],
              pathex=[SPECPATH],
              binaries=[],
              datas=[],