symforce.symbolic module

The core SymForce symbolic API

This combines functions available from various sources:

• Many functions we expose from the SymPy (and SymEngine) API

• Additional functions defined here to override those provided by SymPy or SymEngine, or provide a uniform interface between the two. See https://symforce.org/api/symforce.symbolic.html for information on these

• Logic functions defined in symforce.logic, see the documentation for that module

• Additional geometry and camera types provided by SymForce from the symforce.geo and symforce.cam modules

It typically isn’t necessary to actually access the symbolic API being used internally, but that is available as well as symforce.symbolic.sympy.

class Abs(x)

Bases: OneArgFunction

property func

property is_negative

property is_real

class Add(*args, **kwargs)

Bases: AssocOp

as_coefficients_dict()

property func

identity = 0

property is_Add

class Basic

Bases: object

args

args_as_sage()

args_as_sympy()

as_coefficients_dict()

as_numer_denom()

as_real_imag()

atoms()

coeff()

copy()

diff()

evalf()

expand()

free_symbols

has()

is_Add

is_AlgebraicNumber

is_Atom

is_Boolean

is_DataBufferElement

is_Derivative

is_Dummy

is_Equality

is_Float

is_Function

is_Integer

is_Matrix

is_Mul

is_Not

is_Number

is_Pow

is_Rational

is_Relational

is_Symbol

is_finite

is_integer

is_negative

is_nonnegative

is_nonpositive

is_number

is_positive

is_real

is_symbol

is_zero

msubs()

n()

replace()

simplify()

subs()

subs_dict()

subs_oldnew()

xreplace()

class Contains(expr, sset)

Bases: Boolean

class Derivative(expr, *variables)

Bases: Expr

property expr

property func

property is_Derivative

property variables

class Dummy

Bases: Symbol

func

is_Dummy

class Expr

Bases: Basic

class FiniteSet(*args)

Bases: Set

class Float(num, dps=None, precision=None)

Bases: Number

property is_Float

property is_irrational

property is_rational

property is_real

class Function(*args, **kwargs)

Bases: Expr

func(*values)

property is_Function

class Integer(i)

Bases: Rational

doit(**hints)

property func

get_num_den()

property is_Integer

property is_integer

property p

property q

class Interval(*args)

Bases: Set

class KroneckerDelta(x, y)

Bases: Function

class LambertW(x)

Bases: OneArgFunction

class LeviCivita(*args)

Bases: Function

class Max(*args)

Bases: Function

property func

class Min(*args)

Bases: Function

property func

Mod()

class Mul(*args, **kwargs)

Bases: AssocOp

as_coefficients_dict()

property func

identity = 1

property is_Mul

class Number

Bases: Expr

imag

is_Atom

is_Number

is_commutative

is_complex

is_negative

is_nonnegative

is_nonpositive

is_nonzero

is_number

is_positive

real

class Piecewise(*args)

Bases: Function

class Pow(a, b)

Bases: Expr

as_base_exp()

property base

property exp

property func

property is_Pow

property is_commutative

class Rational(p, q)

Bases: Number

property func

get_num_den()

property is_Rational

property is_finite

property is_integer

property is_rational

property is_real

property p

property q

RealNumber

alias of Float

class Subs(expr, variables, point)

Bases: Expr

property expr

property func

property point

property variables

exception SympifyError

Bases: Exception

class UnevaluatedExpr(x)

Bases: OneArgFunction

property is_finite

property is_integer

property is_number

class acos(x)

Bases: TrigFunction

class acosh(x)

Bases: HyperbolicFunction

class acot(x)

Bases: TrigFunction

class acoth(x)

Bases: HyperbolicFunction

class acsc(x)

Bases: TrigFunction

class acsch(x)

Bases: HyperbolicFunction

class asec(x)

Bases: TrigFunction

class asech(x)

Bases: HyperbolicFunction

class asin(x)

Bases: TrigFunction

class asinh(x)

Bases: HyperbolicFunction

class atan(x)

Bases: TrigFunction

class atanh(x)

Bases: HyperbolicFunction

class beta(x, y)

Bases: Function

class ceiling(x)

Bases: OneArgFunction

class conjugate(x)

Bases: OneArgFunction

class cos(x)

Bases: TrigFunction

class cosh(x)

Bases: HyperbolicFunction

class cot(x)

Bases: TrigFunction

class coth(x)

Bases: HyperbolicFunction

class csc(x)

Bases: TrigFunction

class csch(x)

Bases: HyperbolicFunction

cse()

Perform common subexpression elimination on an expression.

Parameters:

• exprs (iterable of symengine expressions) – The expressions to reduce.

• symbols (infinite iterator yielding unique Symbols) – The symbols used to label the common subexpressions which are pulled out. The default is a stream of symbols of the form “x0”, “x1”, etc. This must be an infinite iterator.

Returns:

• replacements (list of (Symbol, expression) pairs) – All of the common subexpressions that were replaced. Subexpressions earlier in this list might show up in subexpressions later in this list.

• reduced_exprs (list of symengine expressions) – The reduced expressions with all of the replacements above.

diff()

digamma()

class dirichlet_eta(x)

Bases: OneArgFunction

class erf(x)

Bases: OneArgFunction

class erfc(x)

Bases: OneArgFunction

exp()

expand()

class floor(x)

Bases: OneArgFunction

gamma()

init_printing(pretty_print=True, use_latex=True)

integer_nthroot()

isprime()

lambdify(args, exprs, **kwargs)

latex()

linsolve()

Solve a set of linear equations given as an iterable eqs which are linear w.r.t the symbols given as an iterable syms

class log(x, y=None)

Bases: OneArgFunction

class loggamma(x)

Bases: OneArgFunction

class lowergamma(x, y)

Bases: Function

perfect_power()

class polygamma(x, y)

Bases: Function

class sec(x)

Bases: TrigFunction

class sech(x)

Bases: HyperbolicFunction

series()

class sign(x)

Bases: OneArgFunction

property is_complex

property is_finite

class sin(x)

Bases: TrigFunction

class sinh(x)

Bases: HyperbolicFunction

sqrt()

sqrt_mod()

sympify()

Converts an expression ‘a’ into a SymEngine type.

Parameters:

convert. (a ............. An expression to) –

Examples

>>> from symengine import sympify
>>> sympify(1)
1
>>> sympify("a+b")
a + b

class tan(x)

Bases: TrigFunction

class tanh(x)

Bases: HyperbolicFunction

trigamma()

class uppergamma(x, y)

Bases: Function

var(names, **args)

Create symbols and inject them into the global namespace.

INPUT:

• s – a string, either a single variable name, or

• a space separated list of variable names, or

• a list of variable names.

This calls symbols() with the same arguments and puts the results into the global namespace. It’s recommended not to use var() in library code, where symbols() has to be used:

>>> from symengine import var

>>> var('x')
x
>>> x
x

>>> var('a,ab,abc')
(a, ab, abc)
>>> abc
abc

See symbols() documentation for more details on what kinds of arguments can be passed to var().

class zeta(s, a=None)

Bases: Function

create_named_scope(scopes_list)

Return a context manager that adds to the given list of name scopes. This is used to add scopes to symbol names for namespacing.

Parameters:

scopes_list (List[str]) –

Return type:

Callable

set_scope(scope)

Parameters:

scope (str) –

Return type:

None

get_scope()

Return type:

str

scope(scope)

Parameters:

scope (str) –

Return type:

Iterator[None]

class Symbol(name, commutative=True, real=True, positive=None)

Bases: Symbol

Parameters:

• name (str) –

• commutative (bool) –

• real (bool) –

• positive (T.Optional[bool]) –

symbols(names, **args)

Transform strings into instances of Symbol class. symbols() function returns a sequence of symbols with names taken from names argument, which can be a comma or whitespace delimited string, or a sequence of strings:

>>> from symengine import symbols
>>> x, y, z = symbols('x,y,z')
>>> a, b, c = symbols('a b c')

The type of output is dependent on the properties of input arguments::

>>> symbols('x')
x
>>> symbols('x,')
(x,)
>>> symbols('x,y')
(x, y)
>>> symbols(('a', 'b', 'c'))
(a, b, c)
>>> symbols(['a', 'b', 'c'])
[a, b, c]
>>> symbols(set(['a', 'b', 'c']))
set([a, b, c])

If an iterable container is needed for a single symbol, set the seq argument to True or terminate the symbol name with a comma:

>>> symbols('x', seq=True)
(x,)

To reduce typing, range syntax is supported to create indexed symbols. Ranges are indicated by a colon and the type of range is determined by the character to the right of the colon. If the character is a digit then all contiguous digits to the left are taken as the nonnegative starting value (or 0 if there is no digit left of the colon) and all contiguous digits to the right are taken as 1 greater than the ending value:

>>> symbols('x:10')
(x0, x1, x2, x3, x4, x5, x6, x7, x8, x9)
>>> symbols('x5:10')
(x5, x6, x7, x8, x9)
>>> symbols('x5(:2)')
(x50, x51)
>>> symbols('x5:10,y:5')
(x5, x6, x7, x8, x9, y0, y1, y2, y3, y4)
>>> symbols(('x5:10', 'y:5'))
((x5, x6, x7, x8, x9), (y0, y1, y2, y3, y4))

If the character to the right of the colon is a letter, then the single letter to the left (or ‘a’ if there is none) is taken as the start and all characters in the lexicographic range through the letter to the right are used as the range:

>>> symbols('x:z')
(x, y, z)
>>> symbols('x:c')  # null range
()
>>> symbols('x(:c)')
(xa, xb, xc)
>>> symbols(':c')
(a, b, c)
>>> symbols('a:d, x:z')
(a, b, c, d, x, y, z)
>>> symbols(('a:d', 'x:z'))
((a, b, c, d), (x, y, z))

Multiple ranges are supported; contiguous numerical ranges should be separated by parentheses to disambiguate the ending number of one range from the starting number of the next:

>>> symbols('x:2(1:3)')
(x01, x02, x11, x12)
>>> symbols(':3:2')  # parsing is from left to right
(00, 01, 10, 11, 20, 21)

Only one pair of parentheses surrounding ranges are removed, so to include parentheses around ranges, double them. And to include spaces, commas, or colons, escape them with a backslash:

>>> symbols('x((a:b))')
(x(a), x(b))
>>> symbols('x(:1\,:2)')  # or 'x((:1)\,(:2))'
(x(0,0), x(0,1))

epsilon()

The default epsilon for SymForce

Library functions that require an epsilon argument should use a function signature like:

def foo(x: Scalar, epsilon: Scalar = sf.epsilon()) -> Scalar:
    ...

This makes it easy to configure entire expressions that make extensive use of epsilon to either use no epsilon (i.e. 0), or a symbol, or a numerical value. It also means that by setting the default to a symbol, you can confidently generate code without worrying about having forgotten to pass an epsilon argument to one of these functions.

For more information on how we use epsilon to prevent singularities, see the Epsilon Tutorial in the SymForce docs here: https://symforce.org/tutorials/epsilon_tutorial.html

For purely numerical code that just needs a good default numerical epsilon, see symforce.symbolic.numeric_epsilon.

Returns:

• The current default epsilon. This is typically some kind of “Scalar”, like a float or a

• :class:`Symbol <symforce.symbolic.Symbol>`.

Return type:

Any

Scalar

alias of float

is_positive(x)

Returns 1 if x is positive, 0 otherwise

Parameters:

x (float) –

Return type:

float

is_negative(x)

