Pyoints

Pyoints is a python package to conveniently process and analyze point cloud data, voxels and raster images. It is intended to be used to support the development of advanced algorithms for geo-data processing.

General concept

The key idea of Pyoints is to provide unified data structures to handle points, voxels and rasters in the same manner. It is assumed that the data can be interpreted as a two or three dimensional point cloud. Thus we have a collection of geo-objects, here called GeoRecords, which are characterized by two or three dimensional coordinates coords, a spatial reference proj and a transformation matrix t. The spatial reference and transformation matrix are required to define the global location of the geo-objects. Next to the origin, the transformation matrix also stores the scale and rotation of the local coordinate system.

The unified data structures simplify the joint use of point clouds, voxels and rasters significantly, while keeping their natural characteristics. To ease the processing and analysis, each point, voxel or raster cell are stored in the commonly used numpy record array according to its natural structure. For example, a three dimensional point cloud represents a set of points, each characterized by a coordinate and none to many additional attributes. So the points are stored in a one dimensional record array. Conversely raster images are stored in a two dimensional record array, which allows for the commonly used index access of raster cells. Still, each cell is characterized by a coordinate and none to many additional attributes. Three dimensional voxels are accordingly represented by three dimensional record arrays.

Since all objects of a voxel or raster are also interpreted as a point cloud, spatial neighborhood queries, like nearest neighbors or distance search, can be performed with unified functions. Thus, each extension of GeoRecords provides a spatial index IndexKD to conveniently perform efficient neighborhood queries. The class IndexKD is a wrapper of different spatial indices, to handle k-dimensional spatial queries of different kinds. The spatial indices are always only initialized on demand for performance reasons, but cached for future queries. For example, an instance geoRecords of GeoRecords representing three dimensional points allows to create a three dimensional spatial index by calling geoRecords.indexKD(). If you are not interested in the third dimension, you can call geoRecords.indexKD(2) to perform two dimensional spatial queries.

If you just want to handle coordinates without additional attributes, the class Coords might interest you. This class also provides the IndexKD feature, but waives to use of a projection and transformation matrix.

Is Pyoints suitable for me?

Based on the general concept of Pyoints presented above, a bunch of algorithms, functions and filters have been implemented, to process geo-data with low programming efforts.

Of course, one might wonder whether Python is adequate to analyze point cloud data since other languages languages are much more efficient. This is obviously true, but in the experience of the author, Python is very useful to implement and test new algorithms very quickly. Algorithms for point cloud analysis and processing often rely on spatial neighborhood queries. Since Pyoints takes advantage of very efficient Python libraries, which are basically wrappers for binaries written in more efficient languages, the performance loss is limited. Additionally, Pyoints takes care of selecting and caching appropiate spatial indices for you, so you can focus on the core of your algorithm idea.

So, if you have an algorithm idea and you want to implement it quickly and play around with different settings, Pyoints is made for you. After finding an approiate algorithm it can be implemented in a more efficient language if you like. Thus Pyoints is particulary designed for scientists and developers of new geo-spatial algorithms.

Installation

Conda Installation

Conda installation is recommended. To install Pyoints with Conda run:

conda install -c laempy pyoints

Currently only Linux (64 bit) has been packaged with Python 3.5, 3.6 and 3.7.

To enable full LAS support (spatial reference system definition), you need to install liblas and its python bindings manually.

pip install liblas

Installation from source

We recommend to use a virtual environment (like Conda) to install Pyoints.

Installation of the external dependencies: conda install gdal pyproj "numpy>=1.15" rtree

Cloning of the repository: git clone https://github.com/laempy/pyoints.git cd pyoints

Installation of the python dependencies via pip. pip install -e .

Conda Build

If your system is not supported yet, you might build and install it using the conda reciepe specifying your desired Python version.

Build

conda build /path/to/pyoints/conda --python=3.x

Installation

Create a virtual environment pyoints_env and add the newly build Pyoints package. The package path can be found with conda build . --output.

conda create -n pyoints_env /path/to/builded/package/pyoints-*-py*_*.tar.bz2 --use-local

Finally install the package:

conda activate pyoints_env conda install pyoints

Tests

Test the package by running the provided doctests:

python /path/to/pyoints/tests/test_pyoints.py

Documentation

You can find the documentation at docs. Here you can find some introducing tutorials and docstring examples for each module.

License

Copyright (c) 2018, Sebastian Lamprecht, Trier University, lamprecht@uni-trier.de

Pyoints is free software made available under the GNU General Public License v3 or later (GPLv3+). See LICENSE for details.

Citing

Please cite Pyoints as follows:

S. Lamprecht (2019): "Pyoints: A Python package for point cloud, voxel and raster processing".

Contributing

Any conribution to the pyoints project is welcome. See CONTRIBUTING for details.

Acknowledgements

Funding

This work has been supported by the European Commission under the grant agreement number 774571 Project PANTHEON.

Datasets

For the tutorials the "Stanford Bunny" dataset has been used:

Stanford Computer Graphics Laboratory (1994): "Stanford Bunny", URL: https://graphics.stanford.edu/data/3Dscanrep/, (Accessed: 17 January 2019)

Python Depencencies

This software dynamically binds the following Python packages (distributed via pip). Many thanks to the authors for providing such great open source software.

cylinder_fitting

Xingjie Pan * PyPI * homepage * 3-Clause BSD license

dill

Mike McKerns * PyPI * homepage * 3-Clause BSD license

pygdal

Frank Warmerdam * PyPI * homepage * 2-Clause BSD license

laspy

Grant Brown and Howard Butler * PyPI * homepage * 2-Clause BSD license

liblas

Romulo Goncalves * PyPI * homepage * 3-Clause BSD license

networkx

NetworkX Developers * PyPI * homepage * 3-Clause BSD license

numpy

Travis E. Oliphant et al. * PyPI * homepage * 3-Clause BSD license

opencv-python

Olli-Pekka Heinisuo * PyPI * homepage * MIT license

pandas

The PyData Development Team * PyPI * homepage * 3-Clause BSD license

plyfile

Darsh Ranjan * PyPI * homepage * GPL v3.0 (or later)

pyproj

Jeff Whitaker * PyPI * homepage * OSI approved license

scikit-learn

Andreas Mueller * PyPI * homepage * 3-Clause BSD license

scipy

SciPy Developers * PyPI * homepage * 3-Clause BSD license

rtree

Howard Butler * PyPI * homepage * LGPL v2.1 (or later)

External Depencencies

Pyoints binds following external libraries as required by some of the pip packages.

GDAL

Frank Warmerdam * homepage * X11/MIT license

Liblas

Howard Butler, Mateusz Loskot et. al. * homepage * X11/MIT license

libspatialindex

Marios Hadjieleftheriou * homepage * MIT license