forked from s_ranjbar/city_retrofit
2836 lines
88 KiB
Python
2836 lines
88 KiB
Python
# flake8: noqa
|
|
"""
|
|
github.com/mikedh/trimesh
|
|
----------------------------
|
|
|
|
Library for importing, exporting and doing simple operations on triangular meshes.
|
|
"""
|
|
|
|
from . import ray
|
|
from . import util
|
|
from . import units
|
|
from . import poses
|
|
from . import graph
|
|
from . import sample
|
|
from . import repair
|
|
from . import convex
|
|
from . import remesh
|
|
from . import bounds
|
|
from . import caching
|
|
from . import inertia
|
|
from . import nsphere
|
|
from . import boolean
|
|
from . import grouping
|
|
from . import geometry
|
|
from . import permutate
|
|
from . import proximity
|
|
from . import triangles
|
|
from . import collision
|
|
from . import curvature
|
|
from . import smoothing
|
|
from . import comparison
|
|
from . import registration
|
|
from . import decomposition
|
|
from . import intersections
|
|
from . import transformations
|
|
|
|
from .visual import create_visual
|
|
from .exchange.export import export_mesh
|
|
from .constants import log, log_time, tol
|
|
|
|
from .scene import Scene
|
|
from .parent import Geometry
|
|
|
|
import copy
|
|
import numpy as np
|
|
|
|
|
|
class Trimesh(Geometry):
|
|
|
|
def __init__(self,
|
|
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
|
|
"""
|
|
|
|
if initial_cache is None:
|
|
initial_cache = {}
|
|
|
|
# self._data stores information about the mesh which
|
|
# CANNOT be regenerated.
|
|
# in the base class all that is stored here is vertex and
|
|
# face information
|
|
# any data put into the store is converted to a TrackedArray
|
|
# which is a subclass of np.ndarray that provides md5 and crc
|
|
# methods which can be used to detect changes in the array.
|
|
self._data = caching.DataStore()
|
|
|
|
# self._cache stores information about the mesh which CAN be
|
|
# regenerated from self._data, but may be slow to calculate.
|
|
# In order to maintain consistency
|
|
# the cache is cleared when self._data.crc() changes
|
|
self._cache = caching.Cache(
|
|
id_function=self._data.fast_hash,
|
|
force_immutable=True)
|
|
|
|
self._cache.update(initial_cache)
|
|
|
|
# check for None only to avoid warning messages in subclasses
|
|
if vertices is not None:
|
|
# (n, 3) float, set of vertices
|
|
self.vertices = vertices
|
|
if faces is not None:
|
|
# (m, 3) int of triangle faces, references self.vertices
|
|
self.faces = faces
|
|
|
|
# hold visual information about the mesh (vertex and face colors)
|
|
if visual is None:
|
|
self.visual = create_visual(
|
|
face_colors=face_colors,
|
|
vertex_colors=vertex_colors,
|
|
mesh=self)
|
|
else:
|
|
self.visual = visual
|
|
|
|
# normals are accessed through setters/properties and are regenerated
|
|
# if dimensions are inconsistent, but can be set by the constructor
|
|
# to avoid a substantial number of cross products
|
|
if face_normals is not None:
|
|
self.face_normals = face_normals
|
|
|
|
# (n, 3) float of vertex normals, can be created from face normals
|
|
if vertex_normals is not None:
|
|
self.vertex_normals = vertex_normals
|
|
|
|
# embree is a much, much faster raytracer written by Intel
|
|
# if you have pyembree installed you should use it
|
|
# although both raytracers were designed to have a common API
|
|
if ray.has_embree and use_embree:
|
|
self.ray = ray.ray_pyembree.RayMeshIntersector(self)
|
|
else:
|
|
# create a ray-mesh query object for the current mesh
|
|
# initializing is very inexpensive and object is convenient to have.
|
|
# On first query expensive bookkeeping is done (creation of r-tree),
|
|
# and is cached for subsequent queries
|
|
self.ray = ray.ray_triangle.RayMeshIntersector(self)
|
|
|
|
# a quick way to get permuted versions of the current mesh
|
|
self.permutate = permutate.Permutator(self)
|
|
|
|
# convenience class for nearest point queries
|
|
self.nearest = proximity.ProximityQuery(self)
|
|
|
|
# store metadata about the mesh in a dictionary
|
|
self.metadata = dict()
|
|
# update the mesh metadata with passed metadata
|
|
if isinstance(metadata, dict):
|
|
self.metadata.update(metadata)
|
|
elif metadata is not None:
|
|
raise ValueError(
|
|
'metadata should be a dict or None, got %s' % str(metadata))
|
|
|
|
# Set the default center of mass and density
|
|
self._density = 1.0
|
|
self._center_mass = None
|
|
|
|
# store per-face and per-vertex attributes which will
|
|
# be updated when an update_faces call is made
|
|
self.face_attributes = {}
|
|
self.vertex_attributes = {}
|
|
# use update to copy items
|
|
if face_attributes is not None:
|
|
self.face_attributes.update(face_attributes)
|
|
if vertex_attributes is not None:
|
|
self.vertex_attributes.update(vertex_attributes)
|
|
|
|
# process will remove NaN and Inf values and merge vertices
|
|
# if validate, will remove degenerate and duplicate faces
|
|
if process or validate:
|
|
self.process(validate=validate, **kwargs)
|
|
|
|
# save reference to kwargs
|
|
self._kwargs = kwargs
|
|
|
|
def process(self, validate=False, **kwargs):
|
|
"""
|
|
Do processing to make a mesh useful.
|
|
|
|
Does this by:
|
|
1) removing NaN and Inf values
|
|
2) merging duplicate vertices
|
|
If validate:
|
|
3) Remove triangles which have one edge of their rectangular 2D
|
|
oriented bounding box shorter than tol.merge
|
|
4) remove duplicated triangles
|
|
|
|
Parameters
|
|
------------
|
|
validate : bool
|
|
If True, remove degenerate and duplicate faces
|
|
|
|
Returns
|
|
------------
|
|
self: trimesh.Trimesh
|
|
Current mesh
|
|
"""
|
|
# if there are no vertices or faces exit early
|
|
if self.is_empty:
|
|
return self
|
|
|
|
# avoid clearing the cache during operations
|
|
with self._cache:
|
|
self.remove_infinite_values()
|
|
self.merge_vertices(**kwargs)
|
|
# if we're cleaning remove duplicate
|
|
# and degenerate faces
|
|
if validate:
|
|
self.remove_duplicate_faces()
|
|
self.remove_degenerate_faces()
|
|
# since none of our process operations moved vertices or faces
|
|
# we can keep face and vertex normals in the cache without recomputing
|
|
# if faces or vertices have been removed, normals are validated before
|
|
# being returned so there is no danger of inconsistent dimensions
|
|
self._cache.clear(exclude=['face_normals',
|
|
'vertex_normals'])
|
|
self.metadata['processed'] = True
|
|
return self
|
|
|
|
def md5(self):
|
|
"""
|
|
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 : string
|
|
MD5 of everything in the DataStore
|
|
"""
|
|
md5 = self._data.md5()
|
|
return md5
|
|
|
|
def crc(self):
|
|
"""
|
|
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 : int
|
|
Checksum of current mesh data
|
|
"""
|
|
return self._data.fast_hash()
|
|
|
|
@property
|
|
def faces(self):
|
|
"""
|
|
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 : (n, 3) int
|
|
Representing triangles which reference self.vertices
|
|
"""
|
|
return self._data.get('faces', np.empty(shape=(0, 3), dtype=np.int64))
|
|
|
|
@faces.setter
|
|
def faces(self, values):
|
|
"""
|
|
Set the vertex indexes that make up triangular faces.
|
|
|
|
Parameters
|
|
--------------
|
|
values : (n, 3) int
|
|
Indexes of self.vertices
|
|
"""
|
|
if values is None or len(values) == 0:
|
|
if 'faces' in self._data:
|
|
del self._data['faces']
|
|
return
|
|
values = np.asanyarray(values, dtype=np.int64)
|
|
# automatically triangulate quad faces
|
|
if util.is_shape(values, (-1, 4)):
|
|
log.info('triangulating quad faces')
|
|
values = geometry.triangulate_quads(values)
|
|
self._data['faces'] = values
|
|
|
|
@caching.cache_decorator
|
|
def faces_sparse(self):
|
|
"""
|
|
A sparse matrix representation of the faces.
|
|
|
|
Returns
|
|
----------
|
|
sparse : scipy.sparse.coo_matrix
|
|
Has properties:
|
|
dtype : bool
|
|
shape : (len(self.vertices), len(self.faces))
|
|
"""
|
|
sparse = geometry.index_sparse(
|
|
columns=len(self.vertices),
|
|
indices=self.faces)
|
|
return sparse
|
|
|
|
@property
|
|
def face_normals(self):
|
|
"""
|
|
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 : (len(self.faces), 3) np.float64
|
|
Normal vectors of each face
|
|
"""
|
|
# check shape of cached normals
|
|
cached = self._cache['face_normals']
|
|
# get faces from datastore
|
|
if 'faces' in self._data:
|
|
faces = self._data.data['faces']
|
|
else:
|
|
faces = None
|
|
|
|
# if we have no faces exit early
|
|
if faces is None or len(faces) == 0:
|
|
return np.array([], dtype=np.int64).reshape((0, 3))
|
|
|
|
# if the shape of cached normals equals the shape of faces return
|
|
if np.shape(cached) == np.shape(faces):
|
|
return cached
|
|
|
|
log.debug('generating face normals')
|
|
# use cached triangle cross products to generate normals
|
|
# this will always return the correct shape but some values
|
|
# will be zero or an arbitrary vector if the inputs had
|
|
# a cross product below machine epsilon
|
|
normals, valid = triangles.normals(
|
|
triangles=self.triangles,
|
|
crosses=self.triangles_cross)
|
|
|
|
# if all triangles are valid shape is correct
|
|
if valid.all():
|
|
# put calculated face normals into cache manually
|
|
self._cache['face_normals'] = normals
|
|
return normals
|
|
|
|
# make a padded list of normals for correct shape
|
|
padded = np.zeros((len(self.triangles), 3),
|
|
dtype=np.float64)
|
|
padded[valid] = normals
|
|
|
|
# put calculated face normals into cache manually
|
|
self._cache['face_normals'] = padded
|
|
|
|
return padded
|
|
|
|
@face_normals.setter
|
|
def face_normals(self, values):
|
|
"""
|
|
Assign values to face normals.
|
|
|
|
Parameters
|
|
-------------
|
|
values : (len(self.faces), 3) float
|
|
Unit face normals
|
|
"""
|
|
# if nothing passed exit
|
|
if values is None:
|
|
return
|
|
# make sure candidate face normals are C-contiguous float
|
|
values = np.asanyarray(
|
|
values, order='C', dtype=np.float64)
|
|
# face normals need to correspond to faces
|
|
if len(values) == 0 or values.shape != self.faces.shape:
|
|
log.warning('face_normals incorrect shape, ignoring!')
|
|
return
|
|
# check if any values are larger than tol.merge
|
|
# don't set the normals if they are all zero
|
|
ptp = values.ptp()
|
|
if not np.isfinite(ptp):
|
|
log.warning('face_normals contain NaN, ignoring!')
|
|
return
|
|
if ptp < tol.merge:
|
|
log.warning('face_normals all zero, ignoring!')
|
|
return
|
|
|
|
# make sure the first few normals match the first few triangles
|
|
check, valid = triangles.normals(
|
|
self.vertices.view(np.ndarray)[self.faces[:20]])
|
|
compare = np.zeros((len(valid), 3))
|
|
compare[valid] = check
|
|
if not np.allclose(compare, values[:20]):
|
|
log.debug("face_normals didn't match triangles, ignoring!")
|
|
return
|
|
# otherwise store face normals
|
|
self._cache['face_normals'] = values
|
|
|
|
@property
|
|
def vertices(self):
|
|
"""
|
|
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 : (n, 3) float
|
|
Points in cartesian space referenced by self.faces
|
|
"""
|
|
return self._data.get('vertices', np.empty(shape=(0, 3), dtype=np.float64))
|
|
|
|
@vertices.setter
|
|
def vertices(self, values):
|
|
"""
|
|
Assign vertex values to the mesh.
|
|
|
|
Parameters
|
|
--------------
|
|
values : (n, 3) float
|
|
Points in space
|
|
"""
|
|
self._data['vertices'] = np.asanyarray(
|
|
values, order='C', dtype=np.float64)
|
|
|
|
@caching.cache_decorator
|
|
def vertex_normals(self):
|
|
"""
|
|
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 : (n, 3) float
|
|
Represents the surface normal at each vertex.
|
|
Where n == len(self.vertices)
|
|
"""
|
|
# make sure we have faces_sparse
|
|
assert hasattr(self.faces_sparse, 'dot')
|
|
vertex_normals = geometry.weighted_vertex_normals(
|
|
vertex_count=len(self.vertices),
|
|
faces=self.faces,
|
|
face_normals=self.face_normals,
|
|
face_angles=self.face_angles)
|
|
return vertex_normals
|
|
|
|
@vertex_normals.setter
|
|
def vertex_normals(self, values):
|
|
"""
|
|
Assign values to vertex normals.
|
|
|
|
Parameters
|
|
-------------
|
|
values : (len(self.vertices), 3) float
|
|
Unit normal vectors for each vertex
|
|
"""
|
|
if values is not None:
|
|
values = np.asanyarray(values,
|
|
order='C',
|
|
dtype=np.float64)
|
|
if values.shape == self.vertices.shape:
|
|
# check to see if they assigned all zeros
|
|
if values.ptp() < tol.merge:
|
|
log.warning(
|
|
'vertex_normals are all set to zero!')
|
|
self._cache['vertex_normals'] = values
|
|
|
|
@caching.cache_decorator
|
|
def vertex_faces(self):
|
|
"""
|
|
A representation of the face indices that correspond to each vertex.
|
|
|
|
Returns
|
|
----------
|
|
vertex_faces : (n,m) int
|
|
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
|
|
"""
|
|
vertex_faces = geometry.vertex_face_indices(
|
|
vertex_count=len(self.vertices),
|
|
faces=self.faces,
|
|
faces_sparse=self.faces_sparse)
|
|
return vertex_faces
|
|
|
|
@caching.cache_decorator
|
|
def bounds(self):
|
|
"""
|
|
The axis aligned bounds of the faces of the mesh.
|
|
|
|
Returns
|
|
-----------
|
|
bounds : (2, 3) float or None
|
|
Bounding box with [min, max] coordinates
|
|
If mesh is empty will return None
|
|
"""
|
|
# return bounds including ONLY referenced vertices
|
|
in_mesh = self.vertices[self.referenced_vertices]
|
|
# don't crash if we have no vertices referenced
|
|
if len(in_mesh) == 0:
|
|
return None
|
|
# get mesh bounds with min and max
|
|
mesh_bounds = np.array([in_mesh.min(axis=0),
|
|
in_mesh.max(axis=0)])
|
|
return mesh_bounds
|
|
|
|
@caching.cache_decorator
|
|
def extents(self):
|
|
"""
|
|
The length, width, and height of the axis aligned
|
|
bounding box of the mesh.
|
|
|
|
Returns
|
|
-----------
|
|
extents : (3, ) float or None
|
|
Array containing axis aligned [length, width, height]
|
|
If mesh is empty returns None
|
|
"""
|
|
# if mesh is empty return None
|
|
if self.bounds is None:
|
|
return None
|
|
extents = self.bounds.ptp(axis=0)
|
|
|
|
return extents
|
|
|
|
@caching.cache_decorator
|
|
def scale(self):
|
|
"""
|
|
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 : float
|
|
The length of the meshes AABB diagonal
|
|
"""
|
|
# if mesh is empty just return no scale
|
|
if self.extents is None:
|
|
return 1.0
|
|
# make sure we are returning python floats
|
|
scale = float((self.extents ** 2).sum() ** .5)
|
|
return scale
|
|
|
|
@caching.cache_decorator
|
|
def centroid(self):
|
|
"""
|
|
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 : (3, ) float
|
|
The average vertex weighted by face area
|
|
"""
|
|
|
|
# use the centroid of each triangle weighted by
|
|
# the area of the triangle to find the overall centroid
|
|
try:
|
|
centroid = np.average(self.triangles_center,
|
|
weights=self.area_faces,
|
|
axis=0)
|
|
except BaseException:
|
|
# if all triangles are zero-area weights will not work
|
|
centroid = self.triangles_center.mean(axis=0)
|
|
return centroid
|
|
|
|
@property
|
|
def center_mass(self):
|
|
"""
|
|
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 : (3, ) float
|
|
Volumetric center of mass of the mesh
|
|
"""
|
|
center_mass = self.mass_properties['center_mass']
|
|
return center_mass
|
|
|
|
@center_mass.setter
|
|
def center_mass(self, cm):
|
|
self._center_mass = cm
|
|
self._cache.delete('mass_properties')
|
|
|
|
@property
|
|
def density(self):
|
|
"""
|
|
The density of the mesh.
|
|
|
|
Returns
|
|
-----------
|
|
density : float
|
|
The density of the mesh.
|
|
"""
|
|
density = self.mass_properties['density']
|
|
return density
|
|
|
|
@density.setter
|
|
def density(self, value):
|
|
"""
|
|
Set the density of the mesh.
|
|
|
|
Parameters
|
|
-------------
|
|
density : float
|
|
Specify the density of the mesh to be used in inertia calculations
|
|
"""
|
|
self._density = float(value)
|
|
self._cache.delete('mass_properties')
|
|
|
|
@property
|
|
def volume(self):
|
|
"""
|
|
Volume of the current mesh calculated using a surface
|
|
integral. If the current mesh isn't watertight this is
|
|
garbage.
|
|
|
|
Returns
|
|
---------
|
|
volume : float
|
|
Volume of the current mesh
|
|
"""
|
|
volume = self.mass_properties['volume']
|
|
return volume
|
|
|
|
@property
|
|
def mass(self):
|
|
"""
|
|
Mass of the current mesh, based on specified density and
|
|
volume. If the current mesh isn't watertight this is garbage.
|
|
|
|
Returns
|
|
---------
|
|
mass : float
|
|
Mass of the current mesh
|
|
"""
|
|
mass = self.mass_properties['mass']
|
|
return mass
|
|
|
|
@property
|
|
def moment_inertia(self):
|
|
"""
|
|
Return the moment of inertia matrix of the current mesh.
|
|
If mesh isn't watertight this is garbage.
|
|
|
|
Returns
|
|
---------
|
|
inertia : (3, 3) float
|
|
Moment of inertia of the current mesh
|
|
"""
|
|
inertia = self.mass_properties['inertia']
|
|
return inertia
|
|
|
|
@caching.cache_decorator
|
|
def principal_inertia_components(self):
|
|
"""
|
|
Return the principal components of inertia
|
|
|
|
Ordering corresponds to mesh.principal_inertia_vectors
|
|
|
|
Returns
|
|
----------
|
|
components : (3, ) float
|
|
Principal components of inertia
|
|
"""
|
|
# both components and vectors from inertia matrix
|
|
components, vectors = inertia.principal_axis(self.moment_inertia)
|
|
# store vectors in cache for later
|
|
self._cache['principal_inertia_vectors'] = vectors
|
|
|
|
return components
|
|
|
|
@property
|
|
def principal_inertia_vectors(self):
|
|
"""
|
|
Return the principal axis of inertia as unit vectors.
|
|
The order corresponds to `mesh.principal_inertia_components`.
|
|
|
|
Returns
|
|
----------
|
|
vectors : (3, 3) float
|
|
Three vectors pointing along the
|
|
principal axis of inertia directions
|
|
"""
|
|
populate = self.principal_inertia_components
|
|
return self._cache['principal_inertia_vectors']
|
|
|
|
@caching.cache_decorator
|
|
def principal_inertia_transform(self):
|
|
"""
|
|
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 : (4, 4) float
|
|
Homogeneous transformation matrix
|
|
"""
|
|
order = np.argsort(self.principal_inertia_components)[1:][::-1]
|
|
vectors = self.principal_inertia_vectors[order]
|
|
vectors = np.vstack((vectors, np.cross(*vectors)))
|
|
|
|
transform = np.eye(4)
|
|
transform[:3, :3] = vectors
|
|
transform = transformations.transform_around(
|
|
matrix=transform,
|
|
point=self.centroid)
|
|
transform[:3, 3] -= self.centroid
|
|
|
|
return transform
|
|
|
|
@caching.cache_decorator
|
|
def symmetry(self):
|
|
"""
|
|
Check whether a mesh has rotational symmetry around
|
|
an axis (radial) or point (spherical).
|
|
|
|
Returns
|
|
-----------
|
|
symmetry: None, 'radial', 'spherical'
|
|
What kind of symmetry does the mesh have.
|
|
"""
|
|
symmetry, axis, section = inertia.radial_symmetry(self)
|
|
self._cache['symmetry_axis'] = axis
|
|
self._cache['symmetry_section'] = section
|
|
return symmetry
|
|
|
|
@property
|
|
def symmetry_axis(self):
|
|
"""
|
|
If a mesh has rotational symmetry, return the axis.
|
|
|
|
Returns
|
|
------------
|
|
axis : (3, ) float
|
|
Axis around which a 2D profile was revolved to create this mesh.
|
|
"""
|
|
if self.symmetry is not None:
|
|
return self._cache['symmetry_axis']
|
|
|
|
@property
|
|
def symmetry_section(self):
|
|
"""
|
|
If a mesh has rotational symmetry return the two
|
|
vectors which make up a section coordinate frame.
|
|
|
|
Returns
|
|
----------
|
|
section : (2, 3) float
|
|
Vectors to take a section along
|
|
"""
|
|
if self.symmetry is not None:
|
|
return self._cache['symmetry_section']
|
|
|
|
@caching.cache_decorator
|
|
def triangles(self):
|
|
"""
|
|
Actual triangles of the mesh (points, not indexes)
|
|
|
|
Returns
|
|
---------
|
|
triangles : (n, 3, 3) float
|
|
Points of triangle vertices
|
|
"""
|
|
# use of advanced indexing on our tracked arrays will
|
|
# trigger a change flag which means the MD5 will have to be
|
|
# recomputed. We can escape this check by viewing the array.
|
|
triangles = self.vertices.view(np.ndarray)[self.faces]
|
|
|
|
return triangles
|
|
|
|
@caching.cache_decorator
|
|
def triangles_tree(self):
|
|
"""
|
|
An R-tree containing each face of the mesh.
|
|
|
|
Returns
|
|
----------
|
|
tree : rtree.index
|
|
Each triangle in self.faces has a rectangular cell
|
|
"""
|
|
tree = triangles.bounds_tree(self.triangles)
|
|
return tree
|
|
|
|
@caching.cache_decorator
|
|
def triangles_center(self):
|
|
"""
|
|
The center of each triangle (barycentric [1/3, 1/3, 1/3])
|
|
|
|
Returns
|
|
---------
|
|
triangles_center : (len(self.faces), 3) float
|
|
Center of each triangular face
|
|
"""
|
|
triangles_center = self.triangles.mean(axis=1)
|
|
return triangles_center
|
|
|
|
@caching.cache_decorator
|
|
def triangles_cross(self):
|
|
"""
|
|
The cross product of two edges of each triangle.
|
|
|
|
Returns
|
|
---------
|
|
crosses : (n, 3) float
|
|
Cross product of each triangle
|
|
"""
|
|
crosses = triangles.cross(self.triangles)
|
|
return crosses
|
|
|
|
@caching.cache_decorator
|
|
def edges(self):
|
|
"""
|
|
Edges of the mesh (derived from faces).
|
|
|
|
Returns
|
|
---------
|
|
edges : (n, 2) int
|
|
List of vertex indices making up edges
|
|
"""
|
|
edges, index = geometry.faces_to_edges(self.faces.view(np.ndarray),
|
|
return_index=True)
|
|
self._cache['edges_face'] = index
|
|
return edges
|
|
|
|
@caching.cache_decorator
|
|
def edges_face(self):
|
|
"""
|
|
Which face does each edge belong to.
|
|
|
|
Returns
|
|
---------
|
|
edges_face : (n, ) int
|
|
Index of self.faces
|
|
"""
|
|
populate = self.edges
|
|
return self._cache['edges_face']
|
|
|
|
@caching.cache_decorator
|
|
def edges_unique(self):
|
|
"""
|
|
The unique edges of the mesh.
|
|
|
|
Returns
|
|
----------
|
|
edges_unique : (n, 2) int
|
|
Vertex indices for unique edges
|
|
"""
|
|
unique, inverse = grouping.unique_rows(self.edges_sorted)
|
|
edges_unique = self.edges_sorted[unique]
|
|
# edges_unique will be added automatically by the decorator
|
|
# additional terms generated need to be added to the cache manually
|
|
self._cache['edges_unique_idx'] = unique
|
|
self._cache['edges_unique_inverse'] = inverse
|
|
return edges_unique
|
|
|
|
@caching.cache_decorator
|
|
def edges_unique_length(self):
|
|
"""
|
|
How long is each unique edge.
|
|
|
|
Returns
|
|
----------
|
|
length : (len(self.edges_unique), ) float
|
|
Length of each unique edge
|
|
"""
|
|
vector = np.subtract(*self.vertices[self.edges_unique.T])
|
|
length = util.row_norm(vector)
|
|
return length
|
|
|
|
@caching.cache_decorator
|
|
def edges_unique_inverse(self):
|
|
"""
|
|
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 : (len(self.edges), ) int
|
|
Indexes of self.edges_unique
|
|
"""
|
|
populate = self.edges_unique
|
|
return self._cache['edges_unique_inverse']
|
|
|
|
@caching.cache_decorator
|
|
def edges_sorted(self):
|
|
"""
|
|
Edges sorted along axis 1
|
|
|
|
Returns
|
|
----------
|
|
edges_sorted : (n, 2)
|
|
Same as self.edges but sorted along axis 1
|
|
"""
|
|
edges_sorted = np.sort(self.edges, axis=1)
|
|
return edges_sorted
|
|
|
|
@caching.cache_decorator
|
|
def edges_sorted_tree(self):
|
|
"""
|
|
A KDTree for mapping edges back to edge index.
|
|
|
|
Returns
|
|
------------
|
|
tree : scipy.spatial.cKDTree
|
|
Tree when queried with edges will return
|
|
their index in mesh.edges_sorted
|
|
"""
|
|
from scipy.spatial import cKDTree
|
|
return cKDTree(self.edges_sorted)
|
|
|
|
@caching.cache_decorator
|
|
def edges_sparse(self):
|
|
"""
|
|
Edges in sparse bool COO graph format where connected
|
|
vertices are True.
|
|
|
|
Returns
|
|
----------
|
|
sparse: (len(self.vertices), len(self.vertices)) bool
|
|
Sparse graph in COO format
|
|
"""
|
|
sparse = graph.edges_to_coo(self.edges,
|
|
count=len(self.vertices))
|
|
return sparse
|
|
|
|
@caching.cache_decorator
|
|
def body_count(self):
|
|
"""
|
|
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 : int
|
|
Number of connected vertex groups
|
|
"""
|
|
# labels are (len(vertices), int) OB
|
|
count, labels = graph.csgraph.connected_components(
|
|
self.edges_sparse,
|
|
directed=False,
|
|
return_labels=True)
|
|
self._cache['vertices_component_label'] = labels
|
|
return count
|
|
|
|
@caching.cache_decorator
|
|
def faces_unique_edges(self):
|
|
"""
|
|
For each face return which indexes in mesh.unique_edges constructs
|
|
that face.
|
|
|
|
Returns
|
|
---------
|
|
faces_unique_edges : (len(self.faces), 3) int
|
|
Indexes of self.edges_unique that
|
|
construct self.faces
|
|
|
|
Examples
|
|
---------
|
|
In [0]: mesh.faces[0:2]
|
|
Out[0]:
|
|
TrackedArray([[ 1, 6946, 24224],
|
|
[ 6946, 1727, 24225]])
|
|
|
|
In [1]: mesh.edges_unique[mesh.faces_unique_edges[0:2]]
|
|
Out[1]:
|
|
array([[[ 1, 6946],
|
|
[ 6946, 24224],
|
|
[ 1, 24224]],
|
|
[[ 1727, 6946],
|
|
[ 1727, 24225],
|
|
[ 6946, 24225]]])
|
|
"""
|
|
# make sure we have populated unique edges
|
|
populate = self.edges_unique
|
|
# we are relying on the fact that edges are stacked in triplets
|
|
result = self._cache['edges_unique_inverse'].reshape((-1, 3))
|
|
return result
|
|
|
|
@caching.cache_decorator
|
|
def euler_number(self):
|
|
"""
|
|
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 : int
|
|
Topological invariant
|
|
"""
|
|
euler = int(self.referenced_vertices.sum() -
|
|
len(self.edges_unique) +
|
|
len(self.faces))
|
|
return euler
|
|
|
|
@caching.cache_decorator
|
|
def referenced_vertices(self):
|
|
"""
|
|
Which vertices in the current mesh are referenced by a face.
|
|
|
|
Returns
|
|
-------------
|
|
referenced : (len(self.vertices), ) bool
|
|
Which vertices are referenced by a face
|
|
"""
|
|
referenced = np.zeros(len(self.vertices), dtype=np.bool)
|
|
referenced[self.faces] = True
|
|
return referenced
|
|
|
|
@property
|
|
def units(self):
|
|
"""
|
|
Definition of units for the mesh.
|
|
|
|
Returns
|
|
----------
|
|
units : str
|
|
Unit system mesh is in, or None if not defined
|
|
"""
|
|
if 'units' in self.metadata:
|
|
return self.metadata['units']
|
|
else:
|
|
return None
|
|
|
|
@units.setter
|
|
def units(self, value):
|
|
value = str(value).lower()
|
|
self.metadata['units'] = value
|
|
|
|
def convert_units(self, 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?
|
|
"""
|
|
units._convert_units(self, desired, guess)
|
|
return self
|
|
|
|
def merge_vertices(self, **kwargs):
|
|
"""
|
|
If a mesh has vertices that are closer than
|
|
trimesh.constants.tol.merge reindex faces to reference
|
|
the same index for both vertices.
|
|
|
|
Parameters
|
|
-------------
|
|
mesh : Trimesh object
|
|
Mesh to merge vertices on
|
|
use_tex : bool
|
|
If True for textured meshes merge vertices
|
|
with identical positions AND UV coordinates.
|
|
use_norm : bool
|
|
If True meshes with vertex normals defined will
|
|
only have vertices merged with identical normal
|
|
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
|
|
"""
|
|
if 'textured' in kwargs:
|
|
kwargs['merge_tex'] = not kwargs.pop('textured')
|
|
log.warning(
|
|
'merge_vertices depreciation: `not textured`->`merge_tex`')
|
|
grouping.merge_vertices(self, **kwargs)
|
|
|
|
def update_vertices(self, 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
|
|
"""
|
|
# if the mesh is already empty we can't remove anything
|
|
if self.is_empty:
|
|
return
|
|
|
|
# make sure mask is a numpy array
|
|
mask = np.asanyarray(mask)
|
|
|
|
if ((mask.dtype.name == 'bool' and mask.all()) or
|
|
len(mask) == 0 or self.is_empty):
|
|
# mask doesn't remove any vertices so exit early
|
|
return
|
|
|
|
# create the inverse mask if not passed
|
|
if inverse is None:
|
|
inverse = np.zeros(len(self.vertices), dtype=np.int64)
|
|
if mask.dtype.kind == 'b':
|
|
inverse[mask] = np.arange(mask.sum())
|
|
elif mask.dtype.kind == 'i':
|
|
inverse[mask] = np.arange(len(mask))
|
|
else:
|
|
inverse = None
|
|
|
|
# re-index faces from inverse
|
|
if inverse is not None and util.is_shape(self.faces, (-1, 3)):
|
|
self.faces = inverse[self.faces.reshape(-1)].reshape((-1, 3))
|
|
|
|
# update the visual object with our mask
|
|
self.visual.update_vertices(mask)
|
|
# get the normals from cache before dumping
|
|
cached_normals = self._cache['vertex_normals']
|
|
|
|
# apply to face_attributes
|
|
count = len(self.vertices)
|
|
for key, value in self.vertex_attributes.items():
|
|
try:
|
|
# covers un-len'd objects as well
|
|
if len(value) != count:
|
|
raise TypeError()
|
|
except TypeError:
|
|
continue
|
|
# apply the mask to the attribute
|
|
self.vertex_attributes[key] = value[mask]
|
|
|
|
# actually apply the mask
|
|
self.vertices = self.vertices[mask]
|
|
|
|
# if we had passed vertex normals try to save them
|
|
if util.is_shape(cached_normals, (-1, 3)):
|
|
try:
|
|
self.vertex_normals = cached_normals[mask]
|
|
except BaseException:
|
|
pass
|
|
|
|
def update_faces(self, 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 : (m) int or (len(self.faces)) bool
|
|
Mask to remove faces
|
|
"""
|
|
# if the mesh is already empty we can't remove anything
|
|
if self.is_empty:
|
|
return
|
|
|
|
mask = np.asanyarray(mask)
|
|
if mask.dtype.name == 'bool' and mask.all():
|
|
# mask removes no faces so exit early
|
|
return
|
|
|
|
# try to save face normals before dumping cache
|
|
cached_normals = self._cache['face_normals']
|
|
|
|
faces = self._data['faces']
|
|
# if Trimesh has been subclassed and faces have been moved
|
|
# from data to cache, get faces from cache.
|
|
if not util.is_shape(faces, (-1, 3)):
|
|
faces = self._cache['faces']
|
|
|
|
# apply to face_attributes
|
|
count = len(self.faces)
|
|
for key, value in self.face_attributes.items():
|
|
try:
|
|
# covers un-len'd objects as well
|
|
if len(value) != count:
|
|
raise TypeError()
|
|
except TypeError:
|
|
|
|
continue
|
|
# apply the mask to the attribute
|
|
self.face_attributes[key] = value[mask]
|
|
|
|
# actually apply the mask
|
|
self.faces = faces[mask]
|
|
|
|
# apply to face colors
|
|
self.visual.update_faces(mask)
|
|
|
|
# if our normals were the correct shape apply them
|
|
if util.is_shape(cached_normals, (-1, 3)):
|
|
self.face_normals = cached_normals[mask]
|
|
|
|
def remove_infinite_values(self):
|
|
"""
|
|
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`
|
|
"""
|
|
if util.is_shape(self.faces, (-1, 3)):
|
|
# (len(self.faces), ) bool, mask for faces
|
|
face_mask = np.isfinite(self.faces).all(axis=1)
|
|
self.update_faces(face_mask)
|
|
|
|
if util.is_shape(self.vertices, (-1, 3)):
|
|
# (len(self.vertices), ) bool, mask for vertices
|
|
vertex_mask = np.isfinite(self.vertices).all(axis=1)
|
|
self.update_vertices(vertex_mask)
|
|
|
|
def remove_duplicate_faces(self):
|
|
"""
|
|
On the current mesh remove any faces which are duplicates.
|
|
|
|
Alters `self.faces` to remove duplicate faces
|
|
"""
|
|
unique, inverse = grouping.unique_rows(np.sort(self.faces, axis=1))
|
|
self.update_faces(unique)
|
|
|
|
def rezero(self):
|
|
"""
|
|
Translate the mesh so that all vertex vertices are positive.
|
|
|
|
Alters `self.vertices`.
|
|
"""
|
|
self.apply_translation(self.bounds[0] * -1.0)
|
|
|
|
@log_time
|
|
def split(self, **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 : (n, ) trimesh.Trimesh
|
|
Separate bodies from original mesh
|
|
"""
|
|
return graph.split(self, **kwargs)
|
|
|
|
@caching.cache_decorator
|
|
def face_adjacency(self):
|
|
"""
|
|
Find faces that share an edge, which we call here 'adjacent'.
|
|
|
|
Returns
|
|
----------
|
|
adjacency : (n, 2) int
|
|
Pairs of faces which share an edge
|
|
|
|
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)
|
|
"""
|
|
adjacency, edges = graph.face_adjacency(
|
|
mesh=self, return_edges=True)
|
|
self._cache['face_adjacency_edges'] = edges
|
|
return adjacency
|
|
|
|
@caching.cache_decorator
|
|
def face_adjacency_edges(self):
|
|
"""
|
|
Returns the edges that are shared by the adjacent faces.
|
|
|
|
Returns
|
|
--------
|
|
edges : (n, 2) int
|
|
Vertex indices which correspond to face_adjacency
|
|
"""
|
|
# this value is calculated as a byproduct of the face adjacency
|
|
populate = self.face_adjacency
|
|
return self._cache['face_adjacency_edges']
|
|
|
|
@caching.cache_decorator
|
|
def face_adjacency_edges_tree(self):
|
|
"""
|
|
A KDTree for mapping edges back face adjacency index.
|
|
|
|
Returns
|
|
------------
|
|
tree : scipy.spatial.cKDTree
|
|
Tree when queried with SORTED edges will return
|
|
their index in mesh.face_adjacency
|
|
"""
|
|
from scipy.spatial import cKDTree
|
|
return cKDTree(self.face_adjacency_edges)
|
|
|
|
@caching.cache_decorator
|
|
def face_adjacency_angles(self):
|
|
"""
|
|
Return the angle between adjacent faces
|
|
|
|
Returns
|
|
--------
|
|
adjacency_angle : (n, ) float
|
|
Angle between adjacent faces
|
|
Each value corresponds with self.face_adjacency
|
|
"""
|
|
# get pairs of unit vectors for adjacent faces
|
|
pairs = self.face_normals[self.face_adjacency]
|
|
# find the angle between the pairs of vectors
|
|
angles = geometry.vector_angle(pairs)
|
|
return angles
|
|
|
|
@caching.cache_decorator
|
|
def face_adjacency_projections(self):
|
|
"""
|
|
The projection of the non-shared vertex of a triangle onto
|
|
its adjacent face
|
|
|
|
Returns
|
|
----------
|
|
projections : (len(self.face_adjacency), ) float
|
|
Dot product of vertex
|
|
onto plane of adjacent triangle.
|
|
"""
|
|
projections = convex.adjacency_projections(self)
|
|
return projections
|
|
|
|
@caching.cache_decorator
|
|
def face_adjacency_convex(self):
|
|
"""
|
|
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 : (len(self.face_adjacency), ) bool
|
|
Face pairs that are locally convex
|
|
"""
|
|
are_convex = self.face_adjacency_projections < tol.merge
|
|
return are_convex
|
|
|
|
@caching.cache_decorator
|
|
def face_adjacency_unshared(self):
|
|
"""
|
|
Return the vertex index of the two vertices not in the shared
|
|
edge between two adjacent faces
|
|
|
|
Returns
|
|
-----------
|
|
vid_unshared : (len(mesh.face_adjacency), 2) int
|
|
Indexes of mesh.vertices
|
|
"""
|
|
vid_unshared = graph.face_adjacency_unshared(self)
|
|
return vid_unshared
|
|
|
|
@caching.cache_decorator
|
|
def face_adjacency_radius(self):
|
|
"""
|
|
The approximate radius of a cylinder that fits inside adjacent faces.
|
|
|
|
Returns
|
|
------------
|
|
radii : (len(self.face_adjacency), ) float
|
|
Approximate radius formed by triangle pair
|
|
"""
|
|
radii, span = graph.face_adjacency_radius(mesh=self)
|
|
self._cache['face_adjacency_span'] = span
|
|
return radii
|
|
|
|
@caching.cache_decorator
|
|
def face_adjacency_span(self):
|
|
"""
|
|
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 : (len(self.face_adjacency), ) float
|
|
Approximate span between the non-shared vertices
|
|
"""
|
|
populate = self.face_adjacency_radius
|
|
return self._cache['face_adjacency_span']
|
|
|
|
@caching.cache_decorator
|
|
def vertex_adjacency_graph(self):
|
|
"""
|
|
Returns a networkx graph representing the vertices and their connections
|
|
in the mesh.
|
|
|
|
Returns
|
|
---------
|
|
graph: networkx.Graph
|
|
Graph representing vertices and edges between
|
|
them where vertices are nodes and edges are edges
|
|
|
|
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]
|
|
"""
|
|
|
|
adjacency_g = graph.vertex_adjacency_graph(mesh=self)
|
|
return adjacency_g
|
|
|
|
@caching.cache_decorator
|
|
def vertex_neighbors(self):
|
|
"""
|
|
The vertex neighbors of each vertex of the mesh, determined from
|
|
the cached vertex_adjacency_graph, if already existent.
|
|
|
|
Returns
|
|
----------
|
|
vertex_neighbors : (len(self.vertices), ) int
|
|
Represents immediate neighbors of each vertex along
|
|
the edge of a triangle
|
|
|
|
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]
|
|
"""
|
|
return graph.neighbors(
|
|
edges=self.edges_unique, max_index=len(self.vertices))
|
|
|
|
@caching.cache_decorator
|
|
def is_winding_consistent(self):
|
|
"""
|
|
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 : bool
|
|
Is winding is consistent or not
|
|
"""
|
|
if self.is_empty:
|
|
return False
|
|
# consistent winding check is populated into the cache by is_watertight
|
|
populate = self.is_watertight
|
|
return self._cache['is_winding_consistent']
|
|
|
|
@caching.cache_decorator
|
|
def is_watertight(self):
|
|
"""
|
|
Check if a mesh is watertight by making sure every edge is
|
|
included in two faces.
|
|
|
|
Returns
|
|
----------
|
|
is_watertight : bool
|
|
Is mesh watertight or not
|
|
"""
|
|
if self.is_empty:
|
|
return False
|
|
watertight, winding = graph.is_watertight(
|
|
edges=self.edges, edges_sorted=self.edges_sorted)
|
|
self._cache['is_winding_consistent'] = winding
|
|
return watertight
|
|
|
|
@caching.cache_decorator
|
|
def is_volume(self):
|
|
"""
|
|
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 : bool
|
|
Does the mesh represent a volume
|
|
"""
|
|
valid = bool(self.is_watertight and
|
|
self.is_winding_consistent and
|
|
np.isfinite(self.center_mass).all() and
|
|
self.volume > 0.0)
|
|
return valid
|
|
|
|
@property
|
|
def is_empty(self):
|
|
"""
|
|
Does the current mesh have data defined.
|
|
|
|
Returns
|
|
--------
|
|
empty : bool
|
|
If True, no data is set on the current mesh
|
|
"""
|
|
return self._data.is_empty()
|
|
|
|
@caching.cache_decorator
|
|
def is_convex(self):
|
|
"""
|
|
Check if a mesh is convex or not.
|
|
|
|
Returns
|
|
----------
|
|
is_convex: bool
|
|
Is mesh convex or not
|
|
"""
|
|
if self.is_empty:
|
|
return False
|
|
|
|
is_convex = bool(convex.is_convex(self))
|
|
return is_convex
|
|
|
|
@caching.cache_decorator
|
|
def kdtree(self):
|
|
"""
|
|
Return a scipy.spatial.cKDTree of the vertices of the mesh.
|
|
Not cached as this lead to observed memory issues and segfaults.
|
|
|
|
Returns
|
|
---------
|
|
tree : scipy.spatial.cKDTree
|
|
Contains mesh.vertices
|
|
"""
|
|
|
|
from scipy.spatial import cKDTree
|
|
tree = cKDTree(self.vertices.view(np.ndarray))
|
|
return tree
|
|
|
|
def remove_degenerate_faces(self, height=tol.merge):
|
|
"""
|
|
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 : (len(self.faces), ) bool
|
|
Mask used to remove faces
|
|
"""
|
|
nondegenerate = triangles.nondegenerate(
|
|
self.triangles,
|
|
areas=self.area_faces,
|
|
|
|
height=height)
|
|
self.update_faces(nondegenerate)
|
|
|
|
return nondegenerate
|
|
|
|
@caching.cache_decorator
|
|
def facets(self):
|
|
"""
|
|
Return a list of face indices for coplanar adjacent faces.
|
|
|
|
Returns
|
|
---------
|
|
facets : (n, ) sequence of (m, ) int
|
|
Groups of indexes of self.faces
|
|
"""
|
|
facets = graph.facets(self)
|
|
return facets
|
|
|
|
@caching.cache_decorator
|
|
def facets_area(self):
|
|
"""
|
|
Return an array containing the area of each facet.
|
|
|
|
Returns
|
|
---------
|
|
area : (len(self.facets), ) float
|
|
Total area of each facet (group of faces)
|
|
"""
|
|
# avoid thrashing the cache inside a loop
|
|
area_faces = self.area_faces
|
|
# sum the area of each group of faces represented by facets
|
|
# use native python sum in tight loop as opposed to array.sum()
|
|
# as in this case the lower function call overhead of
|
|
# native sum provides roughly a 50% speedup
|
|
areas = np.array([sum(area_faces[i])
|
|
for i in self.facets],
|
|
dtype=np.float64)
|
|
return areas
|
|
|
|
@caching.cache_decorator
|
|
def facets_normal(self):
|
|
"""
|
|
Return the normal of each facet
|
|
|
|
Returns
|
|
---------
|
|
normals: (len(self.facets), 3) float
|
|
A unit normal vector for each facet
|
|
"""
|
|
if len(self.facets) == 0:
|
|
return np.array([])
|
|
|
|
area_faces = self.area_faces
|
|
|
|
# the face index of the largest face in each facet
|
|
index = np.array([i[area_faces[i].argmax()]
|
|
for i in self.facets])
|
|
# (n, 3) float, unit normal vectors of facet plane
|
|
normals = self.face_normals[index]
|
|
# (n, 3) float, points on facet plane
|
|
origins = self.vertices[self.faces[:, 0][index]]
|
|
# save origins in cache
|
|
self._cache['facets_origin'] = origins
|
|
|
|
return normals
|
|
|
|
@caching.cache_decorator
|
|
def facets_origin(self):
|
|
"""
|
|
Return a point on the facet plane.
|
|
|
|
Returns
|
|
------------
|
|
origins : (len(self.facets), 3) float
|
|
A point on each facet plane
|
|
"""
|
|
populate = self.facets_normal
|
|
return self._cache['facets_origin']
|
|
|
|
@caching.cache_decorator
|
|
def facets_boundary(self):
|
|
"""
|
|
Return the edges which represent the boundary of each facet
|
|
|
|
Returns
|
|
---------
|
|
edges_boundary : sequence of (n, 2) int
|
|
Indices of self.vertices
|
|
"""
|
|
# make each row correspond to a single face
|
|
edges = self.edges_sorted.reshape((-1, 6))
|
|
# get the edges for each facet
|
|
edges_facet = [edges[i].reshape((-1, 2)) for i in self.facets]
|
|
edges_boundary = np.array([i[grouping.group_rows(i, require_count=1)]
|
|
for i in edges_facet])
|
|
return edges_boundary
|
|
|
|
@caching.cache_decorator
|
|
def facets_on_hull(self):
|
|
"""
|
|
Find which facets of the mesh are on the convex hull.
|
|
|
|
Returns
|
|
---------
|
|
on_hull : (len(mesh.facets), ) bool
|
|
is A facet on the meshes convex hull or not
|
|
"""
|
|
# if no facets exit early
|
|
if len(self.facets) == 0:
|
|
return np.array([], dtype=np.bool)
|
|
|
|
# facets plane, origin and normal
|
|
normals = self.facets_normal
|
|
origins = self.facets_origin
|
|
|
|
# (n, 3) convex hull vertices
|
|
convex = self.convex_hull.vertices.view(np.ndarray).copy()
|
|
|
|
# boolean mask for which facets are on convex hull
|
|
on_hull = np.zeros(len(self.facets), dtype=np.bool)
|
|
|
|
for i, normal, origin in zip(range(len(normals)), normals, origins):
|
|
# a facet plane is on the convex hull if every vertex
|
|
# of the convex hull is behind that plane
|
|
# which we are checking with dot products
|
|
dot = np.dot(normal, (convex - origin).T)
|
|
on_hull[i] = (dot < tol.merge).all()
|
|
|
|
return on_hull
|
|
|
|
@log_time
|
|
def fix_normals(self, multibody=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
|
|
"""
|
|
if multibody is None:
|
|
multibody = self.body_count > 1
|
|
repair.fix_normals(self, multibody=multibody)
|
|
|
|
def fill_holes(self):
|
|
"""
|
|
Fill single triangle and single quad holes in the current mesh.
|
|
|
|
Returns
|
|
----------
|
|
watertight : bool
|
|
Is the mesh watertight after the function completes
|
|
"""
|
|
return repair.fill_holes(self)
|
|
|
|
def register(self, 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
|
|
"""
|
|
mesh_to_other, cost = registration.mesh_other(mesh=self,
|
|
other=other,
|
|
**kwargs)
|
|
return mesh_to_other, cost
|
|
|
|
def compute_stable_poses(self,
|
|
center_mass=None,
|
|
sigma=0.0,
|
|
n_samples=1,
|
|
threshold=0.0):
|
|
"""
|
|
Computes stable orientations of a mesh and their quasi-static probabilites.
|
|
|
|
This method samples the location of the center of mass from a multivariate
|
|
gaussian (mean at com, cov equal to identity times sigma) over n_samples.
|
|
For each sample, it computes the stable resting poses of the mesh on a
|
|
a planar workspace and evaluates the probabilities of landing in
|
|
each pose if the object is dropped onto the table randomly.
|
|
|
|
This method returns the 4x4 homogeneous transform matrices that place
|
|
the shape against the planar surface with the z-axis pointing upwards
|
|
and a list of the probabilities for each pose.
|
|
The transforms and probabilties that are returned are sorted, with the
|
|
most probable pose first.
|
|
|
|
Parameters
|
|
------------
|
|
center_mass : (3, ) float
|
|
The object center of mass (if None, this method
|
|
assumes uniform density and watertightness and
|
|
computes a center of mass explicitly)
|
|
sigma : float
|
|
The covariance for the multivariate gaussian used
|
|
to sample center of mass locations
|
|
n_samples : int
|
|
The number of samples of the center of mass location
|
|
threshold : float
|
|
The probability value at which to threshold
|
|
returned stable poses
|
|
|
|
Returns
|
|
-------
|
|
transforms : (n, 4, 4) float
|
|
The homogeneous matrices that transform the
|
|
object to rest in a stable pose, with the
|
|
new z-axis pointing upwards from the table
|
|
and the object just touching the table.
|
|
|
|
probs : (n, ) float
|
|
A probability ranging from 0.0 to 1.0 for each pose
|
|
"""
|
|
return poses.compute_stable_poses(mesh=self,
|
|
center_mass=center_mass,
|
|
sigma=sigma,
|
|
n_samples=n_samples,
|
|
threshold=threshold)
|
|
|
|
def subdivide(self, 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 vertex attributes
|
|
vertex_attributes = {}
|
|
if (hasattr(self.visual, 'uv') and
|
|
np.shape(self.visual.uv) == (len(self.vertices), 2)):
|
|
# only subdivide if
|
|
vertex_attributes['uv'] = self.visual.uv
|
|
|
|
# perform the subdivision with vertex attributes
|
|
vertices, faces, attr = remesh.subdivide(
|
|
vertices=self.vertices,
|
|
faces=self.faces,
|
|
face_index=face_index,
|
|
vertex_attributes=vertex_attributes)
|
|
# if we had texture reconstruct it here
|
|
visual = None
|
|
if 'uv' in attr:
|
|
# get a copy of the current visuals
|
|
visual = self.visual.copy()
|
|
# assign the subdivided UV's and remove them
|
|
visual.uv = attr.pop('uv')
|
|
# create a new mesh
|
|
result = Trimesh(
|
|
vertices=vertices,
|
|
faces=faces,
|
|
visual=visual,
|
|
vertex_attributes=attr,
|
|
process=False)
|
|
return result
|
|
|
|
@log_time
|
|
def smoothed(self, **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 : trimesh.Trimesh
|
|
Non watertight version of current mesh
|
|
which will render nicely with smooth shading
|
|
"""
|
|
|
|
# smooth should be recomputed if visuals change
|
|
self.visual._verify_crc()
|
|
cached = self.visual._cache['smoothed']
|
|
if cached is not None:
|
|
return cached
|
|
# run smoothing
|
|
smoothed = graph.smoothed(
|
|
self, **kwargs)
|
|
self.visual._cache['smoothed'] = smoothed
|
|
return smoothed
|
|
|
|
@property
|
|
def visual(self):
|
|
"""
|
|
Get the stored visuals for the current mesh.
|
|
|
|
Returns
|
|
-------------
|
|
visual : ColorVisuals or TextureVisuals
|
|
Contains visual information about the mesh
|
|
"""
|
|
if hasattr(self, '_visual'):
|
|
return self._visual
|
|
return None
|
|
|
|
@visual.setter
|
|
def visual(self, value):
|
|
"""
|
|
When setting a visual object, always make sure
|
|
that `visual.mesh` points back to the source mesh.
|
|
|
|
Parameters
|
|
--------------
|
|
visual : ColorVisuals or TextureVisuals
|
|
Contains visual information about the mesh
|
|
"""
|
|
value.mesh = self
|
|
self._visual = value
|
|
|
|
def section(self,
|
|
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: (3) vector for plane normal
|
|
Normal vector of section plane
|
|
plane_origin : (3, ) float
|
|
Point on the cross section plane
|
|
|
|
Returns
|
|
---------
|
|
intersections: Path3D or None
|
|
Curve of intersection
|
|
"""
|
|
# turn line segments into Path2D/Path3D objects
|
|
from .exchange.load import load_path
|
|
|
|
# return a single cross section in 3D
|
|
lines, face_index = intersections.mesh_plane(
|
|
mesh=self,
|
|
plane_normal=plane_normal,
|
|
plane_origin=plane_origin,
|
|
return_faces=True,
|
|
**kwargs)
|
|
|
|
# if the section didn't hit the mesh return None
|
|
if len(lines) == 0:
|
|
return None
|
|
|
|
# otherwise load the line segments into a Path3D object
|
|
path = load_path(lines)
|
|
|
|
# add the face index info into metadata
|
|
path.metadata['face_index'] = face_index
|
|
|
|
return path
|
|
|
|
def section_multiplane(self,
|
|
plane_origin,
|
|
plane_normal,
|
|
heights):
|
|
"""
|
|
Return multiple parallel cross sections of the current
|
|
mesh in 2D.
|
|
|
|
Parameters
|
|
------------
|
|
plane_normal: (3) vector for plane normal
|
|
Normal vector of section plane
|
|
plane_origin : (3, ) float
|
|
Point on the cross section plane
|
|
heights : (n, ) float
|
|
Each section is offset by height along
|
|
the plane normal.
|
|
|
|
Returns
|
|
---------
|
|
paths : (n, ) Path2D or None
|
|
2D cross sections at specified heights.
|
|
path.metadata['to_3D'] contains transform
|
|
to return 2D section back into 3D space.
|
|
"""
|
|
# turn line segments into Path2D/Path3D objects
|
|
from .exchange.load import load_path
|
|
# do a multiplane intersection
|
|
lines, transforms, faces = intersections.mesh_multiplane(
|
|
mesh=self,
|
|
plane_normal=plane_normal,
|
|
plane_origin=plane_origin,
|
|
heights=heights)
|
|
|
|
# turn the line segments into Path2D objects
|
|
paths = [None] * len(lines)
|
|
for index, L, T in zip(range(len(lines)),
|
|
lines,
|
|
transforms):
|
|
if len(L) > 0:
|
|
paths[index] = load_path(
|
|
L, metadata={'to_3D': T})
|
|
return paths
|
|
|
|
def slice_plane(self,
|
|
plane_origin,
|
|
plane_normal,
|
|
**kwargs):
|
|
"""
|
|
Slice the mesh with a plane, returning a new mesh that is the
|
|
portion of the original mesh to the positive normal side of the plane
|
|
|
|
Parameters
|
|
------------
|
|
plane_normal: (3) vector for plane normal
|
|
Normal vector of slicing plane
|
|
plane_origin : (3, ) float
|
|
Point on the slicing plane
|
|
|
|
Returns
|
|
---------
|
|
new_mesh: trimesh.Trimesh or None
|
|
Subset of current mesh that intersects the half plane
|
|
to the positive normal side of the plane
|
|
"""
|
|
|
|
# return a new mesh
|
|
new_mesh = intersections.slice_mesh_plane(
|
|
mesh=self,
|
|
plane_normal=plane_normal,
|
|
plane_origin=plane_origin,
|
|
**kwargs)
|
|
|
|
return new_mesh
|
|
|
|
@caching.cache_decorator
|
|
def convex_hull(self):
|
|
"""
|
|
Returns a Trimesh object representing the convex hull of
|
|
the current mesh.
|
|
|
|
Returns
|
|
--------
|
|
convex : trimesh.Trimesh
|
|
Mesh of convex hull of current mesh
|
|
"""
|
|
hull = convex.convex_hull(self)
|
|
return hull
|
|
|
|
def sample(self, count, return_index=False):
|
|
"""
|
|
Return random samples distributed across the
|
|
surface of the mesh
|
|
|
|
Parameters
|
|
------------
|
|
count : int
|
|
Number of points to sample
|
|
return_index : bool
|
|
If True will also return the index of which face each
|
|
sample was taken from.
|
|
|
|
Returns
|
|
---------
|
|
samples : (count, 3) float
|
|
Points on surface of mesh
|
|
face_index : (count, ) int
|
|
Index of self.faces
|
|
"""
|
|
samples, index = sample.sample_surface(mesh=self, count=count)
|
|
if return_index:
|
|
return samples, index
|
|
return samples
|
|
|
|
def remove_unreferenced_vertices(self):
|
|
"""
|
|
Remove all vertices in the current mesh which are not
|
|
referenced by a face.
|
|
"""
|
|
referenced = np.zeros(len(self.vertices), dtype=np.bool)
|
|
referenced[self.faces] = True
|
|
|
|
inverse = np.zeros(len(self.vertices), dtype=np.int64)
|
|
inverse[referenced] = np.arange(referenced.sum())
|
|
|
|
self.update_vertices(mask=referenced, inverse=inverse)
|
|
|
|
def unmerge_vertices(self):
|
|
"""
|
|
Removes all face references so that every face contains
|
|
three unique vertex indices and no faces are adjacent.
|
|
"""
|
|
# new faces are incrementing so every vertex is unique
|
|
faces = np.arange(len(self.faces) * 3,
|
|
dtype=np.int64).reshape((-1, 3))
|
|
|
|
# use update_vertices to apply mask to
|
|
# all properties that are per-vertex
|
|
self.update_vertices(self.faces.reshape(-1))
|
|
# set faces to incrementing indexes
|
|
self.faces = faces
|
|
# keep face normals as the haven't changed
|
|
self._cache.clear(exclude=['face_normals'])
|
|
|
|
def apply_transform(self, 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
|
|
"""
|
|
# get c-order float64 matrix
|
|
matrix = np.asanyarray(
|
|
matrix, order='C', dtype=np.float64)
|
|
|
|
# only support homogeneous transformations
|
|
if matrix.shape != (4, 4):
|
|
raise ValueError('Transformation matrix must be (4, 4)!')
|
|
|
|
# exit early if we've been passed an identity matrix
|
|
# np.allclose is surprisingly slow so do this test
|
|
elif util.allclose(matrix, np.eye(4), 1e-8):
|
|
log.debug('apply_transform passed identity matrix')
|
|
return self
|
|
|
|
# new vertex positions
|
|
new_vertices = transformations.transform_points(
|
|
self.vertices,
|
|
matrix=matrix)
|
|
|
|
# check to see if the matrix has rotation
|
|
# rather than just translation
|
|
has_rotation = not util.allclose(
|
|
matrix[:3, :3], np.eye(3), atol=1e-6)
|
|
|
|
# overridden center of mass
|
|
if self._center_mass is not None:
|
|
self._center_mass = transformations.transform_points(
|
|
np.array([self._center_mass, ]),
|
|
matrix)[0]
|
|
|
|
# preserve face normals if we have them stored
|
|
new_face_normals = None
|
|
if has_rotation and 'face_normals' in self._cache:
|
|
# transform face normals by rotation component
|
|
new_face_normals = util.unitize(
|
|
transformations.transform_points(
|
|
self.face_normals,
|
|
matrix=matrix,
|
|
translate=False))
|
|
|
|
# preserve vertex normals if we have them stored
|
|
new_vertex_normals = None
|
|
if has_rotation and 'vertex_normals' in self._cache:
|
|
new_vertex_normals = util.unitize(
|
|
transformations.transform_points(
|
|
self.vertex_normals,
|
|
matrix=matrix,
|
|
translate=False))
|
|
|
|
# if transformation flips winding of triangles
|
|
if has_rotation and transformations.flips_winding(matrix):
|
|
log.debug('transform flips winding')
|
|
# fliplr will make array non C contiguous
|
|
# which will cause hashes to be more
|
|
# expensive than necessary so wrap
|
|
self.faces = np.ascontiguousarray(
|
|
np.fliplr(self.faces))
|
|
|
|
# assign the new values
|
|
self.vertices = new_vertices
|
|
# may be None if we didn't have them previously
|
|
self.face_normals = new_face_normals
|
|
self.vertex_normals = new_vertex_normals
|
|
|
|
# preserve normals and topology in cache
|
|
# while dumping everything else
|
|
self._cache.clear(exclude=[
|
|
'face_normals', # transformed by us
|
|
'vertex_normals' # also transformed by us
|
|
'face_adjacency', # topological
|
|
'face_adjacency_edges',
|
|
'face_adjacency_unshared',
|
|
'edges',
|
|
'edges_face',
|
|
'edges_sorted',
|
|
'edges_unique',
|
|
'edges_unique_idx',
|
|
'edges_unique_inverse',
|
|
'edges_sparse',
|
|
'body_count',
|
|
'faces_unique_edges',
|
|
'euler_number', ])
|
|
# set the cache ID with the current hash value
|
|
self._cache.id_set()
|
|
|
|
log.debug('mesh transformed by matrix')
|
|
return self
|
|
|
|
def voxelized(self, 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 : VoxelGrid object
|
|
Representing the current mesh
|
|
"""
|
|
from .voxel import creation
|
|
return creation.voxelize(
|
|
mesh=self, pitch=pitch, method=method, **kwargs)
|
|
|
|
def outline(self, 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 : Path3D
|
|
Curve in 3D of the outline
|
|
"""
|
|
from .path.exchange.misc import faces_to_path
|
|
from .path.exchange.load import _create_path
|
|
|
|
path = _create_path(**faces_to_path(self,
|
|
face_ids,
|
|
**kwargs))
|
|
return path
|
|
|
|
@caching.cache_decorator
|
|
def area(self):
|
|
"""
|
|
Summed area of all triangles in the current mesh.
|
|
|
|
Returns
|
|
---------
|
|
area : float
|
|
Surface area of mesh
|
|
"""
|
|
area = self.area_faces.sum()
|
|
return area
|
|
|
|
@caching.cache_decorator
|
|
def area_faces(self):
|
|
"""
|
|
The area of each face in the mesh.
|
|
|
|
Returns
|
|
---------
|
|
area_faces : (n, ) float
|
|
Area of each face
|
|
"""
|
|
area_faces = triangles.area(crosses=self.triangles_cross,
|
|
sum=False)
|
|
return area_faces
|
|
|
|
@caching.cache_decorator
|
|
def mass_properties(self):
|
|
"""
|
|
Returns the mass properties of the current mesh.
|
|
|
|
Assumes uniform density, and result is probably garbage if mesh
|
|
isn't watertight.
|
|
|
|
Returns
|
|
----------
|
|
properties : dict
|
|
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
|
|
"""
|
|
mass = triangles.mass_properties(triangles=self.triangles,
|
|
crosses=self.triangles_cross,
|
|
density=self._density,
|
|
center_mass=self._center_mass,
|
|
skip_inertia=False)
|
|
|
|
# if magical clean-up mode is enabled
|
|
# and mesh is watertight/wound correctly but with negative
|
|
# volume it means that every triangle is probably facing
|
|
# inwards, so we invert it in-place without dumping cache
|
|
if (self.is_watertight and
|
|
self.is_winding_consistent and
|
|
np.linalg.det(mass['inertia']) < 0.0 and
|
|
mass['mass'] < 0.0 and
|
|
mass['volume'] < 0.0):
|
|
# negate mass properties so we don't need to recalculate
|
|
mass['inertia'] = -mass['inertia']
|
|
mass['mass'] = -mass['mass']
|
|
mass['volume'] = -mass['volume']
|
|
|
|
return mass
|
|
|
|
def invert(self):
|
|
"""
|
|
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`.
|
|
"""
|
|
with self._cache:
|
|
if 'face_normals' in self._cache:
|
|
self.face_normals = self._cache['face_normals'] * -1.0
|
|
if 'vertex_normals' in self._cache:
|
|
self.vertex_normals = self._cache['vertex_normals'] * -1.0
|
|
# fliplr makes array non-contiguous so cache checks slow
|
|
self.faces = np.ascontiguousarray(
|
|
np.fliplr(self.faces))
|
|
# save our normals
|
|
self._cache.clear(exclude=['face_normals',
|
|
'vertex_normals'])
|
|
|
|
def scene(self, **kwargs):
|
|
"""
|
|
Returns a Scene object containing the current mesh.
|
|
|
|
Returns
|
|
---------
|
|
scene : trimesh.scene.scene.Scene
|
|
Contains just the current mesh
|
|
"""
|
|
return Scene(self, **kwargs)
|
|
|
|
def show(self, **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 : trimesh.scene.Scene
|
|
Scene with current mesh in it
|
|
"""
|
|
scene = self.scene()
|
|
return scene.show(**kwargs)
|
|
|
|
def submesh(self, 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
|
|
"""
|
|
return util.submesh(mesh=self,
|
|
faces_sequence=faces_sequence,
|
|
**kwargs)
|
|
|
|
@caching.cache_decorator
|
|
def identifier(self):
|
|
"""
|
|
Return a float vector which is unique to the mesh
|
|
and is robust to rotation and translation.
|
|
|
|
Returns
|
|
-----------
|
|
identifier : (6, ) float
|
|
Identifying properties of the current mesh
|
|
"""
|
|
identifier = comparison.identifier_simple(self)
|
|
return identifier
|
|
|
|
@caching.cache_decorator
|
|
def identifier_md5(self):
|
|
"""
|
|
An MD5 of the rotation invariant identifier vector
|
|
|
|
Returns
|
|
---------
|
|
hashed : str
|
|
MD5 hash of the identifier vector
|
|
"""
|
|
hashed = comparison.identifier_hash(self.identifier)
|
|
return hashed
|
|
|
|
def export(self, 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
|
|
"""
|
|
return export_mesh(mesh=self,
|
|
file_obj=file_obj,
|
|
file_type=file_type,
|
|
**kwargs)
|
|
|
|
def to_dict(self):
|
|
"""
|
|
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 : dict
|
|
With keys that match trimesh constructor
|
|
"""
|
|
result = self.export(file_type='dict')
|
|
return result
|
|
|
|
def convex_decomposition(self, maxhulls=20, **kwargs):
|
|
"""
|
|
Compute an approximate convex decomposition of a mesh.
|
|
|
|
testVHACD Parameters which can be passed as kwargs:
|
|
|
|
Name Default
|
|
-----------------------------------------------------
|
|
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 trimesh.Trimesh
|
|
List of convex meshes that approximate the original
|
|
"""
|
|
result = decomposition.convex_decomposition(self,
|
|
maxhulls=maxhulls,
|
|
**kwargs)
|
|
return result
|
|
|
|
def union(self, other, engine=None, **kwargs):
|
|
"""
|
|
Boolean union between this mesh and n other meshes
|
|
|
|
Parameters
|
|
------------
|
|
other : Trimesh or (n, ) Trimesh
|
|
Other meshes to union
|
|
engine : None or str
|
|
Which backend to use
|
|
|
|
Returns
|
|
---------
|
|
union : trimesh.Trimesh
|
|
Union of self and other Trimesh objects
|
|
"""
|
|
result = boolean.union(
|
|
meshes=np.append(self, other),
|
|
engine=engine,
|
|
**kwargs)
|
|
return result
|
|
|
|
def difference(self, 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 : trimesh.Trimesh
|
|
Difference between self and other Trimesh objects
|
|
"""
|
|
result = boolean.difference(meshes=np.append(self, other),
|
|
engine=engine, **kwargs)
|
|
return result
|
|
|
|
def intersection(self, 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 : trimesh.Trimesh
|
|
Mesh of the volume contained by all passed meshes
|
|
"""
|
|
result = boolean.intersection(meshes=np.append(self, other),
|
|
engine=engine, **kwargs)
|
|
return result
|
|
|
|
def contains(self, 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 : (n, ) bool
|
|
Whether or not each point is inside the mesh
|
|
"""
|
|
if not self.is_watertight:
|
|
log.warning('Mesh is non-watertight for contained point query!')
|
|
contains = self.ray.contains_points(points)
|
|
return contains
|
|
|
|
@caching.cache_decorator
|
|
def face_angles(self):
|
|
"""
|
|
Returns the angle at each vertex of a face.
|
|
|
|
Returns
|
|
--------
|
|
angles : (len(self.faces), 3) float
|
|
Angle at each vertex of a face
|
|
"""
|
|
angles = triangles.angles(self.triangles)
|
|
return angles
|
|
|
|
@caching.cache_decorator
|
|
def face_angles_sparse(self):
|
|
"""
|
|
A sparse matrix representation of the face angles.
|
|
|
|
Returns
|
|
----------
|
|
sparse : scipy.sparse.coo_matrix
|
|
Float sparse matrix with with shape:
|
|
(len(self.vertices), len(self.faces))
|
|
"""
|
|
angles = curvature.face_angles_sparse(self)
|
|
return angles
|
|
|
|
@caching.cache_decorator
|
|
def vertex_defects(self):
|
|
"""
|
|
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 : (len(self.vertices), ) float
|
|
Vertex defect at the every vertex
|
|
"""
|
|
defects = curvature.vertex_defects(self)
|
|
return defects
|
|
|
|
@caching.cache_decorator
|
|
def vertex_degree(self):
|
|
"""
|
|
Return the number of faces each vertex is included in.
|
|
|
|
Returns
|
|
----------
|
|
degree : (len(self.vertices), ) int
|
|
Number of faces each vertex is included in
|
|
"""
|
|
# get degree through sparse matrix
|
|
degree = np.array(self.faces_sparse.sum(axis=1)).flatten()
|
|
return degree
|
|
|
|
@caching.cache_decorator
|
|
def face_adjacency_tree(self):
|
|
"""
|
|
An R-tree of face adjacencies.
|
|
|
|
Returns
|
|
--------
|
|
tree: rtree.index
|
|
Where each edge in self.face_adjacency has a
|
|
rectangular cell
|
|
"""
|
|
# the (n,6) interleaved bounding box for every line segment
|
|
segment_bounds = np.column_stack((
|
|
self.vertices[self.face_adjacency_edges].min(axis=1),
|
|
self.vertices[self.face_adjacency_edges].max(axis=1)))
|
|
tree = util.bounds_tree(segment_bounds)
|
|
return tree
|
|
|
|
def copy(self, 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 : trimesh.Trimesh
|
|
Copy of current mesh
|
|
"""
|
|
# start with an empty mesh
|
|
copied = Trimesh()
|
|
# always deepcopy vertex and face data
|
|
copied._data.data = copy.deepcopy(self._data.data)
|
|
# copy visual information
|
|
copied.visual = self.visual.copy()
|
|
# get metadata
|
|
copied.metadata = copy.deepcopy(self.metadata)
|
|
# get center_mass and density
|
|
if self._center_mass is not None:
|
|
copied.center_mass = self.center_mass
|
|
copied._density = self._density
|
|
|
|
# make sure cache ID is set initially
|
|
copied._cache.verify()
|
|
|
|
if include_cache:
|
|
# shallow copy cached items into the new cache
|
|
# since the data didn't change here when the
|
|
# data in the new mesh is changed these items
|
|
# will be dumped in the new mesh but preserved
|
|
# in the original mesh
|
|
copied._cache.cache.update(self._cache.cache)
|
|
|
|
return copied
|
|
|
|
def __deepcopy__(self, *args):
|
|
# interpret deep copy as "get rid of cached data"
|
|
return self.copy(include_cache=False)
|
|
|
|
def __copy__(self, *args):
|
|
# interpret shallow copy as "keep cached data"
|
|
return self.copy(include_cache=True)
|
|
|
|
def eval_cached(self, 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 : result of running eval on statement with args
|
|
|
|
Examples
|
|
-----------
|
|
r = mesh.eval_cached('np.dot(self.vertices, args[0])', [0, 0, 1])
|
|
"""
|
|
|
|
statement = str(statement)
|
|
key = 'eval_cached_' + statement
|
|
key += '_'.join(str(i) for i in args)
|
|
|
|
if key in self._cache:
|
|
return self._cache[key]
|
|
|
|
result = eval(statement)
|
|
self._cache[key] = result
|
|
return result
|
|
|
|
def __hash__(self):
|
|
"""
|
|
Return the MD5 hash of the mesh as an integer.
|
|
|
|
Returns
|
|
----------
|
|
hashed : int
|
|
MD5 of mesh data
|
|
"""
|
|
hashed = int(self.md5(), 16)
|
|
return hashed
|
|
|
|
def __add__(self, other):
|
|
"""
|
|
Concatenate the mesh with another mesh.
|
|
|
|
Parameters
|
|
------------
|
|
other : trimesh.Trimesh object
|
|
Mesh to be concatenated with self
|
|
|
|
Returns
|
|
----------
|
|
concat : trimesh.Trimesh
|
|
Mesh object of combined result
|
|
"""
|
|
concat = util.concatenate(self, other)
|
|
return concat
|