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 a pandas.DataFrame (.data) with the point coordinates and all associated per-point attributes.

Note that the index of the points is not preserved when applying processing. 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 = 'from_file', **kwargs)

Extract data from file and construct a PointCloud with it.

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 the format-specific native IO 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', 'DATAFRAME'] = 'PANDAS', instance: ~pandas.core.frame.DataFrame = Empty DataFrame Columns: [] Index: [], **kwargs) → PointCloud

Converts a library instance to a pointcloudset PointCloud.

Parameters:
Returns:

Derived from the instance.

Return type:

PointCloud

Raises:

ValueError – If instance is not supported.

to_instance(library: Literal['DATAFRAME', 'PANDAS'], **kwargs) → DataFrame

Convert PointCloud to another library instance.

Parameters:
Returns:

The derived instance.

Return type:

pandas.DataFrame

Raises:

ValueError – If library is not suppored.

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 | PointCloud | ndarray = None, **kwargs) → PointCloud

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

Parameters:
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:
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: 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

Cluster the PointCloud using DBSCAN.

This method validates inputs and delegates the clustering implementation to pointcloudset.cluster.get_cluster_labels().

Parameters:

  • eps (float) – Density parameter for neighbour search. Must be positive.

  • min_points (int) – Minimum number of points (including self) to form a core point. Must be >= 1.

Returns:

One row per point with column cluster. Noise points receive label -1 and can be retrieved with take_cluster(-1, labels).

Return type:

pandas.DataFrame

Raises:

ValueError – If eps is not positive, min_points is less than 1, or the point cloud is empty.

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

Takes only the points belonging to the cluster_number.

Use cluster_number=-1 to retrieve noise points.

Parameters:
Returns:

PointCloud with selected cluster.

Return type:

PointCloud

Raises:

ValueError – If cluster_labels length does not match this PointCloud.

plane_segmentation(distance_threshold: float, ransac_n: int, num_iterations: int, return_plane_model: bool = False, seed: int = 42) → PointCloud | dict

Segments a plane in the point cloud using the RANSAC algorithm.

After finding the best consensus set the plane is refit via SVD on all inliers, so the returned model is more accurate than the initial sample.

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 points sampled per iteration to fit a candidate plane. Must be >= 3.

  • num_iterations (int) – Number of RANSAC iterations. Must be >= 1.

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

  • seed (int, optional) – Random seed for reproducibility. Defaults to 42.

Returns:

PointCloud with inliers or a dict of PointCloud with inliers and the plane parameters. The plane model is [a, b, c, d] for ax+by+cz+d=0 (normalised).

Return type:

PointCloud or dict

Raises:

ValueError – If the point cloud is empty, distance_threshold is not positive, ransac_n is less than 3 or exceeds the number of points, or num_iterations is less than 1.

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