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.

When 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] (https://conda.io/docs/user-guide/getting-started.html) run:

conda install -c leampy pyoints

Currently Linux (64 bit) and Windows (64 bit) are supported.

Conda Build

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

Build

conda build /path/to/pyoints/conda 

If wished, you can specify the variants, like:

conda build /path/to/pyoints/conda --variants={python: [3.6], target_platform: ['osx-64']}

Installation

Create a virtual environment myenv and add the newly build Pyoints package.

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

The correct package path can be found with conda build . --output.

Finally install the package:

conda activate myenv
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 docstrings with examples for each module and some comprehensive examples. You can also take a look at the source files directly.

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:

Sebastian Lamprecht (2018): "Pyoints: A Python package for point cloud, voxel and raster processing.", URL https://github.com/laempy/pyoints, [Online; accessed date].

@Misc{,
  author = {Sebastian Lamprecht},
  organization = {Trier University}
  title = {{Pyoints}: A Python package for point cloud, voxel and raster processing.},
  year = {2018--},
  url = "https://github.com/laempy/pyoints",
  note = {[Online; accessed <today>]}
}

Contributing

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

Acknowledgements

Funding

This work was supported by the PANTHEON project which is funded by the European Community Horizon 2020 programme under grant agreement 774571.

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

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