trimesh.base module

github.com/mikedh/trimesh

Library for importing, exporting and doing simple operations on triangular meshes.

Classes

Trimesh([vertices, faces, face_normals, …])

class trimesh.base.Trimesh(vertices=None, faces=None, face_normals=None, vertex_normals=None, face_colors=None, vertex_colors=None, face_attributes=None, vertex_attributes=None, metadata=None, process=True, validate=False, use_embree=True, initial_cache=None, visual=None, **kwargs)

Bases: trimesh.parent.Geometry

Methods

apply_obb()

Apply the oriented bounding box transform to the current mesh.

apply_transform(matrix)

Transform mesh by a homogeneous transformation matrix.

compute_stable_poses([center_mass, sigma, …])

Computes stable orientations of a mesh and their quasi-static probabilites.

contains(points)

Given a set of points, determine whether or not they are inside the mesh.

convert_units(desired[, guess])

Convert the units of the mesh into a specified unit.

convex_decomposition([maxhulls])

Compute an approximate convex decomposition of a mesh.

copy()

Safely get a copy of the current mesh.

crc()

A zlib.adler32 checksum for the current mesh data.

difference(other[, engine])

Boolean difference between this mesh and n other meshes

eval_cached(statement, *args)

Evaluate a statement and cache the result before returning.

export([file_obj, file_type])

Export the current mesh to a file object.

fill_holes()

Fill single triangle and single quad holes in the current mesh.

fix_normals(**kwargs)

Find and fix problems with self.face_normals and self.faces winding direction.

intersection(other[, engine])

Boolean intersection between this mesh and n other meshes

invert()

Invert the mesh in- place by reversing the winding of every face and negating normals without dumping the cache.

md5()

An MD5 of the core geometry information for the mesh, faces and vertices.

merge_vertices([digits, textured])

If a mesh has vertices that are closer than trimesh.constants.tol.merge reindex faces to reference the same index for both vertices.

outline([face_ids])

Given a list of face indexes find the outline of those faces and return it as a Path3D.

process()

Do the bare minimum processing to make a mesh useful.

register(other, **kwargs)

Align a mesh with another mesh or a PointCloud using the principal axes of inertia as a starting point which is refined by iterative closest point.

remove_degenerate_faces([height])

Remove degenerate faces (faces without 3 unique vertex indices) from the current mesh.

remove_duplicate_faces()

On the current mesh remove any faces which are duplicates.

remove_infinite_values()

Ensure that every vertex and face consists of finite numbers.

remove_unreferenced_vertices()

Remove all vertices in the current mesh which are not referenced by a face.

rezero()

Translate the mesh so that all vertex vertices are positive.

sample(count[, return_index])

Return random samples distributed across the

scene(**kwargs)

Get a Scene object containing the current mesh.

section(plane_normal, plane_origin)

Returns a 3D cross section of the current mesh and a plane defined by origin and normal.

section_multiplane(plane_origin, …)

Return multiple parallel cross sections of the current mesh in 2D.

show(**kwargs)

Render the mesh in an opengl window.

slice_plane(plane_origin, plane_normal, **kwargs)

Slice the mesh with a plane, returning a new mesh that is the

smoothed(**kwargs)

Return a version of the current mesh which will render nicely, without changing source mesh.

split(**kwargs)

Returns a list of Trimesh objects, based on face connectivity.

subdivide([face_index])

Subdivide a mesh, with each subdivided face replaced with four smaller faces.

submesh(faces_sequence, **kwargs)

Return a subset of the mesh.

to_dict()

Return a dictionary representation of the current mesh, with keys

union(other[, engine])

Boolean union between this mesh and n other meshes

unmerge_vertices()

Removes all face references so that every face contains three unique vertex indices and no faces are adjacent.

update_faces(mask)

In many cases, we will want to remove specific faces.

update_vertices(mask[, inverse])

Update vertices with a mask.

voxelized(pitch[, method])

Return a VoxelGrid object representing the current mesh

Attributes

area

Summed area of all triangles in the current mesh.

area_faces

The area of each face in the mesh.

body_count

How many connected groups of vertices exist in this mesh.

bounds

The axis aligned bounds of the faces of the mesh.

center_mass

The point in space which is the center of mass/volume.

centroid

The point in space which is the average of the triangle centroids weighted by the area of each triangle.

convex_hull

Get a new Trimesh object representing the convex hull of the current mesh.

density

The density of the mesh.

edges

Edges of the mesh (derived from faces).

edges_face

Which face does each edge belong to.

edges_sorted

Edges sorted along axis 1

edges_sorted_tree

A KDTree for mapping edges back to edge index.

edges_sparse

Edges in sparse bool COO graph format where connected vertices are True.

edges_unique

