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

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

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.4.1] - 2025-02-03
+
+### Added
+
+- Field of view is also computed based on focal length and its equivalent in 35mm format (based on ExifTool formula).
+
+### Fixed
+
+- GPS horizontal precision and dilution of precision are also read from fraction values.
+
+## [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 +261,9 @@ 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.1...main
+[1.4.1]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/1.4.0...1.4.1
+[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.1}/PKG-INFO

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

{geopic_tag_reader-1.3.3 → geopic_tag_reader-1.4.1}/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.1}/docs/index.md

@@ -74,10 +74,12 @@ Camera model is read from:
 
 #### Focal length
 
-Camera focal length (to get precise field of view) is read from:
+Camera focal length (basic and 35mm-equivalent, to get precise field of view) is read from:
 
 - `Exif.Image.FocalLength`
 - `Exif.Photo.FocalLength`
+- `Exif.Image.FocalLengthIn35mmFilm`
+- `Exif.Photo.FocalLengthIn35mmFilm`
 
 #### :octicons-horizontal-rule-16: Yaw, Pitch and Roll
 

{geopic_tag_reader-1.3.3 → geopic_tag_reader-1.4.1}/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
 
@@ -71,6 +71,7 @@ This indicator allows to have an idea of how high the picture resolution is, ind
 The value is computed from picture width in pixels, and some EXIF metadata. We rely on the following tags:
 
 - __Focal length__ (`Exif.Image.FocalLength` or `Exif.Photo.FocalLength`): distance in millimeters between the nodal point of the lens and the camera sensor.
+- __Focal length (35mm equivalent)__ (`Exif.Image.FocalLengthIn35mmFilm` or `Exif.Photo.FocalLengthIn35mmFilm`): same as focal length, but in 35mm film equivalent.
 - __Make and model__ (`Exif.Image.Make` and `Exif.Image.Make`): camera model, which is used to find camera sensor width.
 - __Projection type__ (for 360° pictures, `Xmp.GPano.ProjectionType`): to mark a picture as 360°
 

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

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

geopic_tag_reader-1.4.1/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