Python API reference

User API reference

This is the complete reference of the Python API for the py4dgeo package. It focuses on those aspects relevant to end users that are not interested in algorithm development.

class py4dgeo.Epoch(cloud: ndarray, normals: ndarray | None = None, additional_dimensions: ndarray | None = None, timestamp=None, scanpos_info: dict | None = None)

build_kdtree(leaf_size=10, force_rebuild=False)

Build the search tree index

Parameters:

• leaf_size (int) – An internal optimization parameter of the search tree data structure. The algorithm uses a bruteforce search on subtrees of size below the given threshold. Increasing this value speeds up search tree build time, but slows down query times.

• force_rebuild (bool) – Rebuild the search tree even if it was already built before.

build_octree()

Build the search octree index

calculate_normals(radius=1.0, orientation_vector: ndarray = array([0, 0, 1]))

Calculate point cloud normals

Parameters:

• radius – The radius used to determine the neighborhood of a point.

• orientation_vector – A vector to determine orientation of the normals. It should point “up”.

copy()

Copy the epoch object

static load(filename)

Construct an Epoch instance by loading it from a file

Parameters:

filename (str) – The filename to load the epoch from.

property metadata

Provide the metadata of this epoch as a Python dictionary

The return value of this property only makes use of Python built-in data structures such that it can e.g. be serialized using the JSON module. Also, the returned values are understood by Epoch.__init__ such that you can do Epoch(cloud, **other.metadata).

normals_attachment(normals_array)

Attach normals to the epoch object

Parameters:

normals – The point cloud normals of shape (n, 3) where n is the same as the number of points in the point cloud.

save(filename)

Save this epoch to a file

Parameters:

filename (str) – The filename to save the epoch in.

transform(transformation: Transformation | None = None, affine_transformation: ndarray | None = None, rotation: ndarray | None = None, translation: ndarray | None = None, reduction_point: ndarray | None = None)

Transform the epoch with an affine transformation

Parameters:

• transformation (np.ndarray) – A Transformation object that describes the transformation to apply. If this argument is given, the other arguments are ignored. This parameter is typically used if the transformation was calculated by py4dgeo itself.

• affine_transformation – A 4x4 or 3x4 matrix representing the affine transformation. Given as a numpy array. If this argument is given, the rotation and translation arguments are ignored.

• rotation (np.ndarray) – A 3x3 matrix specifying the rotation to apply

• translation (np.ndarray) – A vector specifying the translation to apply

• reduction_point (np.ndarray) – A translation vector to apply before applying rotation and scaling. This is used to increase the numerical accuracy of transformation. If a transformation is given, this argument is ignored.

property transformation

Access the affine transformations that were applied to this epoch

In order to set this property please use the transform method instead, which will make sure to also apply the transformation.

Returns:

Returns a list of applied transformations. These are given as a tuple of a 4x4 matrix defining the affine transformation and the reduction point used when applying it.

py4dgeo.read_from_las(*filenames, normal_columns=[], additional_dimensions={})

Create an epoch from a LAS/LAZ file

Parameters:

• filename (str) – The filename to read from. It is expected to be in LAS/LAZ format and will be processed using laspy.

• normal_columns (list) – The column names of the normal vector components, e.g. “NormalX”, “nx”, “normal_x” etc., keep in mind that there must be exactly 3 columns. Leave empty, if your data file does not contain normals.

• additional_dimensions (dict) – A dictionary, mapping names of additional data dimensions in the input dataset to additional data dimensions in our epoch data structure.

py4dgeo.read_from_xyz(*filenames, xyz_columns=[0, 1, 2], normal_columns=[], additional_dimensions={}, additional_dimensions_dtypes={}, **parse_opts)

Create an epoch from an xyz file

Parameters:

• filename (str) – The filename to read from. Each line in the input file is expected to contain three space separated numbers.

• xyz_columns (list) – The column indices of X, Y and Z coordinates. Defaults to [0, 1, 2].

• normal_columns (list) – The column indices of the normal vector components. Leave empty, if your data file does not contain normals, otherwise exactly three indices for the x, y and z components need to be given.

• parse_opts (dict) – Additional options forwarded to numpy.genfromtxt. This can be used to e.g. change the delimiter character, remove header_lines or manually specify which columns of the input contain the XYZ coordinates.

• additional_dimensions (dict) – A dictionary, mapping column indices to names of additional data dimensions. They will be read from the file and are accessible under their names from the created Epoch objects. Additional column indexes start with 3.

