trimesh.base#
github.com/mikedh/trimesh#
Library for importing, exporting and doing simple operations on triangular meshes.
- class trimesh.base.Trimesh(vertices: ndarray[Any, dtype[float64]] | None = None, faces: ndarray[Any, dtype[int64]] | None = None, face_normals: ndarray[Any, dtype[float64]] | None = None, vertex_normals: ndarray[Any, dtype[float64]] | None = None, face_colors: ndarray[Any, dtype[float64]] | None = None, vertex_colors: ndarray[Any, dtype[float64]] | None = None, face_attributes: Dict[str, ndarray[Any, dtype[_ScalarType_co]]] | None = None, vertex_attributes: Dict[str, ndarray[Any, dtype[_ScalarType_co]]] | None = None, metadata: Dict[str, Any] | None = None, process: bool = True, validate: bool = False, merge_tex: bool | None = None, merge_norm: bool | None = None, use_embree: bool = True, initial_cache: Dict[str, ndarray] | None = None, visual: ColorVisuals | TextureVisuals | None = None, **kwargs)#
Bases:
Geometry3D
- __init__(vertices: ndarray[Any, dtype[float64]] | None = None, faces: ndarray[Any, dtype[int64]] | None = None, face_normals: ndarray[Any, dtype[float64]] | None = None, vertex_normals: ndarray[Any, dtype[float64]] | None = None, face_colors: ndarray[Any, dtype[float64]] | None = None, vertex_colors: ndarray[Any, dtype[float64]] | None = None, face_attributes: Dict[str, ndarray[Any, dtype[_ScalarType_co]]] | None = None, vertex_attributes: Dict[str, ndarray[Any, dtype[_ScalarType_co]]] | None = None, metadata: Dict[str, Any] | None = None, process: bool = True, validate: bool = False, merge_tex: bool | None = None, merge_norm: bool | None = None, use_embree: bool = True, initial_cache: Dict[str, ndarray] | None = None, visual: ColorVisuals | TextureVisuals | None = None, **kwargs) None #
A Trimesh object contains a triangular 3D mesh.
- Parameters:
vertices ((n, 3) float) – Array of vertex locations
faces ((m, 3) or (m, 4) int) – Array of triangular or quad faces (triangulated on load)
face_normals ((m, 3) float) – Array of normal vectors corresponding to faces
vertex_normals ((n, 3) float) – Array of normal vectors for vertices
metadata (dict) – Any metadata about the mesh
process (bool) – if True, Nan and Inf values will be removed immediately and vertices will be merged
validate (bool) – If True, degenerate and duplicate faces will be removed immediately, and some functions will alter the mesh to ensure consistent results.
use_embree (bool) – If True try to use pyembree raytracer. If pyembree is not available it will automatically fall back to a much slower rtree/numpy implementation
initial_cache (dict) – A way to pass things to the cache in case expensive things were calculated before creating the mesh object.
visual (ColorVisuals or TextureVisuals) – Assigned to self.visual
- apply_transform(matrix: ndarray[Any, dtype[float64]]) Trimesh #
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: float64#
Summed area of all triangles in the current mesh.
- Returns:
area – Surface area of mesh
- Return type:
float
- property area_faces: ndarray[Any, dtype[float64]]#
The area of each face in the mesh.
- Returns:
area_faces – Area of each face
- Return type:
(n, ) float
- property as_open3d#
Return an open3d.geometry.TriangleMesh version of the current mesh.
- Returns:
open3d – Current mesh as an open3d object.
- Return type:
open3d.geometry.TriangleMesh
- property body_count: int#
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: ndarray[Any, dtype[float64]]#
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: ndarray[Any, dtype[float64]]#
The point in space which is the center of mass/volume.
- Returns:
center_mass – Volumetric center of mass of the mesh.
- Return type:
(3, ) float
- property centroid: ndarray[Any, dtype[float64]]#
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: ndarray[Any, dtype[float64]] | None = None, sigma: float = 0.0, n_samples: int = 1, threshold: float = 0.0)#
Computes stable orientations of a mesh and their quasi-static probabilities.
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: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) ndarray[Any, dtype[bool]] #
Given an array 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: str, guess: bool = False) Trimesh #
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(**kwargs) List[Trimesh] #
Compute an approximate convex decomposition of a mesh using pip install pyVHACD.
- Returns:
meshes – List of convex meshes that approximate the original
**kwargs (VHACD keyword arguments)
- property convex_hull: Trimesh#
Returns a Trimesh object representing the convex hull of the current mesh.
- Returns:
convex – Mesh of convex hull of current mesh
- Return type:
- copy(include_cache: bool = False) Trimesh #
Safely return a copy of the current mesh.
By default, copied meshes will have emptied cache to avoid memory issues and so may be slow on initial operations until caches are regenerated.
Current object will never have its cache cleared.
- Parameters:
include_cache (bool) – If True, will shallow copy cached data to new mesh
- Returns:
copied – Copy of current mesh
- Return type:
- property density: float#
The density of the mesh used in inertia calculations.
- Returns:
The density of the primitive.
- Return type:
density
- difference(other: Trimesh, engine: str | None = None, **kwargs) Trimesh #
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:
- property edges: ndarray[Any, dtype[int64]]#
Edges of the mesh (derived from faces).
- Returns:
edges – List of vertex indices making up edges
- Return type:
(n, 2) int
- property edges_face: ndarray[Any, dtype[int64]]#
Which face does each edge belong to.
- Returns:
edges_face – Index of self.faces
- Return type:
(n, ) int
- property edges_sorted: ndarray[Any, dtype[int64]]#
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: cKDTree#
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: coo_matrix#
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: ndarray[Any, dtype[int64]]#
The unique edges of the mesh.
- Returns:
edges_unique – Vertex indices for unique edges
- Return type:
(n, 2) int
- property edges_unique_inverse: ndarray[Any, dtype[int64]]#
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: ndarray[Any, dtype[float64]]#
How long is each unique edge.
- Returns:
length – Length of each unique edge
- Return type:
(len(self.edges_unique), ) float
- property euler_number: int#
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: str, *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: str | None = None, **kwargs) Dict[str, Dict[str, str] | List[List[int]] | List[List[float]]] | str | bytes | Dict[str, Dict[str, str] | Dict[str, str | Tuple[int, int]]] #
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, return the export blob
file_type (str) – Which file type to export as, if file_name is passed this is not required.
- property extents: ndarray[Any, dtype[float64]]#
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: ndarray[Any, dtype[int64]]#
Find faces that share an edge i.e. ‘adjacent’ faces.
- 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: ndarray[Any, dtype[float64]]#
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: ndarray[Any, dtype[bool]]#
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: ndarray[Any, dtype[int64]]#
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: cKDTree#
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: ndarray[Any, dtype[float64]]#
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: ndarray[Any, dtype[float64]]#
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: ndarray[Any, dtype[float64]]#
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: Index#
An R-tree of face adjacencies.
- Returns:
Where each edge in self.face_adjacency has a rectangular cell
- Return type:
tree
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: ndarray[Any, dtype[float64]]#
Returns the angle at each vertex of a face.
- Returns:
angles – Angle at each vertex of a face
- Return type:
(len(self.faces), 3) float
- property face_angles_sparse: coo_matrix#
A sparse matrix representation of the face angles.
- Returns:
sparse – Float sparse matrix with with shape: (len(self.vertices), len(self.faces))
- Return type:
scipy.sparse.coo_matrix
- property face_neighborhood: ndarray[Any, dtype[int64]]#
Find faces that share a vertex i.e. ‘neighbors’ faces.
- Returns:
neighborhood – Pairs of faces which share a vertex
- Return type:
(n, 2) int
- property face_normals: ndarray[Any, dtype[float64]]#
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) float64
- property faces: ndarray[Any, dtype[int64]]#
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 altered.
- Returns:
faces – References for self.vertices for triangles.
- Return type:
(n, 3) int64
- property faces_sparse: coo_matrix#
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: ndarray[Any, dtype[int64]]#
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[:2] Out[0]: TrackedArray([[ 1, 6946, 24224],
[ 6946, 1727, 24225]])
In [1]: mesh.edges_unique[mesh.faces_unique_edges[:2]] Out[1]: array([[[ 1, 6946],
[ 6946, 24224], [ 1, 24224]],
- [[ 1727, 6946],
[ 1727, 24225], [ 6946, 24225]]])
- property facets: List[ndarray[Any, dtype[int64]]]#
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: ndarray[Any, dtype[float64]]#
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: List[ndarray[Any, dtype[int64]]]#
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: ndarray[Any, dtype[float64]]#
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: ndarray[Any, dtype[bool]]#
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: ndarray[Any, dtype[float64]]#
Return a point on the facet plane.
- Returns:
origins – A point on each facet plane
- Return type:
(len(self.facets), 3) float
- fill_holes() bool #
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(multibody: bool | None = None) None #
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: ndarray[Any, dtype[float64]]#
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:
(7,) float
- property identifier_hash: str#
A hash of the rotation invariant identifier vector.
- Returns:
hashed – Hex string of the SHA256 hash from the identifier vector at hand-tuned sigfigs.
- Return type:
str
- property integral_mean_curvature: float64#
The integral mean curvature, or the surface integral of the mean curvature.
- Returns:
area – Integral mean curvature of mesh
- Return type:
float
- intersection(other: Trimesh, engine: str | None = None, **kwargs) Trimesh #
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:
- invert() None #
Invert the mesh in-place by reversing the winding of every face and negating normals without dumping the cache.
Alters self.faces by reversing columns, and negating self.face_normals and self.vertex_normals.
- property is_convex: bool#
Check if a mesh is convex or not.
- Returns:
is_convex – Is mesh convex or not
- Return type:
bool
- property is_empty: bool#
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: bool#
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: bool#
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: bool#
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: cKDTree#
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: float64#
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: MassProperties#
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
- merge_vertices(merge_tex: bool | None = None, merge_norm: bool | None = None, digits_vertex: bool | None = None, digits_norm: bool | None = None, digits_uv: bool | None = None) None #
Removes duplicate vertices grouped by position and optionally texture coordinate and normal.
- Parameters:
mesh (Trimesh object) – Mesh to merge vertices on
merge_tex (bool) – If True textured meshes with UV coordinates will have vertices merged regardless of UV coordinates
merge_norm (bool) – If True, meshes with vertex normals will have vertices merged ignoring different normals
digits_vertex (None or int) – Number of digits to consider for vertex position
digits_norm (int) – Number of digits to consider for unit normals
digits_uv (int) – Number of digits to consider for UV coordinates
- property moment_inertia: ndarray[Any, dtype[float64]]#
Return the moment of inertia matrix of the current mesh. If mesh isn’t watertight this is garbage. The returned moment of inertia is axis aligned at the mesh’s center of mass mesh.center_mass. If you want the moment at any other frame including the origin call: mesh.moment_inertia_frame
- Returns:
inertia – Moment of inertia of the current mesh at the center of mass and aligned with the cartesian axis.
- Return type:
(3, 3) float
- moment_inertia_frame(transform: ndarray[Any, dtype[float64]]) ndarray[Any, dtype[float64]] #
Get the moment of inertia of this mesh with respect to an arbitrary frame, versus with respect to the center of mass as returned by mesh.moment_inertia.
For example if transform is an identity matrix np.eye(4) this will give the moment at the origin.
Uses the parallel axis theorum to move the center mass tensor to this arbitrary frame.
- Parameters:
transform ((4, 4) float) – Homogeneous transformation matrix.
- Returns:
inertia – Moment of inertia in the requested frame.
- Return type:
(3, 3)
- property mutable: bool#
Is the current mesh allowed to be altered in-place?
- Returns:
If data is allowed to be set for the mesh.
- Return type:
mutable
- nondegenerate_faces(height: float = 1e-08) ndarray[Any, dtype[bool]] #
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
- outline(face_ids: ndarray[Any, dtype[int64]] | None = None, **kwargs) Path3D #
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:
- property principal_inertia_components: ndarray[Any, dtype[float64]]#
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: ndarray[Any, dtype[float64]]#
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: ndarray[Any, dtype[float64]]#
Return the principal axis of inertia as unit vectors. The order corresponds to mesh.principal_inertia_components.
- Returns:
vectors – Three vectors pointing along the principal axis of inertia directions
- Return type:
(3, 3) float
- process(validate: bool = False, merge_tex: bool | None = None, merge_norm: bool | None = None) Trimesh #
Do processing to make a mesh useful.
- Does this by:
removing NaN and Inf values
merging duplicate vertices
- If validate:
Remove triangles which have one edge of their 2D oriented bounding box shorter than tol.merge
remove duplicated triangles
ensure triangles are consistently wound and normals face outwards
- Parameters:
validate (bool) – Remove degenerate and duplicate faces.
- Returns:
self – Current mesh
- Return type:
- projected(normal, **kwargs) Path2D #
Project a mesh onto a plane and then extract the polygon that outlines the mesh projection on that plane.
- Parameters:
mesh (trimesh.Trimesh) – Source geometry
check (bool) – If True make sure is flat
normal ((3,) float) – Normal to extract flat pattern along
origin (None or (3,) float) – Origin of plane to project mesh onto
pad (float) – Proportion to pad polygons by before unioning and then de-padding result by to avoid zero-width gaps.
tol_dot (float) – Tolerance for discarding on-edge triangles.
max_regions (int) – Raise an exception if the mesh has more than this number of disconnected regions to fail quickly before unioning.
- Returns:
projected – Outline of source mesh
- Return type:
- property referenced_vertices: ndarray[Any, dtype[bool]]#
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: Geometry3D, **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: float = 1e-08) None #
DERECATED MARCH 2024 REPLACE WITH: self.update_faces(self.nondegenerate_faces(height=height))
- remove_duplicate_faces() None #
DERECATED MARCH 2024 REPLACE WITH: mesh.update_faces(mesh.unique_faces())
- remove_infinite_values() None #
Ensure that every vertex and face consists of finite numbers. This will remove vertices or faces containing np.nan and np.inf
Alters self.faces and self.vertices
- remove_unreferenced_vertices() None #
Remove all vertices in the current mesh which are not referenced by a face.
- rezero() None #
Translate the mesh so that all vertex vertices are positive.
Alters self.vertices.
- sample(count: int, return_index: bool = False, face_weight: ndarray[Any, dtype[float64]] | None = None)#
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.
face_weight (None or len(mesh.faces) float) – Weight faces by a factor other than face area. If None will be the same as face_weight=mesh.area
- Returns:
samples ((count, 3) float) – Points on surface of mesh
face_index ((count, ) int) – Index of self.faces
- property scale: float#
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) Scene #
Returns a Scene object containing the current mesh.
- Returns:
scene – Contains just the current mesh
- Return type:
- section(plane_normal: List[int], plane_origin: List[int], **kwargs) Path3D #
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: ndarray[Any, dtype[float64]], plane_normal: ndarray[Any, dtype[float64]], heights: ndarray[Any, dtype[float64]])#
Return multiple parallel cross sections of the current mesh in 2D.
- Parameters:
plane_origin ((3, ) float) – Point on the cross section plane
plane_normal – Normal vector of 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:
- simplify_quadratic_decimation(*args, **kwargs)#
DERECATED MARCH 2024 REPLACE WITH: mesh.simplify_quadric_decimation
- simplify_quadric_decimation(face_count: int) Trimesh #
A thin wrapper around the open3d implementation of this: open3d.geometry.TriangleMesh.simplify_quadric_decimation
- Parameters:
face_count (int) – Number of faces desired in the resulting mesh.
- Returns:
simple – Simplified version of mesh.
- Return type:
- slice_plane(plane_origin, plane_normal, cap=False, face_index=None, cached_dots=None, **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
- plane_origin(3,) float
Point on plane to intersect with mesh
- plane_normal(3,) float
Normal vector of plane to intersect with mesh
- capbool
If True, cap the result with a triangulated polygon
- face_index((m,) int)
Indexes of mesh.faces to slice. When no mask is provided, the default is to slice all faces.
- cached_dots(n, 3) float
If an external function has stored dot products pass them here to avoid recomputing
- 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
- property smooth_shaded#
Smooth shading in OpenGL relies on which vertices are shared, this function will disconnect regions above an angle threshold and return a non-watertight version which will look better in an OpenGL rendering context.
If you would like to use non-default arguments see graph.smooth_shade.
- Returns:
smooth_shaded – Non watertight version of current mesh.
- Return type:
- smoothed(**kwargs)#
DEPRECATED: use mesh.smooth_shaded or trimesh.graph.smooth_shade(mesh)
- split(**kwargs) List[Trimesh] #
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 = None) Trimesh #
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
- subdivide_loop(iterations=None)#
Subdivide a mesh by dividing each triangle into four triangles and approximating their smoothed surface using loop subdivision. Loop subdivision often looks better on triangular meshes than catmul-clark, which operates primarily on quads.
- Parameters:
iterations (int) – Number of iterations to run subdivision.
multibody (bool) – If True will try to subdivide for each submesh
- subdivide_to_size(max_edge, max_iter=10, return_index=False)#
Subdivide a mesh until every edge is shorter than a specified length.
Will return a triangle soup, not a nicely structured mesh.
- Parameters:
max_edge (float) – Maximum length of any edge in the result
max_iter (int) – The maximum number of times to run subdivision
return_index (bool) – If True, return index of original face for new faces
- submesh(faces_sequence: List[ndarray[Any, dtype[int64]]], **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:
submesh – Single mesh if append or list of submeshes
- Return type:
- property symmetry: str | None#
Check whether a mesh has rotational symmetry around an axis (radial) or point (spherical).
- Returns:
symmetry – What kind of symmetry does the mesh have.
- Return type:
None, ‘radial’, ‘spherical’
- property symmetry_axis: ndarray[Any, dtype[float64]]#
If a mesh has rotational symmetry, return the axis.
- Returns:
axis – Axis around which a 2D profile was revolved to create this mesh.
- Return type:
(3, ) float
- property symmetry_section: ndarray[Any, dtype[float64]]#
If a mesh has rotational symmetry return the two vectors which make up a section coordinate frame.
- Returns:
section – Vectors to take a section along
- Return type:
(2, 3) float
- to_dict() Dict[str, str | List[List[float]] | List[List[int]]] #
Return a dictionary representation of the current mesh with keys that can be used as the kwargs for the Trimesh constructor and matches the schema in: trimesh/resources/schema/primitive/trimesh.schema.json
- Returns:
result – Matches schema and Trimesh constructor.
- Return type:
dict
- property triangles: ndarray[Any, dtype[float64]]#
Actual triangles of the mesh (points, not indexes)
- Returns:
triangles – Points of triangle vertices
- Return type:
(n, 3, 3) float
- property triangles_center: ndarray[Any, dtype[float64]]#
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: ndarray[Any, dtype[float64]]#
The cross product of two edges of each triangle.
- Returns:
crosses – Cross product of each triangle
- Return type:
(n, 3) float
- property triangles_tree: Index#
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: Trimesh, engine: str | None = None, **kwargs) Trimesh #
Boolean union between this mesh and n other meshes
- Parameters:
- Returns:
union – Union of self and other Trimesh objects
- Return type:
- unique_faces() ndarray[Any, dtype[bool]] #
On the current mesh find which faces are unique.
- Returns:
unique – A mask where the first occurrence of a unique face is true.
- Return type:
(len(faces),) bool
- property units: str | None#
Definition of units for the mesh.
- Returns:
units – Unit system mesh is in, or None if not defined
- Return type:
str
- unmerge_vertices() None #
Removes all face references so that every face contains three unique vertex indices and no faces are adjacent.
- unwrap(image=None)#
Returns a Trimesh object equivalent to the current mesh where the vertices have been assigned uv texture coordinates. Vertices may be split into as many as necessary by the unwrapping algorithm, depending on how many uv maps they appear in.
Requires pip install xatlas
- Parameters:
image (None or PIL.Image) – Image to assign to the material
- Returns:
unwrapped – Mesh with unwrapped uv coordinates
- Return type:
- update_faces(mask: ndarray[Any, dtype[bool]]) None #
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: ndarray[Any, dtype[bool]], inverse: ndarray[Any, dtype[_ScalarType_co]] | None = None) 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: 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: ndarray[Any, dtype[float64]]#
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: ndarray[Any, dtype[int64]]#
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: ndarray[Any, dtype[int64]]#
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: List[List[int64]]#
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: ndarray[Any, dtype[float64]]#
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: ndarray[Any, dtype[float64]]#
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:
- property volume: float64#
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