Returns 1 if x is negative, 0 otherwise

Parameters:

x (float) –

Return type:

float

is_nonnegative(x)

Returns 1 if x is >= 0, 0 if x is negative

Parameters:

x (float) –

Return type:

float

is_nonpositive(x)

Returns 1 if x is <= 0, 0 if x is positive

Parameters:

x (float) –

Return type:

float

less_equal(x, y)

Returns 1 if x <= y, 0 otherwise

Parameters:

• x (float) –

• y (float) –

Return type:

float

greater_equal(x, y)

Returns 1 if x >= y, 0 otherwise

Parameters:

• x (float) –

• y (float) –

Return type:

float

less(x, y)

Returns 1 if x < y, 0 otherwise

Parameters:

• x (float) –

• y (float) –

Return type:

float

greater(x, y)

Returns 1 if x > y, 0 otherwise

Parameters:

• x (float) –

• y (float) –

Return type:

float

logical_and(*args, unsafe=False)

Logical and of two or more Scalars

Input values are treated as true if they are positive, false if they are 0 or negative. The returned value is 1 for true, 0 for false.

If unsafe is True, the resulting expression is fewer ops but assumes the inputs are exactly 0 or 1; results for other (finite) inputs will be finite, but are otherwise undefined.

Parameters:

• args (float) –

• unsafe (bool) –

Return type:

float

logical_or(*args, unsafe=False)

Logical or of two or more Scalars

Input values are treated as true if they are positive, false if they are 0 or negative. The returned value is 1 for true, 0 for false.

If unsafe is True, the resulting expression is fewer ops but assumes the inputs are exactly 0 or 1; results for other (finite) inputs will be finite, but are otherwise undefined.

Parameters:

• args (float) –

• unsafe (bool) –

Return type:

float

logical_not(a, unsafe=False)

Logical not of a Scalar

Input value is treated as true if it is positive, false if it is 0 or negative. The returned value is 1 for true, 0 for false.

If unsafe is True, the resulting expression is fewer ops but assumes the inputs are exactly 0 or 1; results for other (finite) inputs will be finite, but are otherwise undefined.

Parameters:

• a (float) –

• unsafe (bool) –

Return type:

float

wrap_angle(x)

Wrap an angle to the interval [-pi, pi). Commonly used to compute the shortest signed distance between two angles.

See also: angle_diff()

Parameters:

x (float) –

Return type:

float

angle_diff(x, y)

Return the difference x - y, but wrapped into [-pi, pi); i.e. the angle diff closest to 0 such that x = y + diff (mod 2pi).

See also: wrap_angle()

Parameters:

• x (float) –

• y (float) –

Return type:

float

argmax_onehot(vals, tolerance=0.0)

Returns a list l such that l[i] = 1.0 if i is the smallest index such that vals[i] equals Max(*vals). l[i] = 0.0 otherwise.

Precondition:

vals has at least one element

Parameters:

• tolerance (float) – The selected max will be guaranteed to be within tolerance of the true max. If this is too small (e.g. if this is 0), the returned vector may be all zeros for some inputs.

• vals (Iterable[float]) –

Return type:

List[float]

argmax(vals)

Returns i (as a Scalar) such that i is the smallest index such that vals[i] equals Max(*vals).

Precondition:

vals has at least one element

Parameters:

vals (Iterable[float]) –

Return type:

float

atan2(y, x, epsilon=0.0)

Parameters:

• y (float) –

• x (float) –

• epsilon (float) –

Return type:

float

asin_safe(x, epsilon=0.0)

Parameters:

• x (float) –

• epsilon (float) –

Return type:

float

acos_safe(x, epsilon=0.0)

Parameters:

• x (float) –

• epsilon (float) –

Return type:

float

clamp(x, min_value, max_value)

Clamps x between min_value and max_value

Returns:

min_value if x < min_value
x if min_value <= x <= max_value
max_value if x > max_value

Parameters:

• x (float) – Value to clamp between min_value and max_value

• min_value (float) – Scalar of same type and units as x; minimum value to return

• max_value (float) – Scalar of same type and units as x; maximum value to return. Must be greater than min_value.

Return type:

float

set_eval_on_sympify(eval_on_sympy=True)

When using the symengine backed, set whether we should eval args when converting objects to sympy.

By default, this is enabled since this is the implicit behavior with stock symengine. Disabling eval results in more slightly ops, but greatly speeds up codegen time.

Parameters:

eval_on_sympy (bool) –

Return type:

None

SymPySignNoZero

alias of SignNoZero

SymPyCopysignNoZero

alias of CopysignNoZero

class CopysignNoZero(x, y)

Bases: TwoArgFunction

class SignNoZero(x)

Bases: OneArgFunction

sign_no_zero(x)

Returns -1 if x is negative, 1 if x is positive, and 1 if x is zero.

Parameters:

x (float) –

Return type:

Expr

copysign_no_zero(x, y)

Returns a value with the magnitude of x and sign of y

If y is zero, returns positive x.

Parameters:

• x (float) –

• y (float) –

Return type:

float

simplify(*args, **kwargs)

Parameters:

• args (Any) –

• kwargs (Any) –

Return type:

float

limit(e, z, z0, dir='+')

Parameters:

• e (Any) –

• z (Any) –

• z0 (Any) –

• dir (str) –

Return type:

float

integrate(*args, meijerg=None, conds='piecewise', risch=None, heurisch=None, manual=None, **kwargs)

Parameters:

• args (Any) –

• meijerg (bool | None) –

• conds (Literal['piecewise', 'separate', 'none']) –

• risch (bool | None) –

• heurisch (Any | None) –

• manual (bool | None) –

• kwargs (Any) –

solve(*args, **kwargs)

Parameters:

• args (Any) –

• kwargs (Any) –

Return type:

List[float]

count_ops()

class DataBuffer(name, rows=None)

Bases: Symbol

Represents an external one-dimensional data buffer that can be indexed.

original_get_dict()

Returns a DictBasic instance from args. Inputs can be,

1. a DictBasic

2. a Python dictionary

3. two args old, new

NOTE(harrison): **kwargs are so we can share function signatures with the one we patch in

class LieGroup

Bases: Group

Interface for objects that implement the lie group concept. Because this class is registered using symforce.ops.impl.class_lie_group_ops.ClassLieGroupOps (see bottom of this file), any object that inherits from LieGroup and that implements the functions defined in this class can be used with the LieGroupOps concept.

Note that LieGroup is a subclass of group.Group which is a subclass of storage.Storage, meaning that a LieGroup object can be also be used with GroupOps and StorageOps (assuming the necessary functions are implemented).

LieGroupT = ~LieGroupT

classmethod tangent_dim()

Dimension of the embedded manifold

Return type:

int

classmethod from_tangent(vec, epsilon=0.0)

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

Parameters:

• vec (T.Sequence[T.Scalar]) –

• epsilon (T.Scalar) –

Return type:

LieGroupT

to_tangent(epsilon=0.0)

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

Parameters:

• self (LieGroupT) –

• epsilon (T.Scalar) –

Return type:

T.List[T.Scalar]

retract(vec, epsilon=0.0)

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:

• self (LieGroupT) –

• vec (T.Sequence[T.Scalar]) –

• epsilon (T.Scalar) –

Return type:

LieGroupT

local_coordinates(b, epsilon=0.0)

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:

• self (LieGroupT) –

• b (LieGroupT) –

• epsilon (T.Scalar) –

Return type:

T.List[T.Scalar]

jacobian(X, tangent_space=True, epsilon=0.0)

Computes the jacobian of this LieGroup element with respect to the input X, where X is anything that supports LieGroupOps

If tangent_space is True, the jacobian is computed in the local coordinates of the tangent spaces around self and X. If tangent_space is False, the jacobian is computed in the storage spaces of self and X.

See also

symforce.ops.lie_group_ops.LieGroupOps.jacobian() symforce.jacobian_helpers.tangent_jacobians()

Returns: the jacobian matrix of shape MxN, where M is the dimension of the tangent (or

storage) space of self and N is the dimension of the tangent (or storage) space of X.

Parameters:

• self (LieGroupT) –

• X (T.Any) –

• tangent_space (bool) –

• epsilon (T.Scalar) –

Return type:

geo.Matrix

class Complex(real, imag)

Bases: Group

A complex number is a number that can be expressed in the form a + bi, where a and b are real numbers, and i is a solution of the equation x**2 = -1. Because no real number satisfies this equation, i is called an imaginary number. For the complex number a + bi, a is called the real part, and b is called the imaginary part. Despite the historical nomenclature “imaginary”, complex numbers are regarded in the mathematical sciences as just as “real” as the real numbers, and are fundamental in many aspects of the scientific description of the natural world.

A complex number is also a convenient way to store a two-dimensional rotation.

References

https://en.wikipedia.org/wiki/Complex_number

Parameters:

• real (T.Scalar) –

• imag (T.Scalar) –

classmethod storage_dim()

Dimension of underlying storage

Return type:

int

to_storage()

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)

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

Parameters:

vec (Sequence[float]) –

Return type:

Complex

classmethod symbolic(name, **kwargs)

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:

Complex

classmethod identity()

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

Return type:

Complex

compose(other)

Apply the group operation with other.

Parameters:

other (Complex) –

Return type:

Complex

inverse()

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

Return type:

Complex

classmethod zero()

Zero value.

Returns:

Complex

Return type:

Complex

conj()

Complex conjugate (real, -imag).

Returns:

Complex

Return type:

Complex

squared_norm()

Squared norm of the two-vector.

Returns:

Scalar – real**2 + imag**2

Return type:

float

__mul__(right)

Complex multiplication (composition).

Parameters:

right (Complex) –

Returns:

Complex

Return type:

Complex

__add__(right)

Element-wise addition.

Parameters:

right (Complex) –

Returns:

Complex

Return type:

Complex

__neg__()

Element-wise negation.

Returns:

Complex

Return type:

Complex

__truediv__(scalar)

Scalar element-wise division.

Parameters:

scalar (Scalar) –

Returns:

Complex

Return type:

Complex

classmethod random_uniform(low, high)

Generate a random complex number with real and imaginary parts between the given bounds

Parameters:

• low (float) –

• high (float) –

Return type:

Complex

classmethod unit_random()

Generate a unit-norm random complex number

Return type:

Complex

classmethod unit_random_from_uniform_sample(u1, pi=pi)

Generate a unit-norm random Complex number from a variable sampled uniformly on [0, 1]

Parameters:

• u1 (float) –

• pi (float) –

Return type:

Complex

class DualQuaternion(real_q, inf_q)

Bases: Group

Dual quaternions can be used for rigid motions in 3D. Similar to the way that rotations in 3D space can be represented by quaternions of unit length, rigid motions in 3D space can be represented by dual quaternions of unit length. This fact is used in theoretical kinematics, and in applications to 3D computer graphics, robotics and computer vision.

References

https://en.wikipedia.org/wiki/Dual_quaternion

Parameters:

• real_q (Quaternion) –

• inf_q (Quaternion) –

classmethod storage_dim()

Dimension of underlying storage

Return type:

int

to_storage()

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)

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

Parameters:

vec (Sequence[float]) –

Return type:

DualQuaternion

classmethod identity()

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

Return type:

DualQuaternion

compose(other)

Apply the group operation with other.

Parameters:

other (DualQuaternion) –

Return type:

DualQuaternion

inverse()

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

Return type:

DualQuaternion

__mul__(right)

Left-multiply with another dual quaternion.

