pointtree.operations

Algorithms for tree instance segmentation.

pointtree.operations.cloth_simulation_filtering(
coords: ndarray[Any, dtype[float64]],
classification_threshold: float,
resolution: float,
rigidness: int,
correct_steep_slope: bool = False,
iterations: int = 100,
) → ndarray[Any, dtype[int64]][source]

Detects ground points using the Cloth Simulation Filtering (CSF) algorithm proposed in Zhang, Wuming, et al. “An Easy-to-Use Airborne LiDAR Data Filtering Method Based on Cloth Simulation.” Remote Sensing 8.6 (2016): 501.

Parameters:

  • coords – Point coordinates.

  • classification_threshold – Maximum height above the cloth a point can have in order to be classified as terrain point. All points whose distance to the cloth is equal or below this threshold are classified as terrain points.

  • resolution – Resolution of the cloth grid (in meter).

  • rigidness – Rigidness of the cloth (the three levels 1, 2, and 3 are available, where 1 is the lowest and 3 the highest rigidness).

  • correct_steep_slope – Whether the cloth should be corrected for steep slopes in a post-pressing step. Defaults to False.

  • iterations – Maximum number of iterations. Defaults to 100.

Returns:

Class IDs for each point. For terrain points, the class ID is set to 0 and for non-terrain points to 1.

Raises:

ValueError – If rigidness is not 1, 2, or 3.

Shape:

  • coords: \((N, 3)\)

  • Output: \((N)\).

where

\(N = \text{ number of points}\)
pointtree.operations.create_digital_terrain_model(
terrain_coords: ndarray[Any, dtype[float64]],
grid_resolution: float,
k: int,
p: float,
voxel_size: float | None = None,
) → Tuple[ndarray[Any, dtype[float64]], ndarray[Any, dtype[float64]]][source]

Constructs a rasterized digital terrain model (DTM) from a set of terrain points. The DTM is constructed by creating a grid of regularly arranged DTM points and interpolating the height of the \(k\) closest terrain points for each DTM point on the grid. In the interpolation, terrain points \(x_t\) are weighted with a factor proportional to a power of \(p\) of their inverse distance to the corresponding DTM point \(x_{dtm}\), i.e., \(\frac{1}{||(x_{dtm} - x_{t})||^p}\). If there are terrain points whose distance to the DTM point is zero, only these points are used to calculate the DTM height and more distant points are ignored. Before constructing the DTM, the terrain points can optionally be downsampled using voxel-based subsampling.

Parameters:

  • terrain_coords – Coordinates of the terrain points from which to construct the DTM.

  • grid_resolution – Resolution of the DTM grid (in meter).

  • k – Number of terrain points between which interpolation is performed to obtain the terrain height of a DTM point.

  • p – Power \(p\) for inverse-distance weighting in the interpolation of terrain points.

  • voxel_size – Voxel size with which the terrain points are downsampled before the DTM is created. If set to None, no downsampling is performed. Defaults to None.

Returns:

Tuple of two arrays. The first is the DTM. The second contains the x- and y-coordinate of the top left corner of the DTM grid.

Shape:

  • terrain_coords: \((N, 3)\)

  • Output: Tuple of two arrays. The first has shape \((H, W)\) and second has shape \((2)\).

where

\(N = \text{ number of terrain points}\)
\(H = \text{ extent of the DTM grid in y-direction}\)
\(W = \text{ extent of the DTM grid in x-direction}\)
pointtree.operations.normalize_height(
coords: ndarray[Any, dtype[float64]],
dtm: ndarray[Any, dtype[float64]],
dtm_offset: ndarray[Any, dtype[float64]],
dtm_resolution: float,
allow_outside_points: bool = True,
inplace: bool = False,
) → ndarray[Any, dtype[float64]][source]

Normalizes the height of a point cloud by subtracting the corresponding terrain height from the z-coordinate of each point. The terrain height for a given point is obtained by bilinearly interpolating the terrain heights of the four closest grid points of the digital terrain model.

Parameters:

  • coords – Point coordinates of the point cloud to normalize.

  • dtm – Rasterized digital terrain model.

  • dtm_offset – X and y-coordinates of the top left corner of the DTM grid.

  • allow_outside_points – If this option is set to True and a point in the point cloud to be normalized is not in the area covered by the DTM, the height of the nearest DTM points is still determined and used for normalization. Otherwise, a ValueError is thrown if points are outside the area covered by the DTM. Defaults to True.

  • inplace – Whether the normalization should be applied in place to the coords array. Defaults to False.

Returns:

Height-normalized point cloud.

Raises:

ValueError – If the point cloud to be normalized covers a larger base area than the DTM.

Shape:

  • coords: \((N, 3)\)

  • dtm: \((H, W)\)

  • dtm_offset: \((2)\)

  • Output: \((N, 3)\)

where

\(N = \text{ number of points}\)
\(H = \text{ extent of the DTM in grid in y-direction}\)
\(W = \text{ extent of the DTM in grid in x-direction}\)
pointtree.operations.points_in_ellipse(
xy: ndarray[Any, dtype[float64]],
ellipse: ndarray[Any, dtype[float64]],
) → ndarray[Any, dtype[bool_]][source]

Tests whether 2D points are within the boundaries of an ellipse.

Parameters:

  • xy – Coordinates of the points to test.

  • ellipse – Parameters of the ellipse in the following order: X- and y-coordinates of its center, radius along the semi-major and along the semi-minor axis, and the counterclockwise angle of rotation from the x-axis to the semi-major axis of the ellipse.

Returns:

Boolean array that indicates for each point whether it lies within the ellipse.

Raises:

ValueError – If the shape of xy or ellipse is invalid.

Shape:

  • xy: \((N, 2)\)

  • ellipse: \((5)\)

  • batch_indices_query_points: \((N')\)

  • Output: \((N)\)

    where

    \(N = \text{ number of points}\)