• additional_dimensions_dtypes (dict) – A dictionary, mapping column names to numpy dtypes which should be used in parsing the data.

py4dgeo.save_epoch(epoch, filename)

Save an epoch to a given filename

Parameters:

• epoch (Epoch) – The epoch that should be saved.

• filename (str) – The filename where to save the epoch

py4dgeo.load_epoch(filename)

Load an epoch from a given filename

Parameters:

filename (str) – The filename to load the epoch from.

class py4dgeo.M3C2(normal_radii: List[float] | None = None, orientation_vector: ndarray = array([0, 0, 1]), corepoint_normals: ndarray | None = None, cloud_for_normals: Epoch | None = None, **kwargs)

Bases: M3C2LikeAlgorithm

calculate_distances(epoch1, epoch2, searchtree: str | None = None)

Calculate the distances between two epochs

callback_distance_calculation()

The callback used to calculate the distance between two point clouds

callback_workingset_finder()

The callback used to determine the point cloud subset around a corepoint

directions()

The normal direction(s) to use for this algorithm.

run()

Main entry point for running the algorithm

class py4dgeo.CloudCompareM3C2(**params)

Bases: M3C2

calculate_distances(epoch1, epoch2, searchtree: str | None = None)

Calculate the distances between two epochs

callback_distance_calculation()

The callback used to calculate the distance between two point clouds

callback_workingset_finder()

The callback used to determine the point cloud subset around a corepoint

directions()

The normal direction(s) to use for this algorithm.

run()

Main entry point for running the algorithm

class py4dgeo.SpatiotemporalAnalysis(filename, compress=True, allow_pickle=True, force=False)

add_epochs(*epochs)

Add a numbers of epochs to the existing analysis

property corepoints

Access the corepoints of this analysis

property distances

Access the M3C2 distances of this analysis

property distances_for_compute

Retrieve the distance array used for computation

This might be the raw data or smoothed data, based on whether a smoothing was provided by the user.

invalidate_results(seeds=True, objects=True, smoothed_distances=False)

Invalidate (and remove) calculated results

This is automatically called when new epochs are added or when an algorithm sets the force option.

property m3c2

Access the M3C2 algorithm of this analysis

property objects

The list of objects by change for this analysis

property reference_epoch

Access the reference epoch of this analysis

property seeds

The list of seed candidates for this analysis

property timedeltas

Access the sequence of time stamp deltas for the time series

property uncertainties

Access the M3C2 uncertainties of this analysis

class py4dgeo.RegionGrowingAlgorithm(seed_subsampling=1, seed_candidates=None, window_width=24, window_min_size=12, window_jump=1, window_penalty=1.0, minperiod=24, height_threshold=0.0, use_unfinished=True, intermediate_saving=0, resume_from_seed=0, stop_at_seed=inf, write_nr_seeds=False, **kwargs)

Bases: RegionGrowingAlgorithmBase

property analysis

Access the analysis object that the algorithm operates on

This is only available after run has been called.

distance_measure()

Distance measure between two time series

Expected to return a function that accepts two time series and returns the distance.

filter_objects(obj)

A filter for objects produced by the region growing algorithm

find_seedpoints()

Calculate seedpoints for the region growing algorithm

run(analysis, force=False)

Calculate the _segmentation

Parameters:

• analysis (py4dgeo.segmentation.SpatiotemporalAnalysis) – The analysis object we are working with.

• force – Force recalculation of results. If false, some intermediate results will be restored from the analysis object instead of being recalculated.

seed_sorting_scorefunction()

Neighborhood similarity sorting function

py4dgeo.regular_corepoint_grid(lowerleft, upperright, num_points, zval=0.0)

A helper function to create a regularly spaced grid for the analysis

Parameters:

• lowerleft (np.ndarray) – The lower left corner of the grid. Given as a 2D coordinate.

• upperright (np.ndarray) – The upper right corner of the grid. Given as a 2D coordinate.

• num_points (tuple) – A tuple with two entries denoting the number of points to be used in x and y direction

• zval (double) – The value to fill for the z-direction.

py4dgeo.set_py4dgeo_logfile(filename)

Set the logfile used by py4dgeo

All log messages produced by py4dgeo are logged into this file in addition to be logged to stdout/stderr. By default, that file is called ‘py4dgeo.log’.

Parameters:

filename (str) – The name of the logfile to use

py4dgeo.set_memory_policy(policy: MemoryPolicy)

Globally set py4dgeo’s memory policy

For details about the memory policy, see MemoryPolicy. Use this once before performing any operations. Changing the memory policy in the middle of the computation results in undefined behaviour.