Parameters:

right (DualQuaternion) –

Return type:

DualQuaternion

__truediv__(scalar)

Scalar division.

Parameters:

scalar (float) –

Return type:

DualQuaternion

squared_norm()

Squared norm when considering the dual quaternion as 8-tuple.

Return type:

float

conj()

Dual quaternion conjugate.

Return type:

DualQuaternion

class Storage

Bases: object

Interface for objects that implement the storage concept. Because this class is registered using symforce.ops.impl.class_storage_ops.ClassStorageOps (see bottom of this file), any object that inherits from Storage and that implements the functions defined in this class can be used with the StorageOps concept.

E.g. calling:

ops.StorageOps.storage_dim(my_obj)

will return the same result as my_obj.storage_dim() if my_obj inherits from this class.

StorageT = ~StorageT

classmethod storage_dim()

Dimension of underlying storage

Return type:

int

__repr__()

String representation of this type.

Parameters:

self (StorageT) –

Return type:

str

to_storage()

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

Parameters:

self (StorageT) –

Return type:

List[float]

classmethod from_storage(elements)

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

Parameters:

elements (Sequence[float]) –

Return type:

StorageT

__eq__(other)

Returns exact equality between self and other.

Parameters:

• self (StorageT) –

• other (Any) –

Return type:

bool

subs(*args, **kwargs)

Substitute given values of each scalar element into a new instance.

Parameters:

• self (StorageT) –

• args (Any) –

• kwargs (Any) –

Return type:

StorageT

simplify()

Simplify each scalar element into a new instance.

Parameters:

self (StorageT) –

Return type:

StorageT

classmethod symbolic(name, **kwargs)

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:

StorageT

evalf()

Numerical evaluation.

Parameters:

self (StorageT) –

Return type:

StorageT

__hash__()

Hash this object in immutable form, by combining all their scalar hashes.

NOTE(hayk, nathan): This is somewhat dangerous because we don’t always guarantee that Storage objects are immutable (e.g. sf.Matrix). If you add this object as a key to a dict, modify it, and access the dict, it will show up as another key because it breaks the abstraction that an object will maintain the same hash over its lifetime.

Return type:

int

class Matrix(*args, **kwargs)

Bases: Storage

Matrix type that wraps the SymPy Matrix class. Care has been taken to allow this class to create fixed-size child classes like Matrix31. Anytime __new__() is called, the appropriate fixed size class is returned rather than the type of the arguments. The API is meant to parallel the way Eigen’s C++ matrix classes work with dynamic and fixed sizes, as well as internal use cases within SymPy and SymEngine.

Examples:

1) Matrix32()  # Zero constructed Matrix32
2) Matrix(sm.Matrix([[1, 2], [3, 4]]))  # Matrix22 with [1, 2, 3, 4] data
3A) Matrix([[1, 2], [3, 4]])  # Matrix22 with [1, 2, 3, 4] data
3B) Matrix22([1, 2, 3, 4])  # Matrix22 with [1, 2, 3, 4] data (must matched fixed shape)
3C) Matrix([1, 2, 3, 4])  # Matrix41 with [1, 2, 3, 4] data - column vector assumed
4) Matrix(4, 3)  # Zero constructed Matrix43
5) Matrix(2, 2, [1, 2, 3, 4])  # Matrix22 with [1, 2, 3, 4] data (first two are shape)
6) Matrix(2, 2, lambda row, col: row + col)  # Matrix22 with [0, 1, 1, 2] data
7) Matrix22(1, 2, 3, 4)  # Matrix22 with [1, 2, 3, 4] data (must match fixed length)

References

https://docs.sympy.org/latest/tutorial/matrices.html https://eigen.tuxfamily.org/dox/group__TutorialMatrixClass.html https://en.wikipedia.org/wiki/Vector_space

Matrix does not implement the group or lie group concepts using instance/class methods directly, because we want it to represent the group R^{NxM}, not GL(n), which leads to the identity and inverse methods being confusingly named. For the group ops and lie group ops, use symforce.ops.group_ops.GroupOps and symforce.ops.lie_group_ops.LieGroupOps respectively, which use the implementation in symforce.ops.impl.vector_class_lie_group_ops of the R^{NxM} group under matrix addition. For the identity matrix and inverse matrix, see Matrix.eye() and Matrix.inv() respectively.

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

MatrixT = ~MatrixT

SHAPE = (-1, -1)

static __new__(cls, *args, **kwargs)

Beast of a method for creating a Matrix. Handles a variety of construction use cases and always returns a fixed size child class of Matrix rather than Matrix itself. The available construction options depend on whether cls is a fixed size type or not. See the Matrix docstring for a summary of the construction options.

Parameters:

• args (Any) –

• kwargs (Any) –

Return type:

Matrix

property rows: int

property cols: int

property shape: Tuple[int, int]

property is_Matrix: bool

classmethod storage_dim()

Dimension of underlying storage

Return type:

int

classmethod from_storage(vec)

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

Parameters:

vec (_T.Union[_T.Sequence[_T.Scalar], Matrix]) –

Return type:

MatrixT

to_storage()

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 tangent_dim()

Return type:

int

classmethod from_tangent(vec, epsilon=0.0)

Parameters:

• vec (_T.Sequence[_T.Scalar]) –

• epsilon (_T.Scalar) –

Return type:

MatrixT

to_tangent(epsilon=0.0)

Parameters:

epsilon (float) –

Return type:

List[float]

storage_D_tangent(epsilon=0.0)

Parameters:

epsilon (float) –

Return type:

Matrix

tangent_D_storage(epsilon=0.0)

Parameters:

epsilon (float) –

Return type:

Matrix

classmethod zero()

Matrix of zeros.

Return type:

MatrixT

classmethod zeros(rows, cols)

Matrix of zeros.

Parameters:

• rows (int) –

• cols (int) –

Return type:

MatrixT

classmethod one()

Matrix of ones.

Return type:

MatrixT

classmethod ones(rows, cols)

Matrix of ones.

Parameters:

• rows (int) –

• cols (int) –

Return type:

MatrixT

classmethod diag(diagonal)

Construct a square matrix from the diagonal.

Parameters:

diagonal (_T.Sequence[_T.Scalar]) –

Return type:

MatrixT

classmethod eye(rows=None, cols=None)

Construct an identity matrix

If neither rows nor cols is provided, this must be called as a class method on a fixed-size class.

If rows is provided, returns a square identity matrix of shape (rows x rows).

If rows and cols are provided, returns a (rows x cols) matrix, with ones on the diagonal.

Parameters:

• rows (_T.Optional[int]) –

• cols (_T.Optional[int]) –

Return type:

MatrixT

det()

Determinant of the matrix.

Return type:

float

inv(method='LU')

Inverse of the matrix.

Parameters:

• self (MatrixT) –

• method (str) –

Return type:

MatrixT

classmethod symbolic(name, **kwargs)

Create with symbols.

Parameters:

• name (str) – Name prefix of the symbols

• **kwargs (dict) – Forwarded to sf.Symbol

Return type:

MatrixT

row_join(right)

Concatenates self with another matrix on the right

Parameters:

right (Matrix) –

Return type:

Matrix

col_join(bottom)

Concatenates self with another matrix below

Parameters:

bottom (Matrix) –

Return type:

Matrix

classmethod block_matrix(array)

Constructs a matrix from block elements.

For example:

[[Matrix22(...), Matrix23(...)], [Matrix11(...), Matrix14(...)]]

constructs a Matrix35 with elements equal to given blocks

Parameters:

array (Sequence[Sequence[Matrix]]) –

Return type:

Matrix

simplify(*args, **kwargs)

Simplify this expression.

This overrides the sympy implementation because that clobbers the class type.

Parameters:

• args (Any) –

• kwargs (Any) –

Return type:

Matrix

limit(*args, **kwargs)

Take the limit at z = z0

This overrides the sympy implementation because that clobbers the class type.

Parameters:

• args (Any) –

• kwargs (Any) –

Return type:

Matrix

jacobian(X, tangent_space=True, epsilon=0.0)

Compute the jacobian with respect to the tangent space of X if tangent_space = True, otherwise returns the jacobian with respect to the storage elements of X.

Note that the jacobian is always 2D, even if self or X are matrices - it will be M x N, where M is the size of self and N is the size of X

Parameters:

• X (Any) –

• tangent_space (bool) –

• epsilon (float) –

Return type:

Matrix

diff(*args)

Differentiate w.r.t. a scalar.

Parameters:

args (float) –

Return type:

Matrix

property T: Matrix

Matrix Transpose

transpose()

Matrix Transpose

Return type:

Matrix

lower_triangle()

Returns the lower triangle (including diagonal) of self

self must be square

Parameters:

self (MatrixT) –

Return type:

MatrixT

class Triangle(value)

Bases: Enum

An enumeration.

LOWER = 'lower'

UPPER = 'upper'

symmetric_copy(upper_or_lower)

Returns a symmetric copy of self by copying the lower or upper triangle to the opposite triangle.

Parameters:

• upper_or_lower (Triangle) – The triangle to copy to the opposite triangle

• self (MatrixT) –

Return type:

MatrixT

reshape(rows, cols)

Parameters:

• rows (int) –

• cols (int) –

Return type:

Matrix

dot(other)

Dot product, also known as inner product.

Only supports mapping 1 x n or n x 1 Matrices to scalars. Note that both matrices must have the same shape.

Parameters:

other (Matrix) –

Return type:

float

cross(other)

Cross product.

Parameters:

• self (MatrixT) –

• other (MatrixT) –

Return type:

Vector3

squared_norm()

Squared norm of a vector, equivalent to the dot product with itself.

Return type:

float

norm(epsilon=0.0)

Norm of a vector (square root of magnitude).

Parameters:

epsilon (float) –

Return type:

float

normalized(epsilon=0.0)

Returns a unit vector in this direction (divide by norm).

Parameters:

• self (MatrixT) –

• epsilon (_T.Scalar) –

Return type:

MatrixT

clamp_norm(max_norm, epsilon=0.0)

Clamp a vector to the given norm in a safe/differentiable way.

Is NOT safe if max_norm can be negative, or if derivatives are needed w.r.t. max_norm and max_norm can be 0 or small enough that max_squared_norm / squared_norm is truncated to 0 in the particular floating point type being used (e.g. all of these are true if max_norm is optimized).

Currently only L2 norm is supported

Parameters:

• self (MatrixT) –

• max_norm (_T.Scalar) –

• epsilon (_T.Scalar) –

Return type:

MatrixT

multiply_elementwise(rhs)

Do the elementwise multiplication between self and rhs, and return the result as a new Matrix

Parameters:

• self (MatrixT) –

• rhs (MatrixT) –

Return type:

MatrixT

applyfunc(func)

Apply a unary operation to every scalar.

Parameters:

• self (MatrixT) –

• func (_T.Callable) –

Return type:

MatrixT

__getitem__(item)

Get a scalar value or submatrix slice.

Unlike sympy, for 1D matrices the submatrix slice is returned as a 1D matrix instead of as a list.

Parameters:

item (Any) –

Return type:

Any

row(r)

Extract a row of the matrix

Parameters:

r (int) –

Return type:

Matrix

col(c)

Extract a column of the matrix

Parameters:

c (int) –

Return type:

Matrix

__neg__()

Negate matrix.

Parameters:

self (MatrixT) –

Return type:

MatrixT

__add__(right)

Add a scalar or matrix to this matrix.

Parameters:

