Mesh2D¶

from mcot.surface.mesh import Mesh2D

class mcot.surface.mesh.Mesh2D(vertices, faces, flip_normal=False)[source]¶

Triangular mesh object describing a 2-dimensional surface in M-dimensional space.

__init__(vertices, faces, flip_normal=False)[source]¶

Defines a triangular mesh in M-dimensional space.

Parameters

vertices – (M, N) array with the vertices of the curve in M-dimensional space.
faces – (3, K) index array with all the faces.
flip_normal – flips the normal when it is computed (used by Mesh2D.apply_affine, do not set this)

Inheritance diagram

Methods

`apply_affine`(affine)	Returns a new Mesh to which the affine transformation as been applied.
`as_temp_file`()	Returns the filename of a temporary .surf.gii file containing this mesh.
`clean`()	Returns a clean mesh.
`closed`()	Check if the mesh is closed (i.e.
`closest_vertex`(points)	Finds the closest vertices on the surface for a bunch of vertices.
`connected_components`()	Returns a tuple with (number of connected components, labeling of connected components).
`find_intersections`(position, orientation[, …])	Finds a ray intersection with the surface.
`gradient`(scalar[, atpoint])	Computes the gradient orientations of a scalar across the surface.
`graph_connection_connection`([weight, dtype])	Converts the mesh into a graph, where the nodes are the faces and the edges are between those faces sharing vertices.
`graph_connection_point`([dtype])	Returns the interactions between vertices and faces as a sparse matrix.
`graph_point_point`([weight, dtype, …])	Converts the mesh into a graph describing the edges between the individual vertices (nodes).
`inflate`([shift, volume])	Increases with the given shift or volume.
`neighbour_faces`()	Find the neighbouring faces.
`normal`([atpoint])	Calculates the normal of every connection.
`plane_projection`([position, orientation])	Returns list of ProjectedMesh of the surface projected onto a plane.
`read`(gifti_filename)	Reads a surface from a surface gifti file (i.e.
`render`([color, opacity, view, axes_scale, …])	Plots the mesh on the provided vtkRenderWindow.
`size_faces`()	Compute the size of the faces in the mesh.
`size_vertices`()	Attributes the size of the faces to the vertices they connect.
`smooth`(nsteps[, smooth_step, expand_step])	Smoothing algorithm with rough volume preservation.
`split_mask`(mask)	Splits a mask into contiguous surface patches.
`surface_edge_distance`([use, method, …])	Returns a matrix of the shortest distances across the edges connecting the vertices.
`to_vtk_actor`([color, opacity])	Returns a vtkPolyDataActor mapping the mesh to an actor, that can plot the mesh.
`to_vtk_mapper`([color])	Returns a vtkPolyDataMapper mapping the mesh to an object ready for plotting.
`to_vtk_polydata`([color])	Returns a vtk.vtkPolyData object with the mesh.
`volume`()	Returns the signed volume of the mesh.
`write`(gifti_filename[, scalar_arr])	Writes a surface to a surface gifti file.

Attributes

`faces`
`ndim`	Dimensionality of the embedding space.
`nfaces`	Number of surface elements connecting the vertices.
`nvertices`	Number of vertices on the mesh.
`tree`	A KD tree used to compute the distance between the vertices defining the surface and any other vertices.
`vertices`

apply_affine¶

Mesh2D.apply_affine(affine)[source]¶

Returns a new Mesh to which the affine transformation as been applied.

Parameters: affine – (4, 4) array defining the voxel->mm transformation (i.e. the transformation TOWARDS the space the surface is defined in)
Returns: new Mesh in the origin space of the affine transformation
Rtype Mesh2D

as_temp_file¶

Mesh2D.as_temp_file()[source]¶

Returns the filename of a temporary .surf.gii file containing this mesh.

The user is responsible for deleting this file after use.

clean¶

Mesh2D.clean()[source]¶

Returns a clean mesh.

Merges duplicate vertices
Remove isolated vertices

closed¶

Mesh2D.closed()[source]¶

Check if the mesh is closed (i.e. every line connecting two vertices is used in zero or at least 2 faces).

Return type: bool

closest_vertex¶

Mesh2D.closest_vertex(points)¶

Finds the closest vertices on the surface for a bunch of vertices.

Parameters

points – (ndim, nvertices) array with the reference vertices

Returns

tuple with

(nvertices, ) distance array
(nvertices, ) index array

connected_components¶

Mesh2D.connected_components()¶: Returns a tuple with (number of connected components, labeling of connected components).

find_intersections¶

Mesh2D.find_intersections(position, orientation, return_position=False)[source]¶

Finds a ray intersection with the surface.

If many ray intersections are required grid.GridSurfaceIntersection.ray_intersect will be much faster

Parameters

position – (M, ) array with the starting point of the ray
orientation – (M, ) array with the hemisphere of the ray
return_position – if True returns the position of the intersection in addition to a boolean indicating whether there is one

Returns

boolean indicating whether there is an intersection (as well as the position of the intersection if return_position is set to True)

gradient¶

Mesh2D.gradient(scalar, atpoint=False)[source]¶

Computes the gradient orientations of a scalar across the surface.

Parameters

scalar – (K, ) array with value of scalar function for every point on the surface.
atpoint – if set interpolate the gradients from the vertices to the vertices.

Returns

(3, N) array with the gradient for all N vertices.

graph_connection_connection¶

Mesh2D.graph_connection_connection(weight=None, dtype='bool')¶

Converts the mesh into a graph, where the nodes are the faces and the edges are between those faces sharing vertices.

Parameters

weight – Weights the boundaries by the distance between the connection centers if set to “distance”
dtype – datatype of the resulting sparse matrix (only used if weight is None)

Returns

(N, N) sparse matrix for N faces, which is one (or the value set by weight) if the faces share a vertex.

graph_connection_point¶

Mesh2D.graph_connection_point(dtype='bool')¶

Returns the interactions between vertices and faces as a sparse matrix.

The resulting matrix can be used to multiply a vector of size M faces to get a vector of size N vertices.

The result of this method is cached in _graph (set _graph to None to re-compute the graph).

Parameters: dtype – data type of the resulting sparse matrix
Returns: (N, M) sparse matrix for N vertices and M faces, which is one if connection M interacts with N.

graph_point_point¶

Mesh2D.graph_point_point(weight=None, dtype='bool', include_diagonal=True)¶

Converts the mesh into a graph describing the edges between the individual vertices (nodes).

Parameters

weight – Weights the boundaries by the distance between the vertices if set to “distance”
dtype – datatype of the resulting sparse matrix (only used if weight is None)
include_diagonal – if set to False exclude the diagonal from the sparse matrix

Returns

(N, N) sparse matrix for N vertices, which is one (or the value set by weight) if the vertices are connected.

inflate¶

Mesh2D.inflate(shift=None, volume=None)[source]¶

Increases with the given shift or volume.

Moves each vertex to get the requested volume decrease/increase

Parameters

shift – shift of each vertex in mm
volume – increase in volume in mm^3 (can be negative)

Returns

new surface

neighbour_faces¶

Mesh2D.neighbour_faces()[source]¶

Find the neighbouring faces.

Returns: (3, N) array with for all N faces the indices of the neighbours (padded with -1 if there are less than 3 neighbours).

normal¶

Mesh2D.normal(atpoint=False)[source]¶

Calculates the normal of every connection.

The result of this method is cached in _normal (set to None to re-compute the normals).

Parameters: atpoint – interpolates the normals from the vertices to the vertices (as defined by Freesurfer: https://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurferWiki/SurfaceNormal)
Returns: (Nvertex, 3) (or (Npoint, 3) if atpoint is set) array with the normals

plane_projection¶

Mesh2D.plane_projection(position=(0, 0, 0), orientation=(0, 0, 1))[source]¶

Returns list of ProjectedMesh of the surface projected onto a plane.

Parameters

position – origin of the plane on which the ProjectedMesh will be defined
orientation – normal of the plane on which the ProjectedMesh will be defined

Returns

Each of the ProjectedMesh describes an isolated intersection

Return type

List[ProjectedMesh]

read¶

classmethod Mesh2D.read(gifti_filename)[source]¶

Reads a surface from a surface gifti file (i.e. ending with.

.surf.gii).

If you want to store the cortical information with the cortical mesh use cortical_mesh.CorticalMesh.read

Parameters: gifti_filename – input filename

render¶

Mesh2D.render(color=None, opacity=1.0, view='+x', axes_scale=0.0, filename=None, window=None, renderer=None, interact=True)[source]¶

Plots the mesh on the provided vtkRenderWindow.

Parameters

color – (N, 3) or (N, ) array defining the color across the mesh
opacity – float setting the opacity of the surface
view –
where the object is viewed from; one of ‘+x’, ‘-x’, ‘+y’, ‘-y’, ‘+z’, or ‘-z’ or tuple with
- vector pointing from the mesh center to the camera
- vector defining the hemisphere that is up from the camera
filename – if set saves the image to the given filename
window (vtk.vtkRenderWindow) – If provded the window on which the mesh will be plotted (otherwise a new window is created)
renderer (vtk.vtkRenderer) – the VTK rendered to which the actor plotting the mesh will be added (default: a new one is created)
interact – if True allows interaction of the window (this will pause the evaulation)

Returns

the window the mesh is plotted on and the rendered doing the plotting

Return type

(vtk.vtkRenderWindow, vtk.vtkRenderer)

size_faces¶

Mesh2D.size_faces()[source]¶

Compute the size of the faces in the mesh.

Returns: (3, K) array for K faces

size_vertices¶

Mesh2D.size_vertices()¶: Attributes the size of the faces to the vertices they connect.

smooth¶

Mesh2D.smooth(nsteps, smooth_step=0.5, expand_step=None)[source]¶

Smoothing algorithm with rough volume preservation.

Implements the algorithm from Rypl and Nerad, “VOLUME CONSERVATION OF 3D SURFACE TRIANGULAR MESH SMOOTHING.” See https://pdfs.semanticscholar.org/2c88/01e50f5ecf0035e8c2bdca7976a3a5d45ee8.pdf . This algorithm iterates between smoothing steps and expansion steps with the expansion step sizes determined by the local curvature as to preserve the local volume.

Parameters

nsteps – number of smoothing steps
smooth_step – How much the smoothing step moves the vertex to the mean of the neighbour (between 0 and 1)
expand_step – How much the expansion step moves the vertex back out (default: enough to roughly preserve volume)

Returns

new smooth mesh

split_mask¶

Mesh2D.split_mask(mask)[source]¶

Splits a mask into contiguous surface patches.

Parameters: mask – (N, ) boolean array which is True for any vertices in the mask
Returns: (N, ) integer array with labels for any point on the mask (-1 for vertices outside of the mask)

surface_edge_distance¶

Mesh2D.surface_edge_distance(use=None, method='auto', return_predecessors=False, use_connections=False)¶

Returns a matrix of the shortest distances across the edges connecting the vertices.

This is an upper limit to the true distance across the surface, because the path is limited to following the edges of the triangular mesh.

This is a wrapper around scipy.sparse.csgraph.shortest_path.

Parameters

use – boolean array indicating which vertices or faces to use (default: use all)
method – method used by scipy.sparse.csgraph.shortest_path.
return_predecessors – whether to return the (N, N) predecessor matrix
use_connections – compute the shortest distance between the faces rather than the vertices.

Returns

(N, N) matrix of shortest distances across the graph

to_vtk_actor¶

Mesh2D.to_vtk_actor(color=None, opacity=1)[source]¶

Returns a vtkPolyDataActor mapping the mesh to an actor, that can plot the mesh.

Parameters: color – (N, 3) or (N, ) array defining the color across the mesh
Return type: vtk.vtkActor

to_vtk_mapper¶

Mesh2D.to_vtk_mapper(color=None)[source]¶

Returns a vtkPolyDataMapper mapping the mesh to an object ready for plotting.

Parameters: color – (N, 3) or (N, ) array defining the color across the mesh
Return type: vtk.vtkPolyDataMapper

to_vtk_polydata¶

Mesh2D.to_vtk_polydata(color=None)[source]¶

Returns a vtk.vtkPolyData object with the mesh.

Parameters: color – (3, N) or (N, ) array defining the color across the mesh
Return type: vtk.vtkPolyData

volume¶

Mesh2D.volume()[source]¶: Returns the signed volume of the mesh.

write¶

Mesh2D.write(gifti_filename, scalar_arr=None, **kwargs)[source]¶

Writes a surface to a surface gifti file.

Parameters

gifti_filename – output filename
scalar_arr – optionally include a scalar array with same length as number of vertices (as expected by FSL’s probtrackX)
kwargs – any keywords are added to the meta information in the GIFTI file

Mesh2D¶

apply_affine¶

as_temp_file¶

clean¶

closed¶

closest_vertex¶

connected_components¶

find_intersections¶

gradient¶

graph_connection_connection¶

graph_connection_point¶

graph_point_point¶

inflate¶

neighbour_faces¶

normal¶

plane_projection¶

read¶

render¶

size_faces¶

size_vertices¶

smooth¶

split_mask¶

surface_edge_distance¶

to_vtk_actor¶

to_vtk_mapper¶

to_vtk_polydata¶

volume¶

write¶

mcot

Navigation

Related Topics