geopic-tag-reader 1.1.1__tar.gz → 1.1.3__tar.gz

{geopic_tag_reader-1.1.1 → geopic_tag_reader-1.1.3}/.gitignore

@@ -5,3 +5,5 @@ env/
 venv
 .cache/
 .vscode/
+site/
+*.mo

{geopic_tag_reader-1.1.1 → geopic_tag_reader-1.1.3}/.gitlab-ci.yml

@@ -25,23 +25,26 @@ lint:
 tests-reader:
   image: python:3.8
   script:
-    - apt update && apt install gcc
+    - apt update && apt install gcc gettext
     - pip install .[dev]
+    - make i18n-po2code
     - pytest -s -vv --ignore=tests/test_writer.py --ignore=geopic_tag_reader/writer.py
 
 tests-writer:
   image: python:3.8
   script:
-    - apt update && apt install gcc
+    - apt update && apt install gcc gettext
     - pip install .[dev,write-exif]
+    - make i18n-po2code
     - pytest -s -vv
 
 deploy_pypi:
   stage: deploy
   image: python:3.8
   script:
-    - apt update && apt install gcc git
+    - apt update && apt install -y gcc git gettext
     - pip install .[build]
+    - make i18n-po2code
     - flit publish # use [flit](https://flit.pypa.io/) and FLIT_USERNAME/FLIT_PASSWORD env var
   only:
     - tags

{geopic_tag_reader-1.1.1 → geopic_tag_reader-1.1.3}/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.3] - 2024-07-10
+
+### Changed
+
+- Translations are handled per function call, language code passed as parameter for reader and writer.
+
+## [1.1.2] - 2024-06-25
+
+### Added
+
+- Support of translations for warning/error messages.
+
+### Changed
+
+- Update docs to match organization rename on Gitlab from GeoVisio to Panoramax
+- Test for 360° pictures recognition based on make & model handles different string cases
+
 ## [1.1.1] - 2024-04-26
 
 ### Added
