class cortex.polyutils.Surface(pts, polys)[source]

Represents a single cortical hemisphere surface. Can be the white matter surface, pial surface, fiducial (mid-cortical) surface, inflated surface, flattened surface, etc.

Implements some useful functions for dealing with functions across surfaces.

pts2D ndarray, shape (total_verts, 3)

Location of each vertex in space (mm). Order is x, y, z.

polys2D ndarray, shape (total_polys, 3)

Indices of the vertices in each triangle in the surface.


__init__(self, pts, polys)

Initialize self.

approx_geodesic_distance(self, verts[, m])

Computes approximate geodesic distance (in mm) from each vertex in the surface to any vertex in the collection verts.

call_vtp_geodesic(self, vertex)

Compute geodesic distance using VTP method

create_biharmonic_solver(self, boundary_verts)

Set up biharmonic equation with Dirichlet boundary conditions on the cortical mesh and precompute Cholesky factorization for solving it.

create_subsurface(self[, vertex_mask, …])

Create subsurface for efficient operations on subset of Surface

edge_collapse(self, p1, p2, target)

exact_geodesic_distance(self, vertex)

Compute exact geodesic distance along surface

extract_chunk(self[, nfaces, seed, auxpts])

Extract a chunk of the surface using breadth first search, for testing purposes

extract_geodesic_chunk(self, origin, radius)

Extract a chunk of the surface that is within radius of the origin by geodesic distance.

geodesic_distance(self, verts[, m, fem])

Minimum mesh geodesic distance (in mm) from each vertex in surface to any vertex in the collection verts.

geodesic_path(self, a, b[, max_len, d])

Finds the shortest path between two points a and b.

get_connected_vertices(self, vertex, mask[, …])

return vertices connected to vertex that satisfy mask

get_euclidean_ball(self, xyz, radius)

return vertices within some 3d euclidean distance of an xyz coordinate

get_euclidean_patch(self, vertex, radius[, …])

return connected vertices within some 3d euclidean distance of a vertex

get_geodesic_patch(self, vertex, radius[, …])

return vertices within some 2d geodesic distance of a vertex (or vertices)

get_geodesic_patches(self, radius[, seeds, …])

create patches of cortex centered around each vertex seed

get_geodesic_strip_patch(self, v0, v1, radius)

return patch that includes v0, v1, their geodesic path, and all points within some radius


get_strip_coordinates(self, v0, v1[, …])

get 2D coordinates of surface from v0 to v1

interp(self, verts, vals)

Interpolates a function between N knot points verts with the values vals.

lift_subsurface_data(self, data[, vertex_mask])

expand vertex dimension of data to original surface’s size


Compute mean curvature of this surface using the Laplace-Beltrami operator.

patches(self[, auxpts, n])

plot_subsurface_rotating_gif(self, path[, …])

create a rotating gif of subsurface

polyhedra(self, wm)

Iterates through the polyhedra that make up the closest volume to a certain vertex

smooth(self, scalars[, factor, iterations])

Smooth vertex-wise function given by scalars across the surface using mean curvature flow method (see

surface_gradient(self, scalars[, at_verts])

Gradient of a function with values scalars at each vertex on the surface.



Sparse vertex adjacency matrix.


Average length of all edges in the surface.


return mask of boundary vertices


Sparse matrix of vertex-face associations.


Cotangent of angle opposite each vertex in each face.


return vector of edge lengths


Area of each face.


Normal vector for each face.


return pair of points on surface border that have largest pairwise geodesic distance


NetworkX undirected graph representing this Surface.



iterate through edges


Laplace-Beltrami operator for this surface.


3D matrix of points in each face: n faces x 3 points per face x 3 coords per point.



Normal vector for each vertex (average of normals for neighboring faces).