cedalion.geometry.meshing

Mesh decimation, voxel-to-vertex mapping, and scalar upscaling utilities.

Functions

decimate_mesh(surface, nvertex_target[, ...])

Decimate a triangulated surface mesh to a target vertex count.

map_voxels_to_vertices(surface, cell_coords)

Map voxel centres to their nearest surface vertex.

parcel_aware_voxels_to_vertices_map(surface, ...)

Map voxel centres to surface vertices respecting parcel boundaries.

upscale_scalars(highres_mesh, lowres_mesh, ...)

Upscale a scalar function from a low-resolution mesh to a higher-resolution one.
cedalion.geometry.meshing.upscale_scalars(
highres_mesh: TrimeshSurface,
lowres_mesh: TrimeshSurface,
lowres_scalars: ndarray,
)[source]

Upscale a scalar function from a low-resolution mesh to a higher-resolution one.

Uses barycentric interpolation: for each high-res vertex, the closest point on the low-res mesh is found and the scalar value is interpolated from the enclosing face’s three vertices. The low-res mesh must be a spatial subset of the high-res mesh (e.g. produced by decimate_mesh()).

Parameters:

  • highres_mesh – Target surface at higher resolution.

  • lowres_mesh – Source surface at lower resolution.

  • lowres_scalars – Scalar values defined at each vertex of lowres_mesh, shape (n_lowres_vertices,).

Returns:

NumPy array of scalar values interpolated onto highres_mesh vertices, shape (n_highres_vertices,).

cedalion.geometry.meshing.decimate_mesh(
surface: TrimeshSurface,
nvertex_target: int,
vertex_quality=None,
selected=False,
selection_threshold=0.5,
)[source]

Decimate a triangulated surface mesh to a target vertex count.

Uses PyMeshLab’s quadric edge collapse algorithm. When vertex_quality is provided, it is used as a per-vertex quality scalar to guide the decimation. Optionally, only vertices below a quality threshold are decimated when selected=True.

Parameters:

  • surface – Input TrimeshSurface.

  • nvertex_target – Desired number of vertices in the output mesh.

  • vertex_quality – Optional per-vertex quality scalar array of shape (n_vertices,) used to weight the decimation.

  • selected – If True, only decimate vertices whose quality is below selection_threshold.

  • selection_threshold – Quality threshold for vertex selection when selected=True.

Returns:

New TrimeshSurface with approximately nvertex_target vertices. Per-vertex coordinates stored in surface.vertex_coords are transferred via nearest-neighbour lookup.

cedalion.geometry.meshing.map_voxels_to_vertices(
surface: TrimeshSurface,
cell_coords,
)[source]

Map voxel centres to their nearest surface vertex.

Projects each voxel coordinate onto the surface mesh and then finds the nearest vertex. Processed in chunks to limit memory use.

Parameters:

  • surface – Target TrimeshSurface.

  • cell_coords – Array of voxel-centre coordinates, shape (N, 3).

Returns:

  • voxel2vertex_indices (np.ndarray[int], shape (N,)): index of the nearest vertex for each voxel.

  • voxel_count (np.ndarray[int], shape (n_vertices,)): number of voxels mapped to each vertex.

Return type:

Tuple (voxel2vertex_indices, voxel_count)

cedalion.geometry.meshing.parcel_aware_voxels_to_vertices_map(
surface: TrimeshSurface,
cell_coords,
skip_parcels=('Background+FreeSurfer_Defined_Medial_Wall_LH', 'Background+FreeSurfer_Defined_Medial_Wall_RH'),
voxel_stealing=False,
)[source]

Map voxel centres to surface vertices respecting parcel boundaries.

Each voxel is mapped only to vertices within the same cortical parcel, preventing leakage across parcel boundaries. Optionally, vertices that would otherwise receive no voxel can “steal” the nearest voxel from a neighbouring vertex (voxel_stealing).

Parameters:

  • surface – Target TrimeshSurface whose vertices carry a "parcel" coordinate.

  • cell_coords – xr.DataArray of voxel-centre coordinates with a "parcel" coordinate that groups voxels by parcel.

  • skip_parcels – Parcel labels to ignore (typically medial-wall parcels).

  • voxel_stealing – If True, reassign voxels to ensure every parcel vertex gets at least one voxel via linear assignment.

Returns:

  • voxel2vertex_indices (xr.DataArray[int]): nearest vertex index for each voxel (-1 for skipped parcels).

  • voxel_count (np.ndarray[int], shape (n_vertices,)): number of voxels mapped to each vertex.

Return type:

Tuple (voxel2vertex_indices, voxel_count)