pointcloudset.pointcloud module

class pointcloudset.pointcloud.PointCloud(data: DataFrame = None, orig_file: str = '', timestamp: datetime = None, columns: list = ['x', 'y', 'z'])

Bases: PointCloudCore

PointCloud Class with one pointcloud of lidar measurements, laser scanning, photogrammetry or simular.

One PointCloud consists mainly of PyntCloud pointcloud (PyntCloud.points) and a pandas.DataFrame (.data) with all the associated data.

Note that the index of the points is not preserved when applying processing. This is necessary since PyntCloud does not allow to pass the index. Therefore, a new PointCloud object is generated at each processing stage.

Developer notes:

• All operations have to act on both, pointcloud, data and keep the timestamp.

• All processing methods need to return another PointCloud.

Examples

testbag = Path().cwd().parent.joinpath("tests/testdata/test.bag")
testset = pointcloudset.Dataset(testbag,topic="/os1_cloud_node/points",
    keep_zeros=False)
testpointcloud = testset[0]

classmethod from_file(file_path: Path, timestamp: str | datetime.datetime = 'from_file', **kwargs)

Extract data from file and construct a PointCloud with it. Uses PyntCloud as backend.

Parameters

• file_path (pathlib.Path) – Path of file to read.

• use_file_timestamp (bool) – use the file creation date as timestamp. Defaults to True.

• timestamp (str | datetime.datetime) – timestamp of pointcloud. If “from_file” then the timesamp is taken from file creation datetimne. (Defaults to “from_file”)

• **kwargs – Keyword arguments to pass to func.

Returns

PointCloud with timestamp last modified.

Return type

PointCloud

Raises

• ValueError – If file format is not supported.

• TypeError – If file_path is no Path object.

to_file(file_path: Path = PosixPath('.'), **kwargs) → None

Exports the pointcloud as to a file for use with CloudCompare or similar tools. Currently not all attributes of a pointcloud are saved so some information is lost when using this function. Uses PyntCloud as backend.

Parameters

• file_path (pathlib.Path, optional) – Destination. Defaults to the folder of the bag file and csv with the timestamp of the pointcloud.

• **kwargs – Keyword arguments to pass to func.

Raises

ValueError – If file format is not supported.

classmethod from_instance(library: ~typing.Literal['PANDAS', 'PYNTCLOUD', 'OPEN3D', 'DATAFRAME'] = 'PANDAS', instance: pandas.core.frame.DataFrame | pyntcloud.core_class.PyntCloud | open3d.cpu.pybind.geometry.PointCloud = Empty DataFrame Columns: [] Index: [], **kwargs) → PointCloud

Converts a library instance to a pointcloudset PointCloud.

Parameters

• library (str) –

  Name of the library.

  If PYNTCLOUD: pointcloudset.io.pointcloud.pyntcloud.from_pyntcloud()

  If OPEN3D: pointcloudset.io.pointcloud.open3d.from_open3d()

  If DATAFRAME: pointcloudset.io.pointcloud.pandas.from_dataframe()

  If PANDAS: pointcloudset.io.pointcloud.pandas.from_dataframe()

• instance – (Union[pandas.DataFrame, pyntcloud.PyntCloud, open3d.geometry.PointCloud]): Library instance to convert.

• **kwargs – Keyword arguments to pass to func.

Returns

Derived from the instance.

Return type

PointCloud

Raises

ValueError – If instance is not supported.

Examples

testpointcloud = from_instance("OPEN3D", open3d_pointcloud)

to_instance(library: Literal['PYNTCLOUD', 'OPEN3D', 'DATAFRAME', 'PANDAS'], **kwargs) → pyntcloud.core_class.PyntCloud | open3d.cpu.pybind.geometry.PointCloud | pandas.core.frame.DataFrame

Convert PointCloud to another library instance.

Parameters

• library (str) –

  Name of the library.

  If PYNTCLOUD: pointcloudset.io.pointcloud.pyntcloud.to_pyntcloud()

  If OPEN3D: pointcloudset.io.pointcloud.open3d.to_open3d()

  If DATAFRAME: pointcloudset.io.pointcloud.pandas.to_dataframe()

  If PANDAS: pointcloudset.io.pointcloud.pandas.to_dataframe()

• **kwargs – Keyword arguments to pass to func.

Returns

The derived instance.

Return type

Union[ pandas.DataFrame, pyntcloud.PyntCloud, open3d.geometry.PointCloud ]

Raises

ValueError – If library is not suppored.

Examples

open3d_pointcloud = testpointcloud.to_instance("OPEN3D")

plot(color: None | str = None, overlay: dict | None = None, point_size: float = 2, prepend_id: str = '', hover_data: Union(list[str], bool) = None, **kwargs) → plotly.graph_objs.Figure

Plot a PointCloud as a 3D scatter plot with Plotly. It handles plots of single pointclouds and overlay with other objects, such as other pointclouds from clustering or planes from plane segmentation.

You can also pass arguments to the Plotly express function plotly.express.scatter_3d().

Parameters

• pointcloud (PointCloud) – The pointcloud to plot.

• color (str or None) – Which column to plot. For example “intensity”. Defaults to None.

• overlay (dict, optional) –

  Dict with PointClouds to overlay. {“Cluster 1”: cluster1,”Plane 1”: plane_model}

  See also: pointcloudset.plot.pointcloud.plot_overlay()

  Defaults to empty.

• point_size (float, optional) – Size of each point. Defaults to 2.

• prepend_id (str, optional) – String before point id to display in hover. Defaults to empty.

• hover_data (list(str) or True, optional) – Data columns to display in hover. If True then all the columns are are show in the hover. Defaults to None.

• **kwargs – Keyword arguments to pass to func.

