trimesh.points

points.py

Functions dealing with (n, d) points.

Classes:

Geometry3D()

The Geometry3D object is the parent object of geometry objects which are three dimensional, including Trimesh, PointCloud, and Scene objects.

PointCloud(vertices[, colors, metadata])

Hold 3D points in an object which can be visualized in a scene.

VertexColor([colors, obj])

Create a simple visual object to hold just vertex colors for objects such as PointClouds.

Functions:

k_means(points, k, **kwargs)

Find k centroids that attempt to minimize the k- means problem: https://en.wikipedia.org/wiki/Metric_k-center

major_axis(points)

Returns an approximate vector representing the major axis of the passed points.

plane_fit(points)

Fit a plane to points using SVD.

plane_transform(origin, normal)

Given the origin and normal of a plane find the transform that will move that plane to be coplanar with the XY plane.

plot_points(points[, show])

Plot an (n, 3) list of points using matplotlib

point_plane_distance(points, plane_normal[, …])

The minimum perpendicular distance of a point to a plane.

project_to_plane(points[, plane_normal, …])

Project (n, 3) points onto a plane.

radial_sort(points, origin, normal)

Sorts a set of points radially (by angle) around an an axis specified by origin and normal vector.

remove_close(points, radius)

Given an (n, m) array of points return a subset of points where no point is closer than radius.

tsp(points[, start])

Find an ordering of points where each is visited and the next point is the closest in euclidean distance, and if there are multiple points with equal distance go to an arbitrary one.

class trimesh.points.PointCloud(vertices, colors=None, metadata=None, **kwargs)

Bases: trimesh.parent.Geometry3D

Hold 3D points in an object which can be visualized in a scene.

Methods:

apply_transform(transform)

Apply a homogeneous transformation to the PointCloud object in- place.

copy()

Safely get a copy of the current point cloud.

crc()

Get a CRC hash of the current vertices.

export([file_obj, file_type])

Export the current pointcloud to a file object. If file_obj is a filename, file will be written there. Supported formats are xyz :param file_obj: str, file name where to save the pointcloud None, if you would like this function to return the export blob :type file_obj: open writeable file object :param file_type: Which file type to export as. If file name is passed this is not required :type file_type: str.

md5()

Get an MD5 hash of the current vertices.

merge_vertices()

Merge vertices closer than tol.merge (default: 1e-8)

scene()

A scene containing just the PointCloud

show(**kwargs)

Open a viewer window displaying the current PointCloud

Attributes:

bounds

The axis aligned bounds of the PointCloud

centroid

The mean vertex position

colors

Stored per- point color

convex_hull

A convex hull of every point.

extents

The size of the axis aligned bounds

is_empty

Are there any vertices defined or not.

shape

Get the shape of the pointcloud

vertices

Vertices of the PointCloud

apply_transform(transform)

Apply a homogeneous transformation to the PointCloud object in- place.

Parameters

transform ((4, 4) float) – Homogeneous transformation to apply to PointCloud

property bounds

The axis aligned bounds of the PointCloud

Returns

bounds – Minimum, Maximum verteex

Return type

(2, 3) float

property centroid

The mean vertex position

Returns

centroid – Mean vertex position

Return type

(3,) float

property colors

Stored per- point color

Returns

colors – Per- point RGBA color

Return type

(len(self.vertices), 4) np.uint8

property convex_hull

A convex hull of every point.

Returns

convex_hull – A watertight mesh of the hull of the points

Return type

trimesh.Trimesh

copy()

Safely get a copy of the current point cloud.

Copied objects will have emptied caches to avoid memory issues and so may be slow on initial operations until caches are regenerated.

Current object will not have its cache cleared.

Returns

copied – Copy of current point cloud

Return type

trimesh.PointCloud

crc()

Get a CRC hash of the current vertices.

Returns

crc – Hash of self.vertices

Return type

int

export(file_obj=None, file_type=None, **kwargs)

Export the current pointcloud to a file object. If file_obj is a filename, file will be written there. Supported formats are xyz :param file_obj: str, file name where to save the pointcloud

None, if you would like this function to return the export blob

Parameters

file_type (str) – Which file type to export as. If file name is passed this is not required

property extents

The size of the axis aligned bounds

Returns

extents – Edge length of axis aligned bounding box

Return type

(3,) float

property is_empty

