Functions

This page contains an index of the functions present in the package and a description of them.

Voxelization

dendromatics.voxel.voxel.voxelate(cloud, resolution_xy, resolution_z, n_digits=5, X_field=0, Y_field=1, Z_field=2, with_n_points=True, silent=False)[source]

Function used to voxelate point clouds. It allows to use a different resolution for (z), but (x, y) will always share the same resolution. It also allows to revert the process, by creating a unique code for each point in the point cloud, thus voxelated cloud can be seamlessly reverted to the original point cloud.

Parameters:

cloud (numpy.ndarray) – The point cloud to be voxelated. It is expected to have X, Y, Z fields. 3D or higher array containing data with float type.
resolution_xy (float) – (x, y) voxel resolution.
resolution_z (float) –
1. voxel resolution.
n_digits (int) – Number of digits dedicated to each coordinate ((x), (y) or (z)) during the generation of each point code. Defaults to 5.
X_field (int) – Index at which (x) coordinate is stored. Defaults to 0.
Y_field (int) – Index at which (y) coordinate is stored. Defaults to 1.
Z_field (int) – Index at which (z) coordinate is stored. Defaults to 2.
with_n_points (boolean) – If True, output voxelated cloud will have a field including the number of points that each voxel contains. Defaults to True.

Returns:

voxelated_cloud (numpy.ndarray) – The voxelated cloud. It consists of 3 columns, each with (x), (y) and (z) coordinates, and an optional 4th column having the number of points included in each voxel if with_n_points = True.
vox_to_cloud_ind (numpy.ndarray) – Vector containing the indexes to revert to the original point cloud from the voxelated cloud.
cloud_to_vox_ind (numpy.ndarray) – Vector containing the indexes to directly go from the original point cloud to the voxelated cloud.

Height-normalization

dendromatics.ground.check_normalization(cloud, original_area, res_xy=1.0, z_min=-0.1, z_max=0.15, warning_thresh=0.1)[source]

Compare the area of a slice of points from a point cloud to another area and store a warning indicator if difference is greater than a certain threshold. Area of the slice will be approximated from a voxelated version of it. This function is kept for backward compatibility and call check_normalization_discrepancy under the hood.

Parameters:

cloud (numpy.ndarray) – A 2D numpy array storing the point cloud. It must be a normalized point cloud.
original_area (float) – Area to compare with.
res_xy (float) – (x, y) voxel resolution. Defaults to 1.0 m.
z_min (float) – The minimum Z value that defines the slice. Defaults to -0.10 m.
z_max (float) – The maximum Z value that defines the slice. Defaults to 0.15 m.
warning_thresh (float) – Threshold area difference. Defaults to 0.1 (10 % difference in area).

Returns:

area_warning – True if area difference is greater than threshold, False if not.

Return type:

bool

dendromatics.ground.check_normalization_discrepancy(cloud, original_area, res_xy=1.0, z_min=-0.1, z_max=0.15, warning_thresh=0.1)[source]

Compare the area of a slice of points from a point cloud to another area and return a warning indicator if difference is greater than a certain threshold. The percentage of discrepancy between the too area is also returned. Area of the slice will be approximated from a voxelated version of it.

Parameters:

cloud (numpy.ndarray) – A 2D numpy array storing the point cloud. It must be a normalized point cloud.
original_area (float) – Area to compare with.
res_xy (float) – (x, y) voxel resolution. Defaults to 1.0 m.
z_min (float) – The minimum Z value that defines the slice. Defaults to -0.10 m.
z_max (float) – The maximum Z value that defines the slice. Defaults to 0.15 m.
warning_thresh (float) – Threshold area difference. Defaults to 0.1 (10 % difference in area).

Returns:

area_warning (bool) – True if area difference is greater than threshold, False if not.
difference_percentage – The percentage of discrepancy between the original area and the slice area.

dendromatics.ground.clean_cloth(dtm_points)[source]

This function takes a Digital Terrain Model (DTM) and denoises it. This denoising is done via a 2 MADs criterion from the median height value of a neighbourhood of size 15.

Parameters:: dtm_points (numpy.ndarray) – Matrix containing (x, y, z) coordinates of the DTM points.
Returns:: clean_points – Matrix containing (x, y, z) coordinates of the denoised DTM points.
Return type:: numpy.ndarray

dendromatics.ground.clean_ground(cloud, res_ground=0.15, min_points=2)[source]

