cedalion.dataclasses.geometry

Dataclasses for representing geometric objects.

Functions

affine_transform_from_numpy(transform, ...)

Create a AffineTransform object from a numpy array.

Classes

`PointType`(value[, names, module, qualname, ...])
`PycortexSurface`(mesh, crs, units)	Provides the geodesic functionality of Pycortex.
`SimpleMesh`(pts, polys)
`Surface`(mesh, crs, units)	Abstract base class for surfaces.
`TrimeshSurface`(mesh, crs, units)	A surface represented by a trimesh object.
`VTKSurface`(mesh, crs, units)
`Voxels`(voxels, crs, units)	3D voxels represented by a np.array.

class cedalion.dataclasses.geometry.PointType( value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None, )[source]

Bases: Enum

UNKNOWN = 0[source]

SOURCE = 1[source]

DETECTOR = 2[source]

LANDMARK = 3[source]

class cedalion.dataclasses.geometry.Surface(mesh: Any, crs: str, units: Unit)[source]

Bases: ABC

Abstract base class for surfaces.

mesh: Any[source]

crs: str[source]

units: Unit[source]

abstract property vertices: Annotated[DataArray, DataArraySchema(dims='label', coords='label', 'label', 'type')][source]

abstract property nvertices: int[source]

abstract property nfaces: int[source]

abstract apply_transform(transform: DataArray)[source]

property kdtree[source]

snap( points: Annotated[DataArray, DataArraySchema(dims='label', coords='label', 'label', 'type')], )[source]: Snap points to the nearest vertices on the surface.

class cedalion.dataclasses.geometry.Voxels(voxels: ndarray, crs: str, units: Unit)[source]

Bases: object

3D voxels represented by a np.array.

voxels[source]

The voxels.

Type:: np.ndarray

crs[source]

The coordinate reference system of the voxels.

Type:: str

units[source]

The units of the voxels.

Type:: pint.Unit

voxels: ndarray[source]

crs: str[source]

units: Unit[source]

property vertices: Annotated[DataArray, DataArraySchema(dims='label', coords='label', 'label', 'type')][source]

property nvertices: int[source]

apply_transform( transform: DataArray, ) → Voxels[source]

property kdtree[source]

class cedalion.dataclasses.geometry.TrimeshSurface(mesh: Trimesh, crs: str, units: Unit)[source]

Bases: Surface

A surface represented by a trimesh object.

mesh[source]

The trimesh object representing the surface.

Type:: trimesh.Trimesh

crs[source]

The coordinate reference system of the surface.

Type:: str

units[source]

The units of the surface.

Type:: pint.Unit

mesh: Trimesh[source]

property vertices: Annotated[DataArray, DataArraySchema(dims='label', coords='label', 'label', 'type')][source]

property nvertices: int[source]

property nfaces: int[source]

apply_transform( transform: DataArray, ) → TrimeshSurface[source]

Apply an affine transformation to this surface.

Parameters:: transform (cdt.AffineTransform) – The affine transformation to apply.
Returns:: The transformed surface.
Return type:: TrimeshSurface

decimate( face_count: int, ) → TrimeshSurface[source]

Use quadric decimation to reduce the number of vertices.

Parameters:: face_count – the number of faces of the decimated mesh
Returns:: The surface with a decimated mesh

smooth(lamb: float) → TrimeshSurface[source]: Apply a Taubin filter to smooth this surface.

get_vertex_normals( points: Annotated[DataArray, DataArraySchema(dims='label', coords='label', 'label', 'type')], normalized=True, )[source]: Get normals of vertices closest to the provided points.

fix_vertex_normals()[source]

classmethod from_vtksurface(vtk_surface: VTKSurface)[source]

crs: str[source]

units: Unit[source]

class cedalion.dataclasses.geometry.VTKSurface( mesh: vtkmodules.vtkCommonDataModel.vtkPolyData, crs: str, units: pint.registry.Unit, )[source]

Bases: Surface

mesh: vtkPolyData[source]

property vertices: Annotated[DataArray, DataArraySchema(dims='label', coords='label', 'label', 'type')][source]

property nvertices: int[source]

property nfaces: int[source]

apply_transform(transform: DataArray)[source]

classmethod from_trimeshsurface(tri_mesh: TrimeshSurface)[source]

decimate(

reduction: float,

**kwargs,

) → VTKSurface[source]

Use VTK’s decimate_pro method to reduce the number of vertices.

Parameters:

reduction – Reduction factor. A value of 0.9 will leave 10% of the original number of vertices.
**kwargs – additional keyword arguments are passed to decimate_pro

Returns:

The surface with a decimated mesh

crs: str[source]

units: Unit[source]

class cedalion.dataclasses.geometry.SimpleMesh(pts: numpy.ndarray, polys: numpy.ndarray)[source]

Bases: object

pts: ndarray[source]

polys: ndarray[source]

class cedalion.dataclasses.geometry.PycortexSurface( mesh: SimpleMesh, crs: str, units: Unit, )[source]

Bases: Surface

Provides the geodesic functionality of Pycortex.

References

Functions in this class are based on the implementation in Pycortex (Gao et al. [GHLG15]). Gao JS, Huth AG, Lescroart MD and Gallant JL (2015) Pycortex: an interactive surface visualizer for fMRI. Front. Neuroinform. 9:23. doi: 10.3389/fninf.2015.00023

