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 geo and 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: symengine.lib.symengine_wrapper.OneArgFunction

property func
property is_negative
property is_real
class Add(*args, **kwargs)

Bases: symengine.lib.symengine_wrapper.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: symengine.lib.symengine_wrapper.Boolean

class Derivative(expr, *variables)

Bases: symengine.lib.symengine_wrapper.Expr

property expr
property func
property is_Derivative
property variables
class Dummy

Bases: symengine.lib.symengine_wrapper.Symbol

__init__(*args, **kwargs)
func
is_Dummy
class Expr

Bases: symengine.lib.symengine_wrapper.Basic

class FiniteSet(*args)

Bases: symengine.lib.symengine_wrapper.Set

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

Bases: symengine.lib.symengine_wrapper.Number

property is_Float
property is_irrational
property is_rational
property is_real
class Function(*args, **kwargs)

Bases: symengine.lib.symengine_wrapper.Expr

func(*values)
property is_Function
class Integer(i)

Bases: symengine.lib.symengine_wrapper.Rational

doit(**hints)
property func
get_num_den()
property is_Integer
property is_integer
property p
property q
class Interval(*args)

Bases: symengine.lib.symengine_wrapper.Set

class KroneckerDelta(x, y)

Bases: symengine.lib.symengine_wrapper.Function

class LambertW(x)

Bases: symengine.lib.symengine_wrapper.OneArgFunction

class LeviCivita(*args)

Bases: symengine.lib.symengine_wrapper.Function

class Max(*args)

Bases: symengine.lib.symengine_wrapper.Function

property func
class Min(*args)

Bases: symengine.lib.symengine_wrapper.Function

property func
Mod()
class Mul(*args, **kwargs)

Bases: symengine.lib.symengine_wrapper.AssocOp

as_coefficients_dict()
property func
identity = 1
property is_Mul
class Number

Bases: symengine.lib.symengine_wrapper.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: symengine.lib.symengine_wrapper.Function

class Pow(a, b)

Bases: symengine.lib.symengine_wrapper.Expr

as_base_exp()
property base
property exp
property func
property is_Pow
property is_commutative
class Rational(p, q)

Bases: symengine.lib.symengine_wrapper.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 symengine.lib.symengine_wrapper.Float

class Subs(expr, variables, point)

Bases: symengine.lib.symengine_wrapper.Expr

property expr
property func
property point
property variables
exception SympifyError

Bases: Exception

class UnevaluatedExpr(x)

Bases: symengine.lib.symengine_wrapper.OneArgFunction

property is_finite
property is_integer
property is_number
class acos(x)

Bases: symengine.lib.symengine_wrapper.TrigFunction

class acosh(x)

Bases: symengine.lib.symengine_wrapper.HyperbolicFunction

class acot(x)

Bases: symengine.lib.symengine_wrapper.TrigFunction

class acoth(x)

Bases: symengine.lib.symengine_wrapper.HyperbolicFunction

class acsc(x)

Bases: symengine.lib.symengine_wrapper.TrigFunction

class acsch(x)

Bases: symengine.lib.symengine_wrapper.HyperbolicFunction

class asec(x)

Bases: symengine.lib.symengine_wrapper.TrigFunction

class asech(x)

Bases: symengine.lib.symengine_wrapper.HyperbolicFunction

class asin(x)

Bases: symengine.lib.symengine_wrapper.TrigFunction

class asinh(x)

Bases: symengine.lib.symengine_wrapper.HyperbolicFunction

class atan(x)

Bases: symengine.lib.symengine_wrapper.TrigFunction

class atanh(x)

Bases: symengine.lib.symengine_wrapper.HyperbolicFunction

class beta(x, y)

Bases: symengine.lib.symengine_wrapper.Function

class ceiling(x)

Bases: symengine.lib.symengine_wrapper.OneArgFunction

class conjugate(x)

Bases: symengine.lib.symengine_wrapper.OneArgFunction

class cos(x)

Bases: symengine.lib.symengine_wrapper.TrigFunction

class cosh(x)

Bases: symengine.lib.symengine_wrapper.HyperbolicFunction

class cot(x)

Bases: symengine.lib.symengine_wrapper.TrigFunction

class coth(x)

Bases: symengine.lib.symengine_wrapper.HyperbolicFunction

class csc(x)

Bases: symengine.lib.symengine_wrapper.TrigFunction

class csch(x)

Bases: symengine.lib.symengine_wrapper.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: symengine.lib.symengine_wrapper.OneArgFunction

class erf(x)

Bases: symengine.lib.symengine_wrapper.OneArgFunction

class erfc(x)

Bases: symengine.lib.symengine_wrapper.OneArgFunction

exp()
expand()
class floor(x)

Bases: symengine.lib.symengine_wrapper.OneArgFunction

gamma()
init_printing(pretty_print=True, use_latex=True)[source]
integer_nthroot()
isprime()
lambdify(args, exprs, **kwargs)[source]
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: symengine.lib.symengine_wrapper.OneArgFunction

class loggamma(x)

Bases: symengine.lib.symengine_wrapper.OneArgFunction

class lowergamma(x, y)

Bases: symengine.lib.symengine_wrapper.Function

perfect_power()
class polygamma(x, y)

Bases: symengine.lib.symengine_wrapper.Function

class sec(x)

Bases: symengine.lib.symengine_wrapper.TrigFunction

class sech(x)

Bases: symengine.lib.symengine_wrapper.HyperbolicFunction

series()
class sign(x)

Bases: symengine.lib.symengine_wrapper.OneArgFunction

property is_complex
property is_finite
class sin(x)

Bases: symengine.lib.symengine_wrapper.TrigFunction

class sinh(x)

Bases: symengine.lib.symengine_wrapper.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: symengine.lib.symengine_wrapper.TrigFunction

class tanh(x)

Bases: symengine.lib.symengine_wrapper.HyperbolicFunction

trigamma()
class uppergamma(x, y)

Bases: symengine.lib.symengine_wrapper.Function

var(names, **args)[source]

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: symengine.lib.symengine_wrapper.Function

epsilon()[source]

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 Symbol.

Return type

Any

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

Bases: symengine.lib.symengine_wrapper.Symbol

Parameters
  • name (str) –

  • commutative (bool) –

  • real (bool) –

  • positive (Optional[bool]) –

__init__(name, commutative=True, real=True, positive=None)[source]
Parameters
  • name (str) –

  • commutative (bool) –

  • real (bool) –

  • positive (Optional[bool]) –

original_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))
symbols(names, **args)[source]
Parameters
  • names (str) –

  • args (Any) –

Return type

Union[Sequence[Symbol], Symbol]

Scalar

alias of float

is_positive(x)[source]

Returns 1 if x is positive, 0 otherwise

Parameters

x (float) –

Return type

float

is_negative(x)[source]

Returns 1 if x is negative, 0 otherwise

Parameters

x (float) –

Return type

float

is_nonnegative(x)[source]

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

Parameters

x (float) –

Return type

float

is_nonpositive(x)[source]

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

Parameters

x (float) –

Return type

float

logical_and(a, b, unsafe=False)[source]

Logical and of two 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
  • a (float) –

  • b (float) –

  • unsafe (bool) –

Return type

float

logical_or(a, b, unsafe=False)[source]

Logical or of two 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
  • a (float) –

  • b (float) –

  • unsafe (bool) –

Return type