This function takes a point cloud and denoises it via DBSCAN clustering. It first voxelates the point cloud, then it clusters the voxel cloud and excludes clusters of size less than the value determined by min_points.

Parameters:

cloud (numpy.ndarray) – The point cloud to be denoised. Matrix containing (x, y, z) coordinates of the points.
res_ground (float) – (x, y, z) voxel resolution in meters. Defaults to 0.15.
min_points (int) – Clusters with size smaller than this value will be regarded as noise and thus eliminated from the point cloud. Defaults to 2.

Returns:

clust_cloud – The denoised point cloud. Matrix containing (x, y, z) coordinates of the denoised points.

Return type:

numpy.ndarray

dendromatics.ground.complete_dtm(dtm_points)[source]

This function uses scipy.interpolate.griddata to interpolate the missing values in a Digital Terrain Model (DTM).

Parameters:: dtm_points (numpy array) – Matrix containing (x, y, z) coordinates of the DTM points.
Returns:: completed_dtm – Matrix containing (x, y, z) coordinates of the completed DTM points.
Return type:: numpy.ndarray

dendromatics.ground.generate_dtm(cloud, bSloopSmooth=True, cloth_resolution=0.5, classify_threshold=0.1)[source]

This function takes a point cloud and generates a Digital Terrain Model (DTM) based on its ground. It’s based on ‘Cloth Simulation Filter’ by W. Zhang et al., 2016 (http://www.mdpi.com/2072-4292/8/6/501/htm), which is implemented in CSF package. This function just implements it in a convenient way for this use-case.

Parameters:

cloud (numpy.ndarray) – The point cloud. Matrix containing (x, y, z) coordinates of the points.
bSloopSmooth (Boolean) – The resulting DTM will be smoothed. Refer to CSF documentation. Defaults to True.
cloth_resolution (float) – The resolution of the cloth grid. Refer to CSF documentation. Defaults to 0.5.
classify_threshold (float) – The height threshold used to classify the point cloud into ground and non-ground parts. Refer to CSF documentation. Defaults to 0.1.

Returns:

cloth_nodes – Matrix containing (x, y, z) coordinates of the DTM points.

Return type:

numpy.ndarray

dendromatics.ground.normalize_heights(cloud, dtm_points)[source]

This function takes a point cloud and a Digital Terrain Model (DTM) and normalizes the heights of the first based on the second.

Parameters:

cloud (numpy.ndarray) – Matrix containing (x, y, z) coordinates of the point cloud.
dtm_points (numpy array) – Matrix containing (x, y, z) coordinates of the DTM points.

Returns:

zs_diff_triples – Vector containing the normalized height values for the cloud points.

Return type:

numpy.ndarray

Stem extraction

dendromatics.stripe.verticality_clustering(stripe, scale=0.1, vert_treshold=0.7, n_points=1000, n_iter=2, resolution_xy=0.02, resolution_z=0.02, n_digits=5)[source]

This function implements a for loop that iteratively calls verticality_clustering_iteration, ‘peeling off’ the stems.

Parameters:

stripe (numpy.ndarray) – The point cloud containing the stripe. It is expected to have X, Y, Z0 fields. 3D or higher array containing data with float type.
scale (float) – Scale to be used during verticality computation to define a neighbourhood around a given point. Verticality will be computed from the structure tensor of said neighbourhood via eigendecomposition. Defaults to 0.1.
vert_threshold (float) – Minimum verticality value associated to a point to consider it as part of a stem. Defaults to 0.7.
n_points (int) – Minimum number of points in a cluster for it to be considered as a potential stem. Defaults to 1000.
n_iter (int) – Number of iterations of ‘peeling’. Defaults to 2.
resolution_xy (float) – (x, y) voxel resolution. Defaults to 0.02.
resolution_z (float) –
1. voxel resolution. Defaults to 0.02.
n_digits (int) – Number of digits dedicated to each coordinate ((x), (y) or (z)) during the generation of each point code. Defaults to 5.

Returns:

clust_stripe – Point cloud containing the points from the stripe that are considered as stems. It consists of 4 columns: (x), (y) and (z) coordinates, and a 4th column containing the cluster ID of the cluster that each point belongs to.

Return type:

numpy.ndarray

dendromatics.stripe.verticality_clustering_iteration(stripe, vert_scale, vert_treshold, n_points, resolution_xy, resolution_z, n_digits)[source]

This function is to be used internally by verticality_clustering. The intended use of this function is to accept a stripe as an input, defined this as a subset of the original cloud delimited by a lower height and an upper height, which will narrow down a region where it is expected to only be stems. Then it will voxelate those points and compute the verticality via compute_features() from jakteristics. It will filter points based on their verticality value, voxelate again and then cluster the remaining points. Those are expected to belong to stems.

Parameters:

stripe (numpy.ndarray) – The point cloud containing the stripe. It is expected to have X, Y, Z0 fields. 3D or higher array containing data with float type.
vert_scale (float) – Scale to be used during verticality computation to define a neighbourhood around a given point. Verticality will be computed from the structure tensor of said neighbourhood via eigendecomposition.
vert_threshold (float) – Minimum verticality value associated to a point to consider it as part of a stem.
n_points (int) – Minimum number of points in a cluster for it to be considered as a potential stem.
resolution_xy (float) – (x, y) voxel resolution.
resolution_z (float) –
1. voxel resolution.
n_digits (int) – Number of digits dedicated to each coordinate ((x), (y) or (z)) during the generation of each point code.

Returns:

clust_stripe (numpy.ndarray) – Point cloud containing the points from the stripe that are considered as stems. It consists of 4 columns: (x), (y) and (z) coordinates, and a 4th column containing the cluster ID of the cluster that each point belongs to.
t1 (float) – Time spent.

Tree individualization

dendromatics.individualize.compute_axes(voxelated_cloud, clust_stripe, stripe_lower_limit, stripe_upper_limit, h_range, min_points, d_max, X_field, Y_field, Z_field, Z0_field, tree_id_field, progress_hook=None)[source]

Function used inside individualize_trees during tree individualization process. It identifies tree axes. It expects a voxelated version of the point cloud and a filtered (based on the verticality clustering process) stripe as input, so that it only contains (hopefully) stems. Those stems are isolated and enumerated, and then, their axes are identified using PCA (PCA1 direction). This allows to group points based on their distance to those axes, thus assigning each point to a tree.

It requires a height-normalized cloud in order to function properly.

Parameters:

voxelated_cloud (numpy.ndarray) – The voxelated point cloud. It is expected to have X, Y, Z and Z0 fields.
clust_stripe (numpy.ndarray) – The point cloud containing the clusterized stripe (the stems) from verticality_clustering.
stripe_lower_limit (float) – Lower (vertical) limit of the stripe (units is meters). Defaults to 0.7.
stripe_upper_limit (float) – Upper (vertical) limit of the stripe (units is meters). Defaults to 3.5.
h_range (float) – Only stems where points extend vertically throughout a range as tall as defined by h_range are considered.
min_points (int) – Minimum number of points in a cluster for it to be considered as a potential stem
d_max (float) – Points that are closer than d_max to an axis are assigned to that axis.
X_field (int) – Index at which (x) coordinates are stored.
Y_field (int) – Index at which (y) coordinates are stored.
Z_field (int) – Index at which (z) coordinates are stored.
Z0_field (int) – Index at which (z0) coordinates are stored.
tree_id_field (int) – Index at which cluster ID is stored.
progress_hook (callable, optional) – A hook that take two int, the first is the current number of iteration and the second is the targetted number iteration. Defaults to None.

Returns:

detected_trees (numpy.ndarray) – Matrix with as many rows as trees, containing a description of each individualized tree. It stores the following values: tree ID, PCA1 X value, PCA1 Y value, PCA1 Z value, stem centroid X value, stem centroid Y value, stem centroid Z value, height difference of stem centroid (z - z0), axis vertical deviation.
dist_to_axis (numpy.ndarray) – Matrix containing the distance from each point to the closest axis.
tree_id_vector (numpy.ndarray) – Vector containing the tree IDs.

dendromatics.individualize.compute_heights(voxelated_cloud, detected_trees, dist_to_axis, tree_id_vector, d, max_dev, resolution_heights, n_digits, X_field, Y_field, Z_field)[source]

Function used inside individualize_trees during tree individualization process. It measures tree heights. The function creates a large-resolution voxel cloud to and filters voxels containing few points. This has the purpose to discard any outlier point that might be over the trees, to then identify the highest point within the remaining voxels.

It requires a height-normalized cloud in order to function properly.

Parameters:

voxelated_cloud (numpy.ndarray) – The voxelated point cloud. It is expected to have X, Y, Z and Z0 fields.
detected_trees (numpy.ndarray) – See compute_axes.
dist_to_axis (numpy.ndarray) – See compute_axes.
tree_id_vector (numpynd.array) – See compute_axes.
d (float) – Points within this distance from tree axis will be considered as potential points to define tree height.
max_dev (float) – Maximum degree of vertical deviation of a tree axis to consider its tree height measurement as valid.
resolution_heights (float) – (x, y, z) voxel resolution.
n_digits (int) – Number of digits dedicated to each coordinate ((x), (y) or (z)) during the generation of each point code.
X_field (int) – Index at which (x) coordinates are stored.
Y_field (int) – Index at which (y) coordinates are stored.
Z_field (int) – Index at which (z) coordinates are stored.

Returns:

tree_heights – Matrix containing (x, y, z) coordinates of each tree’s highest point, as well as its normalized height and a binary field stating if the axis was deviated (1) or if it was not (0).

Return type:

numpy.ndarray

dendromatics.individualize.individualize_trees(cloud, clust_stripe, resolution_z=0.035, resolution_xy=0.035, stripe_lower_limit=0.7, stripe_upper_limit=3.5, h_range=1.2, d_max=1.5, min_points=20, d=15, max_dev=25, resolution_heights=0.3, n_digits=5, X_field=0, Y_field=1, Z_field=2, Z0_field=3, tree_id_field=-1, progress_hook=None)[source]

This function expects a filtered (based on the clustering process) stripe as input, so that it only contains (hopefully) stems. Those stems are voxelated and enumerated, and then, their axes are identified using PCA (PCA1 direction). This allows to group points based on their distance to those axes, thus assigning each point to a tree. This last step is applied to the WHOLE original cloud. It also measures tree heights.

It requires a height-normalized cloud in order to function properly.

Parameters:

cloud (numpy.ndarray) – The point cloud. It is expected to have X, Y, Z and Z0 fields.
clust_stripe (numpy.ndarray.) – The point cloud containing the clusterized stripe from verticality_clustering. It is expected to have X, Y, Z0 and cluster ID fields.
resolution_z (float) – (x, y) voxel resolution in meters. Defaults to 0.035.
resolution_xy (float) –
1. voxel resolution in meters. Defaults to 0.035.
stripe_lower_limit (float) – Lower (vertical) limit of the stripe (units is meters). Defaults to 0.7.
stripe_upper_limit (float) – Upper (vertical) limit of the stripe (units is meters). Defaults to 3.5.
h_range (float) – Only stems where points extend vertically throughout a range as tall as defined by h_range are considered (units is meters). Defaults to 1.2.
d_max (float) – Points that are closer than d_max to an axis are assigned to that axis (units is meters). Defaults to 1.5.
min_points (int) – Minimum number of points in a cluster for it to be considered as a potential stem. Defaults to 20.
d (float) – Points within this distance from tree axis will be considered as potential points to define tree height (units is meters). Defaults to 15.
max_dev (float) – Maximum degree of vertical deviation of a tree axis to consider its tree height measurement as valid (units is sexagesimal degrees). Defaults to 25.
n_digits (int) – Number of digits dedicated to each coordinate ((x), (y) or (z)) during the generation of each point code. Defaults to 5.
resolution_heights (float) – (x, y, z) voxel resolution in meters used during height computation. Defaults to 0.3
X_field (int) – Index at which (x) coordinate is stored. Defaults to 0.
Y_field (int) – Index at which (y) coordinate is stored. Defaults to 1.
Z_field (int) – Index at which (z) coordinate is stored. Defaults to 2.
Z0_field (int) – Index at which (z0) coordinate is stored. Defaults to 3.
tree_id_field (int) – Index at which cluster ID is stored. Defaults to -1.
progress_hook (callable, optional) – A hook that take two int, the first is the current number of iteration and the second is the targetted number iteration. Defaults to None.

Returns:

assigned_cloud (numpy.ndarray) – Point cloud containing individualized trees. It consists of (x), (y), (z) and (z0) coordinates, a 5th column containing tree ID that each point belongs to and a 6th column containing point distance to closest axis.
detected_trees (numpy.ndarray) – Matrix with as many rows as trees, containing a description of each individualized tree. It stores tree ID, PCA1 X value, PCA1 Y value, PCA1 Z value, stem centroid X value, stem centroid Y value, stem centroid Z value, height difference of stem centroid (z - z0), axis vertical deviation.
tree_heights (numpy.ndarray) – Matrix containing the heights of individualized trees. It consists of (x), (y), (z) and (z0) coordinates of the highest point of the tree and a 5th column containing a binary indicator: 0 - tree was too deviated from vertical, and height may not be accurate, or 1 - tree was not too deviated from vertical, thus height may be trusted.

Computing sections

dendromatics.sections.compute_sections(stems, sections, section_width=0.02, times_R=0.5, threshold=5, R_min=0.03, R_max=0.5, max_dist=0.02, n_points_section=80, n_sectors=16, min_n_sectors=9, width=2, X_field=0, Y_field=1, Z0_field=3, tree_id_field=4, progress_hook=None)[source]

This function calls fit_circle_check() to compute stem diameter at given sections.

Parameters:

stems (numpy.ndarray) – Point cloud containing the individualized trees. It is expected to have X, Y, Z0 and tree_ID fields.
sections (numpy.ndarray) – Matrix containing a range of height values at which sections will be computed.
section_width (float) – Points within this distance from any sections value will be considered as belonging to said section (units is meters). Defaults to 0.02.
times_R (float) – Refer to fit_circle_check. Defaults to 0.5.
threshold (float) – Refer to fit_circle_check. Defaults to 5.
R_min (float) – Refer to fit_circle_check. Defaults to 0.03.
R_max (float) – Refer to fit_circle_check. Defaults to 0.5.
max_dist (float) – Refer to fit_circle_check. Defaults to 0.02.
n_points_section (int) – Refer to fit_circle_check. Defaults to 80.
n_sectors (int) – Refer to fit_circle_check. Defaults to 16.
min_n_sectors (int) – Refer to fit_circle_check. Defaults to 9.
width (float) – Refer to fit_circle_check. Defaults to 2.0.
X_field (int) – Index at which (x) coordinate is stored. Defaults to 0.
Y_field (int) – Index at which (y) coordinate is stored. Defaults to 1.
Z0_field (int) – Index at which (z0) coordinate is stored. Defaults to 3.
tree_id_field (int) – Index at which cluster ID is stored. Defaults to 4.
progress_hook (callable, optional) – A hook that take two int, the first is the current number of iteration and the second is the targetted number iteration. Defaults to None.

Returns:

X_c (numpy.ndarray) – Matrix containing (x) coordinates of the center of the best-fit circles.
Y_c (numpy.ndarray) – Matrix containing (y) coordinates of the center of the best-fit circles.
R (numpy.ndarray) – Vector containing best-fit circle radii.
section_perct (numpy.ndarray) – Matrix containing the percentage of occupied sectors.
n_points_in (numpy.ndarray) – Matrix containing the number of points in the inner circles.

dendromatics.sections.fit_circle(X, Y)[source]

This function fits points within a tree section into a circle by least squares minimization. It is to be used inside fit_circle_check().

Parameters:

X (numpy.ndarray) – Vector containing (x) coordinates of points belonging to a tree section.
Y (numpy.ndarray) – Vector containing (y) coordinates of points belonging to a tree section.

Returns:

circle_c (numpy.ndarray) – Matrix containing the (x, y) coordinates of the circle center.
mean_radius (numpy.ndarray) – Vector containing the radius of each fitted circle (units is meters).

dendromatics.sections.fit_circle_check(X, Y, review, second_time, times_R, threshold, R_min, R_max, max_dist, n_points_section, n_sectors, min_n_sectors, width)[source]

This function calls fit_circle() to fit points within a section to a circle by least squares minimization. These circles will define tree sections. It checks the goodness of fit using sector_occupancy and inner_circle. If fit is not appropriate, another circle will be fitted using only points from the largest cluster inside the first circle.

Parameters:

X (numpy.ndarray) – Vector containing (x) coordinates of points belonging to a tree section.
Y (numpy.ndarray) – Vector containing (y) coordinates of points belonging to a tree section.
second_time (numpy.ndarray) – Vector containing integers that indicates whether it is the first time a circle is fitted or not (will be modified internally).
times_R (float) – Ratio of radius between outer circle and inner circle.
threshold (float) – Minimum number of points in inner circle for a fitted circle to be valid.
R_min (float) – Minimum radius that a fitted circle must have to be valid.
R_max (float) – Maximum radius that a fitted circle must have to be valid.
max_dist (float) – Max separation among the points to be considered as members of the same cluster.
n_points_section (int) – Minimum points within a section for its fitted circle to be valid.
n_sectors (int) – Number of sectors in which sections will be divided.
min_n_sectors (int) – Minimum number of occupied sectors in a section for its fitted circle to be considered as valid.
width (float) – Width around the fitted circle to look for points (units is milimeters).

Returns:

X_gs (numpy.ndarray) – Matrix containing (x) coordinates of largest clusters.
Y_gs (numpy.ndarray) – Matrix containing (y) coordinates of largest clusters.
X_c (numpy.ndarray) – Matrix containing (x) coordinates of the center of the best-fit circles.
Y_c (numpy.ndarray) – Matrix containing (y) coordinates of the center of the best-fit circles.
R (numpy.ndarray) – Vector containing best-fit circle radii.
section_perct (numpy.ndarray) – Matrix containing the percentage of occupied sectors.
n_points_in (numpy.ndarray) – Matrix containing the number of points in the inner circle.

dendromatics.sections.inner_circle(X, Y, X_c, Y_c, R, times_R)[source]

Function that computes an internal circle inside the one fitted by fit_circle. This new circle is used as a validation tool and it gives insight on the quality of the ‘fit_circle-circle’.

If points are closest to the inner circle, then the first fit was not appropiate

On the contrary, if points are closer to the outer circle, the ‘fit_circle-circle’ is appropiate and describes well the stem diameter.

Instead of directly computing the inner circle, it just takes a proportion (less than one) of the original circle radius and its center. Then, it just checks how many points are closest to the inner circle than to the original circle.

Parameters:

X (numpy.ndarray) – Vector containing (x) coordinates of points belonging to a tree section.
Y (numpy.ndarray) – Vector containing (y) coordinates of points belonging to a tree section.
X_c (numpy.ndarray)
circles. (Vector containing (x) coordinates of fitted)
Y_c (numpy.ndarray) – Vector containing (y) coordinates of fitted circles.
R (numpy.ndarray) – Vector containing the radii of the fitted circles.

Returns:

n_points_in – Vector containing the number of points inside the inner circle of each section.

Return type:

numpy.ndarray

dendromatics.sections.point_clustering(X, Y, max_dist)[source]

This function clusters points by distance and finds the largest cluster. It is to be used inside fit_circle_check().

Parameters:

X (numpy.ndarray) – Vector containing (x) coordinates of points belonging to a tree section.
Y (numpy.ndarray) – Vector containing (y) coordinates of points belonging to a tree section.
max_dist (float) – Max separation among the points to be considered as members of the same cluster.

Returns:

X_g (numpy.ndarray) – Vector containing the (x) coordinates of the largest cluster.
Y_g (numpy.ndarray) – Vector containing the (y) coordinates of the largest cluster.

dendromatics.sections.sector_occupancy(X, Y, X_c, Y_c, R, n_sectors, min_n_sectors, width)[source]

This function provides quality measurements for the fitting of the circle. It divides the section in a number of sectors to check if there are points within them (so they are occupied). If there are not enough occupied sectors, the section fails the test, as it is safe to asume it has an anomale, non desirable structure.

Parameters:

X (numpy.ndarray) – Vector containing (x) coordinates of points belonging to a tree section.
Y (numpy.ndarray) – Vector containing (y) coordinates of points belonging to a tree section.
X_c (numpy.ndarray) – Vector containing (x) coordinates of fitted circles.
Y_c (numpy.ndarray) – Vector containing (y) coordinates of fitted circles.
R (numpy.ndarray) – Vector containing the radii of the fitted circles.
n_sectors (int) – Number of sectors in which sections will be divided.
min_n_sectors (int) – Minimum number of occupied sectors in a section for its fitted circle to be considered as valid.
width (float) – Width around the fitted circle to look for points (units is meters).

Returns:

perct_occuped_sectors (numpy.ndarray) – Vector containing the percentage of occupied sectors in each section.
enough_occuped_sectors (numpy.ndarray) – Vector containing binary indicators whether the fitted circle is valid or not. 1 - valid, 0 - not valid.

dendromatics.sections.tilt_detection(X_tree, Y_tree, radius, sections, Z_field=2, w_1=3.0, w_2=1.0)[source]

This function finds outlier tilting values among sections within a tree and assigns a score to the sections based on those outliers. Two kinds of outliers are considered.

Absolute outliers are obtained from the sum of the deviations from every section center to all axes within a tree (the most tilted sections relative to all axes)

Relative outliers are obtained from the deviations of other section centers from a certain axis, within a tree (the most tilted sections relative to a certain axis)

The ‘outlier score’ consists on a weighted sum of the absolute tilting value and the relative tilting value.

Parameters:

X_tree (numpy.ndarray) – Matrix containing (x) coordinates of the center of the sections.
Y_tree (numpy.ndarray) – Matrix containing (y) coordinates of the center of the sections.
radius (numpy.ndarray) – Vector containing section radii.
sections (numpy.ndarray) – Vector containing the height of the section associated to each section.
Z_field (int) – Index at which (z) coordinate is stored. Defaults to 2.
w_1 (float) – Weight of absolute deviation. Defaults to 3.0.
w_2 (float) – Weight of relative deviation. Defaults to 1.0.

Returns:

outlier_prob – Vector containing the ‘outlier probability’ of each section.

Return type:

numpy.ndarray

dendromatics.sections.tree_locator(sections, X_c, Y_c, tree_vector, sector_perct, R, outliers, n_points_in, threshold=5, X_field=0, Y_field=1, Z_field=2)[source]

This function generates points that locate the individualized trees and computes their DBH (diameter at breast height). It uses all the quality measurements defined in previous functions to check whether the DBH should be computed or not and to check which point should be used as the tree locator.

The tree locators are then saved in a LAS file. Each tree locator corresponds on a one-to-one basis to the individualized trees.

Parameters:

sections (numpy.ndarray) – Vector containing section heights (normalized heights).
X_c (numpy.ndarray) – Matrix containing (x) coordinates of the center of the sections.
Y_c (numpy.ndarray) – Matrix containing (y) coordinates of the center of the sections.
tree_vector (numpy.ndarray) – detected_trees output from individualize_trees.
sector_perct (numpy.ndarray) – Matrix containing the percentage of occupied sectors.
R (numpy.ndarray) – Vector containing section radii.
outliers (numpy.ndarray) – Vector containing the ‘outlier probability’ of each section.
n_points_in (numpy.ndarray) – Matrix containing the number of points in the inner circles.
threshold (float) – Minimum number of points in inner circle for a fitted circle to be valid. Defaults to 5.
X_field (int) – Index at which (x) coordinate is stored. Defaults to 0.
Y_field (int) – Index at which (y) coordinate is stored. Defaults to 1.
Z_field (int) – Index at which (z) coordinate is stored. Defaults to 2.

Returns:

dbh_values (numpy.ndarray) – Vector containing DBH values.
tree_locations (numpy.ndarray) – Matrix containing (x, y, z) coordinates of each tree locator.

Drawing LAS files

dendromatics.draw.draw_axes(tree_vector, filename_las, line_downstep=0.5, line_upstep=10.0, stripe_lower_limit=0.5, stripe_upper_limit=2.5, point_interval=0.01)[source]

This function generates points that comprise the axes computed by individualize_trees, so that they can be visualized. The axes are then saved in a LAS file, along some descriptive fields. Each axis corresponds on a one-to-one basis to the individualized trees.

Parameters:

tree_vector (numpy.ndarray) – detected_trees output from individualize_trees.
filename_las (char) – File name for the output file
line_downstep (float) – From the stripe centroid, how much (downwards direction) will the drawn axes extend (units is meters). Defaults to 0.5.
line_upstep (float) – From the stripe centroid, how much (upwards direction) will the drawn axes extend (units is meters). Defaults to 10.0.
stripe_lower_limit (float) – Lower (vertical) limit of the stripe (units is meters). Defaults to 0.5.
stripe_upper_limit (float) – Upper (vertical) limit of the stripe (units is meters). Defaults to 2.5.
point_interval (float) – Step value used to draw points (unit is meters). Defaults to 0.01..

dendromatics.draw.draw_circles(X_c, Y_c, R, sections, check_circle, sector_perct, n_points_in, tree_vector, outliers, filename_las, R_min=0.03, R_max=0.5, threshold=5, n_sectors=16, min_n_sectors=9, circa_points=200)[source]

This function generates points that comprise the circles computed by fit_circle_check function, so sections can be visualized. The circles are then saved in a LAS file, along some descriptive fields. Each circle corresponds on a one-to-one basis to the sections described by the user.

Parameters:

X_c (numpy.ndarray) – Matrix containing (x) coordinates of the center of the sections.
Y_c (numpy.ndarray) – Matrix containing (y) coordinates of the center of the sections.
R (numpy.ndarray) – Vector containing section radia.
sections (numpy.ndarray) – Vector containing section heights (normalized heights).
section_perct (numpy.ndarray) – Matrix containing the percentage of occupied sectors.
n_points_in (numpy.ndarray) – Matrix containing the number of points in the inner circumferences.
tree_vector (numpy.ndarray) – detected_trees output from individualize_trees.
outliers (numpy.ndarray) – Vector containing the ‘outlier probability’ of each section.
filename_las (char) – File name for the output file.
R_min (float) – Refer to fit_circle_check in ‘sections’ module. Defaults to 0.03.
R_max (float) – Refer to fit_circle_check in ‘sections’ module. Defaults to 0.5.
threshold (float) – Refer to fit_circle_check in ‘sections’ module. Defaults to 5.
n_sectors (int) – Refer to fit_circle_check in ‘sections’ module. Defaults to 16.
min_n_sectors (int) – Refer to fit_circle_check in sections module. Defaults to 9.
circa_points (int) – Number of points used to draw each circle. Defaults to 200.

dendromatics.draw.generate_axis_cloud(tree_vector, line_downstep=0.5, line_upstep=10.0, stripe_lower_limit=0.5, stripe_upper_limit=2.5, point_interval=0.01)[source]

This function generates points that comprise the axes computed by individualize_trees, so that they can be visualized. It output two numpy.ndarray that describes the point cloud of the axis and their associated tilt.

Parameters:

tree_vector (numpy.ndarray) – detected_trees output from individualize_trees.
filename_las (char) – File name for the output file
line_downstep (float) – From the stripe centroid, how much (downwards direction) will the drawn axes extend (units is meters). Defaults to 0.5.
line_upstep (float) – From the stripe centroid, how much (upwards direction) will the drawn axes extend (units is meters). Defaults to 10.0.
stripe_lower_limit (float) – Lower (vertical) limit of the stripe (units is meters). Defaults to 0.7.
stripe_upper_limit (float) – Upper (vertical) limit of the stripe (units is meters). Defaults to 3.5.
point_interval (float) – Step value used to draw points (unit is meters). Defaults to 0.01.

Returns:

axes_point (numpy.ndarray) – Matrix that describes the point cloud of the axes
tilt (numpy.ndarray) – Matrix that describes the tilt of each axes

dendromatics.draw.generate_circles_cloud(X_c, Y_c, R, sections, check_circle, sector_perct, n_points_in, tree_vector, outliers, R_min=0.03, R_max=0.5, threshold=5, n_sectors=16, min_n_sectors=9, circa_points=200)[source]

This function generates points that comprise the circles computed by fit_circle_check function, so sections can be visualized. The circles points cloud along with their associated meta data are retuned as a Matrix (numpy.ndarray)

Parameters:

X_c (numpy.ndarray) – Matrix containing (x) coordinates of the center of the sections.
Y_c (numpy.ndarray) – Matrix containing (y) coordinates of the center of the sections.
R (numpy.ndarray) – Vector containing section radia.
sections (numpy.ndarray) – Vector containing section heights (normalized heights).
section_perct (numpy.ndarray) – Matrix containing the percentage of occupied sectors.
n_points_in (numpy.ndarray) – Matrix containing the number of points in the inner circumferences.
tree_vector (numpy.ndarray) – detected_trees output from individualize_trees.
outliers (numpy.ndarray) – Vector containing the ‘outlier probability’ of each section.
R_min (float) – Refer to fit_circle_check in ‘sections’ module. Defaults to 0.03.
R_max (float) – Refer to fit_circle_check in ‘sections’ module. Defaults to 0.5.
threshold (float) – Refer to fit_circle_check in ‘sections’ module. Defaults to 5.
n_sectors (int) – Refer to fit_circle_check in ‘sections’ module. Defaults to 16.
min_n_sectors (int) – Refer to fit_circle_check in sections module. Defaults to 9.
circa_points (int) – Number of points used to draw each circle. Defaults to 200.

Returns:

coords – Matrix containing the circles coordinates and their associated meta data

Return type:

numpy.ndarray