symforce.geo.unit3 module

class Unit3(rot3=None)[source]

Bases: LieGroup

Direction in R^3, represented as a Rot3 that transforms [0, 0, 1] to the desired direction.

The storage is therefore a quaternion and the tangent space is 2 dimensional. Most operations are implemented using operations from Rot3.

Note: an alternative implementation could directly store a unit vector and define its boxplus manifold as described in Appendix B.2 of [Hertzberg 2013]. This can be done by finding the Householder reflector of x and use it to transform the exponential map of delta, which is a small perturbation in the tangent space (R^2). Namely:

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

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

Parameters:

rot3 (T.Optional[Rot3]) –

E_Z = [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()[source]
Return type:

Matrix42

tangent_D_storage()[source]
Return type:

Matrix24

to_rotation()[source]
Return type:

Rot3

to_unit_vector()[source]
Return type:

Matrix31

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

Return a Unit3 that points along the direction of vector a

a does not have to be a unit vector.

Parameters:
Return type:

Unit3

classmethod random(epsilon=0.0)[source]

Generate a random element of Unit3, by generating a random rotation first and then rotating e_z to get a random direction.

Parameters:

epsilon (float) –

Return type:

Unit3