float

logical_not(a, unsafe=False)[source]

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)[source]

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)[source]

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

sign_no_zero(x)[source]

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

Parameters

x (float) –

Return type

float

copysign_no_zero(x, y)[source]

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

argmax_onehot(vals)[source]

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

vals (Iterable[float]) –

Return type

List[float]

argmax(vals)[source]

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)[source]
Parameters
  • y (float) –

  • x (float) –

  • epsilon (float) –

Return type

float

asin_safe(x, epsilon=0.0)[source]
Parameters
  • x (float) –

  • epsilon (float) –

Return type

float

acos_safe(x, epsilon=0.0)[source]
Parameters
  • x (float) –

  • epsilon (float) –

Return type

float

set_eval_on_sympify(eval_on_sympy=True)[source]

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

simplify(*args, **kwargs)[source]
Parameters
  • args (Any) –

  • kwargs (Any) –

Return type

float

limit(e, z, z0, dir='+')[source]
Parameters
  • e (Any) –

  • z (Any) –

  • z0 (Any) –

  • dir (str) –

Return type

float

solve(*args, **kwargs)[source]
Parameters
  • args (Any) –

  • kwargs (Any) –

Return type

List[float]

count_ops()
class DataBuffer(name, rows=None)

Bases: symengine.lib.symengine_wrapper.Symbol

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

__init__(name, rows=None)
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

create_named_scope(scopes_list)[source]

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)[source]
Parameters

scope (str) –

Return type

None

get_scope()[source]
Return type

str

scope(scope: str) Iterator[None]
Parameters

scope (str) –

Return type

Iterator[None]

class Complex(real, imag)[source]

Bases: symforce.ops.interfaces.group.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 (float) –

  • imag (float) –

__init__(real, imag)[source]

Construct from a real and imaginary scalar.

Parameters
  • real (Scalar) –

  • imag (Scalar) –

classmethod storage_dim()[source]

Dimension of underlying storage

Return type

int

to_storage()[source]

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

Return type

List[float]

classmethod from_storage(vec)[source]

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

Parameters

vec (Sequence[float]) –

Return type

Complex

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

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

Parameters
  • name (str) –

  • kwargs (Any) –

Return type

Complex

classmethod identity()[source]

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

Return type

Complex

compose(other)[source]

Apply the group operation with other.

Parameters

other (Complex) –

Return type

Complex

inverse()[source]

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

Return type

Complex

classmethod zero()[source]

Zero value.

Return type

Complex

conj()[source]

Complex conjugate (real, -imag).

Return type

Complex

squared_norm()[source]

Squared norm of the two-vector.

Returns

real**2 + imag**2

Return type

Scalar

__mul__(right)[source]

Complex multiplication (composition).

Parameters

right (Complex) –

Return type

Complex

__add__(right)[source]

Element-wise addition.

Parameters

right (Complex) –

Return type

Complex

__neg__()[source]

Element-wise negation.

Return type

Complex

__div__(scalar)[source]

Scalar element-wise division.

Parameters

scalar (Scalar) –

Return type

Complex

__truediv__(scalar)

Scalar element-wise division.

Parameters

scalar (Scalar) –

Return type

Complex

classmethod random_uniform(low, high)[source]

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()[source]

Generate a unit-norm random complex number

Return type

Complex

classmethod unit_random_from_uniform_sample(u1, pi=pi)[source]

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)[source]

Bases: symforce.ops.interfaces.group.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
__init__(real_q, inf_q)[source]

Construct from two quaternions - a real one and an infinitesimal one.

Parameters
classmethod storage_dim()[source]

Dimension of underlying storage

Return type

int

to_storage()[source]

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

Return type

List[float]

classmethod from_storage(vec)[source]

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

Parameters

vec (Sequence[float]) –

Return type

DualQuaternion

classmethod identity()[source]

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

Return type

DualQuaternion

compose(other)[source]

Apply the group operation with other.

Parameters

other (DualQuaternion) –

Return type

DualQuaternion

inverse()[source]

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

Return type

DualQuaternion

__mul__(right)[source]

Left-multiply with another dual quaternion.

Parameters
Return type

DualQuaternion

__div__(scalar)[source]

Scalar division.

Parameters

scalar (Scalar) –

Return type

DualQuaternion

__truediv__(scalar)

Scalar division.

Parameters

scalar (Scalar) –

Return type

DualQuaternion

squared_norm()[source]

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

Return type

Scalar

conj()[source]

Dual quaternion conjugate.

Return type

DualQuaternion

class Storage[source]

Bases: object

Interface for objects that implement the storage concept. Because this class is registered using 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.

I.e. 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

alias of TypeVar(‘StorageT’, bound=Storage)

classmethod storage_dim()[source]

Dimension of underlying storage

Return type

int

__repr__()[source]

String representation of this type.

Parameters

self (~StorageT) –

Return type

str

to_storage()[source]

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

Parameters

self (~StorageT) –

Return type

List[float]

classmethod from_storage(elements)[source]

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

Parameters
  • cls (Type[~StorageT]) –

  • elements (Sequence[float]) –

Return type

~StorageT

__eq__(other)[source]

Returns exact equality between self and other.

Parameters
  • self (~StorageT) –

  • other (Any) –

Return type

bool

subs(*args, **kwargs)[source]

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

Parameters
  • self (~StorageT) –

  • args (Any) –

  • kwargs (Any) –

Return type

~StorageT

simplify()[source]

Simplify each scalar element into a new instance.

Parameters

self (~StorageT) –

Return type

~StorageT

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

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

Parameters
  • cls (Type[~StorageT]) –

  • name (str) –

  • kwargs (Any) –

Return type

~StorageT

evalf()[source]

Numerical evaluation.

Parameters

self (~StorageT) –

Return type

~StorageT

__hash__()[source]

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)[source]

Bases: symforce.ops.interfaces.storage.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.

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 ops.GroupOps and ops.LieGroupOps respectively, which use the implementation in vector_class_lie_group_ops.py of the R^{NxM} group under matrix addition. For the identity matrix and inverse matrix, see Matrix.eye and Matrix.inv respectively.

Parameters
  • args (Any) –

  • kwargs (Any) –

MatrixT

alias of TypeVar(‘MatrixT’, bound=Matrix)

SHAPE = (-1, -1)
static __new__(cls, *args, **kwargs)[source]

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.

Generally modeled after the Eigen interface, but must also support internal use within sympy and symengine which we cannot change.

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)

Parameters
  • args (Any) –

  • kwargs (Any) –

Return type

Matrix

__init__(*args, **kwargs)[source]
Parameters
  • args (Any) –

  • kwargs (Any) –

property rows: int
Return type

int

property cols: int
Return type

int

property shape: Tuple[int, int]
Return type

Tuple[int, int]

property is_Matrix: bool
Return type

bool

classmethod storage_dim()[source]

Dimension of underlying storage

Return type

int

classmethod from_storage(vec)[source]

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

Parameters

vec (Sequence[float]) –

Return type

Matrix

to_storage()[source]

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

Return type

List[float]

classmethod tangent_dim()[source]
Return type

int

classmethod from_tangent(vec, epsilon=0)[source]
Parameters
  • vec (Sequence[float]) –

  • epsilon (float) –

Return type

Matrix

to_tangent(epsilon=0)[source]
Parameters

epsilon (float) –

Return type

List[float]