mesh: SimpleMesh[source]

property vertices: Annotated[DataArray, DataArraySchema(dims='label', coords='label', 'label', 'type')][source]

property nvertices: int[source]

property nfaces: int[source]

apply_transform( transform: DataArray, ) → PycortexSurface[source]

decimate( face_count: int, ) → PycortexSurface[source]

get_vertex_normals( points: Annotated[DataArray, DataArraySchema(dims='label', coords='label', 'label', 'type')], normalized=True, )[source]

property ppts: ndarray[source]

3D matrix of points in each face.

n faces x 3 per face x 3 coords per point.

property connected: csr_matrix[source]: Sparse matrix of vertex-face associations.

property adj: csr_matrix[source]: Sparse vertex adjacency matrix.

property face_normals: ndarray[source]: Normal vector for each face.

property vertex_normals: ndarray[source]: Normal vector for each vertex (average of normals for neighboring faces).

property face_areas: ndarray[source]: Area of each face.

property cotangent_weights: ndarray[source]: Cotangent of angle opposite each vertex in each face.

property laplace_operator[source]

Laplace-Beltrami operator for this surface.

A sparse adjacency matrix with edge weights determined by the cotangents of the angles opposite each edge. Returns a 4-tuple (B, D, W, V) where D is the ‘lumped mass matrix’, W is the weighted adjacency matrix, and V is a diagonal matrix that normalizes the adjacencies. The ‘stiffness matrix’, A, can be computed as V - W.

The full LB operator can be computed as D^{-1} (V - W).

B is the finite element method (FEM) ‘mass matrix’, which replaces D in FEM analyses.

See ‘Discrete Laplace-Beltrami operators for shape analysis and segmentation’ by Reuter et al., 2009 for details.

property avg_edge_length[source]: Average length of all edges in the surface.

surface_gradient(scalars, at_verts=True)[source]

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

If at_verts, returns values at each vertex. Otherwise, returns values at each face.

Parameters:

scalars – 1D ndarray, shape (total_verts,) a scalar-valued function across the cortex.
at_verts – bool, optional If True (default), values will be returned for each vertex. Otherwise, values will be returned for each face.

Returns:

2D ndarray, shape (total_verts,3) or (total_polys,3): Contains the x-, y-, and z-axis gradients of the given scalars at either each vertex (if at_verts is True) or each face.

Return type:

gradu

geodesic_distance(verts, m=1.0, fem=False)[source]

Calcualte the inimum mesh geodesic distance (in mm).

The geodesic distance is calculated from each vertex in surface to any vertex in the collection verts.

Geodesic distance is estimated using heat-based method (see ‘Geodesics in Heat’, Crane et al, 2012). Diffusion of heat along the mesh is simulated and then used to infer geodesic distance. The duration of the simulation is controlled by the parameter m. Larger values of m will smooth & regularize the distance computation. Smaller values of m will roughen and will usually increase error in the distance computation. The default value of 1.0 is probably pretty good.

This function caches some data (sparse LU factorizations of the laplace-beltrami operator and the weighted adjacency matrix), so it will be much faster on subsequent runs.

The time taken by this function is independent of the number of vertices in verts.

Parameters:

verts – 1D array-like of ints Set of vertices to compute distance from. This function returns the shortest distance to any of these vertices from every vertex in the surface.
m – float, optional Reverse Euler step length. The optimal value is likely between 0.5 and 1.5. Default is 1.0, which should be fine for most cases.
fem – bool, optional Whether to use Finite Element Method lumped mass matrix. Wasn’t used in Crane 2012 paper. Doesn’t seem to help any.

Returns:

1D ndarray, shape (total_verts,) Geodesic distance (in mm) from each vertex in the surface to the closest vertex in verts.

geodesic_path(a, b, max_len=1000, d=None, **kwargs)[source]

Finds the shortest path between two points a and b.

This shortest path is based on geodesic distances across the surface. The path starts at point a and selects the neighbor of a in the graph that is closest to b. This is done iteratively with the last vertex in the path until the last point in the path is b.

Other Parameters in kwargs are passed to the geodesic_distance function to alter how geodesic distances are actually measured

Parameters:

a – int Vertex that is the start of the path
b – int Vertex that is the end of the path
d – array array of geodesic distances, will be computed if not provided
max_len – int, optional, default=1000 Maximum path length before the function quits. Sometimes it can get stuck in loops, causing infinite paths.
m – float, optional Reverse Euler step length. The optimal value is likely between 0.5 and 1.5. Default is 1.0, which should be fine for most cases.
fem – bool, optional Whether to use Finite Element Method lumped mass matrix. Wasn’t used in Crane 2012 paper. Doesn’t seem to help any.
kwargs – other arugments are passed to self.geodesic_distance

Returns:

list: List of the vertices in the path from a to b

Return type:

path

classmethod from_trimeshsurface( tri_mesh: TrimeshSurface, )[source]

classmethod from_vtksurface(vtk_surface: VTKSurface)[source]

crs: str[source]

units: Unit[source]

cedalion.dataclasses.geometry.affine_transform_from_numpy( transform: ndarray, from_crs: str, to_crs: str, from_units: str, to_units: str, ) → DataArray[source]: Create a AffineTransform object from a numpy array.