The unique edges of the mesh.

edges_unique_inverse

Return the inverse required to reproduce self.edges_sorted from self.edges_unique.

edges_unique_length

How long is each unique edge.

euler_number

Return the Euler characteristic (a topological invariant) for the mesh

extents

The length, width, and height of the axis aligned bounding box of the mesh.

face_adjacency

Find faces that share an edge, which we call here ‘adjacent’.

face_adjacency_angles

Return the angle between adjacent faces

face_adjacency_convex

Return faces which are adjacent and locally convex.

face_adjacency_edges

Returns the edges that are shared by the adjacent faces.

face_adjacency_edges_tree

A KDTree for mapping edges back face adjacency index.

face_adjacency_projections

The projection of the non- shared vertex of a triangle onto

face_adjacency_radius

The approximate radius of a cylinder that fits inside adjacent faces.

face_adjacency_span

The approximate perpendicular projection of the non- shared vertices in a pair of adjacent faces onto the shared edge of the two faces.

face_adjacency_tree

An R-tree of face adjacencies.

face_adjacency_unshared

Return the vertex index of the two vertices not in the shared

face_angles

Returns the angle at each vertex of a face.

face_angles_sparse

A sparse matrix representation of the face angles.

face_normals

Return the unit normal vector for each face.

faces

The faces of the mesh.

faces_sparse

A sparse matrix representation of the faces.

faces_unique_edges

For each face return which indexes in mesh.unique_edges constructs that face.

facets

Return a list of face indices for coplanar adjacent faces.

facets_area

Return an array containing the area of each facet.

facets_boundary

Return the edges which represent the boundary of each facet

facets_normal

Return the normal of each facet

facets_on_hull

Find which facets of the mesh are on the convex hull.

facets_origin

Return a point on the facet plane.

identifier

Return a float vector which is unique to the mesh and is robust to rotation and translation.

identifier_md5

An MD5 of the rotation invariant identifier vector

is_convex

Check if a mesh is convex or not.

is_empty

Does the current mesh have data defined.

is_volume

Check if a mesh has all the properties required to represent a valid volume, rather than just a surface.

is_watertight

Check if a mesh is watertight by making sure every edge is included in two faces.

is_winding_consistent

Does the mesh have consistent winding or not.

kdtree

Return a scipy.spatial.cKDTree of the vertices of the mesh.

mass

Mass of the current mesh, based on specified density and volume.

mass_properties

Returns the mass properties of the current mesh.

moment_inertia

Return the moment of inertia matrix of the current mesh.

principal_inertia_components

Return the principal components of inertia

principal_inertia_transform

A transform which moves the current mesh so the principal inertia vectors are on the X,Y, and Z axis, and the centroid is at the origin.

principal_inertia_vectors

Return the principal axis of inertia.

referenced_vertices

Which vertices in the current mesh are referenced by a face.

scale

A metric for the overall scale of the mesh, the length of the diagonal of the axis aligned bounding box of the mesh.

symmetry

Check whether a mesh has rotational symmetry.

symmetry_axis

If a mesh has rotational symmetry, return the axis.

symmetry_section

If a mesh has rotational symmetry, return the two vectors which make up a section coordinate frame.

triangles

Actual triangles of the mesh (points, not indexes)

triangles_center

The center of each triangle (barycentric [1/3, 1/3, 1/3])

triangles_cross

The cross product of two edges of each triangle.

triangles_tree

An R-tree containing each face of the mesh.

units

Definition of units for the mesh.

vertex_adjacency_graph

Returns a networkx graph representing the vertices and their connections in the mesh.

vertex_defects

Return the vertex defects, or (2*pi) minus the sum of the angles of every face that includes that vertex.

vertex_degree

Return the number of faces each vertex is included in.

vertex_faces

A representation of the face indices that correspond to each vertex.

vertex_neighbors

The vertex neighbors of each vertex of the mesh, determined from the cached vertex_adjacency_graph, if already existent.

vertex_normals

The vertex normals of the mesh.

vertices

The vertices of the mesh.

visual

Get the stored visuals for the current mesh.

volume

Volume of the current mesh calculated using a surface integral.

apply_obb()

Apply the oriented bounding box transform to the current mesh.

This will result in a mesh with an AABB centered at the origin and the same dimensions as the OBB.

Returns

matrix – Transformation matrix that was applied to mesh to move it into OBB frame

Return type

(4, 4) float

apply_transform(matrix)

Transform mesh by a homogeneous transformation matrix.

Does the bookkeeping to avoid recomputing things so this function should be used rather than directly modifying self.vertices if possible.

Parameters

matrix ((4, 4) float) – Homogeneous transformation matrix

property area

Summed area of all triangles in the current mesh.

Returns

area – Surface area of mesh

