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 case faces 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`()	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`([maxhulls])	Compute an approximate convex decomposition of a mesh.
`copy`([include_cache])	Safely return a copy of the current mesh.
`crc`()	DEPRECATED OCTOBER 2023 : Use hash(geometry)
`difference`(other[, engine])	Boolean difference between this mesh and n other meshes
`eval_cached`(statement, *args)	Evaluate a statement and cache the result before returning.
`export`([file_obj, file_type])	Export the current mesh to a file object.
`fill_holes`()	Fill single triangle and single quad holes in the current mesh.
`fix_normals`(**kwargs)	Find and fix problems with self.face_normals and self.faces winding direction.
`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.
`hash`()	DEPRECATED OCTOBER 2023 : Use hash(geometry)
`intersection`(other[, engine])	Boolean intersection between this mesh and n other meshes
`invert`()	Invert the mesh in-place by reversing the winding of every face and negating normals without dumping the cache.
`md5`()	DEPRECATED OCTOBER 2023 : Use hash(geometry)
`merge_vertices`([merge_tex, merge_norm, ...])	Removes duplicate vertices grouped by position and optionally texture coordinate and normal.
`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])	Remove degenerate faces (faces without 3 unique vertex indices) from the current mesh.
`remove_duplicate_faces`()	On the current mesh remove any faces which are duplicates.
`remove_infinite_values`()	Ensure that every vertex and face consists of finite numbers.
`remove_unreferenced_vertices`()	Remove all vertices in the current mesh which are not referenced by a face.
`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)	Return a version of the current mesh which will render nicely, without changing source mesh.
`split`(**kwargs)	Returns a list of Trimesh objects, based on face connectivity.
`subdivide`([face_index])	Subdivide a mesh, with each subdivided face replaced with four smaller faces.
`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
`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.
`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.
`identifier_md5`
`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.
`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.
`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.