storage_D_tangent()[source]
Return type

Matrix

tangent_D_storage()[source]
Return type

Matrix

classmethod zero()[source]

Matrix of zeros.

Parameters

cls (_T.Type[MatrixT]) –

Return type

MatrixT

classmethod zeros(rows, cols)[source]

Matrix of zeros.

Parameters
  • rows (int) –

  • cols (int) –

Return type

Matrix

classmethod one()[source]

Matrix of ones.

Parameters

cls (_T.Type[MatrixT]) –

Return type

MatrixT

classmethod ones(rows, cols)[source]

Matrix of ones.

Parameters
  • rows (int) –

  • cols (int) –

Return type

Matrix

classmethod diag(diagonal)[source]

Construct a square matrix from the diagonal.

Parameters

diagonal (Sequence[float]) –

Return type

Matrix

classmethod eye(rows=None, cols=None)[source]

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
  • cls (_T.Type[MatrixT]) –

  • rows (int) –

  • cols (int) –

Return type

MatrixT

inv(method='LU')[source]

Inverse of the matrix.

Parameters
  • self (MatrixT) –

  • method (str) –

Return type

MatrixT

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

Create with symbols.

Parameters
  • name (str) – Name prefix of the symbols

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

  • cls (_T.Type[MatrixT]) –

  • kwargs (_T.Any) –

Return type

MatrixT

row_join(right)[source]

Concatenates self with another matrix on the right

Parameters

right (Matrix) –

Return type

Matrix

col_join(bottom)[source]

Concatenates self with another matrix below

Parameters

bottom (Matrix) –

Return type

Matrix

classmethod block_matrix(array)[source]

Constructs a matrix from block elements. For example: [[Matrix22(…), Matrix23(…)], [Matrix11(…), Matrix14(…)]] -> Matrix35 with elements equal to given blocks

Parameters

array (Sequence[Sequence[Matrix]]) –

Return type

Matrix

simplify(*args, **kwargs)[source]

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)[source]

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)[source]

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

Parameters
  • X (Any) –

  • tangent_space (bool) –

Return type

Matrix

diff(*args)[source]

Differentiate wrt a scalar.

Parameters

args (float) –

Return type

Matrix

property T: symforce.geo.matrix.Matrix

Matrix Transpose

Return type

Matrix

transpose()[source]

Matrix Transpose

Return type

Matrix

reshape(rows, cols)[source]
Parameters
  • rows (int) –

  • cols (int) –

Return type

Matrix

dot(other)[source]

Dot product, also known as inner product. dot 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)[source]

Cross product.

Parameters
  • self (MatrixT) –

  • other (MatrixT) –

Return type

Vector3

squared_norm()[source]

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

Return type

float

norm(epsilon=0)[source]

Norm of a vector (square root of magnitude).

Parameters

epsilon (float) –

Return type

float

normalized(epsilon=0)[source]

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)[source]

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)[source]

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)[source]

Apply a unary operation to every scalar.

Parameters
  • self (MatrixT) –

  • func (_T.Callable) –

Return type

MatrixT

__getitem__(item)[source]

Get a scalar value or submatrix slice.

Parameters

item (Any) –

Return type

Any

row(r)[source]

Extract a row of the matrix

Parameters

r (int) –

Return type

Matrix

col(c)[source]

Extract a column of the matrix

Parameters

c (int) –

Return type

Matrix

__neg__()[source]

Negate matrix.

Parameters

self (MatrixT) –

Return type

MatrixT

__add__(right)[source]

Add a scalar or matrix to this matrix.

Parameters
  • self (MatrixT) –

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

Return type

MatrixT

__sub__(right)[source]

Subtract a scalar or matrix from this matrix.

Parameters
  • self (MatrixT) –

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

Return type

MatrixT

__mul__(right)[source]

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)[source]

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]

__div__(right)[source]

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)[source]

Compute a symmetric product A.transpose() * A

Parameters

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

Returns

Symmetric matrix AtA = self.transpose() * self

Return type

(Matrix(N, N))

LU()[source]

LU matrix decomposition

Return type

Union[Tuple[Matrix, Matrix], Tuple[Matrix, Matrix, List[Tuple[int, int]]]]

LDL()[source]

LDL matrix decomposition (stable cholesky)

Return type

Tuple[Matrix, Matrix]

FFLU()[source]

Fraction-free LU matrix decomposition

Return type

Tuple[Matrix, Matrix]

FFLDU()[source]

Fraction-free LDU matrix decomposition

Return type

Union[Tuple[Matrix, Matrix, Matrix], Tuple[Matrix, Matrix, Matrix, Matrix]]

solve(b, method='LU')[source]

Solve a linear system using the given method.

Parameters
  • b (Matrix) –

  • method (str) –

Return type

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]

static are_parallel(a, b, epsilon)[source]

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

Parameters
Return type

float

static skew_symmetric(a)[source]

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

Parameters

a (Matrix31) –

Return type

Matrix33

evalf()[source]

Perform numerical evaluation of each element in the matrix.

Return type

Matrix

to_list()[source]

Convert to a nested list

Return type

List[List[float]]

to_flat_list()[source]

Convert to a flattened list

Return type

List[float]

classmethod from_flat_list(vec)[source]
Parameters

vec (Sequence[float]) –

Return type

Matrix

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

Convert to a numpy array.

Parameters

scalar_type (type) –

Return type

ndarray

classmethod column_stack(*columns)[source]

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

Parameters

columns (tuple(Matrix)) – 1-D vectors

Return type

Matrix

is_vector()[source]
Return type

bool

static init_printing()[source]

Initialize SymPy pretty printing

_ipython_display_ is sufficient in Jupyter, but this covers other locations

Return type

None