Return type

float

property area_faces

The area of each face in the mesh.

Returns

area_faces – Area of each face

Return type

(n,) float

property body_count

How many connected groups of vertices exist in this mesh.

Note that this number may differ from result in mesh.split, which is calculated from FACE rather than vertex adjacency.

Returns

count – Number of connected vertex groups

Return type

int

property bounds

The axis aligned bounds of the faces of the mesh.

Returns

bounds – Bounding box with [min, max] coordinates If mesh is empty will return None

Return type

(2, 3) float or None

property center_mass

The point in space which is the center of mass/volume.

If the current mesh is not watertight, this is meaningless garbage unless it was explicitly set.

Returns

center_mass – Volumetric center of mass of the mesh

Return type

(3,) float

property centroid

The point in space which is the average of the triangle centroids weighted by the area of each triangle.

This will be valid even for non- watertight meshes, unlike self.center_mass

Returns

centroid – The average vertex weighted by face area

Return type

(3,) float

compute_stable_poses(center_mass=None, sigma=0.0, n_samples=1, threshold=0.0)

Computes stable orientations of a mesh and their quasi-static probabilites.

This method samples the location of the center of mass from a multivariate gaussian (mean at com, cov equal to identity times sigma) over n_samples. For each sample, it computes the stable resting poses of the mesh on a a planar workspace and evaluates the probabilities of landing in each pose if the object is dropped onto the table randomly.

This method returns the 4x4 homogeneous transform matrices that place the shape against the planar surface with the z-axis pointing upwards and a list of the probabilities for each pose. The transforms and probabilties that are returned are sorted, with the most probable pose first.

Parameters
  • center_mass ((3,) float) – The object center of mass (if None, this method assumes uniform density and watertightness and computes a center of mass explicitly)

  • sigma (float) – The covariance for the multivariate gaussian used to sample center of mass locations

  • n_samples (int) – The number of samples of the center of mass location

  • threshold (float) – The probability value at which to threshold returned stable poses

Returns

  • transforms ((n, 4, 4) float) – The homogeneous matrices that transform the object to rest in a stable pose, with the new z-axis pointing upwards from the table and the object just touching the table.

  • probs ((n,) float) – A probability ranging from 0.0 to 1.0 for each pose

contains(points)

Given a set of points, determine whether or not they are inside the mesh. This raises an error if called on a non- watertight mesh.

Parameters

points ((n, 3) float) – Points in cartesian space

Returns

contains – Whether or not each point is inside the mesh

Return type

(n, ) bool

convert_units(desired, guess=False)

Convert the units of the mesh into a specified unit.

Parameters
  • desired (string) – Units to convert to (eg ‘inches’)

  • guess (boolean) – If self.units are not defined should we guess the current units of the document and then convert?

convex_decomposition(maxhulls=20, **kwargs)

Compute an approximate convex decomposition of a mesh.

testVHACD Parameters which can be passed as kwargs:

resolution 100000 max. concavity 0.001 plane down-sampling 4 convex-hull down-sampling 4 alpha 0.05 beta 0.05 maxhulls 10 pca 0 mode 0 max. vertices per convex-hull 64 min. volume to add vertices to convex-hulls 0.0001 convex-hull approximation 1 OpenCL acceleration 1 OpenCL platform ID 0 OpenCL device ID 0 output output.wrl log log.txt

Parameters
  • maxhulls (int) – Maximum number of convex hulls to return

  • **kwargs (testVHACD keyword arguments) –

Returns

meshes – List of convex meshes that approximate the original

Return type

list of trimesh.Trimesh

property convex_hull

Get a new Trimesh object representing the convex hull of the current mesh.

Returns

convex – Mesh of convex hull of current mesh

Return type

trimesh.Trimesh

copy()

Safely get a copy of the current mesh.

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 mesh

Return type

trimesh.Trimesh

crc()

A zlib.adler32 checksum for the current mesh data.

This is about 5x faster than an MD5, and the checksum is checked every time something is requested from the cache so it gets called a lot.

Returns

crc – Checksum of current mesh data

Return type

int

property density

The density of the mesh.

Returns

density – The density of the mesh.

Return type

float

difference(other, engine=None)

Boolean difference between this mesh and n other meshes

Parameters

other (trimesh.Trimesh, or list of trimesh.Trimesh objects) – Meshes to difference

Returns

difference – Difference between self and other Trimesh objects

Return type

trimesh.Trimesh

property edges

Edges of the mesh (derived from faces).

Returns

edges – List of vertex indices making up edges

Return type

(n, 2) int

property edges_face

Which face does each edge belong to.

Returns

edges_face – Index of self.faces

Return type

(n,) int

property edges_sorted

Edges sorted along axis 1

Returns