• self (MatrixT) –

• right (_T.Union[_T.Scalar, MatrixT]) –

Return type:

MatrixT

__sub__(right)

Subtract a scalar or matrix from this matrix.

Parameters:

• self (MatrixT) –

• right (_T.Union[_T.Scalar, MatrixT]) –

Return type:

MatrixT

__mul__(right)

Multiply a matrix by a scalar or matrix

Parameters:

right (_T.Union[MatrixT, _T.Scalar, Matrix, sf.sympy.MutableDenseMatrix]) –

Return type:

_T.Union[MatrixT, Matrix]

__rmul__(left)

Left multiply a matrix by a scalar or matrix

Parameters:

left (_T.Union[MatrixT, _T.Scalar, Matrix, sf.sympy.MutableDenseMatrix]) –

Return type:

_T.Union[MatrixT, Matrix]

__truediv__(right)

Divide a matrix by a scalar or a matrix (which takes the inverse).

Parameters:

right (_T.Union[MatrixT, _T.Scalar, Matrix, sf.sympy.MutableDenseMatrix]) –

Return type:

_T.Union[MatrixT, Matrix]

compute_AtA(lower_only=False)

Compute a symmetric product A.transpose() * A

Parameters:

lower_only (bool) – If given, only fill the lower half and set upper to zero

Returns:

(Matrix (N, N)) – Symmetric matrix AtA = self.transpose() * self

Return type:

Matrix

LU()

LU matrix decomposition

Return type:

Tuple[Matrix, Matrix] | Tuple[Matrix, Matrix, List[Tuple[int, int]]]

LDL()

LDL matrix decomposition (stable cholesky)

Return type:

Tuple[Matrix, Matrix]

FFLU()

Fraction-free LU matrix decomposition

Return type:

Tuple[Matrix, Matrix]

FFLDU()

Fraction-free LDU matrix decomposition

Return type:

Tuple[Matrix, Matrix, Matrix] | Tuple[Matrix, Matrix, Matrix, Matrix]

solve(b, method='LU')

Solve a linear system using the given method.

Parameters:

• b (Matrix) –

• method (str) –

Return type:

Matrix

static are_parallel(a, b, tolerance)

Returns 1 if a and b are parallel within tolerance, and 0 otherwise.

Parameters:

• a (Matrix31) –

• b (Matrix31) –

• tolerance (float) –

Return type:

float

static skew_symmetric(a)

Compute a skew-symmetric matrix of given a 3-vector.

Parameters:

a (Matrix31) –

Return type:

Matrix33

evalf()

Perform numerical evaluation of each element in the matrix.

Return type:

Matrix

to_list()

Convert to a nested list

Return type:

List[List[float]]

to_flat_list()

Convert to a flattened list

Return type:

List[float]

classmethod from_flat_list(vec)

Parameters:

vec (Sequence[float]) –

Return type:

Matrix

to_numpy(scalar_type=<class 'numpy.float64'>)

Convert to a numpy array.

Parameters:

scalar_type (type) –

Return type:

ndarray

classmethod column_stack(*columns)

Take a sequence of 1-D vectors and stack them as columns to make a single 2-D Matrix.

Parameters:

columns (Matrix) – 1-D vectors

Return type:

Matrix

is_vector()

Return type:

bool

static init_printing()

Initialize SymPy pretty printing

_ipython_display_ is sufficient in Jupyter, but this covers other locations

Return type:

None

