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

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

@@ -7,6 +7,20 @@ 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
+
+- Warnings are shown if any useful metadata is missing for computing a quality score (make, model, GPS accuracy...).
+- New languages : 🇵🇱, 🇳🇱, 🇭🇺, 🇪🇸, 🇩🇪 (thanks to all translators !)
+
 ## [1.3.2] - 2024-10-22
 
 ### Changed
@@ -237,7 +251,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.2...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
 [1.3.0]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/1.2.0...1.3.0

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

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

{geopic_tag_reader-1.3.2 → 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.2 → geopic_tag_reader-1.4.0}/docs/index.md

@@ -54,7 +54,7 @@ Image orientation is read from
 
 #### :material-timer: Milliseconds in date
 
-Milliseconds in date is reade from `SubSecTimeOriginal`.
+Milliseconds in date is read from `SubSecTimeOriginal`.
 
 #### :material-panorama-sphere-outline: 360° or flat
 

geopic_tag_reader-1.4.0/docs/quality_score.md

@@ -0,0 +1,84 @@
+# :white_check_mark: Quality score
+
+Panoramax offers a _Quality Score_ for each picture in its web viewer. It allows easy map filtering and comprehensive display of high-quality pictures availability.
+
+The grade is shown to users as a A/B/C/D/E score (A is the best, E the worst), and shown graphically through this scale (inspired by [Nutri-Score](https://en.wikipedia.org/wiki/Nutri-Score)):
+
+![Quality score graphics](./images/quality_score.png)
+
+## :material-calculator: Score computation
+
+Quality score is based on two indicators:
+
+- :material-crosshairs-gps: __GPS position accuracy__: how precisely the GPS coordinates are set, in meters. This is 1/5 of the score.
+- :material-camera-iris: __Horizontal pixel density__: how many pixels we have on horizon per _field of view_ degree. This is 4/5 of the score.
+
+They are displayed through web viewer in picture metadata popup:
+
+![Metadata popup and score display](./images/quality_score_viewer.png)
+
+!!! info
+
+	We know that this is a pretty simple indicator. Many other information could be taken into account (blurriness, light...) and may be used in the future. We started with something simple to make the _quality score_ available on as many pictures as possible. You can [come and help us](https://docs.panoramax.fr/how-to-contribute/#contribute-to-the-development) to make this happen sooner :grinning:
+
+### :material-crosshairs-gps: GPS position accuracy
+
+This indicator allows to know if we can rely or not on GPS position, based on its precision. It is expressed as a decimal value in meters. The grade is a 5-star rating, and is applied based on these values:
+
+| GPS Accuracy      | Grade |
+| ----------------- | ----- |
+| <= 1 m            |  5/5  |
+| <= 2 m            |  4/5  |
+| <= 5 m            |  3/5  |
+| <= 10 m           |  2/5  |
+| > 10 m or unknown |  1/5  |
+
+The value is read from picture EXIF metadata. We rely on the following tags:
+
+- __Horizontal positioning error__ (`Exif.GPSInfo.GPSHPositioningError` or `Xmp.exif.GPSHPositioningError`) : expected positioning error in meters.
+- __Dilution of precision__ (`Exif.GPSInfo.GPSDOP` or `Xmp.exif.GPSDOP`) : indicator of expected precision on coordinates (<= 1 means good precision for the sensor, >= 5 is not good, [more info on Wikipedia](https://en.wikipedia.org/wiki/Dilution_of_precision_(navigation))).
+- __Is the GPS differential__ (`Exif.GPSInfo.GPSDifferential` or `Xmp.exif.GPSDifferential`) : indicates if GPS sensor is using [Differential GPS](https://en.wikipedia.org/wiki/Differential_GPS) or not. If yes, we expect a better precision.
+
+These are used to define a precision value in meters. If none of these tags are set, we also rely on a default value for several camera vendors (based on `Make` and `Model` EXIF tags).
+
+So, to get a good grade on GPS precision, you can (in order):
+
+- Set a precise _Horizontal positioning error_
+- Set a value for _Differential GPS_ and/or _Dilution of precision_
+- Set values for _Make_ and _Model_ if you use a common camera
+
+
+!!! info
+
+	If you find the shown value not reflecting the real precision of your GPS sensor, feel free to contact us with an example link. We tried to make precision estimates on a large set of cameras, but we may have missed some :material-map-search:
+
+### :material-camera-iris: Horizontal pixel density
+
+This indicator allows to have an idea of how high the picture resolution is, independently of its field of view (360° or classic picture). The formula is: `picture width in pixels / field of view in degrees`. We have in result a number of pixels per FOV degree. The grade is a 5-star rating, and is applied based on these values:
+
+| Grade | Density for 360° | Density for non 360°         |
+| ----- | ---------------- |  --------------------------- |
+| 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
+
+	A different rating is applied for 360°, as they offer a nicer user experience on web viewer. Note that if you're a technical reuser, the API offers raw values for each indicator, allowing you to do your own custom rating.
+
+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.
+- __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°
+
+Based on these information, we are able to compute the _field of view_ (how wide the camera can look horizontally).
+
+As these information are hard to deduce, you may carefully set all of them in EXIF metadata.
+
+!!! info
+
+	If you have pictures with an unknown value for this grade, it's probably because we miss information on your camera model. Make sure your pictures have required information, and contact us with the camera _sensor width_ so we can add it in our listing.
+

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

@@ -2,4 +2,4 @@
 GeoPicTagReader
 """
 
-__version__ = "1.3.2"
+__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