edges_sorted – Same as self.edges but sorted along axis 1

Return type

(n, 2)

property edges_sorted_tree

A KDTree for mapping edges back to edge index.

Returns

tree – Tree when queried with edges will return their index in mesh.edges_sorted

Return type

scipy.spatial.cKDTree

property edges_sparse

Edges in sparse bool COO graph format where connected vertices are True.

Returns

sparse – Sparse graph in COO format

Return type

(len(self.vertices), len(self.vertices)) bool

property edges_unique

The unique edges of the mesh.

Returns

edges_unique – Vertex indices for unique edges

Return type

(n, 2) int

property edges_unique_inverse

Return the inverse required to reproduce self.edges_sorted from self.edges_unique.

Useful for referencing edge properties: mesh.edges_unique[mesh.edges_unique_inverse] == m.edges_sorted

Returns

inverse – Indexes of self.edges_unique

Return type

(len(self.edges),) int

property edges_unique_length

How long is each unique edge.

Returns

length – Length of each unique edge

Return type

(len(self.edges_unique), ) float

property euler_number

Return the Euler characteristic (a topological invariant) for the mesh In order to guarantee correctness, this should be called after remove_unreferenced_vertices

Returns

euler_number – Topological invariant

Return type

int

eval_cached(statement, *args)

Evaluate a statement and cache the result before returning.

Statements are evaluated inside the Trimesh object, and

Parameters
  • statement (str) – Statement of valid python code

  • *args (list) – Available inside statement as args[0], etc

Returns

result

Return type

result of running eval on statement with args

Examples

r = mesh.eval_cached(‘np.dot(self.vertices, args[0])’, [0,0,1])

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

Export the current mesh to a file object. If file_obj is a filename, file will be written there.

Supported formats are stl, off, ply, collada, json, dict, glb, dict64, msgpack.

Parameters
  • file_obj (open writeable file object) – str, file name where to save the mesh None, if you would like this function to return the export blob

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

property extents

The length, width, and height of the axis aligned bounding box of the mesh.

Returns

extents – Array containing axis aligned [length, width, height] If mesh is empty returns None

Return type

(3,) float or None

property face_adjacency

Find faces that share an edge, which we call here ‘adjacent’.

Returns

adjacency – Pairs of faces which share an edge

Return type

(n,2) int

Examples

In [1]: mesh = trimesh.load(‘models/featuretype.STL’)

In [2]: mesh.face_adjacency Out[2]: array([[ 0, 1],

[ 2, 3], [ 0, 3], …, [1112, 949], [3467, 3475], [1113, 3475]])

In [3]: mesh.faces[mesh.face_adjacency[0]] Out[3]: TrackedArray([[ 1, 0, 408],

[1239, 0, 1]], dtype=int64)

In [4]: import networkx as nx

In [5]: graph = nx.from_edgelist(mesh.face_adjacency)

In [6]: groups = nx.connected_components(graph)

property face_adjacency_angles

Return the angle between adjacent faces

Returns

adjacency_angle – Angle between adjacent faces Each value corresponds with self.face_adjacency

Return type

(n,) float

property face_adjacency_convex

Return faces which are adjacent and locally convex.

What this means is that given faces A and B, the one vertex in B that is not shared with A, projected onto the plane of A has a projection that is zero or negative.

Returns

are_convex – Face pairs that are locally convex

Return type

(len(self.face_adjacency),) bool

property face_adjacency_edges

Returns the edges that are shared by the adjacent faces.

Returns

edges – Vertex indices which correspond to face_adjacency

Return type

(n, 2) int

property face_adjacency_edges_tree

A KDTree for mapping edges back face adjacency index.

Returns

tree – Tree when queried with SORTED edges will return their index in mesh.face_adjacency

Return type

scipy.spatial.cKDTree

property face_adjacency_projections

The projection of the non- shared vertex of a triangle onto its adjacent face

Returns

projections – Dot product of vertex onto plane of adjacent triangle.

Return type

(len(self.face_adjacency),) float

property face_adjacency_radius

The approximate radius of a cylinder that fits inside adjacent faces.

Returns

radii – Approximate radius formed by triangle pair

Return type

(len(self.face_adjacency),) float

property face_adjacency_span

The approximate perpendicular projection of the non- shared vertices in a pair of adjacent faces onto the shared edge of the two faces.

Returns

span – Approximate span between the non- shared vertices

Return type

(len(self.face_adjacency),) float

property face_adjacency_tree

An R-tree of face adjacencies.

Returns

tree – Where each edge in self.face_adjacency has a rectangular cell

Return type

rtree.index

property face_adjacency_unshared

Return the vertex index of the two vertices not in the shared edge between two adjacent faces

Returns

vid_unshared – Indexes of mesh.vertices

