navis.Volume¶
- class navis.Volume(vertices, faces=None, name=None, color=(0.85, 0.85, 0.85, 0.2), id=None, **kwargs)[source]¶
Mesh consisting of vertices and faces.
Subclass of
trimesh.Trimesh
with a few additional methods.- Parameters:
vertices (list | array | mesh-like) – (N, 3) vertices coordinates or an object that has
.vertices
and.faces
attributes in which casefaces
parameter will be ignored.faces (list | array) – (M, 3) array of indexed triangle faces.
name (str, optional) – A name for the volume.
color (tuple, optional) – RGB(A) color.
id (int, optional) – If not provided, neuron will be assigned a random UUID as
.id
.**kwargs – Keyword arguments passed through to
trimesh.Trimesh
See also
example_volume()
Loads example volume(s).
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
- __init__(vertices, faces=None, name=None, color=(0.85, 0.85, 0.85, 0.2), id=None, **kwargs)[source]¶
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
Methods
__init__
(vertices[, faces, name, color, id])A Trimesh object contains a triangular 3D mesh.
apply_obb
(**kwargs)Apply the oriented bounding box transform to the current mesh.
apply_scale
(scaling)Scale the mesh.
apply_transform
(matrix)Transform mesh by a homogeneous transformation matrix.
apply_translation
(translation)Translate the current mesh.
combine
(x[, name, color])Merge multiple volumes into a single object.
compute_stable_poses
([center_mass, sigma, ...])Computes stable orientations of a mesh and their quasi-static probabilities.
contains
(points)Given an array of points determine whether or not they are inside the mesh.
convert_units
(desired[, guess])Convert the units of the mesh into a specified unit.
convex_decomposition
(**kwargs)Compute an approximate convex decomposition of a mesh using pip install pyVHACD.
copy
([include_cache])Safely return a copy of the current mesh.
difference
(other[, engine])Boolean difference between this mesh and n other meshes
eval_cached
(statement, *args)Evaluate a statement and cache the result before returning.
export
([file_obj, file_type])Export the current mesh to a file object.
fill_holes
()Fill single triangle and single quad holes in the current mesh.
fix_normals
([multibody])Find and fix problems with self.face_normals and self.faces winding direction.
from_csv
(vertices, faces[, name, color, ...])Load volume from csv files containing vertices and faces.
from_file
(filename[, import_kwargs])Load volume from file.
from_json
(filename[, import_kwargs])Load volume from json file containing vertices and faces.
from_object
(obj, **init_kwargs)Load volume from generic object that has
.vertices
and.faces
attributes.intersection
(other[, engine])Boolean intersection between this mesh and n other meshes
invert
()Invert the mesh in-place by reversing the winding of every face and negating normals without dumping the cache.
merge_vertices
([merge_tex, merge_norm, ...])Removes duplicate vertices grouped by position and optionally texture coordinate and normal.
moment_inertia_frame
(transform)Get the moment of inertia of this mesh with respect to an arbitrary frame, versus with respect to the center of mass as returned by mesh.moment_inertia.
nondegenerate_faces
([height])Remove degenerate faces (faces without 3 unique vertex indices) from the current mesh.
outline
([face_ids])Given a list of face indexes find the outline of those faces and return it as a Path3D.
plot3d
(**kwargs)Plot volume using
navis.plot3d()
.process
([validate, merge_tex, merge_norm])Do processing to make a mesh useful.
projected
(normal, **kwargs)Project a mesh onto a plane and then extract the polygon that outlines the mesh projection on that plane.
register
(other, **kwargs)Align a mesh with another mesh or a PointCloud using the principal axes of inertia as a starting point which is refined by iterative closest point.
remove_degenerate_faces
([height])DERECATED MARCH 2024 REPLACE WITH: self.update_faces(self.nondegenerate_faces(height=height))
remove_duplicate_faces
()DERECATED MARCH 2024 REPLACE WITH: mesh.update_faces(mesh.unique_faces())
remove_infinite_values
()Ensure that every vertex and face consists of finite numbers.
remove_unreferenced_vertices
()Remove all vertices in the current mesh which are not referenced by a face.
resize
(x[, method, inplace])Resize volume.
rezero
()Translate the mesh so that all vertex vertices are positive.
sample
(count[, return_index, face_weight])Return random samples distributed across the surface of the mesh
scene
(**kwargs)Returns a Scene object containing the current mesh.
section
(plane_normal, plane_origin, **kwargs)Returns a 3D cross section of the current mesh and a plane defined by origin and normal.
section_multiplane
(plane_origin, ...)Return multiple parallel cross sections of the current mesh in 2D.
show
(**kwargs)See
.plot3d
.simplify_quadratic_decimation
(*args, **kwargs)DERECATED MARCH 2024 REPLACE WITH: mesh.simplify_quadric_decimation
simplify_quadric_decimation
(face_count)A thin wrapper around the open3d implementation of this: open3d.geometry.TriangleMesh.simplify_quadric_decimation
slice_plane
(plane_origin, plane_normal[, ...])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
smoothed
(**kwargs)DEPRECATED: use mesh.smooth_shaded or trimesh.graph.smooth_shade(mesh)
split
(**kwargs)Returns a list of Trimesh objects, based on face connectivity.
subdivide
([face_index])Subdivide a mesh, with each subdivided face replaced with four smaller faces.
subdivide_loop
([iterations])Subdivide a mesh by dividing each triangle into four triangles and approximating their smoothed surface using loop subdivision.
subdivide_to_size
(max_edge[, max_iter, ...])Subdivide a mesh until every edge is shorter than a specified length.
submesh
(faces_sequence, **kwargs)Return a subset of the mesh.
to_2d
([alpha, view, invert_y])Compute the 2d alpha shape (concave hull) this volume.
to_csv
(filename, **kwargs)Save volume as two separated csv files containing vertices and faces.
to_dict
()Return a dictionary representation of the current mesh with keys that can be used as the kwargs for the Trimesh constructor and matches the schema in: trimesh/resources/schema/primitive/trimesh.schema.json
to_json
(filename)Save volume as json file.
union
(other[, engine])Boolean union between this mesh and n other meshes
unique_faces
()On the current mesh find which faces are unique.
unmerge_vertices
()Removes all face references so that every face contains three unique vertex indices and no faces are adjacent.
unwrap
([image])Returns a Trimesh object equivalent to the current mesh where the vertices have been assigned uv texture coordinates.
update_faces
(mask)In many cases, we will want to remove specific faces.
update_vertices
(mask[, inverse])Update vertices with a mask.
validate
()Use trimesh to try and fix issues (holes/normals).
voxelized
(pitch[, method])Return a VoxelGrid object representing the current mesh discretized into voxels at the specified pitch
Attributes
area
Summed area of all triangles in the current mesh.
area_faces
The area of each face in the mesh.
as_open3d
Return an open3d.geometry.TriangleMesh version of the current mesh.
bbox
Bounding box of this volume.
body_count
How many connected groups of vertices exist in this mesh.
bounding_box
An axis aligned bounding box for the current mesh.
bounding_box_oriented
An oriented bounding box for the current mesh.
bounding_cylinder
A minimum volume bounding cylinder for the current mesh.
bounding_primitive
The minimum volume primitive (box, sphere, or cylinder) that bounds the mesh.
bounding_sphere
A minimum volume bounding sphere for the current mesh.
bounds
The axis aligned bounds of the faces of the mesh.
center
Center of mass.
center_mass
The point in space which is the center of mass/volume.
centroid
The point in space which is the average of the triangle centroids weighted by the area of each triangle.
color
Color used for plotting.
convex_hull
Returns a Trimesh object representing the convex hull of the current mesh.
density
The density of the mesh used in inertia calculations.
edges
Edges of the mesh (derived from faces).
edges_face
Which face does each edge belong to.
edges_sorted
Edges sorted along axis 1
edges_sorted_tree
A KDTree for mapping edges back to edge index.
edges_sparse
Edges in sparse bool COO graph format where connected vertices are True.
edges_unique
The unique edges of the mesh.
edges_unique_inverse
Return the inverse required to reproduce self.edges_sorted from self.edges_unique.
edges_unique_length
How long is each unique edge.
euler_number
Return the Euler characteristic (a topological invariant) for the mesh In order to guarantee correctness, this should be called after remove_unreferenced_vertices
extents
The length, width, and height of the axis aligned bounding box of the mesh.
face_adjacency
Find faces that share an edge i.e. 'adjacent' faces.
face_adjacency_angles
Return the angle between adjacent faces
face_adjacency_convex
Return faces which are adjacent and locally convex.
face_adjacency_edges
Returns the edges that are shared by the adjacent faces.
face_adjacency_edges_tree
A KDTree for mapping edges back face adjacency index.
face_adjacency_projections
The projection of the non-shared vertex of a triangle onto its adjacent face
face_adjacency_radius
The approximate radius of a cylinder that fits inside adjacent faces.
face_adjacency_span
The approximate perpendicular projection of the non-shared vertices in a pair of adjacent faces onto the shared edge of the two faces.
face_adjacency_tree
An R-tree of face adjacencies.
face_adjacency_unshared
Return the vertex index of the two vertices not in the shared edge between two adjacent faces
face_angles
Returns the angle at each vertex of a face.
face_angles_sparse
A sparse matrix representation of the face angles.
face_neighborhood
Find faces that share a vertex i.e. 'neighbors' faces.
face_normals
Return the unit normal vector for each face.
faces
The faces of the mesh.
faces_sparse
A sparse matrix representation of the faces.
faces_unique_edges
For each face return which indexes in mesh.unique_edges constructs that face.
facets
Return a list of face indices for coplanar adjacent faces.
facets_area
Return an array containing the area of each facet.
facets_boundary
Return the edges which represent the boundary of each facet
facets_normal
Return the normal of each facet
facets_on_hull
Find which facets of the mesh are on the convex hull.
facets_origin
Return a point on the facet plane.
id
ID of this volume.
identifier
Return a float vector which is unique to the mesh and is robust to rotation and translation.
identifier_hash
A hash of the rotation invariant identifier vector.
integral_mean_curvature
The integral mean curvature, or the surface integral of the mean curvature.
is_convex
Check if a mesh is convex or not.
is_empty
Does the current mesh have data defined.
is_volume
Check if a mesh has all the properties required to represent a valid volume, rather than just a surface.
is_watertight
Check if a mesh is watertight by making sure every edge is included in two faces.
is_winding_consistent
Does the mesh have consistent winding or not.
kdtree
Return a scipy.spatial.cKDTree of the vertices of the mesh.
mass
Mass of the current mesh, based on specified density and volume.
mass_properties
Returns the mass properties of the current mesh.
moment_inertia
Return the moment of inertia matrix of the current mesh.
mutable
Is the current mesh allowed to be altered in-place?
name
Name of this volume.
principal_inertia_components
Return the principal components of inertia
principal_inertia_transform
A transform which moves the current mesh so the principal inertia vectors are on the X,Y, and Z axis, and the centroid is at the origin.
principal_inertia_vectors
Return the principal axis of inertia as unit vectors.
referenced_vertices
Which vertices in the current mesh are referenced by a face.
scale
A metric for the overall scale of the mesh, the length of the diagonal of the axis aligned bounding box of the mesh.
smooth_shaded
Smooth shading in OpenGL relies on which vertices are shared, this function will disconnect regions above an angle threshold and return a non-watertight version which will look better in an OpenGL rendering context.
symmetry
Check whether a mesh has rotational symmetry around an axis (radial) or point (spherical).
symmetry_axis
If a mesh has rotational symmetry, return the axis.
symmetry_section
If a mesh has rotational symmetry return the two vectors which make up a section coordinate frame.
triangles
Actual triangles of the mesh (points, not indexes)
triangles_center
The center of each triangle (barycentric [1/3, 1/3, 1/3])
triangles_cross
The cross product of two edges of each triangle.
triangles_tree
An R-tree containing each face of the mesh.
units
Definition of units for the mesh.
vertex_adjacency_graph
Returns a networkx graph representing the vertices and their connections in the mesh.
vertex_defects
Return the vertex defects, or (2*pi) minus the sum of the angles of every face that includes that vertex.
vertex_degree
Return the number of faces each vertex is included in.
vertex_faces
A representation of the face indices that correspond to each vertex.
vertex_neighbors
The vertex neighbors of each vertex of the mesh, determined from the cached vertex_adjacency_graph, if already existent.
vertex_normals
The vertex normals of the mesh.
vertices
The vertices of the mesh.
verts
Legacy access to
.vertices
.visual
Get the stored visuals for the current mesh.
volume
Volume of the current mesh calculated using a surface integral.