trimesh
- trimesh.exchange
- trimesh.exchange.assimp
- trimesh.exchange.binvox
- trimesh.exchange.dae
- trimesh.exchange.export
- trimesh.exchange.gltf
- trimesh.exchange.load
- trimesh.exchange.misc
- trimesh.exchange.obj
- trimesh.exchange.off
- trimesh.exchange.openctm
- trimesh.exchange.ply
- trimesh.exchange.stl
- trimesh.exchange.threedxml
- trimesh.exchange.threemf
- trimesh.exchange.urdf
- trimesh.exchange.xaml
- trimesh.exchange.xyz
- trimesh/exchange
- trimesh.interfaces
- trimesh.path
- trimesh.path.exchange
- trimesh.path.arc
- trimesh.path.creation
- trimesh.path.curve
- trimesh.path.entities
- trimesh.path.intersections
- trimesh.path.packing
- trimesh.path.path
- trimesh.path.polygons
- trimesh.path.raster
- trimesh.path.repair
- trimesh.path.segments
- trimesh.path.simplify
- trimesh.path.traversal
- trimesh.path.util
- trimesh.path
- trimesh.ray
- trimesh.resources
- trimesh.scene
- trimesh.viewer
- trimesh.visual
- trimesh.voxel
- trimesh.base
- trimesh.boolean
- trimesh.bounds
- trimesh.caching
- trimesh.collision
- trimesh.comparison
- trimesh.constants
- trimesh.convex
- trimesh.creation
- trimesh.curvature
- trimesh.decomposition
- trimesh.exceptions
- trimesh.geometry
- trimesh.graph
- trimesh.grouping
- trimesh.inertia
- trimesh.integrate
- trimesh.intersections
- trimesh.interval
- trimesh.nsphere
- trimesh.parent
- trimesh.permutate
- trimesh.points
- trimesh.poses
- trimesh.primitives
- trimesh.proximity
- trimesh.registration
- trimesh.remesh
- trimesh.rendering
- trimesh.repair
- trimesh.resolvers
- trimesh.sample
- trimesh.schemas
- trimesh.smoothing
- trimesh.transformations
- trimesh.triangles
- trimesh.units
- trimesh.util
- trimesh.version
https://github.com/mikedh/trimesh
Trimesh is a pure Python (2.7- 3.3+) library for loading and using triangular meshes with an emphasis on watertight meshes. The goal of the library is to provide a fully featured Trimesh object which allows for easy manipulation and analysis, in the style of the Polygon object in the Shapely library.
- class trimesh.PointCloud(vertices, colors=None, metadata=None, **kwargs)
Bases:
trimesh.parent.Geometry3D
Hold 3D points in an object which can be visualized in a scene.
- __init__(vertices, colors=None, metadata=None, **kwargs)
Load an array of points into a PointCloud object.
- Parameters
vertices ((n, 3) float) – Points in space
colors ((n, 4) uint8 or None) – RGBA colors for each point
metadata (dict or None) – Metadata about points
- 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
- 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
- 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
- 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
- class trimesh.Scene(geometry=None, base_frame='world', metadata={}, graph=None, camera=None, lights=None, camera_transform=None)
Bases:
trimesh.parent.Geometry3D
A simple scene graph which can be rendered directly via pyglet/openGL or through other endpoints such as a raytracer. Meshes are added by name, which can then be moved by updating transform in the transform tree.
- __init__(geometry=None, base_frame='world', metadata={}, graph=None, camera=None, lights=None, camera_transform=None)
Create a new Scene object.
- Parameters
geometry (Trimesh, Path2D, Path3D PointCloud or list) – Geometry to initially add to the scene
base_frame (str or hashable) – Name of base frame
metadata (dict) – Any metadata about the scene
graph (TransformForest or None) – A passed transform graph to use
camera (Camera or None) – A passed camera to use
lights ([trimesh.scene.lighting.Light] or None) – A passed lights to use
camera_transform ((4, 4) float or None) – Camera transform in the base frame
- add_geometry(geometry, node_name=None, geom_name=None, parent_node_name=None, transform=None, extras=None)
Add a geometry to the scene.
If the mesh has multiple transforms defined in its metadata, they will all be copied into the TransformForest of the current scene automatically.
- Parameters
geometry (Trimesh, Path2D, Path3D PointCloud or list) – Geometry to initially add to the scene
node_name (Name of the added node.) –
geom_name (Name of the added geometry.) –
parent_node_name (Name of the parent node in the graph.) –
transform (Transform that applies to the added node.) –
extras (Optional metadata for the node.) –
- Returns
node_name – Name of single node in self.graph (passed in) or None if node was not added (eg. geometry was null or a Scene).
- Return type
str
- apply_transform(transform)
Apply a transform to every geometry in the scene.
- Parameters
transform ((4, 4)) – Homogeneous transformation matrix
- property area
What is the summed area of every geometry which has area.
- Returns
area – Summed area of every instanced geometry
- Return type
float
- property bounds
Return the overall bounding box of the scene.
- Returns
bounds – Position of [min, max] bounding box Returns None if no valid bounds exist
- Return type
(2, 3) float or None
- property bounds_corners
A list of points that represent the corners of the AABB of every geometry in the scene.
This can be useful if you want to take the AABB in a specific frame.
- Returns
corners – Points in space
- Return type
(n, 3) float
- property camera
Get the single camera for the scene. If not manually set one will abe automatically generated.
- Returns
camera – Camera object defined for the scene
- Return type
- camera_rays()
Calculate the trimesh.scene.Camera origin and ray direction vectors. Returns one ray per pixel as set in camera.resolution
- Returns
origin ((n, 3) float) – Ray origins in space
vectors ((n, 3) float) – Ray direction unit vectors in world coordinates
pixels ((n, 2) int) – Which pixel does each ray correspond to in an image
- property camera_transform
Get camera transform in the base frame.
- Returns
camera_transform – Camera transform in the base frame
- Return type
(4, 4) float
- property centroid
Return the center of the bounding box for the scene.
- Returns
centroid – Point for center of bounding box
- Return type
float
- convert_units(desired, guess=False)
If geometry has units defined convert them to new units.
Returns a new scene with geometries and transforms scaled.
- Parameters
desired (str) – Desired final unit system: ‘inches’, ‘mm’, etc.
guess (bool) – Is the converter allowed to guess scale when models don’t have it specified in their metadata.
- Returns
scaled – Copy of scene with scaling applied and units set for every model
- Return type
- property convex_hull
The convex hull of the whole scene
- Returns
hull
- Return type
Trimesh object, convex hull of all meshes in scene
- copy()
Return a deep copy of the current scene
- Returns
copied – Copy of the current scene
- Return type
- crc()
Get a CRC of the current geometry and graph information.
- Returns
crc – Hash of current graph and geometry.
- Return type
int
- deduplicated()
Return a new scene where each unique geometry is only included once and transforms are discarded.
- Returns
dedupe – One copy of each unique geometry from scene
- Return type
- delete_geometry(names)
Delete one more multiple geometries from the scene and also remove any node in the transform graph which references it.
- Parameters
name (hashable) – Name that references self.geometry
- dump(concatenate=False)
Append all meshes in scene freezing transforms.
- property duplicate_nodes
Return a sequence of node keys of identical meshes.
Will include meshes with different geometry but identical spatial hashes as well as meshes repeated by self.nodes.
- Returns
duplicates – Keys of self.graph that represent identical geometry
- Return type
sequence
- explode(vector=None, origin=None)
Explode a scene around a point and vector.
- Parameters
vector ((3,) float or float) – Explode radially around a direction vector or spherically
origin ((3,) float) – Point to explode around
- export(file_obj=None, file_type=None, **kwargs)
Export a snapshot of the current scene.
- Parameters
file_obj (str, file-like, or None) – File object to export to
file_type (str or None) – What encoding to use for meshes IE: dict, dict64, stl
- Returns
export – Only returned if file_obj is None
- Return type
bytes
- property extents
Return the axis aligned box size of the current scene.
- Returns
extents – Bounding box sides length
- Return type
(3,) float
- property geometry_identifiers
Look up geometries by identifier MD5
- Returns
identifiers – {Identifier MD5: key in self.geometry}
- Return type
dict
- property has_camera
- property is_empty
Does the scene have anything in it.
- Returns
is_empty
- Return type
bool, True if nothing is in the scene
- property is_valid
Is every geometry connected to the root node.
- Returns
is_valid – Does every geometry have a transform
- Return type
bool
- property lights
Get a list of the lights in the scene. If nothing is set it will generate some automatically.
- Returns
lights – Lights in the scene.
- Return type
- md5()
MD5 of scene which will change when meshes or transforms are changed
- Returns
hashed – MD5 hash of scene
- Return type
str
- rezero()
Move the current scene so that the AABB of the whole scene is centered at the origin.
Does this by changing the base frame to a new, offset base frame.
- save_image(resolution=None, **kwargs)
Get a PNG image of a scene.
- Parameters
resolution ((2,) int) – Resolution to render image
**kwargs – Passed to SceneViewer constructor
- Returns
png – Render of scene as a PNG
- Return type
bytes
- property scale
The approximate scale of the mesh
- Returns
scale – The mean of the bounding box edge lengths
- Return type
float
- scaled(scale)
Return a copy of the current scene, with meshes and scene transforms scaled to the requested factor.
- Parameters
scale (float) – Factor to scale meshes and transforms
- Returns
scaled – A copy of the current scene but scaled
- Return type
- set_camera(angles=None, distance=None, center=None, resolution=None, fov=None)
Create a camera object for self.camera, and add a transform to self.graph for it.
If arguments are not passed sane defaults will be figured out which show the mesh roughly centered.
- Parameters
angles ((3,) float) – Initial euler angles in radians
distance (float) – Distance from centroid
center ((3,) float) – Point camera should be center on
camera (Camera object) – Object that stores camera parameters
- show(viewer=None, **kwargs)
Display the current scene.
- Parameters
viewer (str) – What kind of viewer to open, including ‘gl’ to open a pyglet window, ‘notebook’ for a jupyter notebook or None
kwargs (dict) – Includes smooth, which will turn on or off automatic smooth shading
- subscene(node)
Get part of a scene that succeeds a specified node.
- Parameters
node (any) – Hashable key in scene.graph
- Returns
subscene – Partial scene generated from current.
- Return type
- property triangles
Return a correctly transformed polygon soup of the current scene.
- Returns
triangles – Triangles in space
- Return type
(n, 3, 3) float
- property triangles_node
Which node of self.graph does each triangle come from.
- Returns
triangles_index – Node name for each triangle
- Return type
(len(self.triangles),)
- property units
Get the units for every model in the scene, and raise a ValueError if there are mixed units.
- Returns
units – Units for every model in the scene
- Return type
str
- class trimesh.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.Geometry3D
- __init__(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)
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)
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 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
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 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)
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, 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
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=False)
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
- 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, **kwargs)
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
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
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
(len(self.faces), 3) float
- property face_angles_sparse
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_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[: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
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
- property integral_mean_curvature
The integral mean curvature, or the surface integral of the mean curvature.
- Returns
area – Integral mean curvature of mesh
- Return type
float
- intersection(other, engine=None, **kwargs)
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()
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
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(**kwargs)
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
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
- 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 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=False, **kwargs)
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 rectangular 2D oriented bounding box shorter than tol.merge
remove duplicated triangles
ensure triangles are consistently wound and normals face outwards
- Parameters
validate (bool) – If True, remove degenerate and duplicate faces
- Returns
self – Current mesh
- Return type
- 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.
Alters self.faces to remove duplicate faces
- 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
Alters self.faces and self.vertices
- 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.
Alters self.vertices.
- sample(count, return_index=False, face_weight=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
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)
Returns a Scene object containing the current mesh.
- Returns
scene – Contains just the current mesh
- Return type
- section(plane_normal, plane_origin, **kwargs)
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_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(face_count)
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, **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
- 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
- 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_minarea (float or None) – Minimum area fraction to consider IE for facets_minarea=25 only facets larger than mesh.area / 25 will be considered.
- Returns
smoothed – Non watertight version of current mesh which will render nicely with smooth shading
- Return type
- 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
- 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, **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 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
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
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()
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, **kwargs)
Boolean union between this mesh and n other meshes
- Parameters
- Returns
union – Union of self and other Trimesh objects
- Return type
- 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.
- 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)
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
- 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
- trimesh.available_formats()
Get a list of all available loaders
- Returns
loaders – Extensions of available loaders i.e. ‘stl’, ‘ply’, ‘dxf’, etc.
- Return type
list
- trimesh.load(file_obj, file_type=None, resolver=None, force=None, **kwargs)
Load a mesh or vectorized path into objects like Trimesh, Path2D, Path3D, Scene
- Parameters
file_obj (str, or file- like object) – The source of the data to be loadeded
file_type (str) – What kind of file type do we have (eg: ‘stl’)
resolver (trimesh.visual.Resolver) – Object to load referenced assets like materials and textures
force (None or str) – For ‘mesh’: try to coerce scenes into a single mesh For ‘scene’: try to coerce everything into a scene
kwargs (dict) – Passed to geometry __init__
- Returns
geometry – Loaded geometry as trimesh classes
- Return type
- trimesh.load_mesh(*args, **kwargs)
Load a mesh file into a Trimesh object
- Parameters
file_obj (str or file object) – File name or file with mesh data
file_type (str or None) – Which file type, e.g. ‘stl’
kwargs (dict) – Passed to Trimesh constructor
- Returns
mesh – Loaded geometry data
- Return type
- trimesh.load_path(file_obj, file_type=None, **kwargs)
Load a file to a Path file_object.
- Parameters
file_obj (One of the following:) –
Path, Path2D, or Path3D file_objects
open file file_object (dxf or svg)
file name (dxf or svg)
shapely.geometry.Polygon
shapely.geometry.MultiLineString
dict with kwargs for Path constructor
(n,2,(2|3)) float, line segments
file_type (str) – Type of file is required if file file_object passed.
- Returns
path – Data as a native trimesh Path file_object
- Return type
- trimesh.load_remote(url, **kwargs)
Load a mesh at a remote URL into a local trimesh object.
This must be called explicitly rather than automatically from trimesh.load to ensure users don’t accidentally make network requests.
- trimesh.transform_points(points, matrix, translate=True)
Returns points rotated by a homogeneous transformation matrix.
If points are (n, 2) matrix must be (3, 3) If points are (n, 3) matrix must be (4, 4)
- Parameters
points ((n, D) float) – Points where D is 2 or 3
matrix ((3, 3) or (4, 4) float) – Homogeneous rotation matrix
translate (bool) – Apply translation from matrix or not
- Returns
transformed – Transformed points
- Return type
(n, d) float
- trimesh.unitize(vectors, check_valid=False, threshold=None)
Unitize a vector or an array or row-vectors.
- Parameters
vectors ((n,m) or (j) float) – Vector or vectors to be unitized
check_valid (bool) – If set, will return mask of nonzero vectors
threshold (float) – Cutoff for a value to be considered zero.
- Returns
unit ((n,m) or (j) float) – Input vectors but unitized
valid ((n,) bool or bool) – Mask of nonzero vectors returned if check_valid