Return type

(len(mesh.face_adjacency), 2) int

property face_angles

Returns the angle at each vertex of a face.

Returns

angles – Angle at each vertex of a face

Return type

(n, 3) float

property face_angles_sparse

A sparse matrix representation of the face angles.

Returns

sparse – dtype: float shape: (len(self.vertices), len(self.faces))

Return type

scipy.sparse.coo_matrix with:

property face_normals

Return the unit normal vector for each face.

If a face is degenerate and a normal can’t be generated a zero magnitude unit vector will be returned for that face.

Returns

normals – Normal vectors of each face

Return type

(len(self.faces), 3) np.float64

property faces

The faces of the mesh.

This is regarded as core information which cannot be regenerated from cache, and as such is stored in self._data which tracks the array for changes and clears cached values of the mesh if this is altered.

Returns

faces – Representing triangles which reference self.vertices

Return type

(n,3) int

property faces_sparse

A sparse matrix representation of the faces.

Returns

sparse – Has properties: dtype : bool shape : (len(self.vertices), len(self.faces))

Return type

scipy.sparse.coo_matrix

property faces_unique_edges

For each face return which indexes in mesh.unique_edges constructs that face.

Returns

faces_unique_edges – Indexes of self.edges_unique that construct self.faces

Return type

(len(self.faces), 3) int

Examples

In [0]: mesh.faces[0:2] Out[0]: TrackedArray([[ 1, 6946, 24224],

[ 6946, 1727, 24225]])

In [1]: mesh.edges_unique[mesh.faces_unique_edges[0:2]] Out[1]: array([[[ 1, 6946],

[ 6946, 24224], [ 1, 24224]],

[[ 1727, 6946],

[ 1727, 24225], [ 6946, 24225]]])

property facets

Return a list of face indices for coplanar adjacent faces.

Returns

facets – Groups of indexes of self.faces

Return type

(n, ) sequence of (m,) int

property facets_area

Return an array containing the area of each facet.

Returns

area – Total area of each facet (group of faces)

Return type

(len(self.facets),) float

property facets_boundary

Return the edges which represent the boundary of each facet

Returns

edges_boundary – Indices of self.vertices

Return type

sequence of (n, 2) int

property facets_normal

Return the normal of each facet

Returns

normals – A unit normal vector for each facet

Return type

(len(self.facets), 3) float

property facets_on_hull

Find which facets of the mesh are on the convex hull.

Returns

on_hull – is A facet on the meshes convex hull or not

Return type

(len(mesh.facets),) bool

property facets_origin

Return a point on the facet plane.

Returns

origins – A point on each facet plane

Return type

(len(self.facets), 3) float

fill_holes()

Fill single triangle and single quad holes in the current mesh.

Returns

watertight – Is the mesh watertight after the function completes

Return type

bool

fix_normals(**kwargs)

Find and fix problems with self.face_normals and self.faces winding direction.

For face normals ensure that vectors are consistently pointed outwards, and that self.faces is wound in the correct direction for all connected components.

Parameters

multibody (None or bool) – Fix normals across multiple bodies if None automatically pick from body_count

property identifier

Return a float vector which is unique to the mesh and is robust to rotation and translation.

Returns

identifier – Identifying properties of the current mesh

Return type

(6,) float

property identifier_md5

An MD5 of the rotation invariant identifier vector

Returns

hashed – MD5 hash of the identifier vector

Return type

str

intersection(other, engine=None)

Boolean intersection between this mesh and n other meshes

Parameters

other (trimesh.Trimesh, or list of trimesh.Trimesh objects) – Meshes to calculate intersections with

Returns

intersection – Mesh of the volume contained by all passed meshes

Return type

trimesh.Trimesh

invert()

Invert the mesh in- place by reversing the winding of every face and negating normals without dumping the cache.

self.faces : columns reversed self.face_normals : negated if defined self.vertex_normals : negated if defined

property is_convex

Check if a mesh is convex or not.

Returns

is_convex – Is mesh convex or not

Return type

bool

property is_empty

Does the current mesh have data defined.

Returns

empty – If True, no data is set on the current mesh

Return type

bool

property is_volume

Check if a mesh has all the properties required to represent a valid volume, rather than just a surface.

These properties include being watertight, having consistent winding and outward facing normals.

Returns

valid – Does the mesh represent a volume

Return type

bool

property is_watertight

Check if a mesh is watertight by making sure every edge is included in two faces.

Returns

is_watertight – Is mesh watertight or not

Return type

bool

property is_winding_consistent

Does the mesh have consistent winding or not. A mesh with consistent winding has each shared edge going in an opposite direction from the other in the pair.

Returns

consistent – Is winding is consistent or not

Return type

bool

property kdtree