class Matrix11(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (1, 1)
class Matrix21(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (2, 1)
class Matrix31(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (3, 1)
class Matrix41(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (4, 1)
class Matrix51(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (5, 1)
class Matrix61(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (6, 1)
class Matrix71(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (7, 1)
class Matrix81(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (8, 1)
class Matrix91(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (9, 1)
class Matrix12(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (1, 2)
class Matrix22(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (2, 2)
class Matrix32(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (3, 2)
class Matrix42(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (4, 2)
class Matrix52(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (5, 2)
class Matrix62(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (6, 2)
class Matrix72(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (7, 2)
class Matrix82(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (8, 2)
class Matrix92(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (9, 2)
class Matrix13(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (1, 3)
class Matrix23(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (2, 3)
class Matrix33(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (3, 3)
class Matrix43(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (4, 3)
class Matrix53(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (5, 3)
class Matrix63(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (6, 3)
class Matrix73(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (7, 3)
class Matrix83(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (8, 3)
class Matrix93(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (9, 3)
class Matrix14(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (1, 4)
class Matrix24(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (2, 4)
class Matrix34(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (3, 4)
class Matrix44(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (4, 4)
class Matrix54(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (5, 4)
class Matrix64(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (6, 4)
class Matrix74(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (7, 4)
class Matrix84(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (8, 4)
class Matrix94(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (9, 4)
class Matrix15(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (1, 5)
class Matrix25(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (2, 5)
class Matrix35(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (3, 5)
class Matrix45(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (4, 5)
class Matrix55(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (5, 5)
class Matrix65(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (6, 5)
class Matrix75(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (7, 5)
class Matrix85(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (8, 5)
class Matrix95(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (9, 5)
class Matrix16(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (1, 6)
class Matrix26(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (2, 6)
class Matrix36(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (3, 6)
class Matrix46(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (4, 6)
class Matrix56(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (5, 6)
class Matrix66(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (6, 6)
class Matrix76(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (7, 6)
class Matrix86(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (8, 6)
class Matrix96(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (9, 6)
class Matrix17(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (1, 7)
class Matrix27(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (2, 7)
class Matrix37(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (3, 7)
class Matrix47(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (4, 7)
class Matrix57(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (5, 7)
class Matrix67(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (6, 7)
class Matrix77(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (7, 7)
class Matrix87(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (8, 7)
class Matrix97(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (9, 7)
class Matrix18(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (1, 8)
class Matrix28(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (2, 8)
class Matrix38(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (3, 8)
class Matrix48(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (4, 8)
class Matrix58(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (5, 8)
class Matrix68(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (6, 8)
class Matrix78(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (7, 8)
class Matrix88(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (8, 8)
class Matrix98(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (9, 8)
class Matrix19(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (1, 9)
class Matrix29(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (2, 9)
class Matrix39(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (3, 9)
class Matrix49(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (4, 9)
class Matrix59(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (5, 9)
class Matrix69(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (6, 9)
class Matrix79(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (7, 9)
class Matrix89(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (8, 9)
class Matrix99(*args, **kwargs)[source]

Bases: symforce.geo.matrix.Matrix

Parameters
  • args (Any) –

  • kwargs (Any) –

SHAPE = (9, 9)
m

alias of symforce.geo.matrix.Matrix99

matrix_type_from_shape(shape)[source]

Return a fixed size matrix type (like Matrix32) given a shape. Either use the statically defined ones or dynamically create a new one if not available.

Parameters

shape (Tuple[int, int]) –

Return type

Type[Matrix]

M

alias of symforce.geo.matrix.Matrix

Vector1

alias of symforce.geo.matrix.Matrix11

Vector2

alias of symforce.geo.matrix.Matrix21

Vector3

alias of symforce.geo.matrix.Matrix31

Vector4

alias of symforce.geo.matrix.Matrix41

Vector5

alias of symforce.geo.matrix.Matrix51

Vector6

alias of symforce.geo.matrix.Matrix61

Vector7

alias of symforce.geo.matrix.Matrix71

Vector8

alias of symforce.geo.matrix.Matrix81

Vector9

alias of symforce.geo.matrix.Matrix91

V1

alias of symforce.geo.matrix.Matrix11

V2

alias of symforce.geo.matrix.Matrix21

V3

alias of symforce.geo.matrix.Matrix31

V4

alias of symforce.geo.matrix.Matrix41

V5

alias of symforce.geo.matrix.Matrix51

V6

alias of symforce.geo.matrix.Matrix61

V7

alias of symforce.geo.matrix.Matrix71

V8

alias of symforce.geo.matrix.Matrix81

V9

alias of symforce.geo.matrix.Matrix91

M11

alias of symforce.geo.matrix.Matrix11

M21

alias of symforce.geo.matrix.Matrix21

M31

alias of symforce.geo.matrix.Matrix31

M41

alias of symforce.geo.matrix.Matrix41

M51

alias of symforce.geo.matrix.Matrix51

M61

alias of symforce.geo.matrix.Matrix61

M71

alias of symforce.geo.matrix.Matrix71

M81

alias of symforce.geo.matrix.Matrix81

M91

alias of symforce.geo.matrix.Matrix91

M12

alias of symforce.geo.matrix.Matrix12

M22

alias of symforce.geo.matrix.Matrix22

M32

alias of symforce.geo.matrix.Matrix32

M42

alias of symforce.geo.matrix.Matrix42

M52

alias of symforce.geo.matrix.Matrix52

M62

alias of symforce.geo.matrix.Matrix62

M72

alias of symforce.geo.matrix.Matrix72

M82

alias of symforce.geo.matrix.Matrix82

M92

alias of symforce.geo.matrix.Matrix92

M13

alias of symforce.geo.matrix.Matrix13

M23

alias of symforce.geo.matrix.Matrix23

M33

alias of symforce.geo.matrix.Matrix33

M43

alias of symforce.geo.matrix.Matrix43

M53

alias of symforce.geo.matrix.Matrix53

M63

alias of symforce.geo.matrix.Matrix63

M73

alias of symforce.geo.matrix.Matrix73

M83

alias of symforce.geo.matrix.Matrix83

M93

alias of symforce.geo.matrix.Matrix93

M14

alias of symforce.geo.matrix.Matrix14

M24

alias of symforce.geo.matrix.Matrix24

M34

alias of symforce.geo.matrix.Matrix34

M44

alias of symforce.geo.matrix.Matrix44

M54

alias of symforce.geo.matrix.Matrix54

M64

alias of symforce.geo.matrix.Matrix64

M74

alias of symforce.geo.matrix.Matrix74

M84

alias of symforce.geo.matrix.Matrix84

M94

alias of symforce.geo.matrix.Matrix94

M15

alias of symforce.geo.matrix.Matrix15

M25

alias of symforce.geo.matrix.Matrix25

M35

alias of symforce.geo.matrix.Matrix35

M45

alias of symforce.geo.matrix.Matrix45

M55

alias of symforce.geo.matrix.Matrix55

M65

alias of symforce.geo.matrix.Matrix65

M75

alias of symforce.geo.matrix.Matrix75

M85

alias of symforce.geo.matrix.Matrix85

M95

alias of symforce.geo.matrix.Matrix95

M16

alias of symforce.geo.matrix.Matrix16

M26

alias of symforce.geo.matrix.Matrix26

M36

alias of symforce.geo.matrix.Matrix36

M46

alias of symforce.geo.matrix.Matrix46

M56

alias of symforce.geo.matrix.Matrix56

M66

alias of symforce.geo.matrix.Matrix66

M76

alias of symforce.geo.matrix.Matrix76

M86

alias of symforce.geo.matrix.Matrix86

M96

alias of symforce.geo.matrix.Matrix96

M17

alias of symforce.geo.matrix.Matrix17

M27

alias of symforce.geo.matrix.Matrix27

M37

alias of symforce.geo.matrix.Matrix37

M47

alias of symforce.geo.matrix.Matrix47

M57

alias of symforce.geo.matrix.Matrix57

M67

alias of symforce.geo.matrix.Matrix67

M77

alias of symforce.geo.matrix.Matrix77

M87

alias of symforce.geo.matrix.Matrix87

M97

alias of symforce.geo.matrix.Matrix97

M18

alias of symforce.geo.matrix.Matrix18

M28

alias of symforce.geo.matrix.Matrix28

M38

alias of symforce.geo.matrix.Matrix38

M48

alias of symforce.geo.matrix.Matrix48

M58

alias of symforce.geo.matrix.Matrix58

M68

alias of symforce.geo.matrix.Matrix68

M78

alias of symforce.geo.matrix.Matrix78

M88

alias of symforce.geo.matrix.Matrix88

M98

alias of symforce.geo.matrix.Matrix98

M19

alias of symforce.geo.matrix.Matrix19

M29

alias of symforce.geo.matrix.Matrix29

M39

alias of symforce.geo.matrix.Matrix39

M49

alias of symforce.geo.matrix.Matrix49

M59

alias of symforce.geo.matrix.Matrix59

M69

alias of symforce.geo.matrix.Matrix69

M79

alias of symforce.geo.matrix.Matrix79

M89

alias of symforce.geo.matrix.Matrix89

M99

alias of symforce.geo.matrix.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
  • cls (_T.Type[MatrixT]) –

  • rows (int) –

  • cols (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
  • cls (_T.Type[MatrixT]) –

  • rows (int) –

  • cols (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
  • cls (_T.Type[MatrixT]) –

  • rows (int) –

  • cols (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
  • cls (_T.Type[MatrixT]) –

  • rows (int) –

  • cols (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
  • cls (_T.Type[MatrixT]) –

  • rows (int) –

  • cols (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
  • cls (_T.Type[MatrixT]) –

  • rows (int) –

  • cols (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
  • cls (_T.Type[MatrixT]) –

  • rows (int) –

  • cols (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
  • cls (_T.Type[MatrixT]) –

  • rows (int) –

  • cols (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
  • cls (_T.Type[MatrixT]) –

  • rows (int) –

  • cols (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
  • cls (_T.Type[MatrixT]) –

  • rows (int) –

  • cols (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
  • cls (_T.Type[MatrixT]) –

  • rows (int) –

  • cols (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
  • cls (_T.Type[MatrixT]) –

  • rows (int) –

  • cols (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
  • cls (_T.Type[MatrixT]) –

  • rows (int) –

  • cols (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
  • cls (_T.Type[MatrixT]) –

  • rows (int) –

  • cols (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
  • cls (_T.Type[MatrixT]) –

  • rows (int) –

  • cols (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
  • cls (_T.Type[MatrixT]) –

  • rows (int) –

  • cols (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
  • cls (_T.Type[MatrixT]) –

  • rows (int) –

  • cols (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
  • cls (_T.Type[MatrixT]) –

  • rows (int) –

  • cols (int) –

Return type

MatrixT

class VectorClassLieGroupOps(*args, **kwds)[source]

Bases: symforce.ops.impl.class_storage_ops.ClassStorageOps, symforce.ops.impl.abstract_vector_lie_group_ops.AbstractVectorLieGroupOps[symforce.ops.interfaces.storage.Storage]

A generic implementation of Lie group ops for subclasses of symforce.ops.interfaces.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)[source]

Bases: symforce.ops.interfaces.lie_group.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, if you really really want SE(2) you should use Pose2_SE2. 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

Parameters
Pose2T

alias of TypeVar(‘Pose2T’, bound=Pose2)

__init__(R=None, t=None)[source]

Construct from elements in SO2 and R2.

Parameters
rotation()[source]

Accessor for the rotation component

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

Return type

Rot2

position()[source]

Accessor for the position component

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

Return type

Matrix21

classmethod storage_dim()[source]

Dimension of underlying storage

Return type

int

to_storage()[source]

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

Return type

List[float]

classmethod from_storage(vec)[source]

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

Parameters

vec (Sequence[float]) –

Return type

Pose2

classmethod identity()[source]

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

Return type

Pose2

compose(other)[source]

Apply the group operation with other.

Parameters

other (Pose2) –

Return type

Pose2

inverse()[source]

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

Return type

Pose2

classmethod tangent_dim()[source]

Dimension of the embedded manifold

Return type

int

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

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

Parameters
  • v (Sequence[float]) –

  • epsilon (float) –

Return type

Pose2

to_tangent(epsilon=0.0)[source]

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

Parameters

epsilon (float) –

Return type

List[float]

storage_D_tangent()[source]

Note: generated from symforce/notebooks/storage_D_tangent.ipynb

Return type

Matrix

tangent_D_storage()[source]

Note: generated from symforce/notebooks/tangent_D_storage.ipynb

Return type

Matrix

retract(vec, epsilon=0.0)[source]

Apply 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 (Pose2) –

  • vec (Sequence[float]) –

  • epsilon (float) –

Return type

Pose2

local_coordinates(b, epsilon=0.0)[source]

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

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

Parameters
  • self (Pose2T) –

  • b (Pose2T) –

  • epsilon (T.Scalar) –

Return type

T.List[T.Scalar]

__mul__(right)[source]

Left-multiply with a compatible quantity.

Parameters

right (Union[Pose2, Matrix21]) – (Pose2 | R2)

Return type

Union[Pose2, Matrix21]

Returns

(Pose2 | R2)

to_homogenous_matrix()[source]

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

Return type

Matrix

Returns

3x3 Matrix

class Pose2_SE2(R=None, t=None)[source]

Bases: symforce.geo.pose2.Pose2

Group of two-dimensional rigid body transformations - SE(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 rotated frame. This means we interpolate the translation in the tangent of the rotating frame for lie operations. This can be useful but is more expensive than SO(2) x R2 for often no benefit.

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

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

Parameters
  • v (Sequence[float]) –

  • epsilon (float) –

Return type

Pose2_SE2

to_tangent(epsilon=0.0)[source]

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

Parameters

epsilon (float) –

Return type

List[float]

storage_D_tangent()[source]

Note: generated from symforce/notebooks/storage_D_tangent.ipynb

Return type

Matrix

tangent_D_storage()[source]

Note: generated from symforce/notebooks/tangent_D_storage.ipynb

Return type

Matrix

retract(vec, epsilon=0.0)[source]

Apply 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
  • vec (Sequence[float]) –

  • epsilon (float) –

Return type

Pose2_SE2

local_coordinates(b, epsilon=0.0)[source]

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

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

Parameters
Return type

List[float]

classmethod hat(vec)[source]
Parameters

vec (List[float]) –

Return type

Matrix33

class Pose3(R=None, t=None)[source]

Bases: symforce.ops.interfaces.lie_group.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, if you really really want SE(3) you should use Pose3_SE3. 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

Parameters
Pose3T

alias of TypeVar(‘Pose3T’, bound=Pose3)

__init__(R=None, t=None)[source]

Construct from elements in SO3 and R3.

Parameters
  • R (Optional[Rot3]) – Frame orientation

  • t (Optional[Matrix31]) – Translation 3-vector in the global frame

rotation()[source]

Accessor for the rotation component

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

Return type

Rot3

position()[source]

Accessor for the position component

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

Return type

Matrix31

classmethod storage_dim()[source]

Dimension of underlying storage

Return type

int

to_storage()[source]

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

Return type

List[float]

classmethod from_storage(vec)[source]

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

Parameters
  • cls (T.Type[Pose3T]) –

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

Return type

Pose3T

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

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

Parameters
  • cls (T.Type[Pose3T]) –

  • name (str) –

  • kwargs (T.Any) –

Return type

Pose3T

classmethod identity()[source]

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

Parameters

cls (T.Type[Pose3T]) –

Return type

Pose3T

compose(other)[source]

Apply the group operation with other.

Parameters
  • self (Pose3T) –

  • other (Pose3T) –

Return type

Pose3T

inverse()[source]

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

Parameters

self (Pose3T) –

Return type

Pose3T

classmethod tangent_dim()[source]

Dimension of the embedded manifold

Return type

int

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

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

Parameters
  • cls (T.Type[Pose3T]) –

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

  • epsilon (T.Scalar) –

Return type

Pose3T

to_tangent(epsilon=0.0)[source]

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()[source]

Note: generated from symforce/notebooks/storage_D_tangent.ipynb

Parameters

self (Pose3T) –

Return type

Matrix

tangent_D_storage()[source]

Note: generated from symforce/notebooks/tangent_D_storage.ipynb

Parameters

self (Pose3T) –

Return type

Matrix

retract(vec, epsilon=0.0)[source]

Apply 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 (Pose3T) –

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

  • epsilon (T.Scalar) –

Return type

Pose3T

local_coordinates(b, epsilon=0.0)[source]

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

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

Parameters
  • self (Pose3T) –

  • b (Pose3T) –

  • epsilon (T.Scalar) –

Return type

T.List[T.Scalar]

__mul__(right)[source]

Left-multiply with a compatible quantity.

Parameters
  • self (Pose3T) –

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

Return type

T.Union[Pose3T, Vector3]

to_homogenous_matrix()[source]

4x4 matrix representing this pose transform.

Return type

Matrix

class Pose3_SE3(R=None, t=None)[source]

Bases: symforce.geo.pose3.Pose3

Group of three-dimensional rigid body transformations - SE(3).

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 rotated frame, meaning we interpolate the translation in the tangent of the rotating frame for lie operations. This can be useful but is more expensive than SO(3) x R3 for often no benefit.

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

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

Parameters
  • v (Sequence[float]) –

  • epsilon (float) –

Return type

Pose3_SE3

to_tangent(epsilon=0.0)[source]

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

Parameters

epsilon (float) –

Return type

List[float]

storage_D_tangent()[source]

Note: generated from symforce/notebooks/storage_D_tangent.ipynb

Return type

Matrix

tangent_D_storage()[source]

Note: generated from symforce/notebooks/tangent_D_storage.ipynb

Return type

Matrix

retract(vec, epsilon=0.0)[source]

Apply 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
  • vec (Sequence[float]) –

  • epsilon (float) –

Return type

Pose3_SE3

local_coordinates(b, epsilon=0.0)[source]

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

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

Parameters
Return type

List[float]

classmethod hat(vec)[source]
Parameters

vec (List) –

Return type

Matrix44

class Quaternion(xyz, w)[source]

Bases: symforce.ops.interfaces.group.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
__init__(xyz, w)[source]

Construct from a real scalar and an imaginary unit vector.

Parameters
property x: float
Return type

float

property y: float
Return type

float

property z: float
Return type

float

classmethod storage_dim()[source]

Dimension of underlying storage

Return type

int

to_storage()[source]

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

Return type

List[float]

classmethod from_storage(vec)[source]

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

Parameters

vec (Sequence[float]) –

Return type

Quaternion

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

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

Parameters
  • name (str) –

  • kwargs (Any) –

Return type

Quaternion

classmethod identity()[source]

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

Return type

Quaternion

compose(other)[source]

Apply the group operation with other.

Parameters

other (Quaternion) –

Return type

Quaternion

inverse()[source]

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

Return type

Quaternion

__mul__(right)[source]

Quaternion multiplication.

Parameters

right (Quaternion) –

Return type

Quaternion

__neg__()[source]

Negation of all entries.

Return type

Quaternion

__add__(right)[source]

Quaternion addition.

Parameters

right (Quaternion) –

Return type

Quaternion

__div__(scalar)[source]

Scalar division.

Parameters

scalar (Scalar) –

Return type

Quaternion

__truediv__(scalar)

Scalar division.

Parameters

scalar (Scalar) –

Return type

Quaternion

classmethod zero()[source]

Construct with all zeros.

Return type

Quaternion

squared_norm()[source]

Squared norm when considering the quaternion as 4-tuple.

Return type

Scalar

conj()[source]

Quaternion conjugate.

Return type

Quaternion

classmethod unit_random()[source]

Generate a random unit quaternion

Return type

Quaternion

classmethod unit_random_from_uniform_samples(u1, u2, u3, pi=pi)[source]

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)[source]

Bases: symforce.ops.interfaces.lie_group.LieGroup

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

Parameters

z (Optional[Complex]) –

__init__(z=None)[source]

Construct from a unit complex number, or identity if none provided.

Parameters

z (Complex) –

classmethod storage_dim()[source]

Dimension of underlying storage

Return type

int

to_storage()[source]

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

Return type

List[float]

classmethod from_storage(vec)[source]

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

Parameters

vec (Sequence[float]) –

Return type

Rot2

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

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

Parameters
  • name (str) –

  • kwargs (Any) –

Return type

Rot2

classmethod identity()[source]

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

Return type

Rot2

compose(other)[source]

Apply the group operation with other.

Parameters

other (Rot2) –

Return type

Rot2

inverse()[source]

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

Return type

Rot2

classmethod tangent_dim()[source]

Dimension of the embedded manifold

Return type

int

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

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

Parameters
  • v (Sequence[float]) –

  • epsilon (float) –

Return type

Rot2

to_tangent(epsilon=0.0)[source]

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

Parameters

epsilon (float) –

Return type

List[float]

classmethod hat(vec)[source]
Parameters

vec (Sequence[float]) –

Return type

Matrix22

storage_D_tangent()[source]

Note: generated from symforce/notebooks/storage_D_tangent.ipynb

Return type

Matrix21

tangent_D_storage()[source]

Note: generated from symforce/notebooks/tangent_D_storage.ipynb

Return type

Matrix12

__mul__(right)[source]

Left-multiplication. Either rotation concatenation or point transform.

Parameters

right (Union[Rot2, Matrix21]) –

Return type

Union[Rot2, Matrix21]

classmethod from_angle(theta)[source]

Create a Rot2 from an angle theta in radians

This is equivalent to from_tangent([theta])

Parameters

theta (float) –

Return type

Rot2

to_rotation_matrix()[source]

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

Return type

Matrix22

classmethod random()[source]

Generate a random element of SO3.

Return type

Rot2

classmethod random_from_uniform_sample(u1, pi=pi)[source]

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)[source]

Bases: symforce.ops.interfaces.lie_group.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 (Optional[Quaternion]) –

__init__(q=None)[source]

Construct from a unit quaternion, or identity if none provided.

Parameters

q (Optional[Quaternion]) –

classmethod storage_dim()[source]

Dimension of underlying storage

Return type

int

to_storage()[source]

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

Return type

List[float]

classmethod from_storage(vec)[source]

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

Parameters

vec (Sequence[float]) –

Return type

Rot3

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

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

Parameters
  • name (str) –

  • kwargs (Any) –

Return type

Rot3

classmethod identity()[source]

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

Return type

Rot3

compose(other)[source]

Apply the group operation with other.

Parameters

other (Rot3) –

Return type

Rot3

inverse()[source]

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

Return type

Rot3

classmethod tangent_dim()[source]

Dimension of the embedded manifold

Return type

int

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

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

Parameters
  • v (Sequence[float]) –

  • epsilon (float) –

Return type

Rot3

logmap_acos_clamp_max(epsilon=0.0)[source]

Implementation of logmap that uses epsilon with the Min function to avoid the singularity in the sqrt at w == 1

Also flips the sign of the quaternion of w is negative, which makes sure that the resulting tangent vector has norm <= pi

Parameters

epsilon (float) –

Return type

List[float]

to_tangent(epsilon=0.0)[source]

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

Parameters

epsilon (float) –

Return type

List[float]

classmethod hat(vec)[source]
Parameters

vec (Sequence[float]) –

Return type

Matrix33

storage_D_tangent()[source]

Note: generated from symforce/notebooks/storage_D_tangent.ipynb

Return type

Matrix43

tangent_D_storage()[source]

Note: generated from symforce/notebooks/tangent_D_storage.ipynb

Return type

Matrix34

__mul__(right)[source]

Left-multiplication. Either rotation concatenation or point transform.

Parameters

right (Union[Matrix31, Rot3]) –

Return type

Union[Matrix31, Rot3]

to_rotation_matrix()[source]

Converts to a rotation matrix

Return type

Matrix33

classmethod from_rotation_matrix(R, epsilon=0.0)[source]

Construct from a rotation matrix.

Parameters
Return type

Rot3

to_yaw_pitch_roll(epsilon=0.0)[source]

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

Returns

Yaw angle [radians] Scalar: Pitch angle [radians] Scalar: Roll angle [radians]

Return type

Scalar

Parameters

epsilon (float) –

classmethod from_yaw_pitch_roll(yaw=0, pitch=0, roll=0)[source]

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)[source]

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

Parameters
Return type

Rot3

classmethod from_two_unit_vectors(a, b, epsilon=0.0)[source]

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
Return type

Rot3

angle_between(other, epsilon=0.0)[source]

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

Parameters
  • other (Rot3) –

  • epsilon (float) –

Return type

float

classmethod random()[source]

Generate a random element of SO3.

Return type

Rot3

classmethod random_from_uniform_samples(u1, u2, u3, pi=pi)[source]

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 ATANCameraCal(focal_length, principal_point, omega)[source]

Bases: symforce.cam.camera_cal.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 (Sequence[float]) –

  • principal_point (Sequence[float]) –

  • omega (float) –

NUM_DISTORTION_COEFFS = 1
__init__(focal_length, principal_point, omega)[source]
Parameters
  • focal_length (Sequence[float]) –

  • principal_point (Sequence[float]) –

  • omega (float) –

property omega: float
Return type

float

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

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

Parameters
  • name (str) –

  • kwargs (Any) –

Return type

ATANCameraCal

classmethod storage_order()[source]

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)[source]

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

Returns

(x, y) coordinate in pixels if valid is_valid: 1 if the operation is within bounds else 0

Return type

pixel

Parameters
  • point (Matrix31) –

  • epsilon (float) –

camera_ray_from_pixel(pixel, epsilon=0.0)[source]

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

TODO(hayk): Add a normalize boolean argument? Like in cam.Camera

Returns

The ray in the camera frame (NOT normalized) is_valid: 1 if the operation is within bounds else 0

Return type

camera_ray

Parameters
  • pixel (Matrix21) –

  • epsilon (float) –

class Camera(calibration, image_size=None)[source]

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 (Optional[Sequence[float]]) –

CameraT

alias of TypeVar(‘CameraT’, bound=Camera)

__init__(calibration, image_size=None)[source]
Parameters
  • calibration (CameraCal) –

  • image_size (Optional[Sequence[float]]) –

property focal_length: symforce.geo.matrix.Matrix21
Return type

Matrix21

property principal_point: symforce.geo.matrix.Matrix21
Return type

Matrix21

property distortion_coeffs: symforce.geo.matrix.Matrix
Return type

Matrix

pixel_from_camera_point(point, epsilon=0.0)[source]

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

Returns

(x, y) coordinate in pixels if valid is_valid: 1 if the operation is within bounds (including image_size bounds) else 0

Return type

pixel

Parameters
  • point (Matrix31) –

  • epsilon (float) –

camera_ray_from_pixel(pixel, epsilon=0.0, normalize=False)[source]

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

The ray in the camera frame is_valid: 1 if the operation is within bounds else 0

Return type

camera_ray

has_camera_ray_from_pixel()[source]

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

Return type

bool

maybe_check_in_view(pixel)[source]
Parameters

pixel (Matrix21) –

Return type

int

static in_view(pixel, image_size)[source]

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

Parameters
Return type

int

subs(*args, **kwargs)[source]

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=())[source]

Bases: symforce.ops.interfaces.storage.Storage

Base class for symbolic camera models.

Parameters
  • focal_length (Sequence[float]) –

  • principal_point (Sequence[float]) –

  • distortion_coeffs (Sequence[float]) –

CameraCalT

alias of TypeVar(‘CameraCalT’, bound=CameraCal)

NUM_DISTORTION_COEFFS = 0
__init__(focal_length, principal_point, distortion_coeffs=())[source]
Parameters
  • focal_length (Sequence[float]) –

  • principal_point (Sequence[float]) –

  • distortion_coeffs (Sequence[float]) –

classmethod from_distortion_coeffs(focal_length, principal_point, distortion_coeffs=())[source]

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
  • cls (Type[~CameraCalT]) –

  • focal_length (Sequence[float]) –

  • principal_point (Sequence[float]) –

  • distortion_coeffs (Sequence[float]) –

Return type

~CameraCalT

classmethod storage_order()[source]

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()[source]

Dimension of underlying storage

Return type

int

to_storage()[source]

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

Return type

List[float]

classmethod from_storage(vec)[source]

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

Parameters
  • cls (Type[~CameraCalT]) –

  • vec (Sequence[float]) –

Return type

~CameraCalT

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

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

Parameters
  • cls (Type[~CameraCalT]) –

  • name (str) –

  • kwargs (Any) –

Return type

~CameraCalT

parameters()[source]
Return type

List[float]

pixel_from_camera_point(point, epsilon=0.0)[source]

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

Returns

(x, y) coordinate in pixels if valid is_valid: 1 if the operation is within bounds else 0

Return type

pixel

Parameters
  • point (Matrix31) –

  • epsilon (float) –

camera_ray_from_pixel(pixel, epsilon=0.0)[source]

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

TODO(hayk): Add a normalize boolean argument? Like in cam.Camera

Returns

The ray in the camera frame (NOT normalized) is_valid: 1 if the operation is within bounds else 0

Return type

camera_ray

Parameters
  • pixel (Matrix21) –

  • epsilon (float) –

classmethod has_camera_ray_from_pixel()[source]

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)[source]

Bases: symforce.cam.camera_cal.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 (Sequence[float]) –

  • principal_point (Sequence[float]) –

  • xi (float) –

  • alpha (float) –

NUM_DISTORTION_COEFFS = 2
__init__(focal_length, principal_point, xi, alpha)[source]
Parameters
  • focal_length (Sequence[float]) –

  • principal_point (Sequence[float]) –

  • xi (float) –

  • alpha (float) –

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

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

Parameters
  • name (str) –

  • kwargs (Any) –

Return type

DoubleSphereCameraCal

property xi: float
Return type

float

property alpha: float
Return type

float

classmethod storage_order()[source]

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)[source]

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

Returns

(x, y) coordinate in pixels if valid is_valid: 1 if the operation is within bounds else 0

Return type

pixel

Parameters
  • point (Matrix31) –

  • epsilon (float) –

camera_ray_from_pixel(pixel, epsilon=0.0)[source]

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

TODO(hayk): Add a normalize boolean argument? Like in cam.Camera

Returns

The ray in the camera frame (NOT normalized) is_valid: 1 if the operation is within bounds else 0

Return type

camera_ray

Parameters
  • pixel (Matrix21) –

  • epsilon (float) –

class EquirectangularCameraCal(focal_length, principal_point, distortion_coeffs=())[source]

Bases: symforce.cam.camera_cal.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)[source]

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

Returns

(x, y) coordinate in pixels if valid is_valid: 1 if the operation is within bounds else 0

Return type

pixel

Parameters
  • point (Matrix31) –

  • epsilon (float) –

camera_ray_from_pixel(pixel, epsilon=0.0)[source]

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

TODO(hayk): Add a normalize boolean argument? Like in cam.Camera

Returns

The ray in the camera frame (NOT normalized) is_valid: 1 if the operation is within bounds else 0

Return type

camera_ray

Parameters
  • pixel (Matrix21) –

  • epsilon (float) –

class LinearCameraCal(focal_length, principal_point, distortion_coeffs=())[source]

Bases: symforce.cam.camera_cal.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)[source]

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

Result of projection if the point is valid is_valid: 1 if the point is valid; 0 otherwise

Return type

value_if_is_valid

pixel_from_unit_depth(unit_depth_coords)[source]

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)[source]

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)[source]

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

Returns

(x, y) coordinate in pixels if valid is_valid: 1 if the operation is within bounds else 0

Return type

pixel

Parameters
  • point (Matrix31) –

  • epsilon (float) –

camera_ray_from_pixel(pixel, epsilon=0.0)[source]

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

TODO(hayk): Add a normalize boolean argument? Like in cam.Camera

Returns

The ray in the camera frame (NOT normalized) is_valid: 1 if the operation is within bounds else 0

Return type

camera_ray

Parameters
  • pixel (Matrix21) –

  • epsilon (float) –

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

Bases: symforce.cam.camera_cal.CameraCal

Polynomial camera model in the style of OpenCV. Distortion is a multiplicitive 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 (Sequence[float]) –

  • principal_point (Sequence[float]) –

  • distortion_coeffs (Sequence[float]) –

  • critical_undistorted_radius (Optional[float]) –

  • max_fov (float) –

NUM_DISTORTION_COEFFS = 3
DEFAULT_MAX_FOV = 2.0943951023931953
__init__(focal_length, principal_point, distortion_coeffs=(0.0, 0.0, 0.0), critical_undistorted_radius=None, max_fov=2.0943951023931953)[source]
Parameters
  • critical_undistorted_radius (Optional[float]) – The maximum radius allowable for distortion. This should be as large as largest expected undistorted radius. If the distortion coeffs are all numerical, this will be computed automatically as either the first local maximum of r(radius) in the interval (0, max_radius), or as max_radius if there is no local maximum in the interval.

  • max_fov (float) – Only used to compute critical_undistorted_radius when all camera parameters are numerical. The maximum FOV (field of view) determines the maximum image plane coordinates which is used to compute maximum radius.

  • focal_length (Sequence[float]) –

  • principal_point (Sequence[float]) –

  • distortion_coeffs (Sequence[float]) –

classmethod from_distortion_coeffs(focal_length, principal_point, distortion_coeffs=(), **kwargs)[source]

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()[source]

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)[source]

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

Returns

(x, y) coordinate in pixels if valid is_valid: 1 if the operation is within bounds else 0

Return type

pixel

Parameters
  • point (Matrix31) –

  • epsilon (float) –

camera_ray_from_pixel(pixel, epsilon=0)[source]

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

TODO(hayk): Add a normalize boolean argument? Like in cam.Camera

Returns

The ray in the camera frame (NOT normalized) is_valid: 1 if the operation is within bounds else 0

Return type

camera_ray

Parameters
  • pixel (Matrix21) –

  • epsilon (float) –

classmethod storage_dim()[source]

Dimension of underlying storage

Return type

int

to_storage()[source]

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

Return type

List[float]

classmethod from_storage(vec)[source]

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

Parameters

vec (Sequence[float]) –

Return type

PolynomialCameraCal

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

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

Parameters
  • name (str) –

  • kwargs (Any) –

Return type

PolynomialCameraCal

class PosedCamera(pose, calibration, image_size=None)[source]

Bases: symforce.cam.camera.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 (Pose3) –

  • calibration (CameraCal) –

  • image_size (Optional[Sequence[float]]) –

PosedCameraT

alias of TypeVar(‘PosedCameraT’, bound=PosedCamera)

__init__(pose, calibration, image_size=None)[source]
Parameters
  • pose (Pose3) –

  • calibration (CameraCal) –

  • image_size (Optional[Sequence[float]]) –

pixel_from_global_point(point, epsilon=0.0)[source]

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

UV coodinates in pixel units, assuming the point is in view is_valid: 1 if point is valid

Return type

pixel

global_point_from_pixel(pixel, range_to_point, epsilon=0.0)[source]

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

The point in the global frame. is_valid: 1 if point is valid

Return type

global_point

warp_pixel(pixel, inverse_range, target_cam, epsilon=0.0)[source]

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 in the target camera is_valid: 1 if given point is valid in source camera and target camera

Return type

pixel

subs(*args, **kwargs)[source]

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: Optional[symforce.geo.matrix.Matrix21]
class SphericalCameraCal(focal_length, principal_point, distortion_coeffs=(0.0, 0.0, 0.0, 0.0), critical_theta=None, max_theta=3.141592653589793)[source]

Bases: symforce.cam.camera_cal.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

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.

The storage for this class is: [ fx fy cx cy critical_theta d0 d1 d2 d3 ]

Parameters
  • focal_length (Sequence[float]) –

  • principal_point (Sequence[float]) –

  • distortion_coeffs (Sequence[float]) –

  • critical_theta (Optional[float]) –

  • max_theta (float) –

NUM_DISTORTION_COEFFS = 4
__init__(focal_length, principal_point, distortion_coeffs=(0.0, 0.0, 0.0, 0.0), critical_theta=None, max_theta=3.141592653589793)[source]
Parameters
  • critical_theta (Optional[float]) – The maximum angle from the optical axis for which the projection is valid. In general, this should be at least as large as the FOV of the camera. If the distortion coeffs are all numerical, this will be computed automatically as either the first local maximum of r(theta) in the interval (0, max_theta), or as max_theta if there is no local maximum in the interval.

  • max_theta (float) – Used only to compute critical_theta when the distortion coefficients are all numerical, see the description for critical_theta. The default value of 180 degrees should generally be fine regardless of the actual field of view

  • focal_length (Sequence[float]) –

  • principal_point (Sequence[float]) –

  • distortion_coeffs (Sequence[float]) –

classmethod from_distortion_coeffs(focal_length, principal_point, distortion_coeffs=(), **kwargs)[source]

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()[source]

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()[source]

Dimension of underlying storage

Return type

int

to_storage()[source]

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

Return type

List[float]

classmethod from_storage(vec)[source]

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

Parameters

vec (Sequence[float]) –

Return type

SphericalCameraCal

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

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

Parameters
  • name (str) –

  • kwargs (Any) –

Return type

SphericalCameraCal

pixel_from_camera_point(point, epsilon=0.0)[source]

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

Returns

(x, y) coordinate in pixels if valid is_valid: 1 if the operation is within bounds else 0

Return type

pixel

Parameters
  • point (Matrix31) –

  • epsilon (float) –

camera_ray_from_pixel(pixel, epsilon=0)[source]

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

TODO(hayk): Add a normalize boolean argument? Like in cam.Camera

Returns

The ray in the camera frame (NOT normalized) is_valid: 1 if the operation is within bounds else 0

Return type

camera_ray

Parameters
  • pixel (Matrix21) –

  • epsilon (float) –