C++ API reference

This is the complete reference for the (internal) C++ API of py4dgeo. You only need to consult this documentation if you are aiming to extend the C++ core of py4dgeo.

namespace py4dgeo

Typedefs

using EigenPointCloud = Eigen::Matrix<double, Eigen::Dynamic, 3, Eigen::RowMajor>

The C++ type for a point cloud.

Point clouds are represented as (nx3) matrices from the Eigen library.

The choice of this type allows us both very efficient implementation of numeric algorithms using the Eigen library, as well as no-copy interoperability with numpy’s multidimensional arrays.

using EigenPointCloudRef = Eigen::Ref<EigenPointCloud>

A non-const reference type for passing around EigenPointCloud.

You should use this in function signatures that accept a point cloud as a parameter and need to modify the point cloud.

using EigenPointCloudConstRef = Eigen::Ref<const EigenPointCloud>

A const reference type for passing around EigenPointCloud.

You should use this in function signatures that accept a read-only point cloud.

using EigenNormalSet = Eigen::Matrix<double, Eigen::Dynamic, 3, Eigen::RowMajor>

The C++ type to represent a set of normal vectors on a point cloud.

In contrast to point clouds, these use double precision.

using EigenNormalSetRef = Eigen::Ref<EigenNormalSet>: A mutable reference to a set of normal vectors on a point cloud.

using EigenNormalSetConstRef = Eigen::Ref<const EigenNormalSet>: An immutable reference to a set of normal vectors on a point cloud.

using IndexType = Eigen::Index: The type used for point cloud indices.

using DistanceVector = std::vector<double>: The variable-sized vector type used for distances.

using UncertaintyVector = std::vector<DistanceUncertainty>: The variable-sized vector type used for uncertainties.

Enums

enum class MemoryPolicy

An enumerator for py4dgeo’s memory policy.

This is used and documented through its Python binding equivalent.

Values:

enumerator STRICT

enumerator MINIMAL

enumerator COREPOINTS

enumerator RELAXED

struct DistanceUncertainty

#include <py4dgeo.hpp>

Return structure for the uncertainty of the distance computation.

This structured type is used to describe the uncertainty of point cloud distance at a single corepoint. It contains the level of detection, the spread within both point clouds (e.g. the standard deviation of the distance measure) and the number of sampled points.

Public Members

double lodetection

double spread1

IndexType num_samples1

double spread2

IndexType num_samples2

namespace py4dgeo

class Epoch

#include <epoch.hpp>

A data structure representing an epoch.

It stores the point cloud itself (without taking ownership of it) and the KDTree (with ownership). In the future, relevant metadata fields can be easily added to this data structure without changing any signatures that depend on Epoch.

Public Functions

Epoch(const EigenPointCloudRef&)

Epoch(std::shared_ptr<EigenPointCloud>)

std::ostream &to_stream(std::ostream&) const

Public Members

EigenPointCloudRef cloud

KDTree kdtree

Public Static Functions

static std::unique_ptr<Epoch> from_stream(std::istream&)

Private Members

std::shared_ptr<EigenPointCloud> owned_cloud

namespace py4dgeo

class KDTree

#include <kdtree.hpp>

Efficient KDTree data structure for nearest neighbor/radius searches.

This data structure allows efficient radius searches in 3D point cloud data. It is based on NanoFLANN: https://github.com/jlblancoc/nanoflann

Public Types

using RadiusSearchResult = std::vector<IndexType>: Return type used for radius searches.

using RadiusSearchDistanceResult = std::vector<std::pair<IndexType, double>>: Return type used for radius searches that export calculated distances.

using NearestNeighborsDistanceResult = std::vector<std::pair<std::vector<IndexType>, std::vector<double>>>: Return type used for nearest neighbor searches.

Public Functions

std::ostream &saveIndex(std::ostream &stream) const: Save the index to a (file) stream.

std::istream &loadIndex(std::istream &stream): Load the index from a (file) stream.

void build_tree(int leaf)

Build the KDTree index.

This initializes the KDTree search index. Calling this method is required before performing any nearest neighbors or radius searches.

Parameters:: leaf – The threshold parameter definining at what size the search tree is cutoff. Below the cutoff, a brute force search is performed. This parameter controls a trade off decision between search tree build time and query time.

void invalidate(): Invalidate the KDTree index.

std::size_t radius_search(const double *querypoint, double radius, RadiusSearchResult &result) const

Peform radius search around given query point.

This method determines all the points from the point cloud within the given radius of the query point. It returns only the indices and the result is not sorted according to distance.

Parameters:

querypoint – [in] A pointer to the 3D coordinate of the query point
radius – [in] The radius to search within
result – [out] A data structure to hold the result. It will be cleared during application.

Returns:

The amount of points in the return set

std::size_t radius_search_with_distances(const double *querypoint, double radius, RadiusSearchDistanceResult &result) const

Perform radius search around given query point exporting distance information.

This method determines all the points from the point cloud within the given radius of the query point. It returns their indices and their distances from the query point. The result is sorted by ascending distance from the query point.

Parameters:

querypoint – [in] A pointer to the 3D coordinate of the query point
radius – [in] The radius to search within
result – [out] A data structure to hold the result. It will be cleared during application.

