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

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

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- Update some dependencies and especially pyexiv2 that is now compatible with python 3.13
+
 ## [1.3.1] - 2024-10-09
 
 ### Changed
@@ -231,7 +244,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.1...main
+[Unreleased]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/1.3.3...main
+[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
 [1.2.0]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/1.1.5...1.2.0

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

@@ -1,29 +1,29 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: geopic-tag-reader
-Version: 1.3.1
+Version: 1.3.3
 Summary: GeoPicTagReader
 Author-email: Adrien PAVIE <panieravide@riseup.net>
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 Classifier: License :: OSI Approved :: MIT License
 Requires-Dist: typer ~= 0.12
-Requires-Dist: xmltodict ~= 0.13
-Requires-Dist: pyexiv2 == 2.15.0
-Requires-Dist: timezonefinder == 6.2.0
-Requires-Dist: pytz ~= 2023.3
+Requires-Dist: xmltodict ~= 0.14
+Requires-Dist: pyexiv2 == 2.15.3
+Requires-Dist: timezonefinder == 6.5.3
+Requires-Dist: pytz ~= 2024.2
 Requires-Dist: types-pytz ~= 2023.3.0.1
 Requires-Dist: types-python-dateutil ~= 2.9.0
 Requires-Dist: flit ~= 3.8.0 ; extra == "build"
 Requires-Dist: black ~= 24.3 ; extra == "dev"
-Requires-Dist: mypy ~= 1.9 ; extra == "dev"
+Requires-Dist: mypy ~= 1.12 ; extra == "dev"
 Requires-Dist: pytest ~= 7.2.0 ; extra == "dev"
 Requires-Dist: pytest-datafiles ~= 3.0 ; extra == "dev"
-Requires-Dist: types-xmltodict ~= 0.13 ; extra == "dev"
+Requires-Dist: types-xmltodict ~= 0.14 ; extra == "dev"
 Requires-Dist: pre-commit ~= 3.3.3 ; extra == "dev"
 Requires-Dist: mkdocs-material ~= 9.5.21 ; extra == "docs"
 Requires-Dist: mkdocstrings[python] ~= 0.25.1 ; extra == "docs"
-Requires-Dist: python-dateutil ~= 2.8.2 ; extra == "write-exif"
-Requires-Dist: types-python-dateutil ~= 2.9.0.20240316 ; extra == "write-exif"
+Requires-Dist: python-dateutil ~= 2.9.0 ; extra == "write-exif"
+Requires-Dist: types-python-dateutil ~= 2.9.0.20241003 ; extra == "write-exif"
 Project-URL: Home, https://gitlab.com/panoramax/server/geo-picture-tag-reader
 Provides-Extra: build
 Provides-Extra: dev

{geopic_tag_reader-1.3.1 → geopic_tag_reader-1.3.3}/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.3.3/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   | >= 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 |
+
+!!! 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.1 → geopic_tag_reader-1.3.3}/geopic_tag_reader/__init__.py

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

{geopic_tag_reader-1.3.1 → geopic_tag_reader-1.3.3}/geopic_tag_reader/reader.py

@@ -274,6 +274,9 @@ def readPictureMetadata(picture: bytes, lang_code: str = "en") -> GeoPicTags:
     elif "MAPCompassHeading" in data and isExifTagUsable(data["MAPCompassHeading"], "TrueHeading", float):
         heading = int(round(float(data["MAPCompassHeading"]["TrueHeading"])))
 
+    if heading is None:
+        warnings.append(_("No heading value was found, this reduces usability of picture"))
+
     # Yaw / Pitch / roll
     yaw = None
     pitch = None
@@ -314,12 +317,17 @@ def readPictureMetadata(picture: bytes, lang_code: str = "en") -> GeoPicTags:
     if make is not None and model is not None and model.startswith(make) and len(model) > len(make):
         model = model.replace(make, "").strip()
 
+    if make is None and model is None:
+        warnings.append(_("No make and model value found, no assumption on focal length or GPS precision can be made"))
+
     # Focal length
     focalLength = None
     if isExifTagUsable(data, "Exif.Image.FocalLength", Fraction):
         focalLength = float(Fraction(data["Exif.Image.FocalLength"]))
     elif isExifTagUsable(data, "Exif.Photo.FocalLength", Fraction):
         focalLength = float(Fraction(data["Exif.Photo.FocalLength"]))
+    if focalLength is None:
+        warnings.append(_("No focal length value was found, this prevents calculating field of view"))
 
     # Cropped pano data
     crop = None
@@ -368,9 +376,23 @@ def readPictureMetadata(picture: bytes, lang_code: str = "en") -> GeoPicTags:
         ref = -1 if data.get("Exif.GPSInfo.GPSAltitudeRef") == "1" else 1
         altitude = altitude_raw * ref
 
