lapy.conformal¶

Computes spherical conformal mappings of triangle meshes.

Functions are adopted from Matlab code at https://github.com/garyptchoi/spherical-conformal-map with this Copyright (c) 2013-2020, Gary Pui-Tung Choi https://math.mit.edu/~ptchoi and has been distributed with the Apache 2 License.

Notes¶

If you use this code in your own work, please cite the following paper:

[1] P. T. Choi, K. C. Lam, and L. M. Lui, “FLASH: Fast Landmark Aligned Spherical Harmonic Parameterization for Genus-0 Closed Brain Surfaces.” SIAM Journal on Imaging Sciences, vol. 8, no. 1, pp. 67-94, 2015.

lapy.conformal.beltrami_coefficient(tria, mapping)[source]¶

Compute the Beltrami coefficient of a given mapping.

The Beltrami coefficient is a complex-valued function that characterizes the distortion of a mapping in terms of conformality.

Parameters:

triaTriaMesh: Genus-0 closed triangle mesh. Should be planar mapping on complex plane.
mappingnp.ndarray: Vertex coordinates of shape (n_vertices, 3) representing the spherical conformal parameterization.

Returns:

np.ndarray: Complex Beltrami coefficient per triangle, shape (n_triangles,).

Raises:

ValueError: If mesh is not planar.

lapy.conformal.inverse_stereographic(u)[source]¶

Compute mapping from the complex plane to the sphere using inverse stereographic projection.

Parameters:

unp.ndarray: Input points in the complex plane. Can be: - Array of shape (n_points, 2), representing real and imaginary parts. - Array of complex numbers of shape (n_points,).

Returns:

np.ndarray: Mapped points on the sphere as (x, y, z) coordinates, shape (n_points, 3).

lapy.conformal.linear_beltrami_solver(tria, mu, landmark, target, use_cholmod=False)[source]¶

Solve the Linear Beltrami equation for a given mesh and target.

Parameters:

triaTriaMesh: Genus-0 closed triangle mesh. Should be planar mapping on complex plane.
munp.ndarray: Beltrami coefficients describing distortion at each triangle, shape (n_triangles,).
landmarknp.ndarray: Indices of fixed landmark vertices, shape (n_landmarks,).
targetnp.ndarray: 2D target positions for the landmark vertices, shape (n_landmarks, 2).
use_cholmodbool, default=False: Which solver to use. If True, use Cholesky decomposition from scikit-sparse cholmod. If False, use spsolve (LU decomposition).

Returns:

np.ndarray: Mapping of all vertices to 2D coordinates, shape (n_vertices, 2), aligned to the given landmarks.

Raises:

ValueError: If mesh is not planar. If triangle areas are degenerate. If Beltrami denominator is close to zero.
ImportError: If use_cholmod is True but scikit-sparse is not installed.

lapy.conformal.mobius_area_correction_spherical(tria, mapping)[source]¶

Find an improved Mobius transformation to reduce distortion.

This helps reducing the area distortion of a spherical conformal parameterization using the method in Choi et al, SIAM Journal on Imaging Sciences, 2020.

Parameters:

triaTriaMesh: Genus-0 closed triangle mesh.
mappingnp.ndarray: Vertex coordinates of shape (n_vertices, 3) representing a spherical conformal parameterization.

Returns:

map_mobiusnp.ndarray: Vertex coordinates of shape (n_vertices, 3) updated to minimize area distortion.
resultobject: Optimization result object containing optimal parameters (x) for the Mobius transformation, where

\[f(z) = \frac{az+b}{cz+d} = \frac{(x[0]+x[1]*1j)*z+(x[2]+x[3]*1j)}{(x[4]+x[5]*1j)*z+(x[6]+x[7]*1j)}.\]

lapy.conformal.spherical_conformal_map(tria, use_cholmod=False)[source]¶

Linear method for computing spherical conformal map of a genus-0 closed surface.

Parameters:

triaTriaMesh: A triangular mesh object representing a genus-0 closed surface.
use_cholmodbool, default=False: Which solver to use. If True, use Cholesky decomposition from scikit-sparse cholmod. If False, use spsolve (LU decomposition).

Returns:

np.ndarray: Vertex coordinates of shape (n_vertices, 3) of the spherical conformal parameterization.

Raises:

ValueError: If mesh is not genus-0 (Euler characteristic != 2). If edge lengths are degenerate. If projection contains NaN values.
ImportError: If use_cholmod is True but scikit-sparse is not installed.

lapy.conformal.stereographic(u)[source]¶

Map points on a sphere to the complex plane using the stereographic projection.

Parameters:

unp.ndarray: Points on the sphere as (x, y, z) coordinates, shape (n_points, 3).

Returns:

np.ndarray: Mapped points as complex numbers on the complex plane, shape (n_points,).

Raises:

ValueError: If stereographic denominator (1 - z) is close to zero.