fsl.data.mesh
¶
This module provides the Mesh
class, which represents a
3D model made of triangles.
See also the following modules:
This module provides the
VTKMesh
class, for loading triangle meshes from VTK files.This class provides classes and functions for working with GIFTI files.
This module provides the
FreesurferMesh
class, which can be used for loading Freesurfer geometry and vertex data files.
A handful of standalone functions are provided in this module, for doing various things with meshes:
Calculates face normals for the mesh described by
vertices
andindices
.Calculates vertex normals for the mesh described by
vertices
andindices
.Determines whether the triangle winding order, for the mesh described by
vertices
andindices
, needs to be flipped.
-
class
fsl.data.mesh.
Mesh
(indices, name='mesh', dataSource=None, vertices=None, fixWinding=False)[source]¶ Bases:
fsl.utils.notifier.Notifier
,fsl.utils.meta.Meta
The
Mesh
class represents a 3D model. A mesh is defined by a collection ofN
vertices, andM
triangles. The triangles are defined by(M, 3)
indices into the list of vertices.A
Mesh
instance has the following attributes:name
A name, typically the file name sans-suffix.
dataSource
Full path to the mesh file (or
None
if there is no file associated with this mesh).nvertices
The number of vertices in the mesh.
vertices
A
(n, 3)
array containing the currently selected vertices. You can assign a vertex set key to this attribute to change the selected vertex set.bounds
The lower and upper bounds
indices
A
(m, 3)
array containing the vertex indices form
trianglesnormals
A
(m, 3)
array containing face normals for the trianglesvnormals
A
(n, 3)
array containing vertex normals for the the current vertices.trimesh
(if the trimesh library is present) A
trimesh.Trimesh
object which can be used for geometric queries on the mesh.Vertex sets
A
Mesh
object can be associated with multiple sets of vertices, but only one set of triangles. Vertices can be added via theaddVertices()
method. Each vertex set must be associated with a unique key - you can then select the current vertex set via thevertices()
property. MostMesh
methods will raise aKeyError
if you have not added any vertex sets, or selected a vertex set. The following methods are available for managing vertex sets:Loads vertex data from the given
infile
, and adds it as a vertex set with the givenkey
.Adds a set of vertices to this
Mesh
.Returns the key of the currently selected vertex set.
Returns a list containing the keys of all vertex sets.
Note
Internally the
Mesh
class may store two versions of the triangles, with opposite unwinding orders. It keeps track of the required triangle unwinding order for each vertex set, so that theindices()
method will return the appropriate copy for the currently selected vertex set.Vertex data
A
Mesh
object can store vertex-wise data. The following methods can be used for adding/retrieving vertex data:Loads vertex-wise data from the given
infile
, and adds it with the givenkey
.Adds a vertex-wise data set to the
Mesh
.Returns the vertex data for the given
key
from the internal vertex data cache.Returns a list of keys for all loaded vertex data sets.
Clears the internal vertex data cache - see the
addVertexData()
andgetVertexData()
methods.Notification
The
Mesh
class inherits from theNotifier
class. Whenever theMesh
vertex set is changed, a notification is emitted via theNotifier
interface, with a topic of'vertices'
. When this occurs, thevertices()
,bounds()
,normals()
andvnormals
properties will all change so that they return data specific to the newly selected vertex set.Metadata
The
Mesh
class also inherits from theMeta
class, so any metadata associated with theMesh
may be added via those methods.Geometric queries
If the
trimesh
library is present, the following methods may be used to perform geometric queries on a mesh:Calculate the intersection between the mesh, and the rays defined by
origins
anddirections
.Calculate the intersection of this
TriangleMesh
with the plane defined bynormal
andorigin
.Identifies the nearest vertex to each of the provided points.
-
property
name
¶ Returns the name of this
Mesh
.
-
property
dataSource
¶ Returns the data source of this
Mesh
.
-
property
nvertices
¶ Returns the number of vertices in the mesh.
-
property
vertices
¶ The
(N, 3)
vertices of this mesh.
-
property
indices
¶ The
(M, 3)
triangles of this mesh.
-
property
normals
¶ A
(M, 3)
array containing surface normals for every triangle in the mesh, normalised to unit length.
-
property
vnormals
¶ A
(N, 3)
array containing normals for every vertex in the mesh.
-
property
bounds
¶ Returns a tuple of values which define a minimal bounding box that will contain all of the currently selected vertices in this
Mesh
instance. The bounding box is arranged like so:((xlow, ylow, zlow), (xhigh, yhigh, zhigh))
-
loadVertices
(infile, key=None, **kwargs)[source]¶ Loads vertex data from the given
infile
, and adds it as a vertex set with the givenkey
. This implementation supports loading vertex data from white-space delimited text files vianumpy.loadtxt
, but sub-classes may override this method to support additional file types.- Parameters
infile – File to load data from.
key – Key to pass to
addVertices()
. If not provided, set toinfile
(converted to an absolute path)
All of the other arguments are passed through to
addVertices()
.- Returns
The loaded vertices.
-
addVertices
(vertices, key=None, select=True, fixWinding=False)[source]¶ Adds a set of vertices to this
Mesh
.- Parameters
vertices – A (n, 3) array containing
n
vertices, compatible with the indices specified in__init__()
.key – A key for this vertex set. If
None
defaults to'default'
.select – If
True
(the default), this vertex set is made the currently selected vertex set.fixWinding – Defaults to
False
. IfTrue
, the vertex winding order of every triangle is is fixed so they all have outward-facing normal vectors.
- Returns
The vertices, possibly reshaped
- Raises
ValueError
if the providedvertices
array has the wrong number of vertices.
-
loadVertexData
(infile, key=None)[source]¶ Loads vertex-wise data from the given
infile
, and adds it with the givenkey
. This implementation supports loading data from whitespace-delimited text files vianumpy.loadtxt
, but sub-classes may override this method to support additional file types.- Parameters
infile – File to load data from.
key – Key to pass to
addVertexData()
. If not provided, set toinfile
(converted to an absolute path)
- Returns
The loaded vertex data.
-
addVertexData
(key, vdata)[source]¶ Adds a vertex-wise data set to the
Mesh
. It can be retrieved by passing the specifiedkey
to thegetVertexData()
method.- Returns
The vertex data, possibly reshaped.
-
getVertexData
(key)[source]¶ Returns the vertex data for the given
key
from the internal vertex data cache. If there is no vertex data iwth the given key, aKeyError
is raised.
-
clearVertexData
()[source]¶ Clears the internal vertex data cache - see the
addVertexData()
andgetVertexData()
methods.
-
property
trimesh
¶ Reference to a
trimesh.Trimesh
object which can be used for geometric operations on the mesh.If the
trimesh
orrtree
libraries are not available, this function returnsNone
, and none of the geometric query methods will do anything.
-
rayIntersection
(origins, directions, vertices=False)[source]¶ Calculate the intersection between the mesh, and the rays defined by
origins
anddirections
.- Parameters
origins – Sequence of ray origins
directions – Sequence of ray directions
- Returns
A tuple containing:
A
(n, 3)
array containing the coordinates where the mesh was intersected by each of then
rays.A
(n,)
array containing the indices of the triangles that were intersected by each of then
rays.
-
nearestVertex
(points)[source]¶ Identifies the nearest vertex to each of the provided points.
- Parameters
points – A
(n, 3)
array containing the points to query.- Returns
A tuple containing:
A
(n, 3)
array containing the nearest vertex for for each of then
input points.A
(n,)
array containing the indices of each vertex.A
(n,)
array containing the distance from each point to the nearest vertex.
-
planeIntersection
(normal, origin, distances=False)[source]¶ Calculate the intersection of this
TriangleMesh
with the plane defined bynormal
andorigin
.- Parameters
normal – Vector defining the plane orientation
origin – Point defining the plane location
distances – If
True
, barycentric coordinates for each intersection line vertex are calculated and returned, giving their respective distance from the intersected triangle vertices.
- Returns
A tuple containing
A
(m, 2, 3)
array containingm
vertices: of a set of lines, defining the plane intersectionA
(m,)
array containing the indices of them
triangles that were intersected.(if
distances is True
) A(m, 2, 3)
array containing the barycentric coordinates of each line vertex with respect to its intersected triangle.
-
property
-
fsl.data.mesh.
calcFaceNormals
(vertices, indices)[source]¶ Calculates face normals for the mesh described by
vertices
andindices
.- Parameters
vertices – A
(n, 3)
array containing the mesh vertices.indices – A
(m, 3)
array containing the mesh triangles.
- Returns
A
(m, 3)
array containing normals for every triangle in the mesh.
-
fsl.data.mesh.
calcVertexNormals
(vertices, indices, fnormals)[source]¶ Calculates vertex normals for the mesh described by
vertices
andindices
.- Parameters
vertices – A
(n, 3)
array containing the mesh vertices.indices – A
(m, 3)
array containing the mesh triangles.fnormals – A
(m, 3)
array containing the face/triangle normals.
- Returns
A
(n, 3)
array containing normals for every vertex in the mesh.
-
fsl.data.mesh.
needsFixing
(vertices, indices, fnormals, loBounds, hiBounds)[source]¶ Determines whether the triangle winding order, for the mesh described by
vertices
andindices
, needs to be flipped.If this function returns
True
, the givenindices
andfnormals
need to be adjusted so that all face normals are facing outwards from the centre of the mesh. The necessary adjustments are as follows:indices[:, [1, 2]] = indices[:, [2, 1]] fnormals = fnormals * -1
- Parameters
vertices – A
(n, 3)
array containing the mesh vertices.indices – A
(m, 3)
array containing the mesh triangles.fnormals – A
(m, 3)
array containing the face/triangle normals.loBounds – A
(3, )
array contaning the low vertex bounds.hiBounds – A
(3, )
array contaning the high vertex bounds.
- Returns
True
if theindices
andfnormals
need to be adjusted,False
otherwise.