CorticalMesh

from mcot.surface.cortical_mesh import CorticalMesh
class mcot.surface.cortical_mesh.CorticalMesh(vertices, faces, flip_normal=False, anatomy=None)[source]

Describes a cortical mesh of a brain region.

Besides all the normal mesh operations defined in mesh.Mesh2D this object also contains information about the brain structure in the anatomy attribute This information is stored/used when reading/writing the file.

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

Creates a new CorticalMesh.

Parameters

  • vertices – (M, N) array with the vertices of the curve in M-dimensional space.

  • faces – (2, K) index array with all the line segments.

  • flip_normal – flips the normal when it is computed (used by mesh.Mesh2D.apply_affine(), should normally not be used)

  • anatomy (BrainStructure) – Describes which brain structure this cortical mesh represents

Inheritance diagram

digraph inheritanced7459674d1 { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "mcot.surface.cortical_mesh.CorticalMesh" [URL="#mcot.surface.cortical_mesh.CorticalMesh",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Describes a cortical mesh of a brain region."]; "mcot.surface.mesh.Mesh2D" -> "mcot.surface.cortical_mesh.CorticalMesh" [arrowsize=0.5,style="setlinewidth(0.5)"]; "mcot.surface.mesh.Mesh" [URL="mcot.surface.mesh.Mesh.html#mcot.surface.mesh.Mesh",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="General mesh object."]; "mcot.surface.mesh.Mesh2D" [URL="mcot.surface.mesh.Mesh2D.html#mcot.surface.mesh.Mesh2D",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Triangular mesh object describing a 2-dimensional surface in"]; "mcot.surface.mesh.Mesh" -> "mcot.surface.mesh.Mesh2D" [arrowsize=0.5,style="setlinewidth(0.5)"]; }

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 cortical mesh 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 cortical mesh to a gifti file (i.e.

write_metric(filename, arr_list[, intent_list])

Writes list-like of AxisArrays as a 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

CorticalMesh.apply_affine(affine)

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

CorticalMesh.as_temp_file()

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

The user is responsible for deleting this file after use.

clean

CorticalMesh.clean()

Returns a clean mesh.

  1. Merges duplicate vertices

  2. Remove isolated vertices

closed

CorticalMesh.closed()

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

CorticalMesh.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

CorticalMesh.connected_components()

Returns a tuple with (number of connected components, labeling of connected components).

find_intersections

CorticalMesh.find_intersections(position, orientation, return_position=False)

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

CorticalMesh.gradient(scalar, atpoint=False)

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

CorticalMesh.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

CorticalMesh.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

CorticalMesh.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

CorticalMesh.inflate(shift=None, volume=None)

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

CorticalMesh.neighbour_faces()

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

CorticalMesh.normal(atpoint=False)

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

CorticalMesh.plane_projection(position=(0, 0, 0), orientation=(0, 0, 1))

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 CorticalMesh.read(gifti_filename)[source]

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

.surf.gii).

Parameters

gifti_filename – input filename or Gifti image

render

CorticalMesh.render(color=None, opacity=1.0, view='+x', axes_scale=0.0, filename=None, window=None, renderer=None, interact=True)

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

CorticalMesh.size_faces()

Compute the size of the faces in the mesh.

Returns

(3, K) array for K faces

size_vertices

CorticalMesh.size_vertices()

Attributes the size of the faces to the vertices they connect.

smooth

CorticalMesh.smooth(nsteps, smooth_step=0.5, expand_step=None)

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

CorticalMesh.split_mask(mask)

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

CorticalMesh.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

CorticalMesh.to_vtk_actor(color=None, opacity=1)

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

CorticalMesh.to_vtk_mapper(color=None)

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

CorticalMesh.to_vtk_polydata(color=None)

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

CorticalMesh.volume()

Returns the signed volume of the mesh.

write

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

Writes a cortical mesh to a gifti file (i.e. ending with .surf.gii)

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

write_metric

CorticalMesh.write_metric(filename, arr_list, intent_list=None, **kwargs)[source]

Writes list-like of AxisArrays as a Gifti file.