Parameters:

policy (MemoryPolicy) – The policy value to globally set

class py4dgeo.MemoryPolicy

A descriptor for py4dgeo’s memory usage policy

This can be used to describe the memory usage policy that py4dgeo should follow. The implementation of py4dgeo checks the currently set policy whenever it would make a memory allocation of the same order of magnitude as the input pointcloud or the set of corepoints. To globally set the policy, use set_memory_policy().

Currently the following policies are available:

• STRICT: py4dgeo is not allowed to do additional memory allocations. If such an allocation would be required, an error is thrown.

• MINIMAL: py4dgeo is allowed to do additional memory allocations if and only if they are necessary for a seemless operation of the library.

• COREPOINTS: py4dgeo is allowed to do additional memory allocations as part of performance trade-off considerations (e.g. precompute vs. recompute), but only if the allocation is on the order of the number of corepoints. This is the default behaviour of py4dgeo.

• RELAXED: py4dgeo is allowed to do additional memory allocations as part of performance trade-off considerations (e.g. precompute vs. recompute).

py4dgeo.get_num_threads()

Get the number of threads currently used by py4dgeo

Returns:

The number of threads

Return type:

int

py4dgeo.set_num_threads(num_threads: int)

Set the number of threads to use in py4dgeo

Parameters:

num_threads – The number of threads to use

“type num_threads: int

class py4dgeo.PBM3C2(registration_error=0.0)

Correspondence-driven plane-based M3C2 for lower uncertainty in 3D topographic change quantification.

This class implements the PBM3C2 algorithm as described in Zahs et al. (2022).

apply(apply_ids, search_radius=3.0)

Apply trained classifier to find correspondences.

get_new_ids(orig_epoch0_id=None, orig_epoch1_id=None)

Retrieve new internal segment IDs from original IDs.

get_original_ids(new_epoch0_id=None, new_epoch1_id=None)

Retrieve original segment IDs from new internal IDs.

static preprocess_epochs(epoch0, epoch1, correspondences_file)

Assign globally unique segment IDs using independent sequential numbering. Map correspondence file IDs to the new ID scheme.

Parameters

epoch0, epoch1Epoch

Input epochs with segment_id in additional_dimensions

correspondences_filestr

Path to CSV file with correspondence data

Returns

tuple

(processed_epoch0, processed_epoch1, remapped_correspondences,

epoch0_id_mapping, epoch1_id_mapping, epoch0_reverse_mapping, epoch1_reverse_mapping)

run(epoch0, epoch1, correspondences_file, apply_ids, search_radius=3.0)

Execute complete PBM3C2 workflow.

Parameters

epoch0, epoch1Epoch

Input point cloud epochs with segment_id

correspondences_filestr

Path to CSV with training correspondences

apply_idsarray-like

Segment IDs to find correspondences for (using original IDs)

search_radiusfloat

Spatial search radius in meters

Returns

DataFrame

Correspondences with distances and uncertainties (using original IDs)

train(correspondences)

Train Random Forest classifier on labeled correspondences.

visualize_correspondences(epoch0_segment_id=None, use_original_ids=True, show_all=False, num_samples=10, figsize=(12, 10), elev=30, azim=45)

Visualize matched plane segments and their correspondences.

Parameters

epoch0_segment_idint, optional

Specific segment ID to visualize (original or new ID based on use_original_ids)

use_original_idsbool, optional

If True, interpret epoch0_segment_id as original ID (default: True)

show_allbool, optional

Plot all correspondences (default: False)

num_samplesint, optional

Number of random samples if show_all=False (default: 10)

figsizetuple, optional

Figure size in inches

elevfloat, optional

Elevation angle for 3D view in degrees

azimfloat, optional

Azimuth angle for 3D view in degrees

Returns

tuple

(fig, ax) matplotlib figure and axis objects

Developer API reference

py4dgeo.epoch.as_epoch(cloud)

Create an epoch from a cloud

Idempotent operation to create an epoch from a cloud.

py4dgeo.epoch.normalize_timestamp(timestamp)

Bring a given timestamp into a standardized Python format

class py4dgeo.m3c2.M3C2LikeAlgorithm(epochs: Tuple[Epoch, ...] | None = None, corepoints: ndarray | None = None, cyl_radii: List | None = None, cyl_radius: float | None = None, max_distance: float = 0.0, registration_error: float = 0.0, robust_aggr: bool = False)

calculate_distances(epoch1, epoch2, searchtree: str | None = None)

Calculate the distances between two epochs

