pchandler.core

The base point cloud class for working with point cloud data.

Classes

PointCloudData

Point cloud class with automatic validation and coordinate optimisation.

class pchandler.core.PointCloudData

Bases: CartesianCoordinates

Point cloud class with automatic validation and coordinate optimisation.

scalar_fields: ScalarFieldManager

Contains and manages all the scalar fields associated with the point cloud coordinates

__init__(xyz=None, **kwargs)

Construct a PointCloudData from XYZ coordinates plus optional per-point scalar fields.

Parameters:

• xyz (Array_Nx3_Float_T) – Input coordinates.

• **kwargs (Unpack[PointCloudDataKW]) –

  Optional keyword arguments — see PointCloudDataKW for the full enumeration. Notably:

  • rgb — RGB colour per point.

  • normals — unit normal vectors per point.

  • intensity — intensity scalar field.

  • reflectance — reflectance scalar field.

  • scalar_fields — additional custom scalar fields.

  • socs_origin — scan original coordinate-system origin.

  • Plus every kwarg accepted by CartesianCoordinates (numerical_optimization_shift, project_transformation, unshifted_bbox, _shift_applied_by).

property nbPoints: int

Return the number of points in the point cloud.

Returns:

Point count (number of XYZ rows).

Return type:

int

property normals: NormalFields | None

Return the normal field, if set.

Returns:

Per-point unit normal vectors, or None if not set.

Return type:

NormalFields | None

property rgb: RGBFields | None

Return the RGB field, if set.

Returns:

Per-point RGB colour, or None if not set.

Return type:

RGBFields | None

property intensity: ScalarField | None

Return the intensity field, if set.

Returns:

Per-point intensity scalar field, or None if not set.

Return type:

ScalarField | None

property reflectance: ScalarField | None

Return the reflectance field, if set.

Returns:

Per-point reflectance scalar field, or None if not set.

Return type:

ScalarField | None

sample(mask)

Sample a copy of the point cloud restricted to mask.

Parameters:

mask (IndexLike) – A vector-like index object that corresponds to the number of points in the point cloud.

Returns:

A new point cloud containing only the masked points (and their scalar fields).

Return type:

PointCloudData

reduce(mask)

Reduce the point cloud in-place to the subset selected by mask.

Parameters:

mask (IndexLike) – A vector-like index object that corresponds to the number of points in the point cloud.

classmethod merge(*pcds, **kwargs)

Merge a set of point clouds together.

If point clouds contain similar scalar fields, these are also merged. Where a scalar field is missing in one point cloud, that field is not retained.

The merge function also manages any optimised shifts required by the new objects.

Parameters:

• *pcds (PointCloudData) – Point clouds to merge in order.

• **kwargs (Unpack[PointCloudDataKW]) – Additional keyword arguments forwarded to the base merge implementation — see PointCloudDataKW for the full enumeration.

Returns:

A new point cloud whose coordinates and scalar fields are the row-wise concatenation of pcds.

Return type:

PointCloudData

to_o3d(as_tensor: Literal[False] = False) → o3d.geometry.PointCloud

to_o3d(as_tensor: Literal[True]) → o3d.t.geometry.PointCloud

Convert the point cloud to an Open3D PointCloud object.

Parameters:

as_tensor (bool) – If True, build an Open3D tensor-based PointCloud (o3d.t.geometry).

Returns:

The Open3D point cloud, in legacy or tensor form depending on as_tensor.

Return type:

PointCloud | o3d.t.geometry.PointCloud

Raises:

ModuleNotFoundError – If open3d is not installed.

classmethod from_o3d(pcd_o3d: o3d.geometry.PointCloud) → PointCloudData

classmethod from_o3d(pcd_o3d: o3d.t.geometry.PointCloud) → PointCloudData

Convert an Open3D PointCloud object to a PointCloudData.

Parameters:

pcd_o3d (PointCloud | o3d.t.geometry.PointCloud) – Open3D point cloud, either legacy or tensor-based.

Returns:

The converted point cloud (colours/normals are carried over from the legacy Open3D variant; scalar attributes are carried over from the tensor variant).

Return type:

PointCloudData

Raises:

• ModuleNotFoundError – If open3d is not installed.

• TypeError – If pcd_o3d is neither an o3d.geometry.PointCloud nor an o3d.t.geometry.PointCloud.

to_py4dgeo()

Convert the PointCloudData to a py4dgeo Epoch.

The optional numerical optimization shift is reverted so py4dgeo receives float64 world-frame coordinates (mirrors to_o3d()).

Returns:

Epoch carrying xyz in world-frame, plus optional normals and additional scalar-field dimensions.

Return type:

py4dgeo.Epoch

Raises:

ModuleNotFoundError – If py4dgeo is not installed.

classmethod from_py4dgeo(epoch)

Convert a py4dgeo Epoch to a PointCloudData.

Parameters:

epoch (Epoch) – A py4dgeo Epoch to convert.

Returns:

A new point cloud built from the epoch’s cloud, normals, and additional dimensions.

Return type:

PointCloudData

Raises:

ModuleNotFoundError – If py4dgeo is not installed.