fsl.data.mesh

This module provides the Mesh class, which represents a 3D model made of triangles.

See also the following modules:

fsl.data.vtk	This module provides the VTKMesh class, for loading triangle meshes from VTK files.
fsl.data.gifti	This class provides classes and functions for working with GIFTI files.
fsl.data.freesurfer	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:

calcFaceNormals	Calculates face normals for the mesh described by vertices and indices.
calcVertexNormals	Calculates vertex normals for the mesh described by vertices and indices.
needsFixing	Determines whether the triangle winding order, for the mesh described by vertices and indices, needs to be flipped.

exception fsl.data.mesh.IncompatibleVerticesError

Bases: ValueError

ValueError raised by the Mesh.addVertices() method if an attempt is made to add a vertex set with the wrong number of vertices.

__module__ = 'fsl.data.mesh'

__weakref__

list of weak references to the object (if defined)

class fsl.data.mesh.Mesh(*args, **kwargs)

Bases: Notifier, Meta

The Mesh class represents a 3D model. A mesh is defined by a collection of N vertices, and M 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 for m triangles
normals	A (m, 3) array containing face normals for the triangles
vnormals	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 the addVertices() method. Each vertex set must be associated with a unique key - you can then select the current vertex set via the vertices() property. Most Mesh methods will raise a KeyError if you have not added any vertex sets, or selected a vertex set. The following methods are available for managing vertex sets:

loadVertices	Loads vertex data from the given infile, and adds it as a vertex set with the given key.
addVertices	Adds a set of vertices to this Mesh.
selectedVertices	Returns the key of the currently selected vertex set.
vertexSets	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 the indices() 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:

loadVertexData	Loads vertex-wise data from the given infile, and adds it with the given key.
addVertexData	Adds a vertex-wise data set to the Mesh.
getVertexData	Returns the vertex data for the given key from the internal vertex data cache.
vertexDataSets	Returns a list of keys for all loaded vertex data sets.
clearVertexData	Clears the internal vertex data cache - see the addVertexData() and getVertexData() methods.

Notification

The Mesh class inherits from the Notifier class. Whenever the Mesh vertex set is changed, a notification is emitted via the Notifier interface, with a topic of 'vertices'. When this occurs, the vertices(), bounds(), normals() and vnormals properties will all change so that they return data specific to the newly selected vertex set.

Metadata

The Mesh class also inherits from the Meta class, so any metadata associated with the Mesh 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:

rayIntersection	Calculate the intersection between the mesh, and the rays defined by origins and directions.
planeIntersection	Calculate the intersection of this TriangleMesh with the plane defined by normal and origin.
nearestVertex	Identifies the nearest vertex to each of the provided points.

__init__(indices=None, name='mesh', dataSource=None, vertices=None, fixWinding=False)

Create a Mesh instance.

Before a Mesh can be used, some vertices must be added via the addVertices() method.

Parameters:

• indices – A list of indices into the vertex data, defining the mesh triangles. If not provided, must be provided after creation via the indices() setter method.

• name – A name for this Mesh.

• dataSource – The data source for this Mesh.

• vertices – Initial vertex set to add - given the key 'default'.

• fixWinding – Ignored if vertices is None. Passed through to the addVertices() method along with vertices.

__repr__()

Returns a string representation of this Mesh instance.

__str__()

Returns a string representation of this Mesh instance.

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. Returns None if indices have not yet been assigned.

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))

Returns None if indices or vertices have not yet been assigned.

loadVertices(infile, key=None, **kwargs)

Loads vertex data from the given infile, and adds it as a vertex set with the given key. This implementation supports loading vertex data from white-space delimited text files via numpy.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 to infile (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)

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. If True, the vertex winding order of every triangle is is fixed so they all have outward-facing normal vectors.

Returns:

The vertices, possibly reshaped

Raises:

IncompatibleVerticesError if the provided vertices array has the wrong number of vertices.

vertexSets()

Returns a list containing the keys of all vertex sets.

selectedVertices()

Returns the key of the currently selected vertex set.

loadVertexData(infile, key=None)

Loads vertex-wise data from the given infile, and adds it with the given key. This implementation supports loading data from whitespace-delimited text files via numpy.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 to infile (converted to an absolute path)

Returns:

The loaded vertex data.

addVertexData(key, vdata)

Adds a vertex-wise data set to the Mesh. It can be retrieved by passing the specified key to the getVertexData() method.

Returns:

The vertex data, possibly reshaped.

getVertexData(key)

Returns the vertex data for the given key from the internal vertex data cache. If there is no vertex data iwth the given key, a KeyError is raised.

clearVertexData()

Clears the internal vertex data cache - see the addVertexData() and getVertexData() methods.

vertexDataSets()

Returns a list of keys for all loaded vertex data sets.

property trimesh

Reference to a trimesh.Trimesh object which can be used for geometric operations on the mesh.

If the trimesh or rtree libraries are not available, this function returns None, and none of the geometric query methods will do anything.

rayIntersection(origins, directions, vertices=False)

Calculate the intersection between the mesh, and the rays defined by origins and directions.

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 the n rays.

• A (n,) array containing the indices of the triangles that were intersected by each of the n rays.

nearestVertex(points)

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 the n input points.

• A (n,) array containing the indices of each vertex.

• A (n,) array containing the distance from each point to the nearest vertex.

__annotations__ = {}

__module__ = 'fsl.data.mesh'

planeIntersection(normal, origin, distances=False)

Calculate the intersection of this TriangleMesh with the plane defined by normal and origin.

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 containing m vertices: of a set of lines, defining the plane intersection

• A (m,) array containing the indices of the m 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.

fsl.data.mesh.calcFaceNormals(vertices, indices)

Calculates face normals for the mesh described by vertices and indices.

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)

Calculates vertex normals for the mesh described by vertices and indices.

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)

Determines whether the triangle winding order, for the mesh described by vertices and indices, needs to be flipped.

If this function returns True, the given indices and fnormals 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 the indices and fnormals need to be adjusted, False otherwise.