Directional

This module allows us to work with discrete vector and frame fields. The name is a reference to Amir Vaxman’s award-winning library which partially served as inspiration for this module.

We support two types of directional fields:

• n-RoSy (\(n\) rotationally symmetric) fields, sometimes also known as power fields. These represent fields as the roots of a complex number.

• Frame fields consisting of 2 directions per field element. These are represented as the coefficients of a polyvector field.

Frame Fields

Frame fields the represented as the roots of the 4th order complex polynomial. For each face, we store two coefficients, \(c_2\) and \(c_0\), which go into the polynomial:

\[ p(z) = z^4 + c_2 z^2 + c_0 = 0. \]

This polynomial will have four roots consisting of two symmetric pairs of vectors. We store such a polynomial as a tensor where the last dimension contains \((c_2, c_0)\) in that order.

Oftentimes, it is useful to prescribe one of the roots of this polynomial. We do so via the method of Meekes and Vaxman, 2021 (Appendix A). Concretely, given a symmetric 2-direction field \(\bar u = u^2\), where \(u\) is one of the two symmetric vectors along said direction, we can pull the root term \((z^2 - u^2)\) out of the polynomial \(p\). Define \(\bar z = z^2\), we have:

\[\begin{split} p(\bar z) &= (\bar z^2 + c_2 \bar z + c_0), \\ p(\bar z) &= (\bar z - \bar u) (\bar z - \bar v), \\ p(z) &= (z^2 - u^2) (z^2 - v^2). \end{split}\]

We can express the coefficients \(c_i\) in terms of \(u\) and \(v\) as:

\[\begin{split} c_2 &= -v^2 - u^2 \\ c_0 &= u^2 v^2. \end{split}\]

So, having specified a \(u\), we can map back and forth from \(v^2\) and the full coefficients via:

\[\begin{split} \begin{bmatrix} c_2 \\ c_0 \end{bmatrix} = \begin{bmatrix} - 1 & u^2 \\ u^2 & 0 \end{bmatrix} \begin{bmatrix} v^2 \\ - 1 \end{bmatrix}. \end{split}\]

iskra.directional

complex_nth_root(z, n)	Compute the nth roots of a complex number z.
face_connection_d_01(n_faces, flaps, connection)	Construct the face-based connection differetial for an N-RoSy field.
face_connection_laplacian(verts, faces, ...)	Construct the face-based connection laplacian for an N-RoSy field.
face_connection_mass(verts, edges, ...)	Makes the face-based connection mass matrix for an N-RoSy field via edge lengths.
face_tangent_bundle(vertices, faces, edge_flaps)	Construct a tangent bundle for a face-based vector field.
smooth_frame_field(verts, faces, flaps, ...)	Smooth a frame field with sparse hard constraints.
smooth_n_rosy(vertices, faces, flaps, ...)	Smooths an N-RoSy field.
to_extrinsic(u, tangents, binormals)	Reconstructs 3D vector from intrinsic complex directional.
to_extrinsic_frame_field(uv, tangents, binormals)	Reconstructs 3D vectors from complex frame field.
to_extrinsic_n_rosy(u, tangents, binormals, n)	Reconstructs 3D vectors from intrinsic complex N-RoSy field.
to_intrinsic(v, tangents, binormals)	Projects 3D vector onto 2D basis spanned by tangents and binormals.
to_intrinsic_frame_field(u, v, tangents, ...)	Constructs a frame field from two 3D vectors.
to_intrinsic_n_rosy(v, tangents, binormals, n)	Constructs an N-RoSy field from a 3D vector.
transport_from_face(source, intrinsic, ...)	Parallelly transports of a vector from face source to all neighboring faces.