Return a scipy.spatial.cKDTree of the vertices of the mesh. Not cached as this lead to observed memory issues and segfaults.

Returns

tree – Contains mesh.vertices

Return type

scipy.spatial.cKDTree

property mass

Mass of the current mesh, based on specified density and volume. If the current mesh isn’t watertight this is garbage.

Returns

mass – Mass of the current mesh

Return type

float

property mass_properties

Returns the mass properties of the current mesh.

Assumes uniform density, and result is probably garbage if mesh isn’t watertight.

Returns

properties – With keys: ‘volume’ : in global units^3 ‘mass’ : From specified density ‘density’ : Included again for convenience (same as kwarg density) ‘inertia’ : Taken at the center of mass and aligned with global

coordinate system

’center_mass’ : Center of mass location, in global coordinate system

Return type

dict

md5()

An MD5 of the core geometry information for the mesh, faces and vertices.

Generated from TrackedArray which subclasses np.ndarray to monitor array for changes and returns a correct lazily evaluated md5 so it only has to recalculate the hash occasionally, rather than on every call.

Returns

md5 – MD5 of everything in the DataStore

Return type

string

merge_vertices(digits=None, textured=True)

If a mesh has vertices that are closer than trimesh.constants.tol.merge reindex faces to reference the same index for both vertices.

Parameters
  • digits (int) – If specified overrides tol.merge

  • textured (bool) – If True avoids merging vertices with different UV coordinates. No effect on untextured meshes.

property moment_inertia

Return the moment of inertia matrix of the current mesh. If mesh isn’t watertight this is garbage.

Returns

inertia – Moment of inertia of the current mesh

Return type

(3, 3) float

outline(face_ids=None, **kwargs)

Given a list of face indexes find the outline of those faces and return it as a Path3D.

The outline is defined here as every edge which is only included by a single triangle.

Note that this implies a non-watertight mesh as the outline of a watertight mesh is an empty path.

Parameters
  • face_ids ((n,) int) – Indices to compute the outline of. If None, outline of full mesh will be computed.

  • **kwargs (passed to Path3D constructor) –

Returns

path – Curve in 3D of the outline

Return type

Path3D

property principal_inertia_components

Return the principal components of inertia

Ordering corresponds to mesh.principal_inertia_vectors

Returns

components – Principal components of inertia

Return type

(3,) float

property principal_inertia_transform

A transform which moves the current mesh so the principal inertia vectors are on the X,Y, and Z axis, and the centroid is at the origin.

Returns

transform – Homogeneous transformation matrix

Return type

(4, 4) float

property principal_inertia_vectors

Return the principal axis of inertia.

Ordering corresponds to mesh.principal_inertia_components

Returns

vectors – Three vectors pointing along the principal axis of inertia directions

Return type

(3, 3) float

process()

Do the bare minimum processing to make a mesh useful.

Does this by:
  1. removing NaN and Inf values

  2. merging duplicate vertices

If self._validate:
  1. Remove triangles which have one edge of their rectangular 2D oriented bounding box shorter than tol.merge

  2. remove duplicated triangles

Returns

self – Current mesh

Return type

trimesh.Trimesh

property referenced_vertices

Which vertices in the current mesh are referenced by a face.

Returns

referenced – Which vertices are referenced by a face

Return type

(len(self.vertices),) bool

register(other, **kwargs)

Align a mesh with another mesh or a PointCloud using the principal axes of inertia as a starting point which is refined by iterative closest point.

Parameters
  • mesh (trimesh.Trimesh object) – Mesh to align with other

  • other (trimesh.Trimesh or (n, 3) float) – Mesh or points in space

  • samples (int) – Number of samples from mesh surface to align

  • icp_first (int) – How many ICP iterations for the 9 possible combinations of

  • icp_final (int) – How many ICP itertations for the closest candidate from the wider search

Returns

  • mesh_to_other ((4, 4) float) – Transform to align mesh to the other object

  • cost (float) – Average square distance per point

remove_degenerate_faces(height=1e-08)

Remove degenerate faces (faces without 3 unique vertex indices) from the current mesh.

If a height is specified, it will remove any face with a 2D oriented bounding box with one edge shorter than that height.

If not specified, it will remove any face with a zero normal.

Parameters

height (float) – If specified removes faces with an oriented bounding box shorter than this on one side.

Returns

nondegenerate – Mask used to remove faces

Return type

(len(self.faces),) bool

remove_duplicate_faces()

On the current mesh remove any faces which are duplicates.

self.faces : removes duplicates

remove_infinite_values()

Ensure that every vertex and face consists of finite numbers.

This will remove vertices or faces containing np.nan and np.inf

self.faces : masked to remove np.inf/np.nan self.vertices : masked to remove np.inf/np.nan