@@ -120,7 +137,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- Bump [Typer](typer.tiangolo.com/) version, and use fork of [Typer-cli](https://gitlab.com/geovisio/infra/typer-cli)
+- Bump [Typer](typer.tiangolo.com/) version, and use fork of [Typer-cli](https://gitlab.com/panoramax/server/infra/typer-cli)
 
 ## [0.1.2]
 
@@ -164,26 +181,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- EXIF tag reading methods extracted from [GeoVisio API](https://gitlab.com/geovisio/api)
-
-[Unreleased]: https://gitlab.com/geovisio/geo-picture-tag-reader/-/compare/1.1.1...main
-[1.1.1]: https://gitlab.com/geovisio/geo-picture-tag-reader/-/compare/1.1.0...1.1.1
-[1.1.0]: https://gitlab.com/geovisio/geo-picture-tag-reader/-/compare/1.0.6...1.1.0
-[1.0.6]: https://gitlab.com/geovisio/geo-picture-tag-reader/-/compare/1.0.5...1.0.6
-[1.0.5]: https://gitlab.com/geovisio/geo-picture-tag-reader/-/compare/1.0.4...1.0.5
-[1.0.4]: https://gitlab.com/geovisio/geo-picture-tag-reader/-/compare/1.0.3...1.0.4
-[1.0.3]: https://gitlab.com/geovisio/geo-picture-tag-reader/-/compare/1.0.2...1.0.3
-[1.0.2]: https://gitlab.com/geovisio/geo-picture-tag-reader/-/compare/1.0.1...1.0.2
-[1.0.1]: https://gitlab.com/geovisio/geo-picture-tag-reader/-/compare/1.0.0...1.0.1
-[1.0.0]: https://gitlab.com/geovisio/geo-picture-tag-reader/-/compare/0.4.1...1.0.0
-[0.4.1]: https://gitlab.com/geovisio/geo-picture-tag-reader/-/compare/0.4.0...0.4.1
-[0.4.0]: https://gitlab.com/geovisio/geo-picture-tag-reader/-/compare/0.3.1...0.4.0
-[0.3.1]: https://gitlab.com/geovisio/geo-picture-tag-reader/-/compare/0.3.0...0.3.1
-[0.3.0]: https://gitlab.com/geovisio/geo-picture-tag-reader/-/compare/0.2.0...0.3.0
-[0.2.0]: https://gitlab.com/geovisio/geo-picture-tag-reader/-/compare/0.1.3...0.2.0
-[0.1.3]: https://gitlab.com/geovisio/geo-picture-tag-reader/-/compare/0.1.2...0.1.3
-[0.1.2]: https://gitlab.com/geovisio/geo-picture-tag-reader/-/compare/0.1.1...0.1.2
-[0.1.1]: https://gitlab.com/geovisio/geo-picture-tag-reader/-/compare/0.1.0...0.1.1
-[0.1.0]: https://gitlab.com/geovisio/geo-picture-tag-reader/-/compare/0.0.2...0.1.0
-[0.0.2]: https://gitlab.com/geovisio/geo-picture-tag-reader/-/compare/0.0.1...0.0.2
-[0.0.1]: https://gitlab.com/geovisio/geo-picture-tag-reader/-/commits/0.0.1
+- EXIF tag reading methods extracted from [GeoVisio API](https://gitlab.com/panoramax/server/api)
+
+[Unreleased]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/1.1.3...main
+[1.1.3]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/1.1.2...1.1.3
+[1.1.2]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/1.1.1...1.1.2
+[1.1.1]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/1.1.0...1.1.1
+[1.1.0]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/1.0.6...1.1.0
+[1.0.6]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/1.0.5...1.0.6
+[1.0.5]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/1.0.4...1.0.5
+[1.0.4]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/1.0.3...1.0.4
+[1.0.3]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/1.0.2...1.0.3
+[1.0.2]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/1.0.1...1.0.2
+[1.0.1]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/1.0.0...1.0.1
+[1.0.0]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/0.4.1...1.0.0
+[0.4.1]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/0.4.0...0.4.1
+[0.4.0]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/0.3.1...0.4.0
+[0.3.1]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/0.3.0...0.3.1
+[0.3.0]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/0.2.0...0.3.0
+[0.2.0]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/0.1.3...0.2.0
+[0.1.3]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/0.1.2...0.1.3
+[0.1.2]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/0.1.1...0.1.2
+[0.1.1]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/0.1.0...0.1.1
+[0.1.0]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/0.0.2...0.1.0
+[0.0.2]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/compare/0.0.1...0.0.2
+[0.0.1]: https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/commits/0.0.1

geopic_tag_reader-1.1.3/Makefile

@@ -0,0 +1,37 @@
+.DEFAULT_GOAL := help
+
+.PHONY: docs test type-check fmt ci
+
+prepare_release: i18n-code2pot i18n-po2code docs ci
+
+test: ## Run tests
+	pytest
+
+type-check: ## Check all python types
+	mypy geopic_tag_reader/
+
+fmt: ## Format code
+	black --fast .
+
+ci: type-check fmt test ## Run all check like the ci
+
+docs:  ## Generates documentation from Typer embedded docs
+	python -m typer ./geopic_tag_reader/main.py utils docs --name geopic-tag-reader --output docs/tech/cli.md
+
+help: ## Print this help message
+	@grep -E '^[a-zA-Z_-]+:.*## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
+
+#############################
+# Internationalization
+#
+
+# Extract labels from Python code into POT catalog
+i18n-code2pot:
+	xgettext -d geopic_tag_reader -o geopic_tag_reader/translations/geopic_tag_reader.pot geopic_tag_reader/*.py
+
+# Transform all PO translated files into MO for Python to use them
+SOURCES=$(wildcard geopic_tag_reader/translations/**/LC_MESSAGES/*.po)
+TARGETS=$(SOURCES:.po=.mo)
+i18n-po2code: $(TARGETS)
+%.mo: %.po
+	msgfmt $< -o $@

{geopic_tag_reader-1.1.1 → geopic_tag_reader-1.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: geopic-tag-reader
-Version: 1.1.1
+Version: 1.1.3
 Summary: GeoPicTagReader
 Author-email: Adrien PAVIE <panieravide@riseup.net>
 Requires-Python: >=3.8
@@ -17,39 +17,26 @@ Requires-Dist: black ~= 24.3 ; extra == "dev"
 Requires-Dist: mypy ~= 1.9 ; extra == "dev"
 Requires-Dist: pytest ~= 7.2.0 ; extra == "dev"
 Requires-Dist: pytest-datafiles ~= 3.0 ; extra == "dev"
-Requires-Dist: lazydocs ~= 0.4.8 ; extra == "dev"
 Requires-Dist: types-xmltodict ~= 0.13 ; 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"
-Project-URL: Home, https://gitlab.com/geovisio/geo-picture-tag-reader
+Requires-Dist: types-python-dateutil ~= 2.9.0.20240316 ; extra == "write-exif"
+Project-URL: Home, https://gitlab.com/panoramax/server/geo-picture-tag-reader
 Provides-Extra: build
 Provides-Extra: dev
+Provides-Extra: docs
 Provides-Extra: write-exif
 
-# ![GeoVisio](https://gitlab.com/geovisio/api/-/raw/develop/images/logo_full.png)
+# ![Panoramax](https://upload.wikimedia.org/wikipedia/commons/thumb/a/a9/Panoramax.svg/40px-Panoramax.svg.png) Panoramax
 
-__GeoVisio__ is a complete solution for storing and __serving your own 📍📷 geolocated pictures__ (like [StreetView](https://www.google.com/streetview/) / [Mapillary](https://mapillary.com/)).
-
-➡️ __Give it a try__ at [panoramax.ign.fr](https://panoramax.ign.fr/) or [geovisio.fr](https://geovisio.fr/viewer) !
-
-## 📦 Components
-
-GeoVisio is __modular__ and made of several components, each of them standardized and ♻️ replaceable.
-
-![GeoVisio architecture](https://gitlab.com/geovisio/api/-/raw/develop/images/big_picture.png)
-
-All of them are 📖 __open-source__ and available online:
-
-|                               🌐 Server                                 |                      💻 Client                       |
-|:-----------------------------------------------------------------------:|:----------------------------------------------------:|
-|                 [API](https://gitlab.com/geovisio/api)                  |    [Website](https://gitlab.com/geovisio/website)    |
-|            [Blur API](https://gitlab.com/geovisio/blurring)             | [Web viewer](https://gitlab.com/geovisio/web-viewer) |
-| [GeoPic Tag Reader](https://gitlab.com/geovisio/geo-picture-tag-reader) |   [Command line](https://gitlab.com/geovisio/cli)    |
+__Panoramax__ is a digital resource for sharing and exploiting 📍📷 field photos. Anyone can take photographs of places visible from the public streets and contribute them to the Panoramax database. This data is then freely accessible and reusable by all. More information available at [gitlab.com/panoramax](https://gitlab.com/panoramax) and [panoramax.fr](https://panoramax.fr/).
 
 
 # 📷 GeoPic Tag Reader
 
-This repository only contains the Python library to __read and write standardized metadata__ from geolocated pictures EXIF metadata.
+This repository only contains the Python library to __read and write standardized metadata__ from geolocated pictures EXIF metadata. It can be used completely apart from all GeoVisio/Panoramax components for your own projects and needs.
 
 ## Features
 
@@ -71,7 +58,7 @@ geopic-tag-reader --help
 
 To know more about install and other options, see [install documentation](./docs/Install.md).
 
-If at some point you're lost or need help, you can contact us through [issues](https://gitlab.com/geovisio/geo-picture-tag-reader/-/issues) or by [email](mailto:panieravide@riseup.net).
+If at some point you're lost or need help, you can contact us through [issues](https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/issues) or by [email](mailto:panieravide@riseup.net).
 
 
 ## Usage
@@ -137,26 +124,12 @@ editedImg.close()
 
 ## Contributing
 
-Pull requests are welcome. For major changes, please open an [issue](https://gitlab.com/geovisio/geo-picture-tag-reader/-/issues) first to discuss what you would like to change.
+Pull requests are welcome. For major changes, please open an [issue](https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/issues) first to discuss what you would like to change.
 
 More information about developing is available in [documentation](./docs/Develop.md).
 
 
-## 🤗 Special thanks
-
-![Sponsors](https://gitlab.com/geovisio/api/-/raw/develop/images/sponsors.png)
-
-GeoVisio was made possible thanks to a group of ✨ __amazing__ people ✨ :
-
-- __[GéoVélo](https://geovelo.fr/)__ team, for 💶 funding initial development and for 🔍 testing/improving software
-- __[Carto Cité](https://cartocite.fr/)__ team (in particular Antoine Riche), for 💶 funding improvements on viewer (map browser, flat pictures support)
-- __[La Fabrique des Géocommuns (IGN)](https://www.ign.fr/institut/la-fabrique-des-geocommuns-incubateur-de-communs-lign)__ for offering long-term support and funding the [Panoramax](https://panoramax.fr/) initiative and core team (Camille Salou, Mathilde Ferrey, Christian Quest, Antoine Desbordes, Jean Andreani, Adrien Pavie)
-- Many _many_ __wonderful people__ who worked on various parts of GeoVisio or core dependencies we use : 🧙 Stéphane Péneau, 🎚 Albin Calais & Cyrille Giquello, 📷 [Damien Sorel](https://www.strangeplanet.fr/), Pascal Rhod, Nick Whitelegg...
-- __[Adrien Pavie](https://pavie.info/)__, for ⚙️ initial development of GeoVisio
-- And you all ✨ __GeoVisio users__ for making this project useful !
-
-
 ## ⚖️ License
 
-Copyright (c) GeoVisio team 2022-2023, [released under MIT license](https://gitlab.com/geovisio/geo-picture-tag-reader/-/blob/main/LICENSE).
+Copyright (c) Panoramax team 2022-2024, [released under MIT license](https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/blob/main/LICENSE).
 

geopic_tag_reader-1.1.3/README.md

@@ -0,0 +1,103 @@
+# ![Panoramax](https://upload.wikimedia.org/wikipedia/commons/thumb/a/a9/Panoramax.svg/40px-Panoramax.svg.png) Panoramax
+
+__Panoramax__ is a digital resource for sharing and exploiting 📍📷 field photos. Anyone can take photographs of places visible from the public streets and contribute them to the Panoramax database. This data is then freely accessible and reusable by all. More information available at [gitlab.com/panoramax](https://gitlab.com/panoramax) and [panoramax.fr](https://panoramax.fr/).
+
+
+# 📷 GeoPic Tag Reader
+
+This repository only contains the Python library to __read and write standardized metadata__ from geolocated pictures EXIF metadata. It can be used completely apart from all GeoVisio/Panoramax components for your own projects and needs.
+
+## Features
+
+This tool allows you to:
+
+- 🔍 Analyse various EXIF variables to extract standardized metadata for geolocated pictures applications (coordinates, date, orientation, altitude...)
+- ✏️ Edit a picture to change its EXIF variables through a simpler command
+- 💻 Either as Python code or as a command-line utility
+
+
+## Install
+
+The library can be installed easily, for a quick glance:
+
+```bash
+pip install geopic_tag_reader
+geopic-tag-reader --help
+```
+
+To know more about install and other options, see [install documentation](./docs/Install.md).
+
+If at some point you're lost or need help, you can contact us through [issues](https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/issues) or by [email](mailto:panieravide@riseup.net).
+
+
+## Usage
+
+This library can be used both from command-line or as Python module.
+
+### As command-line
+
+To see all available commands:
+
+```bash
+geopic-tag-reader --help
+```
+
+To read metadata from a single picture:
+
+```bash
+geopic-tag-reader read --image /path/to/my_image.jpg
+```
+
+To edit metadata of a single picture, for example change its capture date:
+
+```bash
+geopic-tag-reader write \
+	--input /path/to/original_image.jpg \
+	--capture-time "2023-01-01T12:56:38Z" \
+	--output /path/to/edited_image.jpg
+```
+
+[Full documentation is also available here](./docs/CLI_USAGE.md).
+
+### As Python library
+
+In your own script, for reading and writing a picture metadata, you can use:
+
+```python
+from geopic_tag_reader import reader, writer, model
+
+# Open image as binary file
+img = open("my_picture.jpg", "rb")
+imgBytes = img.read()
+img.close()
+
+# Read EXIF metadata
+metadata = reader.readPictureMetadata(imgBytes)
+print(metadata)
+
+# Edit picture EXIF metadata
+editedMetadata = writer.PictureMetadata(
+	picture_type = model.PictureType.equirectangular,
+	direction = writer.Direction(125)
+)
+editedImgBytes = writer.writePictureMetadata(imgBytes, editedMetadata)
+
+# Save edited file
+editedImg = open("my_new_picture.jpg", "wb")
+editedImg.write(editedImgBytes)
+editedImg.close()
+```
+
+[Full documentation is also available here](./docs/API_USAGE.md).
+
+
+## Contributing
+
+Pull requests are welcome. For major changes, please open an [issue](https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/issues) first to discuss what you would like to change.
+
+More information about developing is available in [documentation](./docs/Develop.md).
+
+
+## ⚖️ License
+
+Copyright (c) Panoramax team 2022-2024, [released under MIT license](https://gitlab.com/panoramax/server/geo-picture-tag-reader/-/blob/main/LICENSE).

geopic_tag_reader-1.1.3/docs/develop.md

@@ -0,0 +1,89 @@
+# Development
+
+## Tests
+
+Tests are run using PyTest. You can simply run this command to launch tests:
+
+```bash
+pytest
+```
+
+## Documentation
+
+High-level documentation is handled by [Typer](https://typer.tiangolo.com/). You can update the generated `USAGE.md` file using this command:
+
+```bash
+make docs
+```
+
+[Mkdocs](https://www.mkdocs.org/) is also used to generate a clean web page for documentation, you can check out its rendering by launching:
+
+```bash
+pip install -e .[docs]
+mkdocs serve
+```
+
+## Translations
+
+Translations and internationalization are managed with Python `gettext`. Translations files are located in `geopic_tag_reader/geopic_tag_reader/translations/` folder. You can make a string in code translated using:
+
+```python
+# Load i18n module
+from geopic_tag_reader.i18n import init as i18n_init
+
+# Create translator with appropriate language
+_ = i18n_init("fr")
+
+# Use _ function to translate
+print(_("My label is {mood}").format(mood="good"))
+```
+
+Once you have done all your translations, run this command to update the POT label catalog (you will need to have the [`gettext` utilities](https://www.gnu.org/software/gettext/) installed):
+
+```bash
+make i18n-code2pot
+```
+
+Then, our translations are managed through [our Weblate instance](https://weblate.panoramax.xyz/).
+
+If you want to convert translated PO files into MO files, you can run:
+
+```bash
+make i18n-po2code
+```
+
+## Contributing
+
+Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
+
+Note that before opening a pull requests, you may want to check formatting and tests of your changes:
+
+```bash
+make ci
+```
+
+You can also install git [pre-commit](https://pre-commit.com/) hooks to format code on commit with:
+
+```bash
+pip install -e .[dev]
+pre-commit install
+```
+
+## Make a release
+
+```bash
+git checkout develop
+git pull
+
+vim CHANGELOG.md					# Edit version + links at bottom
+vim geopic_tag_reader/__init__.py	# Edit version
+make prepare_release
+
+git add *
+git commit -m "Release x.x.x"
+git tag -a x.x.x -m "Release x.x.x"
+git push origin develop
+git checkout main
+git merge develop
+git push origin main --tags
+```

geopic_tag_reader-1.1.3/docs/index.md

@@ -0,0 +1,115 @@
+# Pictures metadata
+
+Panoramax have some prerequisites for a pictures to be accepted:
+
+- Position 📍
+- Capture time ⏲️
+
+Those metadata are usually integrated inside the picture file (in what is called [EXIF tags](https://en.wikipedia.org/wiki/Exif)). For some complex use cases, those tags can also be given alongside the picture to the uploading API.
+
+## :octicons-file-binary-16: Exif tags
+
+Exif tags are quite complex and usually one metadata can be read from several EXIF tags. In order to handle many camera vendors, Panoramax will try to read each metadata from several EXIF tags.
+
+!!! note
+
+    The following documentation uses the [Exiv2](https://exiv2.org) notation for EXIF tags as it gives a unique identifier for an EXIF tag, and is the notation used by the API to expose those tags.
+
+!!! note
+
+    Panoramax accepts both __360° and classic/flat pictures__.
+
+### 📍 GPS coordinates
+
+📍 GPS coordinates are read from:
+
+- `Exif.GPSInfo.GPSLatitude`/`Exif.GPSInfo.GPSLatitudeRef`, `Exif.GPSInfo.GPSLongitude`/`Exif.GPSInfo.GPSLongitudeRef`
+- or `Xmp.exif.GPSLatitude`/`Xmp.exif.GPSLatitudeRef`, `Xmp.exif.GPSLongitude`/`Xmp.exif.GPSLongitudeRef`
+- or in [Mapillary](https://www.mapillary.com/) tags: `MAPLatitude`/`MAPLongitude`
+
+### ⏲️ Capture time
+
+⏲️ Capture time is read from:
+
+- `Exif.GPSInfo.GPSDateStamp`
+- `Exif.GPSInfo.GPSDateTime`
+- `Xmp.exif.GPSDateStamp`
+- `Xmp.exif.GPSDateTime`
+- `Exif.Image.DateTimeOriginal`
+- `Exif.Photo.DateTimeOriginal`
+- `Exif.Image.DateTime`
+- `Xmp.GPano.SourceImageCreateTime`
+- or in [Mapillary](https://www.mapillary.com/) tags: `MAPGpsTime`
+
+### Optional metadata
+
+The following EXIF tags are recognized and used if defined, but are **optional**:
+
+#### 🧭 Image orientation
+
+Image orientation is read from
+
+- `GPSImgDirection`
+- `GPano:PoseHeadingDegrees`
+- or in [Mapillary](https://www.mapillary.com/) tags: `MAPCompassHeading`
+
+#### :material-timer: Milliseconds in date
+
+Milliseconds in date is reade from `SubSecTimeOriginal`.
+
+#### :material-panorama-sphere-outline: 360° or flat
+
+To detect if a picture is 360° / spherical, we use `GPano:ProjectionType` or an heuristic based on the model of the camera and dimension of the picture ([see doc for more details](./tech/api_reference.md#camera)).
+
+#### 📷 Make and model
+
+Camera vendor (`make`) is read from:
+
+- `Exif.Image.Make`
+- or in [Mapillary](https://www.mapillary.com/) tags: `MAPDeviceMake`
+
+Camera model is read from:
+
+- `Exif.Image.Model`
+- or in [Mapillary](https://www.mapillary.com/) tags: `MAPDeviceModel`
+
+#### Focal length
+
+Camera focal length (to get precise field of view) is read from:
+
+- `Exif.Image.FocalLength`
+- `Exif.Photo.FocalLength`
+
+#### :octicons-horizontal-rule-16: Pitch and roll
+
+Pitch value is read from:
+
+- `Xmp.Camera.Pitch`
+- `Exif.GPSInfo.GPSPitch`
+- `Xmp.GPano.PosePitchDegrees`
+- `Xmp.GPano.InitialViewPitchDegrees`
+
+Roll value is read from:
+
+- `Xmp.Camera.Roll`
+- `Exif.GPSInfo.GPSRoll`
+- `Xmp.GPano.PoseRollDegrees`
+- `Xmp.GPano.InitialViewRollDegrees`
+
+#### ⛰️ Altitude
+
+Altitude is read from:
+
+- `Exif.GPSInfo.GPSAltitude`
+
+## :simple-python: Using as Python library
+
+All this metadata reading logic has been extracted in a python library.
+
+[:octicons-arrow-right-24: How to use as a Python library](./tech/api_reference.md)
+
+## :octicons-terminal-16: Using as Command-line tool
+
+A command-line tool is also available to quickly read and write a picture's metadata.
+
+[:octicons-arrow-right-24: How to use the command-line tool](./tech/cli.md)

geopic_tag_reader-1.1.3/docs/install.md

@@ -0,0 +1,82 @@
+# Install as a command-line tool
+
+GeoPicTagReader can be installed using two methods:
+
+- :simple-python: From [PyPI](https://pypi.org/project/geopic-tag-reader/), the Python central package repository
+- :simple-git: Using this [Git repository](https://gitlab.com/panoramax/server/geo-picture-tag-reader)
+
+GeoPicTagReader is compatible with all Python versions >= 3.8.
+
+!!! note
+    Due to [Pyexiv2 dependency on a recent GLIBC version](https://github.com/LeoHsiao1/pyexiv2/issues/120), you have to make sure to run on a recent, up-to-date operating system.
+
+=== ":simple-python: PyPI"
+
+    Just launch this command:
+
+    ```bash
+    pip install geopic_tag_reader
+    ```
+
+=== "pipx"
+
+    Alternatively, you can use [pipx](https://github.com/pypa/pipx) if you want all the script dependencies to be in a custom virtual env.
+
+    You need to [install pipx](https://pypa.github.io/pipx/installation/), then:
+
+    ```bash
+    pipx install geopic_tag_reader
+    ```
+
+=== ":simple-git: Git repository"
+
+    Download the repository:
+
+	<div class="annotate" markdown>
+
+    ```bash
+    git clone https://gitlab.com/panoramax/server/geo-picture-tag-reader.git geopic_tag_reader
+    cd geopic_tag_reader/
+    
+    # Create the virtual environment in a folder named "env" (1)
+    python3 -m venv env
+
+    # Launches utilities to make environment available in your Bash
+    source ./env/bin/activate
+
+    # Then, install the dependencies using pip:
+    pip install -e .
+    ```
+    </div>
+
+    1. To avoid conflicts, it's considered a good practice to create a _[virtual environment](https://docs.python.org/3/library/venv.html)_ (or virtualenv).
+
+After this you should be able to use the CLI tool with the name `geopic-tag-reader`:
+
+```bash
+geopic-tag-reader --help
+```
+
+### Write EXIF tags
+
+If you want to be able to write exif tags, you need to also install the `write-exif` extra:
+
+This will install [libexiv2](https://exiv2.org/) if available in the target platform.
+
+=== ":simple-python: PyPI"
+
+    ```bash
+    pip install geopic_tag_reader[write-exif]
+    ```
+
+=== "pipx"
+
+    ```bash
+    pipx install geopic_tag_reader[write-exif]
+    ```
+
+=== ":simple-git: Git repository"
+
+    ```bash
+    pip install -e .[write-exif]
+    ```

geopic_tag_reader-1.1.3/docs/tech/api_reference.md

@@ -0,0 +1,25 @@
+# Tag Reader's API Reference
+
+## Reader
+
+::: geopic_tag_reader.reader
+
+## Writer
+
+!!! warning
+
+    To use this module, you need to install the `write-exif` dependency:
+
+    ```bash
+    pip install -e .[write-exif]
+    ```
+
+::: geopic_tag_reader.writer
+
+## Camera
+
+::: geopic_tag_reader.camera
+
+## Model
+
+::: geopic_tag_reader.model