callback_distance_calculation()

The callback used to calculate the distance between two point clouds

callback_workingset_finder()

The callback used to determine the point cloud subset around a corepoint

directions()

The normal direction(s) to use for this algorithm.

run()

Main entry point for running the algorithm

class py4dgeo.fallback.PythonFallbackM3C2(normal_radii: List[float] | None = None, orientation_vector: ndarray = array([0, 0, 1]), corepoint_normals: ndarray | None = None, cloud_for_normals: Epoch | None = None, **kwargs)

Bases: M3C2

An implementation of M3C2 that makes use of Python fallback implementations

calculate_distances(epoch1, epoch2, searchtree: str | None = None)

Calculate the distances between two epochs

callback_distance_calculation()

The callback used to calculate the distance between two point clouds

callback_workingset_finder()

The callback used to determine the point cloud subset around a corepoint

directions()

The normal direction(s) to use for this algorithm.

run()

Main entry point for running the algorithm

class py4dgeo.segmentation.RegionGrowingAlgorithmBase(neighborhood_radius=1.0, thresholds=[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9], min_segments=20, max_segments=None)

property analysis

Access the analysis object that the algorithm operates on

This is only available after run has been called.

distance_measure()

Distance measure between two time series

Expected to return a function that accepts two time series and returns the distance.

filter_objects(obj)

A filter for objects produced by the region growing algorithm

Objects are discarded if this method returns False.

find_seedpoints()

Calculate seedpoints for the region growing algorithm

run(analysis, force=False)

Calculate the _segmentation

Parameters:

• analysis (py4dgeo.segmentation.SpatiotemporalAnalysis) – The analysis object we are working with.

• force – Force recalculation of results. If false, some intermediate results will be restored from the analysis object instead of being recalculated.

seed_sorting_scorefunction()

A function that computes a score for a seed candidate

This function is used to prioritize seed candidates.

class py4dgeo.segmentation.RegionGrowingSeed(index, start_epoch, end_epoch)

class py4dgeo.segmentation.ObjectByChange(data, seed, analysis=None)

Representation a change object in the spatiotemporal domain

property end_epoch

The index of the end epoch of the change object

property indices

The set of corepoint indices that compose the object by change

plot(filename=None)

Create an informative visualization of the Object By Change

Parameters:

filename (str) – The filename to use to store the plot. Can be omitted to only show plot in a Jupyter notebook session.

property start_epoch

The index of the start epoch of the change object

property threshold

The distance threshold that produced this object

py4dgeo.segmentation.check_epoch_timestamp(epoch)

Validate an epoch to be used with SpatiotemporalSegmentation

class py4dgeo.util.Py4DGeoError(msg, loggername='py4dgeo')

py4dgeo.util.find_file(filename, fatal=True)

Find a file of given name on the file system.

This function is intended to use in tests and demo applications to locate data files without resorting to absolute paths. You may use it for your code as well.

It looks in the following locations:

• If an absolute filename is given, it is used

• Check whether the given relative path exists with respect to the current working directory

• Check whether the given relative path exists with respect to the specified XDG data directory (e.g. through the environment variable XDG_DATA_DIRS).

• Check whether the given relative path exists in downloaded test data.

• If still not found, attempt to download test data and search again.

Parameters:

• filename (str) – The (relative) filename to search for

• fatal (bool) – Whether not finding the file should be a fatal error

Returns:

An absolute filename

py4dgeo.util.as_double_precision(arr: ndarray, policy_check=True)

Ensure that a numpy array is double precision

This is a no-op if the array is already double precision and makes a copy if it is not. It checks py4dgeo’s memory policy before copying.

Parameters:

arr (np.ndarray) – The numpy array

py4dgeo.util.make_contiguous(arr: ndarray)

Make a numpy array contiguous

This is a no-op if the array is already contiguous and makes a copy if it is not. It checks py4dgeo’s memory policy before copying.

Parameters:

arr (np.ndarray) – The numpy array

py4dgeo.util.memory_policy_is_minimum(policy: MemoryPolicy)

Whether or not the globally set memory policy is at least the given one

Parameters:

policy (MemoryPolicy) – The policy value to compare against

Returns:

Whether the globally set policy is at least the given one

Return type:

bool

py4dgeo.util.append_file_extension(filename, extension)

Append a file extension if and only if the original filename has none

py4dgeo.util.is_iterable(obj)

Whether the object is an iterable (excluding a string)

py4dgeo.logger.create_default_logger(filename=None)

py4dgeo.logger.logger_context(msg, level=20)