remove_unreferenced_vertices()

Remove all vertices in the current mesh which are not referenced by a face.

rezero()

Translate the mesh so that all vertex vertices are positive.

self.vertices : Translated to first octant (all values > 0)

sample(count, return_index=False)

Return random samples distributed across the surface of the mesh

Parameters
  • count (int) – Number of points to sample

  • return_index (bool) – If True will also return the index of which face each sample was taken from.

Returns

  • samples ((count, 3) float) – Points on surface of mesh

  • face_index ((count, ) int) – Index of self.faces

property scale

A metric for the overall scale of the mesh, the length of the diagonal of the axis aligned bounding box of the mesh.

Returns

scale – The length of the meshes AABB diagonal

Return type

float

scene(**kwargs)

Get a Scene object containing the current mesh.

Returns

scene – Contains just the current mesh

Return type

trimesh.scene.scene.Scene

section(plane_normal, plane_origin)

Returns a 3D cross section of the current mesh and a plane defined by origin and normal.

Parameters
  • plane_normal – Normal vector of section plane

  • plane_origin ((3,) float) – Point on the cross section plane

Returns

intersections – Curve of intersection

Return type

Path3D or None

section_multiplane(plane_origin, plane_normal, heights)

Return multiple parallel cross sections of the current mesh in 2D.

Parameters
  • plane_normal – Normal vector of section plane

  • plane_origin ((3,) float) – Point on the cross section plane

  • heights ((n,) float) – Each section is offset by height along the plane normal.

Returns

paths – 2D cross sections at specified heights. path.metadata[‘to_3D’] contains transform to return 2D section back into 3D space.

Return type

(n,) Path2D or None

show(**kwargs)

Render the mesh in an opengl window. Requires pyglet.

Parameters

smooth (bool) – Run smooth shading on mesh or not, large meshes will be slow

Returns

scene – Scene with current mesh in it

Return type

trimesh.scene.Scene

slice_plane(plane_origin, plane_normal, **kwargs)

Slice the mesh with a plane, returning a new mesh that is the portion of the original mesh to the positive normal side of the plane

Parameters
  • plane_normal – Normal vector of slicing plane

  • plane_origin ((3,) float) – Point on the slicing plane

Returns

new_mesh – Subset of current mesh that intersects the half plane to the positive normal side of the plane

Return type

trimesh.Trimesh or None

smoothed(**kwargs)

Return a version of the current mesh which will render nicely, without changing source mesh.

Parameters
  • angle (float or None) – Angle in radians face pairs with angles smaller than this will appear smoothed

  • facet_minlen (int or None) – Minimum length of facets to consider

Returns

smoothed – Non watertight version of current mesh which will render nicely with smooth shading

Return type

trimesh.Trimesh

split(**kwargs)

Returns a list of Trimesh objects, based on face connectivity. Splits into individual components, sometimes referred to as ‘bodies’

Parameters
  • only_watertight (bool) – Only return watertight meshes and discard remainder

  • adjacency (None or (n, 2) int) – Override face adjacency with custom values

Returns

meshes – Separate bodies from original mesh

Return type

(n,) trimesh.Trimesh

subdivide(face_index=None)

Subdivide a mesh, with each subdivided face replaced with four smaller faces.

Parameters

face_index ((m,) int or None) – If None all faces of mesh will be subdivided If (m,) int array of indices: only specified faces will be subdivided. Note that in this case the mesh will generally no longer be manifold, as the additional vertex on the midpoint will not be used by the adjacent faces to the faces specified, and an additional postprocessing step will be required to make resulting mesh watertight

submesh(faces_sequence, **kwargs)

Return a subset of the mesh.

Parameters
  • faces_sequence (sequence (m,) int) – Face indices of mesh

  • only_watertight (bool) – Only return submeshes which are watertight

  • append (bool) – Return a single mesh which has the faces appended. if this flag is set, only_watertight is ignored

Returns

  • if append (trimesh.Trimesh object)

  • else (list of trimesh.Trimesh objects)

property symmetry

Check whether a mesh has rotational symmetry.

Returns

symmetry – ‘radial’ Symmetric around an axis ‘spherical’ Symmetric around a point

Return type

None No rotational symmetry

property symmetry_axis

If a mesh has rotational symmetry, return the axis.

Returns

axis – Axis around which a 2D profile was revolved to generate this mesh

Return type

(3,) float

property symmetry_section

If a mesh has rotational symmetry, return the two vectors which make up a section coordinate frame.

Returns

section

Return type

(2, 3) float, vectors to take a section along

to_dict()

Return a dictionary representation of the current mesh, with keys that can be used as the kwargs for the Trimesh constructor, eg:

a = Trimesh(**other_mesh.to_dict())

Returns

