geopic-tag-reader 1.3.3__tar.gz → 1.4.0__tar.gz

{geopic_tag_reader-1.3.3 → geopic_tag_reader-1.4.0}/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.4.0] - 2025-01-06
+
+### Added
+
+- Camera general metadata (sensor width, 360° devices, GPS average accuracy) is made available through a single CSV file named `cameras.csv`. This make info centralized and will lighten camera info in Panoramax API.
+- New fields are offered in GeoPicTags: `sensor_width, gps_accuracy, field_of_view`
+
 ## [1.3.3] - 2024-11-24
 
 ### Added
@@ -244,7 +251,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - EXIF tag reading methods extracted from [Panoramax/GeoVisio API](https://gitlab.com/panoramax/server/api)
 
-[Unreleased]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/1.3.3...main
+[Unreleased]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/1.4.0...main
+[1.4.0]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/1.3.3...1.4.0
 [1.3.3]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/1.3.2...1.3.3
 [1.3.2]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/1.3.1...1.3.2
 [1.3.1]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/1.3.0...1.3.1

{geopic_tag_reader-1.3.3 → geopic_tag_reader-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: geopic-tag-reader
-Version: 1.3.3
+Version: 1.4.0
 Summary: GeoPicTagReader
 Author-email: Adrien PAVIE <panieravide@riseup.net>
 Requires-Python: >=3.8

{geopic_tag_reader-1.3.3 → geopic_tag_reader-1.4.0}/docs/develop.md

@@ -69,6 +69,20 @@ pip install -e .[dev]
 pre-commit install
 ```
 
+### Add camera information
+
+Many fallback information are made available through the `geopic_tag_reader/cameras.csv` file, which is structured this way:
+
+- `make`: name of camera builder (as noted in `Make` EXIF field in picture)
+- `model`: name of camera model (as noted in `Model` EXIF field in picture)
+- `sensor_width`: the width of camera sensor (in millimeters)
+- `is_360`: set to `1` if camera is a 360° device, left empty or set to `0` otherwise
+- `gps_accuracy`: average GPS accuracy (in meters) if the camera has an embed GPS and pictures don't contain GPS horizontal positioning error in their metadata
+
+If a camera is missing in this list, feel free to offer a pull request or send us these information through an issue or an email so we can expand the list.
+
+Also note that more generic information about GPS accuracy from various camera brands is present in `geopic_tag_reader/camera.py` file (`GPS_ACCURACY_MAKE` constant). This allows us to say _"all smartphones from this brand have this GPS accuracy"_, feel free to contact us if we missed some brands.
+
 ## Make a release
 
 ```bash

{geopic_tag_reader-1.3.3 → geopic_tag_reader-1.4.0}/docs/quality_score.md

@@ -58,11 +58,11 @@ This indicator allows to have an idea of how high the picture resolution is, ind
 
 | Grade | Density for 360° | Density for non 360°         |
 | ----- | ---------------- |  --------------------------- |
-| 5/5   | >= 38 px/deg     | Not possible                 |
-| 4/5   | >= 20 px/deg     | >= 60 px/deg                 |
-| 3/5   | >= 15px/deg      | >= 38px/deg                  |
-| 2/5   | < 15px/deg       | >= 15 px/deg                 |
-| 1/5   | Unknown value    | < 15 px/deg or unknown value |
+| 5/5   | >= 30 px/deg     | Not possible                 |
+| 4/5   | >= 15 px/deg     | >= 30 px/deg                 |
+| 3/5   | < 15px/deg       | >= 15px/deg                  |
+| 2/5   | Not possible     | >= 10 px/deg                 |
+| 1/5   | Unknown value    | < 10 px/deg or unknown value |
 
 !!! info
 

{geopic_tag_reader-1.3.3 → geopic_tag_reader-1.4.0}/geopic_tag_reader/__init__.py

@@ -2,4 +2,4 @@
 GeoPicTagReader
 """
 
-__version__ = "1.3.3"
+__version__ = "1.4.0"

geopic_tag_reader-1.4.0/geopic_tag_reader/camera.py

@@ -0,0 +1,148 @@
+from typing import Optional, Dict, List
+import importlib.resources
+import csv
+from dataclasses import dataclass
+
+
+# Per-make GPS estimated accuracy (in meters)
+GPS_ACCURACY_MAKE = {
+    # Diff GPS
+    "stfmani": 2,
+    "trimble": 2,
+    "imajing": 2,
+    # Good GPS
+    "gopro": 4,
+    "insta360": 4,
+    "garmin": 4,
+    "viofo": 4,
+    "xiaoyi": 4,
+    "blackvue": 4,
+    "tectectec": 4,
+    "arashi vision": 4,
+    # Smartphone GPS
+    "samsung": 5,
+    "xiaomi": 5,
+    "huawei": 5,
+    "ricoh": 5,
+    "lenovo": 5,
+    "motorola": 5,
+    "oneplus": 5,
+    "apple": 5,
+    "google": 5,
+    "sony": 5,
+    "wiko": 5,
+    "asus": 5,
+    "cubot": 5,
+    "lge": 5,
+    "fairphone": 5,
+    "realme": 5,
+    "symphony": 5,
+    "crosscall": 5,
+    "htc": 5,
+    "homtom": 5,
+    "hmd global": 5,
+    "oppo": 5,
+    "ulefone": 5,
+}
+
+
+@dataclass
+class CameraMetadata:
+    is_360: bool = False
+    sensor_width: Optional[float] = None
+    gps_accuracy: Optional[float] = None
+
+
+CAMERAS: Dict[str, Dict[str, CameraMetadata]] = {}  # Make -> Model -> Metadata
+
+
+def get_cameras() -> Dict[str, Dict[str, CameraMetadata]]:
+    """
+    Retrieve general metadata about cameras
+    """
+
+    if len(CAMERAS) > 0:
+        return CAMERAS
+
+    # Cameras.csv file is a composite of various sources:
+    #  - Wikipedia's list of 360° cameras ( https://en.wikipedia.org/wiki/List_of_omnidirectional_(360-degree)_cameras )
+    #  - OpenSfM's sensor widths ( https://github.com/mapillary/OpenSfM/blob/main/opensfm/data/sensor_data.json )
+
+    with importlib.resources.open_text("geopic_tag_reader", "cameras.csv") as camerasCsv:
+        camerasReader = csv.DictReader(camerasCsv, delimiter=";")
+        for camera in camerasReader:
+            make = camera["make"].lower()
+            model = camera["model"].lower()
+            sensorWidth = float(camera["sensor_width"]) if camera["sensor_width"] != "" else None
+            is360 = camera["is_360"] == "1"
+            gpsAccuracy = float(camera["gps_accuracy"]) if camera["gps_accuracy"] != "" else None
+
+            # Override GPS Accuracy with Make one if necessary
+            if gpsAccuracy is None and make in GPS_ACCURACY_MAKE:
+                gpsAccuracy = GPS_ACCURACY_MAKE[make]
+
+            # Append to general list
+            if not make in CAMERAS:
+                CAMERAS[make] = {}
+
+            CAMERAS[make][model] = CameraMetadata(is360, sensorWidth, gpsAccuracy)
+
+        return CAMERAS
+
+
+def find_camera(make: Optional[str] = None, model: Optional[str] = None) -> Optional[CameraMetadata]:
+    """
+    Finds camera metadata based on make and model.
+
+    >>> find_camera()
+
+    >>> find_camera("GoPro")
+
+    >>> find_camera("GoPro", "Max")
+    CameraMetadata(is_360=True, sensor_width=6.17, gps_accuracy=4)
+    >>> find_camera("GoPro", "Max 360")
+    CameraMetadata(is_360=True, sensor_width=6.17, gps_accuracy=4)
+    """
+
+    # Check make and model are defined
+    if not make or not model:
+        return None
+
+    # Find make
+    cameras = get_cameras()
+    matchMake = next((m for m in cameras.keys() if m in make.lower()), None)
+    if matchMake is None:
+        return None
+
+    # Find model
+    return next((cameras[matchMake][matchModel] for matchModel in cameras[matchMake].keys() if model.lower().startswith(matchModel)), None)
+
+
+def is_360(make: Optional[str] = None, model: Optional[str] = None, width: Optional[str] = None, height: Optional[str] = None) -> bool:
+    """
+    Checks if given camera is equirectangular (360°) based on its make, model and dimensions (width, height).
+
+    >>> is_360()
+    False
+    >>> is_360("GoPro")
+    False
+    >>> is_360("GoPro", "Max 360")
+    True
+    >>> is_360("GoPro", "Max 360", "2048", "1024")
+    True
+    >>> is_360("GoPro", "Max 360", "1024", "768")
+    False
+    >>> is_360("RICOH", "THETA S", "5376", "2688")
+    True
+    """
+
+    # Check make and model are defined
+    camera = find_camera(make, model)
+    if not camera:
+        return False
+
+    # Check width and height are equirectangular
+    if not ((width is None or height is None) or int(width) == 2 * int(height)):
+        return False
+
+    return camera.is_360