symforce.geo.unit3 module

class Unit3(x)[source]

Bases: LieGroup

Direction in R^3 represented as a unit vector on the S^2 sphere manifold.

Storage is three dimensional, and tangent space is two dimensional. Due to the nature of the manifold, the unit X vector is handled as a singularity.

The implementation of the retract and local_coordinates functions are based on Appendix B.2 :

[Hertzberg 2013] Integrating Generic Sensor Fusion Algorithms with Sound State Representations through Encapsulation of Manifolds

The retract operation performs a perturbation to the desired unit X vector, which is then rotated to desired position along the actual stored unit vector through a Householder-reflection + relection across the XZ plane.

x.retract(delta) = x [+] delta = Rx * Exp(delta), where Exp(delta) = [cos(||delta||), sinc(||delta||) * delta], and Rx = (I - 2 vv^T / (v^Tv))X, v = x - e_x != 0, X is a matrix negating 2nd vector component

= diag(1, -1, -1) , x = e_x

See: unit3_visualization.ipynb for a visualization of the Unit3 manifold.

Parameters:

x (Vector3) –

E_X = [1] [0] [0]
E_Z = [0] [0] [1]
FLIP_Y = [1, 0, 0] [0, -1, 0] [0, 0, 1]
classmethod storage_dim()[source]

Dimension of underlying storage

Return type:

int

to_storage()[source]

Flat list representation of the underlying storage, length of storage_dim(). This is used purely for plumbing, it is NOT like a tangent space.

Return type:

List[float]

classmethod from_storage(vec)[source]

Construct from a flat list representation. Opposite of to_storage().

Parameters:

vec (Sequence[float]) –

Return type:

Unit3

classmethod symbolic(name, **kwargs)[source]

Construct a symbolic element with the given name prefix. Kwargs are forwarded to sf.Symbol (for example, sympy assumptions).

Parameters:

  • name (str) –

  • kwargs (Any) –

Return type:

Unit3

classmethod identity()[source]

Identity element such that compose(a, identity) = a.

Return type:

Unit3

compose(other)[source]

Apply the group operation with other.

Parameters:

other (Unit3) –

Return type:

Unit3

inverse()[source]

Group inverse, such that compose(a, inverse(a)) = identity.

Return type:

Unit3

classmethod tangent_dim()[source]

Dimension of the embedded manifold

Return type:

int

classmethod from_tangent(v, epsilon=0.0)[source]

Mapping from the tangent space vector about identity into a group element.

Parameters:
Return type:

Unit3

to_tangent(epsilon=0.0)[source]

Mapping from this element to the tangent space vector about identity.

Parameters:

epsilon (float) –

Return type:

List[float]

storage_D_tangent(epsilon=0.0)[source]
Parameters:

epsilon (float) –

Return type:

Matrix32

tangent_D_storage(epsilon=0.0)[source]
Parameters:

epsilon (float) –

Return type:

Matrix23

retract(delta, epsilon=0.0)[source]

Applies a tangent space perturbation vec to self. Often used in optimization to update nonlinear values from an update step in the tangent space.

Implementation is simply compose(self, from_tangent(vec)). Conceptually represents “self + vec” if self is a vector.

Parameters:
Return type:

Unit3

local_coordinates(vector, epsilon=0.0)[source]

Computes a tangent space perturbation around self to produce b. Often used in optimization to minimize the distance between two group elements.

Implementation is simply to_tangent(between(self, b)). Tangent space perturbation that conceptually represents “b - self” if self is a vector.

Parameters:
Return type:

List[float]

to_unit_vector()[source]

Returns a Vector3 version of the unit direction.

Return type:

Matrix31

basis(epsilon=0.0)[source]

Returns a Matrix32 with the basis vectors of the tangent space (in R^3) at the current Unit3 direction.

Parameters:

epsilon (float) –

Return type:

Matrix32

classmethod from_vector(a, epsilon=0.0)[source]

Return a Unit3 that points along the direction of vector a

a will be normalized.

Parameters:
Return type:

Unit3

classmethod from_unit_vector(a)[source]

Return a Unit3 that points along the direction of vector a

a is expected to be a unit vector.

Parameters:

a (Matrix31) –

Return type:

Unit3

classmethod random(epsilon=0.0)[source]

Generate a random Unit3 direction.

Parameters:

epsilon (float) –

Return type:

Unit3

classmethod random_from_uniform_samples(u1, u2, epsilon=0.0)[source]

Generate a random Unit3 direction from two variables uniformly sampled in [0, 1].

Parameters:
Return type:

Unit3