L4 Spherical Harmonics
Spherical Harmonics are a basis of functions over which any function defined on the sphere can be decomposed. In mouette, we make use of the nine frequency L=4 harmonics to represent orthogonal frame fields in 3D. The geometry.SphericalHarmonics utility allow to manipulate such objects.
Attributes:
| Name | Type | Description |
|---|---|---|
EYE |
L4_SH
|
Coefficient of the identity frame in L4_SH |
LX |
L4_Operator
|
Angular momentum operator for spherical harmonics representation, x-axis |
LY |
L4_Operator
|
Angular momentum operator for spherical harmonics representation, y-axis |
LZ |
L4_Operator
|
Angular momentum operator for spherical harmonics representation, z-axis |
Rxpi4 |
L4_Operator
|
rotation of angle pi/4 around axis x |
Rypi4 |
L4_Operator
|
rotation of angle pi/4 around axis y |
Rzpi4 |
L4_Operator
|
rotation of angle pi/4 around axis z |
Rxzpi4 |
L4_Operator
|
composition Rzpi4 * Rxpi4 |
Rxpi2 |
L4_Operator
|
rotation of angle pi/2 around axis x |
Rypi2 |
L4_Operator
|
rotation of angle pi/2 around axis y |
Rzpi2 |
L4_Operator
|
rotation of angle pi/2 around axis z |
References
Algebraic Representations for Volumetric Frame Fields, Palmer et al. (Supplementary materials)
L4_Operator = Annotated[np.ndarray, (9, 9)]
module-attribute
Type annotation for linear operators acting on L4_SH (i.e. 9x9 matrices)
L4_SH = Annotated[np.ndarray, 9]
module-attribute
Type annotation for linear combinations of L4 Spherical Harmonics. Orthogonal frames are represented by 9 coefficients in the L4 band of the spherical harmonics basis. In practice, L4_SH is a size 9 numpy array.
RX(a)
The L4 operator representing a rotation around x-axis of angle a
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
a
|
float
|
angle |
required |
Returns:
| Name | Type | Description |
|---|---|---|
L4_Operator |
L4_Operator
|
9x9 matrix |
RY(a)
The L4 operator representing a rotation around y-axis of angle a
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
a
|
float
|
angle |
required |
Returns:
| Name | Type | Description |
|---|---|---|
L4_Operator |
L4_Operator
|
9x9 matrix |
RZ(a)
The L4 operator representing a rotation around z-axis of angle a
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
a
|
float
|
angle |
required |
Returns:
| Name | Type | Description |
|---|---|---|
L4_Operator |
L4_Operator
|
9x9 matrix |
from_frame(frame)
Given a rotation as a scipy.Rotation object, computes the corresponding frame coefficients in L4_SH basis.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
frame
|
Rotation
|
a scipy rotation. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
L4_SH |
L4_SH
|
corresponding coefficients |
from_vec3(v)
orthogonality_energy(sh)
Computes an energy that is 0 if and only if the given spherical harmonics has octahedral symetry (ie represents an orthogonal frame) The energy is quadratic in terms of the harmonic coefficients
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sh
|
ndarray
|
a spherical harmonics (9 coefficients) |
required |
Returns:
| Type | Description |
|---|---|
float
|
the computed energy |
project_to_frame(sh, stop_threshold=1e-08, max_iter=1000, nrml_cstr=None)
Given the coefficients in the spherical harmonic basis, finds the frames that correspond the most. Also recomputes spherical harmonics coefficients to a perfect match. Uses the Cayleigh transform to approximate the 9D rotation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sh
|
Vec
|
the 9 coefficients representing the frame in spherical harmonics basis |
required |
stop_threshold
|
float,optional)
|
Stoping criterion on the norm of the residual. Defaults to 1e-8. |
1e-08
|
max_iter
|
int
|
Maximum number of gradient steps. Defaults to 100. |
1000
|
nrml_cstr
|
Vec)
|
a 3 dimensionnal normal direction, to constraint the projection to only be around an axis. Defaults to None. |
None
|
Returns:
| Type | Description |
|---|---|
|
frame (scipy.spatial.transform.Rotation) : the obtained frame |
|
|
a (L4_SH) : the projected and updated spherical harmonics coefficients |
project_to_frame_grad(sh, lr=0.1, grad_threshold=0.0001, dot_threshold=1e-06, max_iter=1000)
Given the coefficients in the spherical harmonic basis, finds the frames that correspond the most. Computation is unfortunately not direct: starting from the reference frame, we perform a gradient descent on the l2 distance between spherical harmonics coefficients.
Also recomputes spherical harmonics coefficients to a perfect match. Uses the linearization of the exponential to approximate 9D rotations.
Warning
This algorithm is less precise and less efficient than project_to_frame. Use the latter instead.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sh
|
Vec
|
the 9 coefficients representing the frame in spherical harmonics basis |
required |
lr
|
float
|
Gradient descent learning rate. Defaults to 1. |
0.1
|
grad_threshold
|
float,optional)
|
Stoping criterion on the norm of the gradient. Defaults to 1e-4 |
0.0001
|
dot_threshold
|
float,optional)
|
Stoping criterion on the norm of the step. Defaults to 1e-6 |
1e-06
|
max_iter
|
int
|
Maximum number of gradient steps. Defaults to 1000. |
1000
|
Returns:
| Type | Description |
|---|---|
|
frame (scipy.spatial.transform.Rotation) : the obtained frame |
|
|
a (Vec) : the projected and updated spherical harmonics coefficients |
rot_matrix_from_euler(w)
Given three euler angles (XYZ), computes the 9x9 corresponding rotation matrix that performs the same rotation onto L4_SH coefficients
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
w
|
Vec
|
vector of size 3 representing three euler angles in convention XYZ. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
L4_Operator |
L4_Operator
|
a 9x9 matrix |
rot_matrix_from_rotvec(v)
Given a rotation in angle-axis form, computes the 9x9 corresponding rotation matrix that performs the same rotation onto L4_SH coefficients, defined as the exponential of the corresponding skew-symmetric matrix.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
v
|
Vec
|
a rotation axis vector where norm(v) represents the angle of rotation. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
L4_Operator |
L4_Operator
|
a 9x9 matrix |
rotate_frame(sh, r)
Applies a rotation to a frame decomposed in L4_SH basis.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sh
|
L4_SH
|
coefficients of the frame |
required |
r
|
Rotation | Vec
|
rotation to be applied, either a scipy.Rotation object or a axis-angle representation. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
L4_SH |
L4_SH
|
the rotated frame coefficients |
skew_matrix_from_rotvec(w)
Given a rotation in angle-axis form, computes the 9x9 corresponding skew-symmetric matrix
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
w
|
Vec
|
a rotation axis vector where norm(v) represents the angle of rotation. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
L4_Operator |
L4_Operator
|
a 9x9 matrix |