Returns:

The amount of points in the return set

void nearest_neighbors_with_distances(EigenPointCloudConstRef cloud, NearestNeighborsDistanceResult &result, int k) const

Calculate the nearest neighbors for an entire point cloud.

Parameters:

cloud – [in] The point cloud to use as query points
result – [out] The indexes and distances of k nearest neighbors for each point
k – [in] The amount of nearest neighbors to calculate

int get_leaf_parameter() const: Return the leaf parameter this KDTree has been built with.

Public Static Functions

static KDTree create(const EigenPointCloudRef &cloud)

Construct instance of KDTree from a given point cloud.

This is implemented as a static function instead of a public constructor to ease the implementation of Python bindings.

Parameters:: cloud – The point cloud to construct the search tree for

Private Types

using KDTreeImpl = nanoflann::KDTreeSingleIndexAdaptor<nanoflann::L2_Simple_Adaptor<double, Adaptor, double>, Adaptor, 3, IndexType>: The NanoFLANN index implementation that we use.

Private Functions

KDTree(const EigenPointCloudRef&): Private constructor from pointcloud - use through KDTree::create.

Private Members

friend Epoch

Adaptor adaptor

std::shared_ptr<KDTreeImpl> search

int leaf_parameter = 0

struct Adaptor

An adaptor between our Eigen data structures and NanoFLANN.

Public Functions

inline std::size_t kdtree_get_point_count() const

inline double kdtree_get_pt(const IndexType idx, const IndexType dim) const

template<class BBOX> inline bool kdtree_get_bbox(BBOX&) const

Public Members

EigenPointCloudRef cloud

struct NoDistancesReturnSet

A structure to perform efficient radius searches with NanoFLANN.

The built-in return set of NanoFLANN does automatically export the distances as well, which we want to omit if we already know that we do not need the distance information.

Public Functions

inline std::size_t size() const

inline bool full() const

inline bool addPoint(double dist, IndexType idx)

inline double worstDist() const

Public Members

double radius

RadiusSearchResult &indices

void py4dgeo::compute_distances(EigenPointCloudConstRef, double, const Epoch&, const Epoch&, EigenNormalSetConstRef, double, double, DistanceVector&, UncertaintyVector&, const WorkingSetFinderCallback&, const DistanceUncertaintyCalculationCallback&): Compute M3C2 distances.

void py4dgeo::compute_multiscale_directions(const Epoch&, EigenPointCloudConstRef, const std::vector<double>&, EigenNormalSetConstRef, EigenNormalSetRef): Compute M3C2 multi scale directions.

namespace py4dgeo

Typedefs

using EigenSpatiotemporalArray = Eigen::Matrix<double, Eigen::Dynamic, Eigen::Dynamic, Eigen::RowMajor>: The type to use for the spatiotemporal distance array.

using EigenSpatiotemporalArrayRef = Eigen::Ref<EigenSpatiotemporalArray>

using EigenSpatiotemporalArrayConstRef = Eigen::Ref<const EigenSpatiotemporalArray>

using EigenTimeSeries = Eigen::Vector<double, Eigen::Dynamic>: The type to use for a TimeSeries.

using EigenTimeSeriesRef = Eigen::Ref<EigenTimeSeries>

using EigenTimeSeriesConstRef = Eigen::Ref<const EigenTimeSeries>

using TimeseriesDistanceFunction = std::function<double(const TimeseriesDistanceFunctionData&)>: The signature to use for a distance function.

struct TimeseriesDistanceFunctionData

#include <segmentation.hpp>

The data object passed to time series distance functions.

Public Members

EigenTimeSeriesConstRef ts1

EigenTimeSeriesConstRef ts2

double norm1

double norm2

struct ObjectByChange

#include <segmentation.hpp>

Basic data structure for 4D change object.

Public Members

std::unordered_map<IndexType, double> indices_distances

IndexType start_epoch

IndexType end_epoch

double threshold

struct RegionGrowingSeed

Public Members

IndexType index

IndexType start_epoch

IndexType end_epoch

struct RegionGrowingAlgorithmData

Public Members

EigenSpatiotemporalArrayConstRef distances

const Epoch &corepoints

double radius

RegionGrowingSeed seed

std::vector<double> thresholds

std::size_t min_segments

std::size_t max_segments

struct ChangePointDetectionData

Public Members

EigenTimeSeriesConstRef ts

IndexType window_width

IndexType min_size

IndexType jump

double penalty

class CallbackExceptionVault

#include <openmp.hpp>

A container to handle exceptions in parallel regions.

OpenMP does have limited support for C++ exceptions in parallel regions: Exceptions need to be catched on the same thread they have been thrown on. This class allows to store the first thrown exception to then rethrow it after we left the parallel region. This is a necessary construct to propagate exceptions from Python callbacks through the multithreaded C++ layer back to the calling Python scope. Inspiration is taken from: https://stackoverflow.com/questions/11828539/elegant-exceptionhandling-in-openmp

Public Functions

template<typename Function, typename ...Parameters> inline void run(Function &&f, Parameters&&... parameters)

inline void rethrow() const

Private Members

std::exception_ptr ptr = nullptr