+    # GPS accuracy (only for warning display)
+    gpshpos = isExifTagUsable(data, "Exif.GPSInfo.GPSHPositioningError", float) or isExifTagUsable(
+        data, "Xmp.exif.GPSHPositioningError", float
+    )
+    gpsdop = isExifTagUsable(data, "Exif.GPSInfo.GPSDOP", float) or isExifTagUsable(data, "Xmp.exif.GPSDOP", float)
+    gpsdiff = isExifTagUsable(data, "Exif.GPSInfo.GPSDifferential", int) or isExifTagUsable(data, "Xmp.exif.GPSDifferential", int)
+
+    if not gpshpos:
+        if not gpsdop and not gpsdiff:
+            warnings.append(_("No GPS accuracy value found, this prevents computing a quality score"))
+        else:
+            warnings.append(_("No GPS horizontal positioning error value found, GPS accuracy can only be estimated"))
+
     errors = []
     missing_fields = set()
-    if not lat or not lon:
+    if lat is None or lon is None or (lat == 0 and lon == 0):
+        # Note: we consider that null island is not a valid position
         errors.append(_("No GPS coordinates or broken coordinates in picture EXIF tags"))
         if not lat:
             missing_fields.add("lat")
@@ -411,7 +433,7 @@ def readPictureMetadata(picture: bytes, lang_code: str = "en") -> GeoPicTags:
             ),
         )
 