class Matrix11(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (1, 1)

class Matrix21(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (2, 1)

static unit_x()

The unit vector [1, 0]

Return type:

Matrix21

static unit_y()

The unit vector [0, 1]

Return type:

Matrix21

property x: float

The entry self[0, 0]

property y: float

The entry self[1, 0]

class Matrix31(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (3, 1)

static unit_x()

The unit vector [1, 0, 0]

Return type:

Matrix31

static unit_y()

The unit vector [0, 1, 0]

Return type:

Matrix31

static unit_z()

The unit vector [0, 0, 1]

Return type:

Matrix31

property x: float

The entry self[0, 0]

property y: float

The entry self[1, 0]

property z: float

The entry self[2, 0]

class Matrix41(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (4, 1)

class Matrix51(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (5, 1)

class Matrix61(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (6, 1)

class Matrix71(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (7, 1)

class Matrix81(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (8, 1)

class Matrix91(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (9, 1)

class Matrix12(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (1, 2)

class Matrix22(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (2, 2)

class Matrix32(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (3, 2)

class Matrix42(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (4, 2)

class Matrix52(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (5, 2)

class Matrix62(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (6, 2)

class Matrix72(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (7, 2)

class Matrix82(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (8, 2)

class Matrix92(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (9, 2)

class Matrix13(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (1, 3)

class Matrix23(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (2, 3)

class Matrix33(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (3, 3)

class Matrix43(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (4, 3)

class Matrix53(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (5, 3)

class Matrix63(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (6, 3)

class Matrix73(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (7, 3)

class Matrix83(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (8, 3)

class Matrix93(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (9, 3)

class Matrix14(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (1, 4)

class Matrix24(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (2, 4)

class Matrix34(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (3, 4)

class Matrix44(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (4, 4)

class Matrix54(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (5, 4)

class Matrix64(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (6, 4)

class Matrix74(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (7, 4)

class Matrix84(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (8, 4)

class Matrix94(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (9, 4)

class Matrix15(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (1, 5)

class Matrix25(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (2, 5)

class Matrix35(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (3, 5)

class Matrix45(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (4, 5)

class Matrix55(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (5, 5)

class Matrix65(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (6, 5)

class Matrix75(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (7, 5)

class Matrix85(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (8, 5)

class Matrix95(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (9, 5)

class Matrix16(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (1, 6)

class Matrix26(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (2, 6)

class Matrix36(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (3, 6)

class Matrix46(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (4, 6)

class Matrix56(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (5, 6)

class Matrix66(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (6, 6)

class Matrix76(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (7, 6)

class Matrix86(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (8, 6)

class Matrix96(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (9, 6)

class Matrix17(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (1, 7)

class Matrix27(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (2, 7)

class Matrix37(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (3, 7)

class Matrix47(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (4, 7)

class Matrix57(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (5, 7)

class Matrix67(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (6, 7)

class Matrix77(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (7, 7)

class Matrix87(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (8, 7)

class Matrix97(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (9, 7)

class Matrix18(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (1, 8)

class Matrix28(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (2, 8)

class Matrix38(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (3, 8)

class Matrix48(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (4, 8)

class Matrix58(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (5, 8)

class Matrix68(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (6, 8)

class Matrix78(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (7, 8)

class Matrix88(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (8, 8)

class Matrix98(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (9, 8)

class Matrix19(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (1, 9)

class Matrix29(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (2, 9)

class Matrix39(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (3, 9)

class Matrix49(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (4, 9)

class Matrix59(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (5, 9)

class Matrix69(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (6, 9)

class Matrix79(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (7, 9)

class Matrix89(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (8, 9)

class Matrix99(*args, **kwargs)

Bases: Matrix

Parameters:

• args (_T.Any) –

• kwargs (_T.Any) –

Return type:

Matrix

SHAPE = (9, 9)

m

alias of Matrix99

matrix_type_from_shape(shape)

Return a fixed size matrix type (like Matrix32) given a shape

Either uses the statically defined ones or dynamically creates a new one if not available.

Parameters:

shape (Tuple[int, int]) –

Return type:

Type[Matrix]

M

alias of Matrix

Vector1

alias of Matrix11

Vector2

alias of Matrix21

Vector3

alias of Matrix31

Vector4

alias of Matrix41

Vector5

alias of Matrix51

Vector6

alias of Matrix61

Vector7

alias of Matrix71

Vector8

alias of Matrix81

Vector9

alias of Matrix91

V1

alias of Matrix11

V2

alias of Matrix21

V3

alias of Matrix31

V4

alias of Matrix41

V5

alias of Matrix51

V6

alias of Matrix61

V7

alias of Matrix71

V8

alias of Matrix81

V9

alias of Matrix91

M11

alias of Matrix11

M21

alias of Matrix21

M31

alias of Matrix31

M41

alias of Matrix41

M51

alias of Matrix51

M61

alias of Matrix61

M71

alias of Matrix71

M81

alias of Matrix81

M91

alias of Matrix91

M12

alias of Matrix12

M22

alias of Matrix22

M32

alias of Matrix32

M42

alias of Matrix42

M52

alias of Matrix52

M62

alias of Matrix62

M72

alias of Matrix72

M82

alias of Matrix82

M92

alias of Matrix92

M13

alias of Matrix13

M23

alias of Matrix23

M33

alias of Matrix33

M43

alias of Matrix43

M53

alias of Matrix53

M63

alias of Matrix63

M73

alias of Matrix73

M83

alias of Matrix83

M93

alias of Matrix93

M14

alias of Matrix14

M24

alias of Matrix24

M34

alias of Matrix34

M44

alias of Matrix44

M54

alias of Matrix54

M64

alias of Matrix64

M74

alias of Matrix74

M84

alias of Matrix84

M94

alias of Matrix94

M15

alias of Matrix15

M25

alias of Matrix25

M35

alias of Matrix35

M45

alias of Matrix45

M55

alias of Matrix55

M65

alias of Matrix65

M75

alias of Matrix75

M85

alias of Matrix85

M95

alias of Matrix95

M16

alias of Matrix16

M26

alias of Matrix26

M36

alias of Matrix36

M46

alias of Matrix46

M56

alias of Matrix56

M66

alias of Matrix66

M76

alias of Matrix76

M86

alias of Matrix86

M96

alias of Matrix96

M17

alias of Matrix17

M27

alias of Matrix27

M37

alias of Matrix37

M47

alias of Matrix47

M57

alias of Matrix57

M67

alias of Matrix67

M77

alias of Matrix77

M87

alias of Matrix87

M97

alias of Matrix97

M18

alias of Matrix18

M28

alias of Matrix28

M38

alias of Matrix38

M48

alias of Matrix48

M58

alias of Matrix58

M68

alias of Matrix68

M78

alias of Matrix78

M88

alias of Matrix88

M98

alias of Matrix98

M19

alias of Matrix19

M29

alias of Matrix29

M39

alias of Matrix39

M49

alias of Matrix49

M59

alias of Matrix59

M69

alias of Matrix69

M79

alias of Matrix79

M89

alias of Matrix89

M99

alias of Matrix99

I1(rows=None, cols=None)

Construct an identity matrix

If neither rows nor cols is provided, this must be called as a class method on a fixed-size class.

If rows is provided, returns a square identity matrix of shape (rows x rows).

If rows and cols are provided, returns a (rows x cols) matrix, with ones on the diagonal.

Parameters:

• rows (_T.Optional[int]) –

• cols (_T.Optional[int]) –

Return type:

MatrixT

I11(rows=None, cols=None)

Construct an identity matrix

If neither rows nor cols is provided, this must be called as a class method on a fixed-size class.

If rows is provided, returns a square identity matrix of shape (rows x rows).

If rows and cols are provided, returns a (rows x cols) matrix, with ones on the diagonal.

Parameters:

• rows (_T.Optional[int]) –

• cols (_T.Optional[int]) –

Return type:

MatrixT

I2(rows=None, cols=None)

Construct an identity matrix

If neither rows nor cols is provided, this must be called as a class method on a fixed-size class.

If rows is provided, returns a square identity matrix of shape (rows x rows).

If rows and cols are provided, returns a (rows x cols) matrix, with ones on the diagonal.

Parameters:

• rows (_T.Optional[int]) –

• cols (_T.Optional[int]) –

Return type:

MatrixT

I22(rows=None, cols=None)

Construct an identity matrix

If neither rows nor cols is provided, this must be called as a class method on a fixed-size class.

If rows is provided, returns a square identity matrix of shape (rows x rows).

If rows and cols are provided, returns a (rows x cols) matrix, with ones on the diagonal.

Parameters:

• rows (_T.Optional[int]) –

• cols (_T.Optional[int]) –

Return type:

MatrixT

I3(rows=None, cols=None)

Construct an identity matrix

If neither rows nor cols is provided, this must be called as a class method on a fixed-size class.

If rows is provided, returns a square identity matrix of shape (rows x rows).

If rows and cols are provided, returns a (rows x cols) matrix, with ones on the diagonal.

Parameters:

• rows (_T.Optional[int]) –

• cols (_T.Optional[int]) –

Return type:

MatrixT

I33(rows=None, cols=None)

Construct an identity matrix

If neither rows nor cols is provided, this must be called as a class method on a fixed-size class.

If rows is provided, returns a square identity matrix of shape (rows x rows).

If rows and cols are provided, returns a (rows x cols) matrix, with ones on the diagonal.

Parameters:

• rows (_T.Optional[int]) –

• cols (_T.Optional[int]) –

Return type:

MatrixT

I4(rows=None, cols=None)

Construct an identity matrix

If neither rows nor cols is provided, this must be called as a class method on a fixed-size class.

If rows is provided, returns a square identity matrix of shape (rows x rows).

If rows and cols are provided, returns a (rows x cols) matrix, with ones on the diagonal.

Parameters:

• rows (_T.Optional[int]) –

• cols (_T.Optional[int]) –

Return type:

MatrixT

I44(rows=None, cols=None)

Construct an identity matrix

If neither rows nor cols is provided, this must be called as a class method on a fixed-size class.

If rows is provided, returns a square identity matrix of shape (rows x rows).

If rows and cols are provided, returns a (rows x cols) matrix, with ones on the diagonal.

Parameters:

• rows (_T.Optional[int]) –

• cols (_T.Optional[int]) –

Return type:

MatrixT

I5(rows=None, cols=None)

Construct an identity matrix

If neither rows nor cols is provided, this must be called as a class method on a fixed-size class.

If rows is provided, returns a square identity matrix of shape (rows x rows).

If rows and cols are provided, returns a (rows x cols) matrix, with ones on the diagonal.

Parameters:

• rows (_T.Optional[int]) –

• cols (_T.Optional[int]) –

Return type:

MatrixT

I55(rows=None, cols=None)

Construct an identity matrix

If neither rows nor cols is provided, this must be called as a class method on a fixed-size class.

If rows is provided, returns a square identity matrix of shape (rows x rows).

If rows and cols are provided, returns a (rows x cols) matrix, with ones on the diagonal.

Parameters:

• rows (_T.Optional[int]) –

• cols (_T.Optional[int]) –

Return type:

MatrixT

I6(rows=None, cols=None)

Construct an identity matrix

If neither rows nor cols is provided, this must be called as a class method on a fixed-size class.

If rows is provided, returns a square identity matrix of shape (rows x rows).

If rows and cols are provided, returns a (rows x cols) matrix, with ones on the diagonal.

Parameters:

• rows (_T.Optional[int]) –

• cols (_T.Optional[int]) –

Return type:

MatrixT

I66(rows=None, cols=None)

Construct an identity matrix

If neither rows nor cols is provided, this must be called as a class method on a fixed-size class.

If rows is provided, returns a square identity matrix of shape (rows x rows).

If rows and cols are provided, returns a (rows x cols) matrix, with ones on the diagonal.

Parameters:

• rows (_T.Optional[int]) –

• cols (_T.Optional[int]) –

Return type:

MatrixT

I7(rows=None, cols=None)

Construct an identity matrix

If neither rows nor cols is provided, this must be called as a class method on a fixed-size class.

If rows is provided, returns a square identity matrix of shape (rows x rows).

If rows and cols are provided, returns a (rows x cols) matrix, with ones on the diagonal.

Parameters:

• rows (_T.Optional[int]) –

• cols (_T.Optional[int]) –

Return type:

MatrixT

I77(rows=None, cols=None)

Construct an identity matrix

If neither rows nor cols is provided, this must be called as a class method on a fixed-size class.

If rows is provided, returns a square identity matrix of shape (rows x rows).

If rows and cols are provided, returns a (rows x cols) matrix, with ones on the diagonal.

Parameters:

• rows (_T.Optional[int]) –

• cols (_T.Optional[int]) –

Return type:

MatrixT

I8(rows=None, cols=None)

Construct an identity matrix

If neither rows nor cols is provided, this must be called as a class method on a fixed-size class.

If rows is provided, returns a square identity matrix of shape (rows x rows).

If rows and cols are provided, returns a (rows x cols) matrix, with ones on the diagonal.

Parameters:

• rows (_T.Optional[int]) –

• cols (_T.Optional[int]) –

Return type:

MatrixT

I88(rows=None, cols=None)

Construct an identity matrix

If neither rows nor cols is provided, this must be called as a class method on a fixed-size class.

If rows is provided, returns a square identity matrix of shape (rows x rows).

If rows and cols are provided, returns a (rows x cols) matrix, with ones on the diagonal.

Parameters:

• rows (_T.Optional[int]) –

• cols (_T.Optional[int]) –

Return type:

MatrixT

I9(rows=None, cols=None)

Construct an identity matrix

If neither rows nor cols is provided, this must be called as a class method on a fixed-size class.

If rows is provided, returns a square identity matrix of shape (rows x rows).

If rows and cols are provided, returns a (rows x cols) matrix, with ones on the diagonal.

Parameters:

• rows (_T.Optional[int]) –

• cols (_T.Optional[int]) –

Return type:

MatrixT

I99(rows=None, cols=None)

Construct an identity matrix

If neither rows nor cols is provided, this must be called as a class method on a fixed-size class.

If rows is provided, returns a square identity matrix of shape (rows x rows).

If rows and cols are provided, returns a (rows x cols) matrix, with ones on the diagonal.

Parameters:

• rows (_T.Optional[int]) –

• cols (_T.Optional[int]) –

Return type:

MatrixT

class VectorClassLieGroupOps(*args, **kwds)

Bases: ClassStorageOps, AbstractVectorLieGroupOps[Storage]

A generic implementation of Lie group ops for subclasses of symforce.ops.interfaces.storage.Storage.

Treats the subclass like R^n where the vector is the storage representation.

To elaborate, treats the subclass as a Lie group whose identity is the zero vector, group operation is vector addition, and whose vector representation is given by the to_storage operation.

class Pose2(R=None, t=None)

Bases: LieGroup

Group of two-dimensional rigid body transformations - R2 x SO(2).

The storage space is a complex (real, imag) for rotation followed by a position (x, y).

The tangent space is one angle for rotation followed by two elements for translation in the non-rotated frame.

For Lie group enthusiasts: This class is on the PRODUCT manifold. On this class, the group operations (e.g. compose and between) operate as you’d expect for a Pose or SE(2), but the manifold operations (e.g. retract and local_coordinates) operate on the product manifold SO(2) x R2. This means that:

• retract(a, vec) != compose(a, from_tangent(vec))

• local_coordinates(a, b) != to_tangent(between(a, b))

• There is no hat operator, because from_tangent/to_tangent is not the matrix exp/log

If you need a type that has these properties in symbolic expressions, you should use symforce.geo.unsupported.pose2_se2.Pose2_SE2. There is no runtime equivalent of Pose2_SE2, see the docstring on that class for more information.

Parameters:

• R (T.Optional[Rot2]) –

• t (T.Optional[Vector2]) –

Pose2T = ~Pose2T

rotation()

Accessor for the rotation component

Does not make a copy. Also accessible as self.R

Return type:

Rot2

position()

Accessor for the position component

Does not make a copy. Also accessible as self.t

Return type:

Matrix21

classmethod storage_dim()

Dimension of underlying storage

Return type:

int

to_storage()

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)

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

Parameters:

vec (Sequence[float]) –

Return type:

Pose2

classmethod symbolic(name, **kwargs)

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

Parameters:

• name (str) –

• kwargs (T.Any) –

Return type:

Pose2T

classmethod identity()

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

Return type:

Pose2

compose(other)

Apply the group operation with other.

Parameters:

other (Pose2) –

Return type:

Pose2

inverse()

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

Return type:

Pose2

classmethod tangent_dim()

Dimension of the embedded manifold

Return type:

int

classmethod from_tangent(v, epsilon=0.0)

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

Parameters:

• v (Sequence[float]) –

• epsilon (float) –

Return type:

Pose2

to_tangent(epsilon=0.0)

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

Parameters:

epsilon (float) –

Return type:

List[float]

storage_D_tangent(epsilon=0.0)

Note: generated from symforce/notebooks/storage_D_tangent.ipynb

Parameters:

epsilon (float) –

Return type:

Matrix

tangent_D_storage(epsilon=0.0)

Note: generated from symforce/notebooks/tangent_D_storage.ipynb

Parameters:

epsilon (float) –

Return type:

Matrix

retract(vec, epsilon=0.0)

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

Conceptually represents self + vec if self is a vector.

Implementation retracts the R and t components separately, which is different from compose(self, from_tangent(vec)). See the class docstring for more information.

Parameters:

• self (Pose2) –

• vec (Sequence[float]) –

• epsilon (float) –

Return type:

Pose2

local_coordinates(b, epsilon=0.0)

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

Tangent space perturbation that conceptually represents b - self if self is a vector.

Implementation takes local_coordinates of the R and t components separately, which is different from to_tangent(between(self, b)). See the class docstring for more information.

Parameters:

• self (Pose2T) –

• b (Pose2T) –

• epsilon (T.Scalar) –

Return type:

T.List[T.Scalar]

__mul__(right)

Left-multiply with a compatible quantity.

Parameters:

right (Pose2 | Matrix21) –

Return type:

Pose2 | Matrix21

to_homogenous_matrix()

A matrix representation of this element in the Euclidean space that contains it.

Returns:

3x3 Matrix

Return type:

Matrix

class Pose3(R=None, t=None)

Bases: LieGroup

Group of three-dimensional rigid body transformations - SO(3) x R3.

The storage is a quaternion (x, y, z, w) for rotation followed by position (x, y, z).

The tangent space is 3 elements for rotation followed by 3 elements for translation in the non-rotated frame.

For Lie group enthusiasts: This class is on the PRODUCT manifold. On this class, the group operations (e.g. compose and between) operate as you’d expect for a Pose or SE(3), but the manifold operations (e.g. retract and local_coordinates) operate on the product manifold SO(3) x R3. This means that:

• retract(a, vec) != compose(a, from_tangent(vec))

• local_coordinates(a, b) != to_tangent(between(a, b))

• There is no hat operator, because from_tangent/to_tangent is not the matrix exp/log

If you need a type that has these properties in symbolic expressions, you should use symforce.geo.unsupported.pose3_se3.Pose3_SE3. There is no runtime equivalent of Pose3_SE3, see the docstring on that class for more information.

Parameters:

• R (T.Optional[Rot3]) –

• t (T.Optional[Vector3]) –

Pose3T = ~Pose3T

rotation()

Accessor for the rotation component

Does not make a copy. Also accessible as self.R

Return type:

Rot3

position()

Accessor for the position component

Does not make a copy. Also accessible as self.t

Return type:

Matrix31

classmethod storage_dim()

Dimension of underlying storage

Return type:

int

to_storage()

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)

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

Parameters:

vec (T.Sequence[T.Scalar]) –

Return type:

Pose3T

classmethod symbolic(name, **kwargs)

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

Parameters:

• name (str) –

• kwargs (T.Any) –

Return type:

Pose3T

classmethod identity()

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

Return type:

Pose3T

compose(other)

Apply the group operation with other.

Parameters:

• self (Pose3T) –

• other (Pose3T) –

Return type:

Pose3T

inverse()

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

Parameters:

self (Pose3T) –

Return type:

Pose3T

classmethod tangent_dim()

Dimension of the embedded manifold

Return type:

int

classmethod from_tangent(v, epsilon=0.0)

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

Parameters:

• v (T.Sequence[T.Scalar]) –

• epsilon (T.Scalar) –

Return type:

Pose3T

to_tangent(epsilon=0.0)

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

Parameters:

• self (Pose3T) –

• epsilon (T.Scalar) –

Return type:

T.List[T.Scalar]

storage_D_tangent(epsilon=0.0)

Note: generated from symforce/notebooks/storage_D_tangent.ipynb

Parameters:

• self (Pose3T) –

• epsilon (T.Scalar) –

Return type:

Matrix

tangent_D_storage(epsilon=0.0)

Note: generated from symforce/notebooks/tangent_D_storage.ipynb

Parameters:

• self (Pose3T) –

• epsilon (sf.Scalar) –

Return type:

Matrix

retract(vec, epsilon=0.0)

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

Conceptually represents self + vec if self is a vector.

Implementation retracts the R and t components separately, which is different from compose(self, from_tangent(vec)). See the class docstring for more information.

Parameters:

• self (Pose3T) –

• vec (T.Sequence[T.Scalar]) –

• epsilon (T.Scalar) –

Return type:

Pose3T

local_coordinates(b, epsilon=0.0)

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

Tangent space perturbation that conceptually represents b - self if self is a vector.

Implementation takes local_coordinates of the R and t components separately, which is different from to_tangent(between(self, b)). See the class docstring for more information.

Parameters:

• self (Pose3T) –

• b (Pose3T) –

• epsilon (T.Scalar) –

Return type:

T.List[T.Scalar]

__mul__(right)

Left-multiply with a compatible quantity.

Parameters:

• self (Pose3T) –

• right (T.Union[Pose3T, Vector3]) –

Return type:

T.Union[Pose3T, Vector3]

to_homogenous_matrix()

4x4 matrix representing this pose transform.

Return type:

Matrix

class Quaternion(xyz, w)

Bases: Group

Unit quaternions, also known as versors, provide a convenient mathematical notation for representing orientations and rotations of objects in three dimensions. Compared to Euler angles they are simpler to compose and avoid the problem of gimbal lock. Compared to rotation matrices they are more compact, more numerically stable, and more efficient.

Storage is (x, y, z, w).

References

https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation

Parameters:

• xyz (Vector3) –

• w (T.Scalar) –

property x: float

property y: float

property z: float

classmethod storage_dim()

Dimension of underlying storage

Return type:

int

to_storage()

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)

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

Parameters:

vec (Sequence[float]) –

Return type:

Quaternion

classmethod symbolic(name, **kwargs)

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:

Quaternion

classmethod identity()

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

Return type:

Quaternion

compose(other)

Apply the group operation with other.

Parameters:

other (Quaternion) –

Return type:

Quaternion

inverse()

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

Return type:

Quaternion

__mul__(right)

Quaternion multiplication.

Parameters:

right (Quaternion) –

Returns:

Quaternion

Return type:

Quaternion

__neg__()

Negation of all entries.

Returns:

Quaternion

Return type:

Quaternion

__add__(right)

Quaternion addition.

Parameters:

right (Quaternion) –

Returns:

Quaternion

Return type:

Quaternion

__truediv__(scalar)

Scalar division.

Parameters:

scalar (Scalar) –

Returns:

Quaternion

Return type:

Quaternion

classmethod zero()

Construct with all zeros.

Returns:

Quaternion

Return type:

Quaternion

squared_norm()

Squared norm when considering the quaternion as 4-tuple.

Returns:

Scalar

Return type:

float

conj()

Quaternion conjugate.

Returns:

Quaternion

Return type:

Quaternion

classmethod unit_random()

Generate a random unit quaternion

Return type:

Quaternion

classmethod unit_random_from_uniform_samples(u1, u2, u3, pi=pi)

Generate a random unit quaternion from three variables uniformly sampled in [0, 1].

Reference:

http://planning.cs.uiuc.edu/node198.html

Parameters:

• u1 (float) –

• u2 (float) –

• u3 (float) –

• pi (float) –

Return type:

Quaternion

class Rot2(z=None)

Bases: LieGroup

Group of two-dimensional orthogonal matrices with determinant +1, representing rotations in 2D space. Backed by a complex number.

Parameters:

z (T.Optional[Complex]) –

classmethod storage_dim()

Dimension of underlying storage

Return type:

int

to_storage()

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)

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

Parameters:

vec (Sequence[float]) –

Return type:

Rot2

classmethod symbolic(name, **kwargs)

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:

Rot2

classmethod identity()

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

Return type:

Rot2

compose(other)

Apply the group operation with other.

Parameters:

other (Rot2) –

Return type:

Rot2

inverse()

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

Return type:

Rot2

classmethod tangent_dim()

Dimension of the embedded manifold

Return type:

int

classmethod from_tangent(v, epsilon=0.0)

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

Parameters:

• v (Sequence[float]) –

• epsilon (float) –

Return type:

Rot2

to_tangent(epsilon=0.0)

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

Parameters:

epsilon (float) –

Return type:

List[float]

classmethod hat(vec)

Parameters:

vec (Sequence[float]) –

Return type:

Matrix22

storage_D_tangent(epsilon=0.0)

Note: generated from symforce/notebooks/storage_D_tangent.ipynb

Parameters:

epsilon (float) –

Return type:

Matrix21

tangent_D_storage(epsilon=0.0)

Note: generated from symforce/notebooks/tangent_D_storage.ipynb

Parameters:

epsilon (float) –

Return type:

Matrix12

__mul__(right)

Left-multiplication. Either rotation concatenation or point transform.

Parameters:

right (Rot2 | Matrix21) –

Return type:

Rot2 | Matrix21

classmethod from_angle(theta)

Create a Rot2 from an angle theta in radians

This is equivalent to from_tangent([theta])

Parameters:

theta (float) –

Return type:

Rot2

to_angle(epsilon=0.0)

Get the angle of this Rot2 in radians

This is equivalent to to_tangent()[0]

Parameters:

epsilon (float) –

Return type:

float

to_rotation_matrix()

A matrix representation of this element in the Euclidean space that contains it.

Return type:

Matrix22

classmethod from_rotation_matrix(r)

Create a Rot2 from a 2x2 rotation matrix.

Returns the closest Rot2 to the input matrix, by the Frobenius norm. Will be singular when r[0, 0] == -r[1, 1] and r[0, 1] == r[1, 0] are both true.

See notebooks/rot2_from_rotation_matrix_derivation.ipynb for the derivation.

Parameters:

r (Matrix22) –

Return type:

Rot2

classmethod random()

Generate a random element of SO3.

Return type:

Rot2

classmethod random_from_uniform_sample(u1, pi=pi)

Generate a random element of SO2 from a variable uniformly sampled on [0, 1].

Parameters:

• u1 (float) –

• pi (float) –

Return type:

Rot2

class Rot3(q=None)

Bases: LieGroup

Group of three-dimensional orthogonal matrices with determinant +1, representing rotations in 3D space. Backed by a quaternion with (x, y, z, w) storage.

Parameters:

q (T.Optional[Quaternion]) –

classmethod storage_dim()

Dimension of underlying storage

Return type:

int

to_storage()

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)

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

Parameters:

vec (Sequence[float]) –

Return type:

Rot3

classmethod symbolic(name, **kwargs)

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:

Rot3

classmethod identity()

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

Return type:

Rot3

compose(other)

Apply the group operation with other.

Parameters:

other (Rot3) –

Return type:

Rot3

inverse()

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

Return type:

Rot3

classmethod tangent_dim()

Dimension of the embedded manifold

Return type:

int

classmethod from_tangent(v, epsilon=0.0)

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

Parameters:

• v (Sequence[float]) –

• epsilon (float) –

Return type:

Rot3

to_tangent(epsilon=0.0)

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

Parameters:

epsilon (float) –

Return type:

List[float]

classmethod hat(vec)

Parameters:

vec (Sequence[float]) –

Return type:

Matrix33

storage_D_tangent(epsilon=0.0)

Note: generated from symforce/notebooks/storage_D_tangent.ipynb

Parameters:

epsilon (float) –

Return type:

Matrix43

tangent_D_storage(epsilon=0.0)

Note: generated from symforce/notebooks/tangent_D_storage.ipynb

Parameters:

epsilon (float) –

Return type:

Matrix34

__mul__(right)

Left-multiplication. Either rotation concatenation or point transform.

Parameters:

right (Matrix31 | Rot3) –

Return type:

Matrix31 | Rot3

to_tangent_norm(epsilon=0.0)

Returns the norm of the tangent vector corresponding to this rotation

This is equal to the angle that should be rotated through to get this Rot3, in radians. Using this function directly is usually more efficient than computing the norm of the tangent vector, both in symbolic and generated code; by default, symbolic APIs will not automatically simplify to this

Parameters:

epsilon (float) –

Return type:

float

to_rotation_matrix()

Converts to a rotation matrix

Return type:

Matrix33

classmethod from_rotation_matrix(R, epsilon=0.0)

Construct from a rotation matrix.

Parameters:

• R (Matrix33) –

• epsilon (float) –

Return type:

Rot3

to_yaw_pitch_roll(epsilon=0.0)

Compute the yaw, pitch, and roll Euler angles in radians of this rotation

Euler angles are subject to gimbal lock: https://en.wikipedia.org/wiki/Gimbal_lock

This means that when the pitch is close to +/- pi/2, the yaw and roll angles are not uniquely defined, so the returned values are not unique in this case.

Returns:

• Scalar – Yaw angle [radians]

• Scalar – Pitch angle [radians]

• Scalar – Roll angle [radians]

Parameters:

epsilon (float) –

Return type:

Tuple[float, float, float]

classmethod from_yaw_pitch_roll(yaw=0, pitch=0, roll=0)

Construct from yaw, pitch, and roll Euler angles in radians

Parameters:

• yaw (float) –

• pitch (float) –

• roll (float) –

Return type:

Rot3

classmethod from_angle_axis(angle, axis)

Construct from an angle in radians and a (normalized) axis as a 3-vector.

Parameters:

• angle (float) –

• axis (Matrix31) –

Return type:

Rot3

classmethod from_two_unit_vectors(a, b, epsilon=0.0)

Return a rotation that transforms a to b. Both inputs are three-vectors that are expected to be normalized.

Reference:

http://lolengine.net/blog/2013/09/18/beautiful-maths-quaternion-from-vectors

Parameters:

• a (Matrix31) –

• b (Matrix31) –

• epsilon (float) –

Return type:

Rot3

angle_between(other, epsilon=0.0)

Return the angle between this rotation and the other in radians.

Parameters:

• other (Rot3) –

• epsilon (float) –

Return type:

float

classmethod random()

Generate a random element of SO3.

Return type:

Rot3

classmethod random_from_uniform_samples(u1, u2, u3, pi=pi)

Generate a random element of SO3 from three variables uniformly sampled in [0, 1].

Parameters:

• u1 (float) –

• u2 (float) –

• u3 (float) –

• pi (float) –

Return type:

Rot3

class Unit3(x)

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()

Dimension of underlying storage

Return type:

int

to_storage()

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)

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

Parameters:

vec (Sequence[float]) –

Return type:

Unit3

classmethod symbolic(name, **kwargs)

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()

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

Return type:

Unit3

compose(other)

Apply the group operation with other.

Parameters:

other (Unit3) –

Return type:

Unit3

inverse()

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

Return type:

Unit3

classmethod tangent_dim()

Dimension of the embedded manifold

Return type:

int

classmethod from_tangent(v, epsilon=0.0)

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

Parameters:

• v (Sequence[float]) –

• epsilon (float) –

Return type:

Unit3

to_tangent(epsilon=0.0)

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

Parameters:

epsilon (float) –

Return type:

List[float]

storage_D_tangent(epsilon=0.0)

Parameters:

epsilon (float) –

Return type:

Matrix32

tangent_D_storage(epsilon=0.0)

Parameters:

epsilon (float) –

Return type:

Matrix23

retract(delta, epsilon=0.0)

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:

• delta (Sequence[float]) –

• epsilon (float) –

Return type:

Unit3

local_coordinates(vector, epsilon=0.0)

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:

• vector (Unit3) –

• epsilon (float) –

Return type:

List[float]

to_unit_vector()

Returns a Vector3 version of the unit direction.

Return type:

Matrix31

basis(epsilon=0.0)

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)

Return a Unit3 that points along the direction of vector a

a will be normalized.

Parameters:

• a (Matrix31) –

• epsilon (float) –

Return type:

Unit3

classmethod from_unit_vector(a)

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)

Generate a random Unit3 direction.

Parameters:

epsilon (float) –

Return type:

Unit3

classmethod random_from_uniform_samples(u1, u2, epsilon=0.0)

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

Parameters:

• u1 (float) –

• u2 (float) –

• epsilon (float) –

Return type:

Unit3

class ATANCameraCal(focal_length, principal_point, omega)

Bases: CameraCal

ATAN camera with 5 parameters [fx, fy, cx, cy, omega].

(fx, fy) representing focal length, (cx, cy) representing principal point, and omega representing the distortion parameter.

See here for more details: https://hal.inria.fr/inria-00267247/file/distcalib.pdf

Parameters:

• focal_length (T.Sequence[T.Scalar]) –

• principal_point (T.Sequence[T.Scalar]) –

• omega (T.Scalar) –

NUM_DISTORTION_COEFFS = 1

property omega: float

classmethod symbolic(name, **kwargs)

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:

ATANCameraCal

classmethod storage_order()

Return list of the names of values returned in the storage paired with the dimension of each value.

Return type:

Tuple[Tuple[str, int], …]

pixel_from_camera_point(point, epsilon=0.0)

Project a 3D point in the camera frame into 2D pixel coordinates.

Returns:

• pixel – (x, y) coordinate in pixels if valid

• is_valid – 1 if the operation is within bounds else 0

Parameters:

• point (Matrix31) –

• epsilon (float) –

Return type:

Tuple[Matrix21, float]

camera_ray_from_pixel(pixel, epsilon=0.0)

Backproject a 2D pixel coordinate into a 3D ray in the camera frame.

Returns:

• camera_ray – The ray in the camera frame (NOT normalized)

• is_valid – 1 if the operation is within bounds else 0

Parameters:

• pixel (Matrix21) –

• epsilon (float) –

Return type:

Tuple[Matrix31, float]

class Camera(calibration, image_size=None)

Bases: object

Camera with a given camera calibration and an optionally specified image size (width, height).

If the image size is specified, we use it to check whether pixels (either given or computed by projection of 3D points into the image frame) are in the image frame and thus valid/invalid.

Parameters:

• calibration (CameraCal) –

• image_size (Sequence[float] | None) –

CameraT = ~CameraT

property focal_length: Matrix21

property principal_point: Matrix21

property distortion_coeffs: Matrix

pixel_from_camera_point(point, epsilon=0.0)

Project a 3D point in the camera frame into 2D pixel coordinates.

Returns:

• pixel – (x, y) coordinate in pixels if valid

• is_valid – 1 if the operation is within bounds (including image_size bounds) else 0

Parameters:

• point (Matrix31) –

• epsilon (float) –

Return type:

Tuple[Matrix21, float]

camera_ray_from_pixel(pixel, epsilon=0.0, normalize=False)

Backproject a 2D pixel coordinate into a 3D ray in the camera frame.

NOTE: If image_size is specified and the given pixel is out of bounds, is_valid will be set to zero.

Parameters:

• normalize (bool) – Whether camera_ray will be normalized (False by default)

• pixel (Matrix21) –

• epsilon (float) –

Returns:

• camera_ray – The ray in the camera frame

• is_valid – 1 if the operation is within bounds else 0

Return type:

Tuple[Matrix31, float]

has_camera_ray_from_pixel()

Returns True if self has implemented the method camera_ray_from_pixel, and False otherwise.

Return type:

bool

maybe_check_in_view(pixel)

Parameters:

pixel (Matrix21) –

Return type:

int

static in_view(pixel, image_size)

Returns 1.0 if the pixel coords are in bounds of the image, 0.0 otherwise.

Parameters:

• pixel (Matrix21) –

• image_size (Matrix21) –

Return type:

int

subs(*args, **kwargs)

Substitute given values of each scalar element into a new instance.

Parameters:

• self (CameraT) –

• args (Any) –

• kwargs (Any) –

Return type:

CameraT

class CameraCal(focal_length, principal_point, distortion_coeffs=())

Bases: Storage

Base class for symbolic camera models.

Parameters:

• focal_length (Sequence[float]) –

• principal_point (Sequence[float]) –

• distortion_coeffs (Sequence[float]) –

CameraCalT = ~CameraCalT

NUM_DISTORTION_COEFFS = 0

classmethod from_distortion_coeffs(focal_length, principal_point, distortion_coeffs=())

Construct a Camera Cal of type cls from the focal_length, principal_point, and distortion_coeffs.

Note, some subclasses may not allow symbolic arguments unless additional keyword arguments are passed in.

Parameters:

• focal_length (Sequence[float]) –

• principal_point (Sequence[float]) –

• distortion_coeffs (Sequence[float]) –

Return type:

CameraCalT

classmethod storage_order()

Return list of the names of values returned in the storage paired with the dimension of each value.

Return type:

Tuple[Tuple[str, int], …]

classmethod storage_dim()

Dimension of underlying storage

Return type:

int

to_storage()

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)

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

Parameters:

vec (Sequence[float]) –

Return type:

CameraCalT

classmethod symbolic(name, **kwargs)

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:

CameraCalT

parameters()

Return type:

List[float]

pixel_from_camera_point(point, epsilon=0.0)

Project a 3D point in the camera frame into 2D pixel coordinates.

Returns:

• pixel – (x, y) coordinate in pixels if valid

• is_valid – 1 if the operation is within bounds else 0

Parameters:

• point (Matrix31) –

• epsilon (float) –

Return type:

Tuple[Matrix21, float]

camera_ray_from_pixel(pixel, epsilon=0.0)

Backproject a 2D pixel coordinate into a 3D ray in the camera frame.

Returns:

• camera_ray – The ray in the camera frame (NOT normalized)

• is_valid – 1 if the operation is within bounds else 0

Parameters:

• pixel (Matrix21) –

• epsilon (float) –

Return type:

Tuple[Matrix31, float]

classmethod has_camera_ray_from_pixel()

Returns True if cls has implemented the method camera_ray_from_pixel(), and False otherwise.

Return type:

bool

class DoubleSphereCameraCal(focal_length, principal_point, xi, alpha)

Bases: CameraCal

Camera model where a point is consecutively projected onto two unit spheres with centers shifted by xi, then projected into the image plane using the pinhole model shifted by alpha / (1 - alpha).

There are important differences here from the derivation in the paper and in other open-source packages with double sphere models; see notebooks/double_sphere_derivation.ipynb for more information.

The storage for this class is:

[ fx fy cx cy xi alpha ]

TODO(aaron): Create double_sphere_derivation.ipynb

TODO(aaron): Probably want to check that values and derivatives are correct (or at least sane) on the valid side of the is_valid boundary

Reference:

https://vision.in.tum.de/research/vslam/double-sphere

Parameters:

• focal_length (T.Sequence[T.Scalar]) –

• principal_point (T.Sequence[T.Scalar]) –

• xi (T.Scalar) –

• alpha (T.Scalar) –

NUM_DISTORTION_COEFFS = 2

classmethod symbolic(name, **kwargs)

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:

DoubleSphereCameraCal

property xi: float

property alpha: float

classmethod storage_order()

Return list of the names of values returned in the storage paired with the dimension of each value.

Return type:

Tuple[Tuple[str, int], …]

pixel_from_camera_point(point, epsilon=0.0)

Project a 3D point in the camera frame into 2D pixel coordinates.

Returns:

• pixel – (x, y) coordinate in pixels if valid

• is_valid – 1 if the operation is within bounds else 0

Parameters:

• point (Matrix31) –

• epsilon (float) –

Return type:

Tuple[Matrix21, float]

camera_ray_from_pixel(pixel, epsilon=0.0)

Backproject a 2D pixel coordinate into a 3D ray in the camera frame.

Returns:

• camera_ray – The ray in the camera frame (NOT normalized)

• is_valid – 1 if the operation is within bounds else 0

Parameters:

• pixel (Matrix21) –

• epsilon (float) –

Return type:

Tuple[Matrix31, float]

class EquirectangularCameraCal(focal_length, principal_point, distortion_coeffs=())

Bases: CameraCal

Equirectangular camera model with parameters [fx, fy, cx, cy].

(fx, fy) representing focal length; (cx, cy) representing principal point.

Parameters:

• focal_length (Sequence[float]) –

• principal_point (Sequence[float]) –

• distortion_coeffs (Sequence[float]) –

NUM_DISTORTION_COEFFS = 0

pixel_from_camera_point(point, epsilon=0.0)

Project a 3D point in the camera frame into 2D pixel coordinates.

Returns:

• pixel – (x, y) coordinate in pixels if valid

• is_valid – 1 if the operation is within bounds else 0

Parameters:

• point (Matrix31) –

• epsilon (float) –

Return type:

Tuple[Matrix21, float]

camera_ray_from_pixel(pixel, epsilon=0.0)

Backproject a 2D pixel coordinate into a 3D ray in the camera frame.

Returns:

• camera_ray – The ray in the camera frame (NOT normalized)

• is_valid – 1 if the operation is within bounds else 0

Parameters:

• pixel (Matrix21) –

• epsilon (float) –

Return type:

Tuple[Matrix31, float]

class LinearCameraCal(focal_length, principal_point, distortion_coeffs=())

Bases: CameraCal

Standard pinhole camera w/ four parameters [fx, fy, cx, cy].

(fx, fy) representing focal length; (cx, cy) representing principal point.

Parameters:

• focal_length (Sequence[float]) –

• principal_point (Sequence[float]) –

• distortion_coeffs (Sequence[float]) –

NUM_DISTORTION_COEFFS = 0

static project(point, epsilon=0.0)

Linearly project the 3D point by dividing by the depth.

Points behind the camera (z <= 0 in the camera frame) are marked as invalid.

Parameters:

• point (Matrix31) – 3D point

• epsilon (float) –

Returns:

• value_if_is_valid – Result of projection if the point is valid

• is_valid – 1 if the point is valid; 0 otherwise

Return type:

Tuple[Matrix21, float]

pixel_from_unit_depth(unit_depth_coords)

Convert point in unit-depth image plane to pixel coords by applying camera matrix.

Parameters:

unit_depth_coords (Matrix21) –

Return type:

Matrix21

unit_depth_from_pixel(pixel)

Convert point in pixel coordinates to unit-depth image plane by applying K_inv.

Parameters:

pixel (Matrix21) –

Return type:

Matrix21

pixel_from_camera_point(point, epsilon=0.0)

Project a 3D point in the camera frame into 2D pixel coordinates.

Returns:

• pixel – (x, y) coordinate in pixels if valid

• is_valid – 1 if the operation is within bounds else 0

Parameters:

• point (Matrix31) –

• epsilon (float) –

Return type:

Tuple[Matrix21, float]

camera_ray_from_pixel(pixel, epsilon=0.0)

Backproject a 2D pixel coordinate into a 3D ray in the camera frame.

Returns:

• camera_ray – The ray in the camera frame (NOT normalized)

• is_valid – 1 if the operation is within bounds else 0

Parameters:

• pixel (Matrix21) –

• epsilon (float) –

Return type:

Tuple[Matrix31, float]

class OrthographicCameraCal(focal_length, principal_point, distortion_coeffs=())

Bases: CameraCal

Orthographic camera model with four parameters [fx, fy, cx, cy].

It would be possible to define orthographic cameras with only two parameters [fx, fy] but we keep the [cx, cy] parameters for consistency with the CameraCal interface.

The orthographic camera model can be thought of as a special case of the LinearCameraCal model, where (x,y,z) in the camera frame projects to pixel (x * fx + cx, y * fy + cy). The z-coordinate of the point is ignored in the projection, except that only points with positive z-coordinates are considered valid.

Because this is a noncentral camera model, the camera_ray_from_pixel function is not implemented.

Parameters:

• focal_length (Sequence[float]) –

• principal_point (Sequence[float]) –

• distortion_coeffs (Sequence[float]) –

NUM_DISTORTION_COEFFS = 0

pixel_from_camera_point(point, epsilon=0.0)

Project a 3D point in the camera frame into 2D pixel coordinates.

Returns:

• pixel – (x, y) coordinate in pixels if valid

• is_valid – 1 if the operation is within bounds else 0

Parameters:

• point (Matrix31) –

• epsilon (float) –

Return type:

Tuple[Matrix21, float]

class PolynomialCameraCal(focal_length, principal_point, distortion_coeffs=(0.0, 0.0, 0.0), critical_undistorted_radius=None, max_fov=2.0943951023931953)

Bases: CameraCal

Polynomial camera model in the style of OpenCV

Distortion is a multiplicative factor applied to the image plane coordinates in the camera frame. Mapping between distorted image plane coordinates and image coordinates is done using a standard linear model.

The distortion function is a 6th order even polynomial that is a function of the radius of the image plane coordinates:

r = (p_img[0] ** 2 + p_img[1] ** 2) ** 0.5
distorted_weight = 1 + c0 * r^2 + c1 * r^4 + c2 * r^6
uv = p_img * distorted_weight

Parameters:

• focal_length (T.Sequence[T.Scalar]) –

• principal_point (T.Sequence[T.Scalar]) –

• distortion_coeffs (T.Sequence[T.Scalar]) –

• critical_undistorted_radius (T.Optional[T.Scalar]) –

• max_fov (T.Scalar) –

NUM_DISTORTION_COEFFS = 3

DEFAULT_MAX_FOV = 2.0943951023931953

classmethod from_distortion_coeffs(focal_length, principal_point, distortion_coeffs=(), **kwargs)

Construct a Camera Cal of type cls from the focal_length, principal_point, and distortion_coeffs.

kwargs are additional arguments which will be passed to the constructor.

Symbolic arguments may only be passed if the kwarg critical_undistorted_radius is passed.

Parameters:

• focal_length (Sequence[float]) –

• principal_point (Sequence[float]) –

• distortion_coeffs (Sequence[float]) –

• kwargs (float) –

Return type:

PolynomialCameraCal

classmethod storage_order()

Return list of the names of values returned in the storage paired with the dimension of each value.

Return type:

Tuple[Tuple[str, int], …]

pixel_from_camera_point(point, epsilon=0.0)

Project a 3D point in the camera frame into 2D pixel coordinates.

Returns:

• pixel – (x, y) coordinate in pixels if valid

• is_valid – 1 if the operation is within bounds else 0

Parameters:

• point (Matrix31) –

• epsilon (float) –

Return type:

Tuple[Matrix21, float]

camera_ray_from_pixel(pixel, epsilon=0)

Backproject a 2D pixel coordinate into a 3D ray in the camera frame.

Returns:

• camera_ray – The ray in the camera frame (NOT normalized)

• is_valid – 1 if the operation is within bounds else 0

Parameters:

• pixel (Matrix21) –

• epsilon (float) –

Return type:

Tuple[Matrix31, float]

classmethod storage_dim()

Dimension of underlying storage

Return type:

int

to_storage()

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)

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

Parameters:

vec (Sequence[float]) –

Return type:

PolynomialCameraCal

classmethod symbolic(name, **kwargs)

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:

PolynomialCameraCal

class PosedCamera(pose, calibration, image_size=None)

Bases: Camera

Camera with a given pose, camera calibration, and an optionally specified image size.

If the image size is specified, we use it to check whether pixels (either given or computed by projection of 3D points into the image frame) are in the image frame and thus valid/invalid.

Parameters:

• pose (geo.Pose3) –

• calibration (CameraCal) –

• image_size (Matrix21 | None) –

PosedCameraT = ~PosedCameraT

pixel_from_global_point(point, epsilon=0.0)

Transforms the given point into the camera frame using the given camera pose, and then uses the given camera calibration to compute the resulted pixel coordinates of the projected point.

Parameters:

• point (Matrix31) – Vector written in camera frame.

• epsilon (float) – Small value intended to prevent division by 0.

Returns:

• pixel – UV coordinates in pixel units, assuming the point is in view

• is_valid – 1 if point is valid

Return type:

Tuple[Matrix21, float]

global_point_from_pixel(pixel, range_to_point, epsilon=0.0)

Computes a point written in the global frame along the ray passing through the center of the given pixel. The point is positioned at a given range along the ray.

Parameters:

• pixel (Matrix21) – Vector in pixels in camera image.

• range_to_point (float) – Distance of the returned point along the ray passing through pixel

• epsilon (float) – Small value intended to prevent division by 0.

Returns:

• global_point – The point in the global frame.

• is_valid – 1 if point is valid

Return type:

Tuple[Matrix31, float]

warp_pixel(pixel, inverse_range, target_cam, epsilon=0.0)

Project a pixel in this camera into another camera.

Parameters:

• pixel (Matrix21) – Pixel in the source camera

• inverse_range (float) – Inverse distance along the ray to the global point

• target_cam (PosedCamera) – Camera to project global point into

• epsilon (float) –

Returns:

• pixel – Pixel in the target camera

• is_valid – 1 if given point is valid in source camera and target camera

Return type:

Tuple[Matrix21, float]

subs(*args, **kwargs)

Substitute given values of each scalar element into a new instance.

Parameters:

• self (PosedCameraT) –

• args (T.Any) –

• kwargs (T.Any) –

Return type:

PosedCameraT

image_size: Matrix21 | None

class SphericalCameraCal(focal_length, principal_point, distortion_coeffs=(0.0, 0.0, 0.0, 0.0, 0.0, 0.0), critical_theta=None, max_theta=3.141592653589793)

Bases: CameraCal

Kannala-Brandt camera model, where radial distortion is modeled relative to the 3D angle theta off the optical axis as opposed to radius within the image plane (i.e. ATANCamera)

I.e. the radius in the image plane as a function of the angle theta from the camera z-axis is assumed to be given by:

r(theta) = theta + d[0] * theta^3 + d[1] * theta^5 + d[2] * theta^7 + d[3] * theta^9

This model also includes two tangential coefficients, implemented similar to the Brown-Conrady model. For details, see the Fisheye62 model from Project Aria: https://facebookresearch.github.io/projectaria_tools/docs/tech_insights/camera_intrinsic_models

With no tangential coefficients, this model is over-parameterized in that we may scale all the distortion coefficients by a constant, and the focal length by the inverse of that constant. To fix this issue, we peg the first coefficient at 1. So while the distortion dimension is ‘4’, the actual total number of coeffs is 5.

Additionally, the storage for this class includes the critical theta, the maximum angle from the optical axis where projection is invertible; although the critical theta is a function of the other parameters, this function requires polynomial root finding, so it should be computed externally at runtime and set to the computed value.

Paper:

A generic camera model and calibration method for conventional, wide-angle, and fish-eye lenses
Kannala, Juho; Brandt, Sami S.
PAMI 2006

This is the simpler “P9” model without any non-radially-symmetric distortion params, but also includes two tangential distortion params similar to the Brown-Conrady model.

The storage for this class is:

[ fx fy cx cy critical_theta d0 d1 d2 d3 p0 p1]

Parameters:

• focal_length (T.Sequence[T.Scalar]) –

• principal_point (T.Sequence[T.Scalar]) –

• distortion_coeffs (T.Sequence[T.Scalar]) –

• critical_theta (T.Optional[T.Scalar]) –

• max_theta (T.Scalar) –

NUM_DISTORTION_COEFFS = 6

classmethod from_distortion_coeffs(focal_length, principal_point, distortion_coeffs=(), **kwargs)

Construct a Camera Cal of type cls from the focal_length, principal_point, and distortion_coeffs.

kwargs are additional arguments which will be passed to the constructor.

Symbolic arguments may only be passed if the kwarg critical_theta is passed.

Parameters:

• focal_length (Sequence[float]) –

• principal_point (Sequence[float]) –

• distortion_coeffs (Sequence[float]) –

• kwargs (float) –

Return type:

SphericalCameraCal

classmethod storage_order()

Return list of the names of values returned in the storage paired with the dimension of each value.

Return type:

Tuple[Tuple[str, int], …]

classmethod storage_dim()

Dimension of underlying storage

Return type:

int

to_storage()

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)

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

Parameters:

vec (Sequence[float]) –

Return type:

SphericalCameraCal

classmethod symbolic(name, **kwargs)

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:

SphericalCameraCal

pixel_from_camera_point(point, epsilon=0.0)

Project a 3D point in the camera frame into 2D pixel coordinates.

Returns:

• pixel – (x, y) coordinate in pixels if valid

• is_valid – 1 if the operation is within bounds else 0

Parameters:

• point (Matrix31) –

• epsilon (float) –

Return type:

Tuple[Matrix21, float]

camera_ray_from_pixel(pixel, epsilon=0)

Backproject a 2D pixel coordinate into a 3D ray in the camera frame.

Returns:

• camera_ray – The ray in the camera frame (NOT normalized)

• is_valid – 1 if the operation is within bounds else 0

Parameters:

• pixel (Matrix21) –

• epsilon (float) –

Return type:

Tuple[Matrix31, float]