Are there any vertices defined or not.

Returns

empty – True if no vertices defined

Return type

bool

md5()

Get an MD5 hash of the current vertices.

Returns

md5 – Hash of self.vertices

Return type

str

merge_vertices()

Merge vertices closer than tol.merge (default: 1e-8)

scene()

A scene containing just the PointCloud

Returns

scene – Scene object containing this PointCloud

Return type

trimesh.Scene

property shape

Get the shape of the pointcloud

Returns

shape – Shape of vertex array

Return type

(2,) int

show(**kwargs)

Open a viewer window displaying the current PointCloud

property vertices

Vertices of the PointCloud

Returns

vertices – Points in the PointCloud

Return type

(n, 3) float

trimesh.points.k_means(points, k, **kwargs)

Find k centroids that attempt to minimize the k- means problem: https://en.wikipedia.org/wiki/Metric_k-center

Parameters
  • points ((n, d) float) – Points in space

  • k (int) – Number of centroids to compute

  • **kwargs (dict) – Passed directly to scipy.cluster.vq.kmeans

Returns

  • centroids ((k, d) float) – Points in some space

  • labels ((n) int) – Indexes for which points belong to which centroid

trimesh.points.major_axis(points)

Returns an approximate vector representing the major axis of the passed points.

Parameters

points ((n, dimension) float) – Points in space

Returns

axis – Vector along approximate major axis

Return type

(dimension,) float

trimesh.points.plane_fit(points)

Fit a plane to points using SVD.

Parameters

points ((n, 3) float) – 3D points in space

Returns

  • C ((3,) float) – Point on the plane

  • N ((3,) float) – Unit normal vector of plane

trimesh.points.plot_points(points, show=True)

Plot an (n, 3) list of points using matplotlib

Parameters
  • points ((n, 3) float) – Points in space

  • show (bool) – If False, will not show until plt.show() is called

trimesh.points.point_plane_distance(points, plane_normal, plane_origin=[0.0, 0.0, 0.0])

The minimum perpendicular distance of a point to a plane.

Parameters
  • points ((n, 3) float) – Points in space

  • plane_normal ((3,) float) – Unit normal vector

  • plane_origin ((3,) float) – Plane origin in space

Returns

distances – Distance from point to plane

Return type

(n,) float

trimesh.points.project_to_plane(points, plane_normal=[0, 0, 1], plane_origin=[0, 0, 0], transform=None, return_transform=False, return_planar=True)

Project (n, 3) points onto a plane.

Parameters
  • points ((n, 3) float) – Points in space.

  • plane_normal ((3,) float) – Unit normal vector of plane

  • plane_origin ((3,)) – Origin point of plane

  • transform (None or (4, 4) float) – Homogeneous transform, if specified, normal+origin are overridden

  • return_transform (bool) – Returns the (4, 4) matrix used or not

  • return_planar (bool) – Return (n, 2) points rather than (n, 3) points

trimesh.points.radial_sort(points, origin, normal)

Sorts a set of points radially (by angle) around an an axis specified by origin and normal vector.

Parameters
  • points ((n, 3) float) – Points in space

  • origin ((3,) float) – Origin to sort around

  • normal ((3,) float) – Vector to sort around

Returns

ordered – Same as input points but reordered

Return type

(n, 3) float

trimesh.points.remove_close(points, radius)

Given an (n, m) array of points return a subset of points where no point is closer than radius.

Parameters
  • points ((n, dimension) float) – Points in space

  • radius (float) – Minimum radius between result points

Returns

  • culled ((m, dimension) float) – Points in space

  • mask ((n,) bool) – Which points from the original points were returned

trimesh.points.tsp(points, start=0)

Find an ordering of points where each is visited and the next point is the closest in euclidean distance, and if there are multiple points with equal distance go to an arbitrary one.

Assumes every point is visitable from every other point, i.e. the travelling salesman problem on a fully connected graph. It is not a MINIMUM traversal; rather it is a “not totally goofy traversal, quickly.” On random points this traversal is often ~20x shorter than random ordering, and executes on 1000 points in around 29ms on a 2014 i7.

Parameters
  • points ((n, dimension) float) – ND points in space

  • start (int) – The index of points we should start at

Returns

  • traversal ((n,) int) – Ordered traversal visiting every point

  • distances ((n - 1,) float) – The euclidean distance between points in traversal