weitsicht 0.0.1__tar.gz

weitsicht-0.0.1/LICENSE

@@ -0,0 +1,177 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

weitsicht-0.0.1/PKG-INFO

@@ -0,0 +1,489 @@
+Metadata-Version: 2.4
+Name: weitsicht
+Version: 0.0.1
+Summary: A package that uses image georeferencing for monoplotting (single-image pixel-to-3D ray/surface intersection) and for projecting 3D coordinates into an image. Supports perspective imagery and orthophotos.
+Author: Martin Wieser
+License: 
+                                         Apache License
+                                   Version 2.0, January 2004
+                                http://www.apache.org/licenses/
+        
+           TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+        
+           1. Definitions.
+        
+              "License" shall mean the terms and conditions for use, reproduction,
+              and distribution as defined by Sections 1 through 9 of this document.
+        
+              "Licensor" shall mean the copyright owner or entity authorized by
+              the copyright owner that is granting the License.
+        
+              "Legal Entity" shall mean the union of the acting entity and all
+              other entities that control, are controlled by, or are under common
+              control with that entity. For the purposes of this definition,
+              "control" means (i) the power, direct or indirect, to cause the
+              direction or management of such entity, whether by contract or
+              otherwise, or (ii) ownership of fifty percent (50%) or more of the
+              outstanding shares, or (iii) beneficial ownership of such entity.
+        
+              "You" (or "Your") shall mean an individual or Legal Entity
+              exercising permissions granted by this License.
+        
+              "Source" form shall mean the preferred form for making modifications,
+              including but not limited to software source code, documentation
+              source, and configuration files.
+        
+              "Object" form shall mean any form resulting from mechanical
+              transformation or translation of a Source form, including but
+              not limited to compiled object code, generated documentation,
+              and conversions to other media types.
+        
+              "Work" shall mean the work of authorship, whether in Source or
+              Object form, made available under the License, as indicated by a
+              copyright notice that is included in or attached to the work
+              (an example is provided in the Appendix below).
+        
+              "Derivative Works" shall mean any work, whether in Source or Object
+              form, that is based on (or derived from) the Work and for which the
+              editorial revisions, annotations, elaborations, or other modifications
+              represent, as a whole, an original work of authorship. For the purposes
+              of this License, Derivative Works shall not include works that remain
+              separable from, or merely link (or bind by name) to the interfaces of,
+              the Work and Derivative Works thereof.
+        
+              "Contribution" shall mean any work of authorship, including
+              the original version of the Work and any modifications or additions
+              to that Work or Derivative Works thereof, that is intentionally
+              submitted to Licensor for inclusion in the Work by the copyright owner
+              or by an individual or Legal Entity authorized to submit on behalf of
+              the copyright owner. For the purposes of this definition, "submitted"
+              means any form of electronic, verbal, or written communication sent
+              to the Licensor or its representatives, including but not limited to
+              communication on electronic mailing lists, source code control systems,
+              and issue tracking systems that are managed by, or on behalf of, the
+              Licensor for the purpose of discussing and improving the Work, but
+              excluding communication that is conspicuously marked or otherwise
+              designated in writing by the copyright owner as "Not a Contribution."
+        
+              "Contributor" shall mean Licensor and any individual or Legal Entity
+              on behalf of whom a Contribution has been received by Licensor and
+              subsequently incorporated within the Work.
+        
+           2. Grant of Copyright License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              copyright license to reproduce, prepare Derivative Works of,
+              publicly display, publicly perform, sublicense, and distribute the
+              Work and such Derivative Works in Source or Object form.
+        
+           3. Grant of Patent License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              (except as stated in this section) patent license to make, have made,
+              use, offer to sell, sell, import, and otherwise transfer the Work,
+              where such license applies only to those patent claims licensable
+              by such Contributor that are necessarily infringed by their
+              Contribution(s) alone or by combination of their Contribution(s)
+              with the Work to which such Contribution(s) was submitted. If You
+              institute patent litigation against any entity (including a
+              cross-claim or counterclaim in a lawsuit) alleging that the Work
+              or a Contribution incorporated within the Work constitutes direct
+              or contributory patent infringement, then any patent licenses
+              granted to You under this License for that Work shall terminate
+              as of the date such litigation is filed.
+        
+           4. Redistribution. You may reproduce and distribute copies of the
+              Work or Derivative Works thereof in any medium, with or without
+              modifications, and in Source or Object form, provided that You
+              meet the following conditions:
+        
+              (a) You must give any other recipients of the Work or
+                  Derivative Works a copy of this License; and
+        
+              (b) You must cause any modified files to carry prominent notices
+                  stating that You changed the files; and
+        
+              (c) You must retain, in the Source form of any Derivative Works
+                  that You distribute, all copyright, patent, trademark, and
+                  attribution notices from the Source form of the Work,
+                  excluding those notices that do not pertain to any part of
+                  the Derivative Works; and
+        
+              (d) If the Work includes a "NOTICE" text file as part of its
+                  distribution, then any Derivative Works that You distribute must
+                  include a readable copy of the attribution notices contained
+                  within such NOTICE file, excluding those notices that do not
+                  pertain to any part of the Derivative Works, in at least one
+                  of the following places: within a NOTICE text file distributed
+                  as part of the Derivative Works; within the Source form or
+                  documentation, if provided along with the Derivative Works; or,
+                  within a display generated by the Derivative Works, if and
+                  wherever such third-party notices normally appear. The contents
+                  of the NOTICE file are for informational purposes only and
+                  do not modify the License. You may add Your own attribution
+                  notices within Derivative Works that You distribute, alongside
+                  or as an addendum to the NOTICE text from the Work, provided
+                  that such additional attribution notices cannot be construed
+                  as modifying the License.
+        
+              You may add Your own copyright statement to Your modifications and
+              may provide additional or different license terms and conditions
+              for use, reproduction, or distribution of Your modifications, or
+              for any such Derivative Works as a whole, provided Your use,
+              reproduction, and distribution of the Work otherwise complies with
+              the conditions stated in this License.
+        
+           5. Submission of Contributions. Unless You explicitly state otherwise,
+              any Contribution intentionally submitted for inclusion in the Work
+              by You to the Licensor shall be under the terms and conditions of
+              this License, without any additional terms or conditions.
+              Notwithstanding the above, nothing herein shall supersede or modify
+              the terms of any separate license agreement you may have executed
+              with Licensor regarding such Contributions.
+        
+           6. Trademarks. This License does not grant permission to use the trade
+              names, trademarks, service marks, or product names of the Licensor,
+              except as required for reasonable and customary use in describing the
+              origin of the Work and reproducing the content of the NOTICE file.
+        
+           7. Disclaimer of Warranty. Unless required by applicable law or
+              agreed to in writing, Licensor provides the Work (and each
+              Contributor provides its Contributions) on an "AS IS" BASIS,
+              WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+              implied, including, without limitation, any warranties or conditions
+              of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+              PARTICULAR PURPOSE. You are solely responsible for determining the
+              appropriateness of using or redistributing the Work and assume any
+              risks associated with Your exercise of permissions under this License.
+        
+           8. Limitation of Liability. In no event and under no legal theory,
+              whether in tort (including negligence), contract, or otherwise,
+              unless required by applicable law (such as deliberate and grossly
+              negligent acts) or agreed to in writing, shall any Contributor be
+              liable to You for damages, including any direct, indirect, special,
+              incidental, or consequential damages of any character arising as a
+              result of this License or out of the use or inability to use the
+              Work (including but not limited to damages for loss of goodwill,
+              work stoppage, computer failure or malfunction, or any and all
+              other commercial damages or losses), even if such Contributor
+              has been advised of the possibility of such damages.
+        
+           9. Accepting Warranty or Additional Liability. While redistributing
+              the Work or Derivative Works thereof, You may choose to offer,
+              and charge a fee for, acceptance of support, warranty, indemnity,
+              or other liability obligations and/or rights consistent with this
+              License. However, in accepting such obligations, You may act only
+              on Your own behalf and on Your sole responsibility, not on behalf
+              of any other Contributor, and only if You agree to indemnify,
+              defend, and hold each Contributor harmless for any liability
+              incurred by, or claims asserted against, such Contributor by reason
+              of your accepting any such warranty or additional liability.
+        
+           END OF TERMS AND CONDITIONS
+        
+Project-URL: Homepage, https://github.com/MartinW-S2M/weitsicht
+Project-URL: Bug Tracker, https://github.com/MartinW-S2M/weitsicht/issues
+Keywords: Photogrammetry,Mapping,Georefernced Imagery,Geographical Data,Monoplotting
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: pyproj>=3.6.1
+Requires-Dist: shapely>=2.0.1
+Requires-Dist: rasterio>=1.3.8
+Requires-Dist: trimesh>=4.6.8
+Requires-Dist: rtree>=1.4.0
+Requires-Dist: tomli>=2.4.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == "test"
+Provides-Extra: coverage
+Requires-Dist: coverage>=7.5.4; extra == "coverage"
+Provides-Extra: docs
+Requires-Dist: pydata_sphinx_theme; extra == "docs"
+Requires-Dist: sphinx-design; extra == "docs"
+Provides-Extra: develop
+Requires-Dist: pre-commit; extra == "develop"
+Requires-Dist: pyright; extra == "develop"
+Requires-Dist: ruff; extra == "develop"
+Requires-Dist: pytest>=8.0.0; extra == "develop"
+Requires-Dist: coverage>=7.5.4; extra == "develop"
+Requires-Dist: pydata_sphinx_theme; extra == "develop"
+Requires-Dist: sphinx-design; extra == "develop"
+Dynamic: license-file
+
+<p align="center">
+  <a href=https://github.com/MartinW-S2M/weitsicht>
+  <img src="https://github.com/MartinW-S2M/weitsicht/blob/main/logos/weitsicht.svg" alt="weitsicht logo" width="240">
+</p>
+
+# weitsicht
+[![pypi](https://img.shields.io/pypi/v/weitsicht)](https://pypi.org/project/weitsicht/)
+![Python Version 3.10,3.11,3.12,3.13](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue?style=flat&logo=python&logoColor=white)
+[![License](https://img.shields.io/badge/License-Apache_2.0-yellowgreen.svg)](https://opensource.org/licenses/Apache-2.0)
+
+
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
+[![pep8](https://img.shields.io/badge/code%20style-pep8-orange.svg)](https://www.python.org/dev/peps/pep-0008/)
+![PyPI - Types](https://img.shields.io/pypi/types/weitsicht)
+
+![tests](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/MartinW-S2M/43e035fba612a7cf89ff180d3a41fc2f/raw/test_count.json)
+![cov](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/MartinW-S2M/43e035fba612a7cf89ff180d3a41fc2f/raw/covbadge.json)
+&emsp;&emsp;![loc](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/MartinW-S2M/43e035fba612a7cf89ff180d3a41fc2f/raw/loc.json)
+![comments](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/MartinW-S2M/43e035fba612a7cf89ff180d3a41fc2f/raw/comments.json)
+
+[![Tests](https://github.com/MartinW-S2M/weitsicht/actions/workflows/tests.yml/badge.svg)](https://github.com/MartinW-S2M/weitsicht/actions/workflows/tests.yml)
+&emsp;&emsp;
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/MartinW-S2M/weitsicht/main.svg)](https://results.pre-commit.ci/latest/github/MartinW-S2M/weitsicht/main)
+&emsp;&emsp;![Docs passing](https://app.readthedocs.org/projects/weitsicht/badge/?version=latest)
+
+
+**Python package to use the direct geo-reference information of images for mapping and projection.**
+
+Its designed to simplify the use and implementation of functions and classes needed all the way from image points to mapped
+3d points or the other way around from 3d point to image points.
+Additionally, it is easy to get information like mapped image footprints, center points or transform them to other coordinate systems. Single-image ray intersection with a ground/3D model is often called **Monoplotting** (in ``weitsicht`` this is what the image ``map_*`` methods like ``map_points`` / ``map_center_point`` / ``map_footprint`` do with a mapper).
+
+There are classes for camera models, images, mapping functions and additional utils which simplify and abstract to a level where non-photogrammetry experts can work with it.
+
+Currently, it is possible to use perspective and ortho-imagery and for mapping a horizontal plane, rasters (e.g. DSM) and meshes.
+
+<table>
+  <tr>
+    <td><img src="docs/source/_static/raster_mapping.jpg" alt="Raster mapping example" width="80%"></td>
+    <td><img src="docs/source/_static/mesh_pic.jpg" alt="Mesh example" width="80%"></td>
+    <td><img src="docs/source/_static/example_images/image_batch_footprints.jpg" alt="Image batch footprints" width="100%"></td>
+  </tr>
+</table>
+
+**Capabilities**:
+
+- **Monoplotting/Mapping**, map the image’s center-point and footprint (image extend) or image point easily.
+- **Projection**, get the pixel position of 3D coordinates.
+- **CRS**, weitsicht handles coordinate system conversions (to some extend)
+- **Perspective Image and Camera**, mathematic model of your digital camera and pose.
+- **Ortho imagery**, use ortho imagery to map contant or convert 2D coordinates to 3D.
+- **Mapper Classes**, several mapper classes can be used to map your pixel data: HorizontalPlane, Raster, Mesh
+- **ImageBatch**, container class to perform tasks on multiple images. Find all images where coordinates are visible. Map for all images footprint and centerpoint.
+- **Meta-Data**, use image’s meta-data (EXIF, XMP) to estimate camera model and image pose.
+
+
+## Table of Contents
+- [Installation](#installation)
+- [Dependencies](#dependencies)
+- [Documentation](#documentation)
+- [Brief History](#brief-history)
+- [Goals](#goals)
+- [Future Plans](#future-plans)
+- [Contribution](#contribution)
+- [Discussion](#discussion)
+- [Package Structure](#package-structure)
+- [Example Usage](#example-usage)
+- [Notes on PyProj](#notes-on-pyproj)
+- [License](#licence)
+
+## Installation
+The source code is currently hosted on GitHub at: https://github.com/MartinW-S2M/weitsicht
+
+### PyPI
+Binary installers for the latest released version are available at the [Python
+Package Index (PyPI)] https://pypi.org/project/weitsicht/
+```
+  pip install weitsicht
+```
+
+### From Source
+In the `weitsicht` directory (same one where you found this file after cloning the git repo), execute:
+```
+  pip install .
+
+  # include test dependencies
+  pip install .[test]
+```
+
+Tests use ``pytest`` and live in the **tests** folder. As well all scripts within **examples** are tested.
+For testing Internet access has to be available as pyproj will download needed rasters (e.g EGM2008 earth gravity model)
+Alternative its possible to tell pyproj to use local stored grids/data - see [pyproj-datadir](https://pyproj4.github.io/pyproj/stable/api/datadir.html)
+
+### Installation of 3rd-party dependencies
+To provide a full simple workflow a package to read metadata is needed. see [Dependencies](#dependencies)
+
+## Dependencies
+
+### Python
+weitsicht runs on **Python 3.10+**.
+weitsicht has been tested on Windows, Linux and MacOS, and probably also runs on other Unix-like platforms.
+
+### Packages
+  It relies only on well-developed packages
+- [numpy](https://www.numpy.org)
+- [pyproj - Python interface to proj](https://pyproj4.github.io/pyproj/stable)
+- [rasterio - Easy access to geospatial raster](https://rasterio.readthedocs.io/en/stable)
+- [shapely](https://shapely.readthedocs.io/en/stable/index.html)
+- [trimesh](https://trimesh.org/)
+
+Additionally, to provide a workflow for drone imagery the metadata from images has to be extracted.
+You can use Phil Harvey's exiftool together with [PyExifTool](https://sylikc.github.io/pyexiftool/index.html).
+Although long‑term maintenance of those packages is not clear, Phil Harvey's tool provides to date the most complete metadata
+reader for most image formats, including raw camera files. In ``weitsicht`` provides an interface for different exiftool wrappers, but currently only a parser for tags from PyExifTool is implemented. A exiv2 parser would be very welcome as contributions.
+
+## Documentation
+The current documentation is available at [weitsicht.readthedocs.io](https://weitsicht.readthedocs.io)
+There you will also find information about the mathematical background and definitions.
+ANy contributions are welcome for extending documentation.
+
+## Brief History
+weitsicht was formerly part of **WISDAM (Wildlife Imagery Survey – Detection and Mapping)** (and its predecessor DugongDetector) but is now provided as its own python package.
+It is used as the photogrammetry/mapping core of WISDAMapp to map images, objects and project them back into images.
+This allows the users to assign groups, spatial metadata and find resights.
+
+**WISDAMapp (Wildlife Imagery Survey – Detection and Mapping)** is a python GUI framework based on QT for the digitization and metadata enrichment of objects
+digitized in images and ortho-photos. Geo-referenced imagery can be used to map digitized objects to 3D or project them back into images for the purpose of grouping
+
+**The WISDAMapp repository can be found under http://www.github.com/WISDAMapp/**
+
+Currently WISDAMapp undergoes refactoring to switch from the old WISDAMcore to ``weitsicht``
+
+
+## Goals
+The intention of weitsicht is to provide the community an easy-to-use package to deal with geo-referenced imagery.
+No matter if environmental science, geomatic, GIS or drone community more and more imagery is available (mostly from drones/UAS) which can be used to perform mapping operations.
+
+Many users can’t leverage their imagery beyond basic tasks without photogrammetry/SfM software; we aim to bridge that gap.
+
+## Future Plans
+As the package is currently very basic, already a few topics are around which could be implemented:
++ Extend image and camera model classes (For example, 360degree imagery)
++ Extend Rotation class to other common notations.
++ Import/Conversion of the results from photogrammetry / sfm packages.
++ Improve mapping on mesh. (holes in the mesh are currently a problem)
++ Provide ability to save derived geometries.
++ Maybe switch coordinate class to use geopandas.
++ Provide ability to use network assets for mapping (e.g. Cloud optimized geotiff)
+
+
+## Discussion
+Use the discussion page for questions, support, and general discussion.
+
+## Contribution
+Contributions are highly welcome to extend the package.
+All levels of contributions are welcome from extending the docs, examples, mathematical discussions, coding, test implementations, providing test samples.
+Please find more info in CONTRIBUTION.md
+
+## Package Structure
+
+> [!IMPORTANT]
+> weitsicht uses pyproj and using the setting always_xy for all Transformers.
+
+weitsicht was designed with flexibility and extensibility in mind.
+The library consists of a few classes, each with increasingly more features.
+
+* ``weitsicht.camera`` is the sub package for camera models (e.g. OpenCV camera model)
+It contains only the mathematical model used to transform 2D image coordinates to 3D coordinates in the camera system
+and backwards. This class mostly does not need to be called itself on a basic level but is used by the image class.
+New classes can be easily implemented or extended.
+
+
+* ``weitsicht.image`` is the subpackage which provides image classes. It is used to deal with the geo-reference
+information which states the image pose in 3D space. Main functions of the classes are:
+  * project: Project 3D coordinates into image 2D space
+  * map_points: Map pixel points into 3D space using a provided mapper.
+
+
+* ``weitsicht.mapping`` is the subpackage which provides mapping classes.
+Currently, mapping bases on a horizontal plane (mappingPlane) and mapping based on raster (mappingRaster) using rasterio.
+Main functions of the classes are:
+  * map_heights_from_coordinates: Get the height of coordinates.
+  * map_coordinates_from_rays: Get the intersection coordinates of a ray in 3D space
+
+
+* ``weitsicht.transform`` is the subpackage which provides transformation classes and functions
+  * cooTransformer class: Transform points using pyproj. Also provides an option to create geojson dict
+  * utm_converter: Convert a coordinate to WGS84/utm and get crs class as well
+  * rotation class: Class dealing with Rotation matrices used in photogrammetry
+
+> [!NOTE]
+> Some additional helper functions are needed to be used by WISDAM (e.g. the function to load classes by a dictionary)
+
+## Example Usage
+
+### Map Pixels to ground with height 0.0
+
+    import numpy as np
+    import pyproj
+    from pyproj import CRS
+
+    from weitsicht import (CameraOpenCVPerspective, ImagePerspective, MappingHorizontalPlane)
+    from weitsicht import Rotation
+
+    # To directly download the grids needed for coordinate transformation we enable the network capability of proj
+    pyproj.network.set_network_enabled(True)
+
+    # Construct Mapper
+    # We use the horizontal plane mapper in the CRS System WGS84 with EGM2008 heights
+    crs_mapper = CRS("EPSG:4326+3855")
+    mapper = MappingHorizontalPlane(plane_altitude=0.0, crs=crs_mapper)
+
+    # Camera Model
+    # The camera model's width and height is the image shape which was used during calibration,
+    # allowing the image class to use resampled images.
+    cam = CameraOpenCVPerspective(width=6000, height=4000, fx=2360, fy=2360)
+
+    # Image Pose
+    position = np.array([602013.0, 5340384.696, 100.0])
+    orientation = Rotation.from_opk_degree(omega=1.5, phi=5.6, kappa=65.0)
+
+    # Image Coordinate Reference System
+    crs = CRS("EPSG:25833+3855")  # UTM Zone 33
+    image = ImagePerspective(width=6000, height=4000, mapper=mapper, camera=cam,
+                             crs=crs, position=position, orientation=orientation)
+
+    # Map to image coordinates
+    result = image.map_points(np.array([[2000,300],[2300, 400]]))
+    if result.ok:
+      print("GSD of points: %f" % result.gsd)
+      print("Coordinates mapped", *result.coordinates)
+
+
+Refer to documentation for more examples http://weitsicht.github.io/
+
+## Notes on PyProj
+This packages heavily depends on pyproj CRS and Transformer/TransformerGroups.
+
+> [!IMPORTANT]
+> weitsicht uses the setting always_xy for all Transformers.
+> Except you are constructing your own transformation pipeline
+
+The user must take care that all data is available for the Transformation needed
+([Pyproj - Datadir](https://pyproj4.github.io/pyproj/stable/api/datadir.html))  or the network option is enabled
+([Pyproj - Network settings ](https://pyproj4.github.io/pyproj/stable/api/network.html#proj-network-settings)).
+
+    pyproj.network.set_network_enabled(True)
+
+All transformation are done by `Transformer.from_crs()`.
+Standard option is to allow only best transformations and an exception will be raised otherwise (Including ballpark transformations,
+[PyProj - Transformer](https://pyproj4.github.io/pyproj/stable/api/transformer.html#pyproj.transformer.Transformer.from_crs)).
+To allow ballpark and allow also other than the best transformations, set:
+
+    weitsicht.allow_ballpark_transformations() # sets cfg._ballpark_transformation to True
+    # is the same as allow_ballpark_transformations(True), to disallow set to False
+
+    weitsicht.allow_non_best_transformations() # sets cfg._only_best_transformation to False
+    # is the same as allow_non_best_transformations(True), to disallow set to False
+
+## Licence
+weitsicht is licensed under the Apache License, Version 2.0 (Apache-2.0).
+
+See `LICENSE` for the full license text.
+
+[Go to Top](#table-of-contents)