PointCloud structures

PointCloud class

class PointCloud(points, n_dimensions=None, properties=None)

A class representing a \(E\)-dimensional point cloud, which is a collection of \(N_p\) points in a \(E\)-dimensional space.

Point clouds can store any scalar/vector properties associated with each point in the cloud.

Note

The dimension \(E\) of the cloud is not designed to change after point cloud creation.

Note

The coordinates and the properties of the points are stored as copy-on-write (cow) NumPy arrays of type numpy.float64. Accesing these arrays directly will return unwritable views to prevent accidental modifications.

Parameters:

• points (ArrayLike) – A NumPy array of shape \((N_{p}, E)\) representing the coordinates of the points.

• n_dimensions (Optional[Integral])

• properties (Optional[Dict[str, ArrayLike]])

n_dimensions: Integral, optional

The dimension \(E\) of the point cloud. If not provided, it is inferred from the shape of the points array. If points second dimension is less than n_dimensions, the points will be reshaped accordingly and filled with zeros. If points second dimension is greater than n_dimensions, a ValueError will be raised. Default is None.

properties: Optional[Dict[str, ArrayLike]], optional

A dictionary of additional properties to associate with the point cloud. Keys are property names, and values are NumPy arrays of property data of shape \((N_{p}, A)\) where \(A\) is the number of attributes per point for the given property. Default is None, meaning no additional properties are set.

Raises:

• TypeError – If the input points is not a NumPy array. If the given dimension is not an integer. If the properties is not a dictionary of string keys and NumPy array values.

• ValueError – If the input array does not have the correct shape. If the given dimension is not a strictly positive integer. If the properties arrays do not have the correct shape.

Parameters:

• points (ArrayLike)

• n_dimensions (Optional[Integral])

• properties (Optional[Dict[str, ArrayLike]])

Instantiate and export PointCloud object

To Instantiate a PointCloud object, use one of the following class methods:

PointCloud.from_array(points[, copy, properties])	Create a PointCloud object from a NumPy array of shape \((N_p, E)\).
PointCloud.from_meshio(mesh[, load_properties])	Create a PointCloud object from a meshio.Mesh object.
PointCloud.from_vtk(filepath[, load_properties])	Create a PointCloud object from a VTK file (only for 3D point clouds).
PointCloud.from_npz(filepath[, load_properties])	Create a PointCloud object from a NumPy NPZ file.

The PointCloud can then be exported to different formats using the following methods:

PointCloud.to_array()	Convert the point cloud to a NumPy array of shape \((N_p, E)\).
PointCloud.to_meshio([save_properties])	Convert the point cloud to a meshio.Mesh object.
PointCloud.to_vtk(filepath[, binary, ...])	Save the point cloud to a VTK file (only for \(E=3\) point clouds).
PointCloud.to_npz(filepath[, save_properties])	Save the point cloud to a NumPy NPZ file.

Accessing PointCloud attributes

The public attributes of a PointCloud object can be accessed using the following properties:

PointCloud.coordinates	[Get or Set] Alias for points() property.
PointCloud.points	[Get or Set] An numpy array of shape \((N_p, E)\) representing the coordinates of the points in the cloud.
PointCloud.n_dimensions	[Get] The dimension \(E\) of the point cloud.
PointCloud.n_points	[Get] The number of points \(N_p\) in the point cloud.
PointCloud.shape	[Get] The shape of the points array (\(N_p\), \(E\)).

Add and manage PointCloud points properties

The properties of the points in a PointCloud object can be managed using the following methods:

Note

Point properties are stored as named NumPy arrays of shape \((N_p, A)\) where \(N_p\) is the number of points and \(A\) is the number of property components (e.g., 3 for RGB color). All the point properties must have the same number of points as the PointCloud object and are stored as numpy.float64 arrays.

PointCloud.set_property(key, values)	Set a property for the point cloud as a NumPy array of shape \((N_p, A)\) where \(A\) is the number of attributes per point for the given property.
PointCloud.get_property(key)	Get a property of the point cloud by its key/name.
PointCloud.has_property(key)	Check if the point cloud has a property with the given key/name.
PointCloud.delete_property(key)	Delete a property of the point cloud by its key/name.
PointCloud.list_properties()	List all property keys/names associated with the point cloud.
PointCloud.copy_properties()	Return a copy of all properties of the point cloud.
PointCloud.clear_properties()	Remove all properties from the point cloud.

Add, remove or modify points in PointCloud objects

The points of a PointCloud object can be manipulated using the following methods:

PointCloud.all_close(other[, rtol, atol, ...])	Check if all points in the current point cloud are approximately equal to the points in another PointCloud instance within a tolerance.
PointCloud.all_finite()	Check if all points in the point cloud are finite (i.e., not NaN or infinite).
PointCloud.concatenate(other[, inplace])	Concatenate the current point cloud with another PointCloud instance.
PointCloud.copy([copy_properties])	Create a copy of the current PointCloud instance.
PointCloud.filter_points(mask[, inplace])	Filter points in the point cloud based on a boolean mask.
PointCloud.frame_transform([input_frame, ...])	Transform the point cloud from an input frame of reference to an output frame of reference (only for 3D point clouds).
PointCloud.is_finite()	Check which points in the point cloud are finite (not NaN or infinite).
PointCloud.is_nan()	Check which points in the point cloud are NaN.
PointCloud.keep_points(indices[, inplace])	Keep only the points at the specified indices in the point cloud.
PointCloud.remove_not_finite([inplace])	Remove points from the point cloud that contain non-finite values (NaN or Inf).
PointCloud.remove_points(indices[, inplace])	Remove points from the point cloud based on their indices.

PointCloud object geometric computations

The following methods can be used to perform geometric computations on PointCloud objects:

PointCloud.bounding_box()	Compute the axis-aligned bounding box of the point cloud.
PointCloud.bounding_sphere()	Compute the bounding sphere of the point cloud.

Visualize PointCloud object (1D, 2D, 3D only)

The PointCloud class provides a method to visualize the point cloud in 1D, 2D, or 3D space using pyvista:

PointCloud.visualize([point_color, ...])

Visualize the point cloud using PyVista (only for \(E \leq 3\) point clouds).