Returns

The interactive Plotly plot, best used inside a Jupyter Notebook.

Return type

plotly.graph_objs.Figure

Raises

ValueError – If the color column name is not in the data.

diff(name: Literal['origin', 'plane', 'pointcloud', 'point', 'nearest'], target: None | pointcloudset.pointcloud.PointCloud | numpy.ndarray = None, **kwargs) → PointCloud

Calculate differences and distances to the origin, plane, point and pointcloud.

Parameters

• name (str) –

  “origin”: pointcloudset.diff.origin.calculate_distance_to_origin()

  ”plane”: pointcloudset.diff.plane.calculate_distance_to_plane()

  ”pointcloud”: pointcloudset.diff.pointcloud.calculate_distance_to_pointcloud()

  ”point”: pointcloudset.diff.point.calculate_distance_to_point()

  ”nearest”: pointcloudset.diff.point.calculate_distance_to_nearest()

• target (Union[None, PointCloud, numpy.ndarray], optional) – Pass argument according to chosen object. Defaults to None.

• **kwargs – Keyword arguments to pass to func.

Returns

New PointCloud with added column of the differences.

Return type

PointCloud

Raises

ValueError – If name is not supported.

Examples

newpointcloud = testpointcloud.diff("pointcloud", targetpointcloud)

filter(name: Literal['quantile', 'value', 'radiusoutlier'], *args, **kwargs) → PointCloud

Filters a PointCloud according to criteria.

Parameters

• name (str) –

  “quantile”: pointcloudset.filter.stat.quantile_filter()

  ”value”: pointcloudset.filter.stat.value_filter()

  ”radiusoutlier”: pointcloudset.filter.stat.remove_radius_outlier()

• *args – Positional arguments to pass to func.

• **kwargs – Keyword arguments to pass to func.

Returns

PointCloud which fullfils the criteria.

Return type

PointCloud

Raises

ValueError – If name is not supported.

Examples

filteredpointcloud = testpointcloud.filter("quantile","intensity","==",0.5)

filteredpointcloud = testpointcloud.filter("value","intensity",">",100)

limit(dim: str, minvalue: float, maxvalue: float) → PointCloud

Limit the range of certain values in pointcloudset PointCloud. Can be chained together.

Parameters

• dim (str) – Dimension to limit, any column in data not just x, y, or z.

• minvalue (float) – Min value to limit. (greater equal)

• maxvalue (float) – Max value to limit. (smaller equal)

Returns

Limited pointcloud, where rows which did not match the criteria were dropped.

Return type

PointCloud

Examples

limitedpointcloud = testpointcloud.limit("x", -1.0, 1.0).limit("intensity", 0.0, 50.0)

limit_less(dim: str, value: float) → PointCloud

Limit the range if a diminsion to a value.

Same as filter(“value”, dim, “<”, value)

Parameters

• dim (str) – Dimension to limit, any column in data not just x, y, or z.

• value (float) – Min value to limit. (less)

Returns

Limited pointcloud, where rows which did not match the criteria were dropped.

Return type

PointCloud

Examples

limitedpointcloud = testpointcloud.limit_less("x",1.0)

limit_greater(dim: str, value: float) → PointCloud

Limit the range if a diminsion to a value.

Same as filter(“value”, dim, “>”, value)

Parameters

• dim (str) – Dimension to limit, any column in data not just x, y, or z.

• value (float) – Value to limit. (greater)

Returns

Limited pointcloud, where rows which did not match the criteria were dropped.

Return type

PointCloud

Examples

limitedpointcloud = testpointcloud.limit_greater("x",10.0)

apply_filter(filter_result: numpy.ndarray | list[int]) → PointCloud

Generating a new PointCloud by removing points according to a call of the filter method.

Parameters

filter_result (Union[numpy.ndarray, list[int]]) – Filter result.

Returns

PointCloud with filtered rows and reindexed data and points.

Return type

PointCloud

Raises

TypeError – If the filter_result has the wrong type.

get_cluster(eps: float, min_points: int) → DataFrame

Get the clusters based on open3d.geometry.PointCloud.cluster_dbscan(). Process further with pointcloudset.pointcloud.PointCloud.take_cluster().

Parameters

• eps (float) – Density parameter that is used to find neighboring points.

• min_points (int) – Minimum number of points to form a cluster.

Returns

Dataframe with list of clusters.

Return type

pandas.DataFrame

take_cluster(cluster_number: int, cluster_labels: DataFrame) → PointCloud

Takes only the points belonging to the cluster_number.

Parameters

• cluster_number (int) – Cluster ID to keep.

• cluster_labels (pandas.DataFrame) – Clusters generated with pointcloudset.pointcloud.PointCloud.get_cluster().

Returns

PointCloud with selected cluster.

Return type

PointCloud

plane_segmentation(distance_threshold: float, ransac_n: int, num_iterations: int, return_plane_model: bool = False) → pointcloudset.pointcloud.PointCloud | dict

Segments a plane in the point cloud using the RANSAC algorithm. Based on open3d.geometry.PointCloud.segment_plane().

Parameters

• distance_threshold (float) – Max distance a point can be from the plane model, and still be considered as an inlier.

• ransac_n (int) – Number of initial points to be considered inliers in each iteration.

• num_iterations (int) – Number of iterations.

• return_plane_model (bool, optional) – Return also plane model parameters if True. Defaults to False.

Returns

PointCloud with inliers or a dict of PointCloud with inliers and the plane parameters.

Return type

PointCloud or dict

random_down_sample(number_of_points: int) → PointCloud

Function to downsample input pointcloud into output pointcloud randomly. Made

Parameters

number_of_points ([int]) – number_of_points

Returns

subsampled PointCloud

Return type

PointCloud