result – With keys that match trimesh constructor

Return type

dict

property triangles

Actual triangles of the mesh (points, not indexes)

Returns

triangles – Points of triangle vertices

Return type

(n, 3, 3) float

property triangles_center

The center of each triangle (barycentric [1/3, 1/3, 1/3])

Returns

triangles_center – Center of each triangular face

Return type

(len(self.faces), 3) float

property triangles_cross

The cross product of two edges of each triangle.

Returns

crosses – Cross product of each triangle

Return type

(n, 3) float

property triangles_tree

An R-tree containing each face of the mesh.

Returns

tree – Each triangle in self.faces has a rectangular cell

Return type

rtree.index

union(other, engine=None)

Boolean union between this mesh and n other meshes

Parameters

other (trimesh.Trimesh, or list of trimesh.Trimesh objects) – Other meshes to union

Returns

union – Union of self and other Trimesh objects

Return type

trimesh.Trimesh

property units

Definition of units for the mesh.

Returns

units – Unit system mesh is in, or None if not defined

Return type

str

unmerge_vertices()

Removes all face references so that every face contains three unique vertex indices and no faces are adjacent.

update_faces(mask)

In many cases, we will want to remove specific faces. However, there is additional bookkeeping to do this cleanly. This function updates the set of faces with a validity mask, as well as keeping track of normals and colors.

Parameters

valid – Mask to remove faces

update_vertices(mask, inverse=None)

Update vertices with a mask.

Parameters
  • vertex_mask ((len(self.vertices)) bool) – Array of which vertices to keep

  • inverse ((len(self.vertices)) int) – Array to reconstruct vertex references such as output by np.unique

property vertex_adjacency_graph

Returns a networkx graph representing the vertices and their connections in the mesh.

Returns

graph – Graph representing vertices and edges between them where vertices are nodes and edges are edges

Return type

networkx.Graph

Examples

This is useful for getting nearby vertices for a given vertex, potentially for some simple smoothing techniques.

mesh = trimesh.primitives.Box() graph = mesh.vertex_adjacency_graph graph.neighbors(0) > [1,2,3,4]

property vertex_defects

Return the vertex defects, or (2*pi) minus the sum of the angles of every face that includes that vertex.

If a vertex is only included by coplanar triangles, this will be zero. For convex regions this is positive, and concave negative.

Returns

vertex_defect – Vertex defect at the every vertex

Return type

(len(self.vertices), ) float

property vertex_degree

Return the number of faces each vertex is included in.

Returns

degree – Number of faces each vertex is included in

Return type

(len(self.vertices), ) int

property vertex_faces

A representation of the face indices that correspond to each vertex.

Returns

vertex_faces – Each row contains the face indices that correspond to the given vertex, padded with -1 up to the max number of faces corresponding to any one vertex Where n == len(self.vertices), m == max number of faces for a single vertex

Return type

(n,m) int

property vertex_neighbors

The vertex neighbors of each vertex of the mesh, determined from the cached vertex_adjacency_graph, if already existent.

Returns

vertex_neighbors – Represents immediate neighbors of each vertex along the edge of a triangle

Return type

(len(self.vertices),) int

Examples

This is useful for getting nearby vertices for a given vertex, potentially for some simple smoothing techniques.

>>> mesh = trimesh.primitives.Box()
>>> mesh.vertex_neighbors[0]
[1,2,3,4]
property vertex_normals

The vertex normals of the mesh. If the normals were loaded we check to make sure we have the same number of vertex normals and vertices before returning them. If there are no vertex normals defined or a shape mismatch we calculate the vertex normals from the mean normals of the faces the vertex is used in.

Returns

vertex_normals – Represents the surface normal at each vertex. Where n == len(self.vertices)

Return type

(n,3) float

property vertices

The vertices of the mesh.

This is regarded as core information which cannot be generated from cache and as such is stored in self._data which tracks the array for changes and clears cached values of the mesh if this is altered.

Returns

vertices – Points in cartesian space referenced by self.faces

Return type

(n, 3) float

property visual

Get the stored visuals for the current mesh.

Returns

visual – Contains visual information about the mesh

Return type

ColorVisuals or TextureVisuals

property volume

Volume of the current mesh calculated using a surface integral. If the current mesh isn’t watertight this is garbage.

Returns

volume – Volume of the current mesh

Return type

float

voxelized(pitch, method='subdivide', **kwargs)

Return a VoxelGrid object representing the current mesh discretized into voxels at the specified pitch

Parameters
  • pitch (float) – The edge length of a single voxel

  • method (implementation key. See trimesh.voxel.creation.voxelizers) –

  • **kwargs (additional kwargs passed to the specified implementation.) –

Returns

voxelized – Representing the current mesh

Return type

VoxelGrid object