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)

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

A numpy array of shape (n, 3) representing the coordinates of the spherical conformal parameterization.

Returns:
munp.ndarray

Complex Beltrami coefficient per triangle.

lapy.conformal.inverse_stereographic(u)

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

Parameters:
uUnion[np.ndarray, list[complex], list[tuple[float, float]]]
Input points in the complex plane. Can be:

  • A numpy array of shape (n, 2), representing real and imaginary parts.

  • A list of complex numbers.

  • A list of tuples representing (real, imaginary) coordinates.

Returns:
np.ndarray:

A numpy array of shape (n, 3) containing the mapped points on the sphere as (x, y, z) coordinates.

lapy.conformal.linear_beltrami_solver(tria, mu, landmark, target, use_cholmod=False)

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

A numpy array containing Beltrami coefficients, describing distortion at each vertex.

landmarknp.ndarray

A numpy array of indices specifying the fixed landmark vertices.

targetnp.ndarray
A numpy array of shape (len(landmark), 2), specifying the 2D target positions

for the landmark vertices.

use_cholmodbool, default=False
Which solver to use:

  • True : Attempt to use Cholesky decomposition from scikit-sparse cholmod.

  • False: Use spsolve (LU decomposition).

Returns:
mappingnp.ndarray
An array of shape (n, 2) representing the mapping of all vertices in the

triangulation to 2D coordinates, aligned to the given landmarks.

lapy.conformal.mobius_area_correction_spherical(tria, mapping)

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

A NumPy array of shape (n, 3) representing vertex coordinates of a spherical conformal parameterization.

Returns:
map_mobius: np.ndarray

A NumPy array of shape (n, 3) with vertex coordinates updated to minimize area distortion.

result: np.ndarray

Optimal parameters (x) for the Mobius transformation, where

\[f(z) = \frac{az+b}{cz+d} = \frac{(x(1)+x(2)*1j)*z+(x(3)+x(4)*1j)}{(x(5)+x(6)*1j)*z+(x(7)+x(8)*1j)}.\]
lapy.conformal.spherical_conformal_map(tria, use_cholmod=False)

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:

  • True : Use Cholesky decomposition from scikit-sparse cholmod.

  • False: Use spsolve (LU decomposition).

Returns:
mapping: np.ndarray

Vertex coordinates as NumPy array of shape (n, 3) of the spherical conformal parameterization.

lapy.conformal.stereographic(u)

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

Parameters:
unp.ndarray

A numpy array of shape (n, 3), where each row represents a point on the sphere as (x, y, z) coordinates.

Returns:
np.ndarray:

A numpy array of shape (n,) containing the mapped points as complex numbers on the complex plane.