search

3dgeo-heidelberg / py4dgeo

py4dgeo - A Python library for change analysis in 4D point clouds
https://py4dgeo.readthedocs.io
MIT License
76 stars 12 forks source link

readme

Welcome to py4dgeo

logo

License: MIT GitHub Workflow Status PyPI Release Documentation Status codecov

py4dgeo is a C++ library with Python bindings for change analysis in multitemporal and 4D point clouds.

Topographic 3D/4D point clouds are omnipresent in geosciences, environmental, ecological and archaeological sciences, robotics, and many more fields and applications. Technology to capture such data using laser scanning and photogrammetric techniques have evolved into standard tools. Dense time series of topographic point clouds are becoming increasing available and require tools for automatic analysis. Moreover, methods considering the full 4D (3D space + time) data are being developed in research and need to be made available in an accessible way with flexible integration into existent workflows.

The main objective of py4dgeo is to bundle and provide different methods of 3D/4D change analysis in a dedicated, comprehensive Python library. py4dgeo is designed as an international open source project that can be integrated into almost any 3D and GIS software in the geodata domain supporting Python, e.g. as plugins.

py4dgeo is under ongoing active development. Below, you find a list of provided methods.

🔨 Methods provided by py4dgeo

🎮 Examples

Demo notebooks using methods provided by py4dgeo
Example 1 Example 2
Example 3 Example 4
Example 5 Example 6
Example 7

💻 Installation

Prerequisites

Using py4dgeo requires the following software installed:

In order to build the package from source, the following tools are also needed.

Installing py4dgeo

The preferred way of installing py4dgeo is using pip.

Installing the release version using pip

py4dgeo can be installed using pip to obtain the current release:

python -m pip install py4dgeo

Building from source using pip

The following sequence of commands is used to build py4dgeo from source:

git clone --recursive https://github.com/3dgeo-heidelberg/py4dgeo.git
cd py4dgeo
python -m pip install -v --editable .

The --editable flag allows you to change the Python sources of py4dgeo without reinstalling the package. The -v flag enables verbose output which gives you detailed information about the compilation process that you should include into potential bug reports. To recompile the C++ source, please run pip install again. In order to enable multi-threading on builds from source, your compiler toolchain needs to support OpenMP.

If you want to contribute to the library's development you should also install its additional Python dependencies for testing and documentation building:

python -m pip install -r requirements-dev.txt

Setting up py4dgeo using Docker

Additionally, py4dgeo provides a Docker image that allows to explore the library using JupyterLab. The image can be locally built and run with the following commands:

docker build -t py4dgeo:latest .
docker run -t -p 8888:8888 py4dgeo:latest

🐍 Documentation of software usage

As a starting point, please have a look to the Jupyter Notebooks available in the repository and find the py4dgeo documentation on readthedocs.

🌐 Published test data

If you are looking for data to test different methods, consider the following open data publications:

Hourly TLS point clouds of a sandy beach


Vos et al. (2022): https://doi.org/10.1038/s41597-022-01291-9.

By-weekly TLS point clouds of an Alpine rock glacier


Zahs et al. (2022): https://doi.org/10.11588/data/TGSVUI.

📑 Citation

Please cite py4dgeo when using it in your research and reference the appropriate release version.

article{py4dgeo,
author = {py4dgeo Development Core Team}
title = {py4dgeo: library for change analysis in 4D point clouds},
journal = {},
year = {2022},
number = {},
volume = {},
doi = {},
url = {https://github.com/3dgeo-heidelberg/py4dgeo},
}

💟 Funding / Acknowledgements

The initial software development was supported by the Scientific Software Center (SSC) in the Open Call 2021. The scientific software project is further supported by the research projects CharAct4D and AImon5.0.

🔔 Contact / Bugs / Feature Requests

You think you have found a bug or have specific request for a new feature? Please open a new issue in the online code repository on Github. Also for general questions please use the issue system.

Scientific requests can be directed to the 3DGeo Research Group Heidelberg and its respective members.

📜 License

See LICENSE.md.

📚 Literature