-    assert lon and lat and d  # at this point all those fields cannot be null
+    assert lon is not None and lat is not None and d is not None  # at this point all those fields cannot be null
     return GeoPicTags(
         lat,
         lon,

{geopic_tag_reader-1.3.1 → geopic_tag_reader-1.3.3}/geopic_tag_reader/translations/de/LC_MESSAGES/geopic_tag_reader.po

@@ -8,7 +8,7 @@ msgstr ""
 "Project-Id-Version: PACKAGE VERSION\n"
 "Report-Msgid-Bugs-To: \n"
 "POT-Creation-Date: 2024-07-10 13:05+0200\n"
-"PO-Revision-Date: 2024-08-07 13:42+0000\n"
+"PO-Revision-Date: 2024-11-23 22:10+0000\n"
 "Last-Translator: Bastian Greshake Tzovaras <bastian@gedankenstuecke.de>\n"
 "Language-Team: German <http://weblate.panoramax.xyz/projects/panoramax/"
 "tag-reader/de/>\n"
@@ -167,3 +167,46 @@ msgstr "Nicht unterstützter Schlüssel in den zusätzlichen Attributen ({k})"
 #: geopic_tag_reader/main.py:37
 msgid "Yaw:"
 msgstr "Gierwinkel:"
+
+#: geopic_tag_reader/main.py:30
+msgid "(GPS)"
+msgstr "(GPS)"
+
+#: geopic_tag_reader/main.py:31
+msgid "(Camera)"
+msgstr "(Kamera)"
+
+#: geopic_tag_reader/main.py:30 geopic_tag_reader/main.py:31
+msgid "not set"
+msgstr "nicht gesetzt"
+
+#: geopic_tag_reader/reader.py:330
+msgid ""
+"No focal length value was found, this prevents calculating field of view"
+msgstr "Keine Brennweite gefunden, dies verhindert den Blickwinkel zu berechnen"
+
+#: geopic_tag_reader/reader.py:388
+msgid ""
+"No GPS horizontal positioning error value found, GPS accuracy can only be "
+"estimated"
+msgstr ""
+"Kein horizontaler GPS-Positionierungsfehlerwert gefunden, GPS-Genauigkeit "
+"kann nur geschätzt werden"
+
+#: geopic_tag_reader/reader.py:278
+msgid "No heading value was found, this reduces usability of picture"
+msgstr "Kein Kompasskurs gefunden, dies reduziert die Nutzbarkeit des Fotos"
+
+#: geopic_tag_reader/reader.py:386
+msgid "No GPS accuracy value found, this prevents computing a quality score"
+msgstr ""
+"Keine GPS-Genauigkeit gefunden, dies verhindert das Berechnen eines "
+"Qualitätswerts"
+
+#: geopic_tag_reader/reader.py:321
+msgid ""
+"No make and model value found, no assumption on focal length or GPS "
+"precision can be made"
+msgstr ""
+"Kein Hersteller und Modell gefunden, keine Annahmen zu Brennweite oder GPS-"
+"Genauigkeit können angestellt werden"

{geopic_tag_reader-1.3.1 → geopic_tag_reader-1.3.3}/geopic_tag_reader/translations/en/LC_MESSAGES/geopic_tag_reader.po

@@ -7,8 +7,8 @@ msgid ""
 msgstr ""
 "Project-Id-Version: PACKAGE VERSION\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2024-10-09 10:49+0200\n"
-"PO-Revision-Date: 2024-10-09 10:49+0200\n"
+"POT-Creation-Date: 2024-11-24 15:36+0100\n"
+"PO-Revision-Date: 2024-11-24 15:36+0100\n"
 "Last-Translator: Automatically generated\n"
 "Language-Team: none\n"
 "Language: en\n"
@@ -94,35 +94,65 @@ msgstr "Read longitude is out of WGS84 bounds (should be in [-180, 180])"
 msgid "Skipping Mapillary date/time as it was not recognized: {v}"
 msgstr "Skipping Mapillary date/time as it was not recognized: {v}"
 
-#: geopic_tag_reader/reader.py:374
+#: geopic_tag_reader/reader.py:278
+msgid "No heading value was found, this reduces usability of picture"
+msgstr "No heading value was found, this reduces usability of picture"
+
+#: geopic_tag_reader/reader.py:321
+msgid ""
+"No make and model value found, no assumption on focal length or GPS "
+"precision can be made"
+msgstr ""
+"No make and model value found, no assumption on focal length or GPS "
+"precision can be made"
+
+#: geopic_tag_reader/reader.py:330
+msgid ""
+"No focal length value was found, this prevents calculating field of view"
+msgstr ""
+"No focal length value was found, this prevents calculating field of view"
+
+#: geopic_tag_reader/reader.py:388
+msgid "No GPS accuracy value found, this prevents computing a quality score"
+msgstr "No GPS accuracy value found, this prevents computing a quality score"
+
+#: geopic_tag_reader/reader.py:390
+msgid ""
+"No GPS horizontal positioning error value found, GPS accuracy can only be "
+"estimated"
+msgstr ""
+"No GPS horizontal positioning error value found, GPS accuracy can only be "
+"estimated"
+
+#: geopic_tag_reader/reader.py:396
 msgid "No GPS coordinates or broken coordinates in picture EXIF tags"
 msgstr "No GPS coordinates or broken coordinates in picture EXIF tags"
 
-#: geopic_tag_reader/reader.py:380
+#: geopic_tag_reader/reader.py:402
 msgid "No valid date in picture EXIF tags"
 msgstr "No valid date in picture EXIF tags"
 
-#: geopic_tag_reader/reader.py:385
+#: geopic_tag_reader/reader.py:407
 msgid "The picture is missing mandatory metadata:"
 msgstr "The picture is missing mandatory metadata:"
 
-#: geopic_tag_reader/reader.py:476 geopic_tag_reader/reader.py:505
+#: geopic_tag_reader/reader.py:498 geopic_tag_reader/reader.py:527
 msgid "GPSLatitudeRef not found, assuming GPSLatitudeRef is North"
 msgstr "GPSLatitudeRef not found, assuming GPSLatitudeRef is North"
 
-#: geopic_tag_reader/reader.py:484
+#: geopic_tag_reader/reader.py:506
 msgid "Broken GPS coordinates in picture EXIF tags"
 msgstr "Broken GPS coordinates in picture EXIF tags"
 
-#: geopic_tag_reader/reader.py:487 geopic_tag_reader/reader.py:511
+#: geopic_tag_reader/reader.py:509 geopic_tag_reader/reader.py:533
 msgid "GPSLongitudeRef not found, assuming GPSLongitudeRef is East"
 msgstr "GPSLongitudeRef not found, assuming GPSLongitudeRef is East"
 
-#: geopic_tag_reader/reader.py:572
+#: geopic_tag_reader/reader.py:594
 msgid "Precise timezone information not found, fallback to UTC"
 msgstr "Precise timezone information not found, fallback to UTC"
 
-#: geopic_tag_reader/reader.py:577
+#: geopic_tag_reader/reader.py:599
 msgid ""
 "Precise timezone information not found (and no GPS coordinates to help), "
 "fallback to UTC"
@@ -130,14 +160,14 @@ msgstr ""
 "Precise timezone information not found (and no GPS coordinates to help), "
 "fallback to UTC"
 
-#: geopic_tag_reader/reader.py:581
+#: geopic_tag_reader/reader.py:603
 #, python-brace-format
 msgid ""
 "Skipping original date/time (from {datefield}) as it was not recognized: {v}"
 msgstr ""
 "Skipping original date/time (from {datefield}) as it was not recognized: {v}"
 
-#: geopic_tag_reader/reader.py:613
+#: geopic_tag_reader/reader.py:635
 #, python-brace-format
 msgid ""
 "GPSTimeStamp and GPSDateTime don't contain supported time format (in {group} "
@@ -146,12 +176,12 @@ msgstr ""
 "GPSTimeStamp and GPSDateTime don't contain supported time format (in {group} "
 "group)"
 
-#: geopic_tag_reader/reader.py:644
+#: geopic_tag_reader/reader.py:666
 #, python-brace-format
 msgid "Skipping GPS date/time ({group} group) as it was not recognized: {v}"
 msgstr "Skipping GPS date/time ({group} group) as it was not recognized: {v}"
 
-#: geopic_tag_reader/reader.py:670
+#: geopic_tag_reader/reader.py:692
 #, python-brace-format
 msgid ""
 "Microseconds read from decimal seconds value ({microsecondsFromSeconds}) is "