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 Add(*args, **kwargs)¶
Bases:
AssocOp
- as_coefficients_dict()¶
- property func¶
- identity = 0¶
- property is_Add¶
- class Basic¶
Bases:
object
- args¶
- args_as_sage()¶
- args_as_sympy()¶
- as_coefficients_dict()¶
- as_numer_denom()¶
- as_real_imag()¶
- atoms()¶
- coeff()¶
- copy()¶
- diff()¶
- evalf()¶
- expand()¶
- free_symbols¶
- has()¶
- is_Add¶
- is_AlgebraicNumber¶
- is_Atom¶
- is_Boolean¶
- is_DataBufferElement¶
- is_Derivative¶
- is_Dummy¶
- is_Equality¶
- is_Float¶
- is_Function¶
- is_Integer¶
- is_Matrix¶
- is_Mul¶
- is_Not¶
- is_Number¶
- is_Pow¶
- is_Rational¶
- is_Relational¶
- is_Symbol¶
- is_finite¶
- is_integer¶
- is_negative¶
- is_nonnegative¶
- is_nonpositive¶
- is_number¶
- is_positive¶
- is_real¶
- is_symbol¶
- is_zero¶
- msubs()¶
- n()¶
- replace()¶
- simplify()¶
- subs()¶
- subs_dict()¶
- subs_oldnew()¶
- xreplace()¶
- class Contains(expr, sset)¶
Bases:
Boolean
- class Derivative(expr, *variables)¶
Bases:
Expr
- property expr¶
- property func¶
- property is_Derivative¶
- property variables¶
- class FiniteSet(*args)¶
Bases:
Set
- class Float(num, dps=None, precision=None)¶
Bases:
Number
- property is_Float¶
- property is_irrational¶
- property is_rational¶
- property is_real¶
- class Integer(i)¶
Bases:
Rational
- doit(**hints)¶
- property func¶
- get_num_den()¶
- property is_Integer¶
- property is_integer¶
- property p¶
- property q¶
- class Interval(*args)¶
Bases:
Set
- class LambertW(x)¶
Bases:
OneArgFunction
- Mod()¶
- class Mul(*args, **kwargs)¶
Bases:
AssocOp
- as_coefficients_dict()¶
- property func¶
- identity = 1¶
- property is_Mul¶
- class Number¶
Bases:
Expr
- imag¶
- is_Atom¶
- is_Number¶
- is_commutative¶
- is_complex¶
- is_negative¶
- is_nonnegative¶
- is_nonpositive¶
- is_nonzero¶
- is_number¶
- is_positive¶
- real¶
- class Pow(a, b)¶
Bases:
Expr
- as_base_exp()¶
- property base¶
- property exp¶
- property func¶
- property is_Pow¶
- property is_commutative¶
- class Rational(p, q)¶
Bases:
Number
- property func¶
- get_num_den()¶
- property is_Rational¶
- property is_finite¶
- property is_integer¶
- property is_rational¶
- property is_real¶
- property p¶
- property q¶
- class Subs(expr, variables, point)¶
Bases:
Expr
- property expr¶
- property func¶
- property point¶
- property variables¶
- exception SympifyError¶
Bases:
Exception
- class UnevaluatedExpr(x)¶
Bases:
OneArgFunction
- property is_finite¶
- property is_integer¶
- property is_number¶
- class acos(x)¶
Bases:
TrigFunction
- class acosh(x)¶
Bases:
HyperbolicFunction
- class acot(x)¶
Bases:
TrigFunction
- class acoth(x)¶
Bases:
HyperbolicFunction
- class acsc(x)¶
Bases:
TrigFunction
- class acsch(x)¶
Bases:
HyperbolicFunction
- class asec(x)¶
Bases:
TrigFunction
- class asech(x)¶
Bases:
HyperbolicFunction
- class asin(x)¶
Bases:
TrigFunction
- class asinh(x)¶
Bases:
HyperbolicFunction
- class atan(x)¶
Bases:
TrigFunction
- class atanh(x)¶
Bases:
HyperbolicFunction
- class ceiling(x)¶
Bases:
OneArgFunction
- class conjugate(x)¶
Bases:
OneArgFunction
- class cos(x)¶
Bases:
TrigFunction
- class cosh(x)¶
Bases:
HyperbolicFunction
- class cot(x)¶
Bases:
TrigFunction
- class coth(x)¶
Bases:
HyperbolicFunction
- class csc(x)¶
Bases:
TrigFunction
- class csch(x)¶
Bases:
HyperbolicFunction
- cse()¶
Perform common subexpression elimination on an expression.
- Parameters:
exprs (iterable of symengine expressions) – The expressions to reduce.
symbols (infinite iterator yielding unique Symbols) – The symbols used to label the common subexpressions which are pulled out. The default is a stream of symbols of the form “x0”, “x1”, etc. This must be an infinite iterator.
- Returns:
replacements (list of (Symbol, expression) pairs) – All of the common subexpressions that were replaced. Subexpressions earlier in this list might show up in subexpressions later in this list.
reduced_exprs (list of symengine expressions) – The reduced expressions with all of the replacements above.
- diff()¶
- digamma()¶
- class dirichlet_eta(x)¶
Bases:
OneArgFunction
- class erf(x)¶
Bases:
OneArgFunction
- class erfc(x)¶
Bases:
OneArgFunction
- exp()¶
- expand()¶
- class floor(x)¶
Bases:
OneArgFunction
- gamma()¶
- integer_nthroot()¶
- isprime()¶
- latex()¶
- linsolve()¶
Solve a set of linear equations given as an iterable eqs which are linear w.r.t the symbols given as an iterable syms
- class log(x, y=None)¶
Bases:
OneArgFunction
- class loggamma(x)¶
Bases:
OneArgFunction
- perfect_power()¶
- class sec(x)¶
Bases:
TrigFunction
- class sech(x)¶
Bases:
HyperbolicFunction
- series()¶
- class sin(x)¶
Bases:
TrigFunction
- class sinh(x)¶
Bases:
HyperbolicFunction
- sqrt()¶
- sqrt_mod()¶
- sympify()¶
Converts an expression ‘a’ into a SymEngine type.
- Parameters:
convert. (a ............. An expression to) –
Examples
>>> from symengine import sympify >>> sympify(1) 1 >>> sympify("a+b") a + b
- class tan(x)¶
Bases:
TrigFunction
- class tanh(x)¶
Bases:
HyperbolicFunction
- trigamma()¶
- 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 usevar()
in library code, wheresymbols()
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 tovar()
.
- 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
.- Return type:
Any
- Returns:
The current default epsilon. This is typically some kind of “Scalar”, like a float or a
Symbol
.
- class Symbol(name, commutative=True, real=True, positive=None)[source]¶
Bases:
Symbol
- 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 fromnames
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 toTrue
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))
- 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
- less_equal(x, y)[source]¶
Returns 1 if x <= y, 0 otherwise
- Parameters:
x (
float
) –y (
float
) –
- Return type:
float
- greater_equal(x, y)[source]¶
Returns 1 if x >= y, 0 otherwise
- Parameters:
x (
float
) –y (
float
) –
- Return type:
float
- less(x, y)[source]¶
Returns 1 if x < y, 0 otherwise
- Parameters:
x (
float
) –y (
float
) –
- Return type:
float
- greater(x, y)[source]¶
Returns 1 if x > y, 0 otherwise
- Parameters:
x (
float
) –y (
float
) –
- Return type:
float
- logical_and(*args, unsafe=False)[source]¶
Logical and of two or more Scalars
Input values are treated as true if they are positive, false if they are 0 or negative. The returned value is 1 for true, 0 for false.
If unsafe is True, the resulting expression is fewer ops but assumes the inputs are exactly 0 or 1; results for other (finite) inputs will be finite, but are otherwise undefined.
- Parameters:
args (
float
) –unsafe (
bool
) –
- Return type:
float
- logical_or(*args, unsafe=False)[source]¶
Logical or of two or more Scalars
Input values are treated as true if they are positive, false if they are 0 or negative. The returned value is 1 for true, 0 for false.
If unsafe is True, the resulting expression is fewer ops but assumes the inputs are exactly 0 or 1; results for other (finite) inputs will be finite, but are otherwise undefined.
- Parameters:
args (
float
) –unsafe (
bool
) –
- Return type:
float
- logical_not(a, unsafe=False)[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 thatl[i] = 1.0
ifi
is the smallest index such thatvals[i]
equalsMax(*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 thati
is the smallest index such thatvals[i]
equalsMax(*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
- clamp(x, min_value, max_value)[source]¶
Clamps x between min_value and max_value
Returns:
min_value if x < min_value x if min_value <= x <= max_value max_value if x > max_value
- Parameters:
x (
float
) – Value to clamp between min_value and max_valuemin_value (
float
) – Scalar of same type and units as x; minimum value to returnmax_value (
float
) – Scalar of same type and units as x; maximum value to return. Must be greater than min_value.
- Return type:
float
- set_eval_on_sympify(eval_on_sympy=True)[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
- limit(e, z, z0, dir='+')[source]¶
- Parameters:
e (
Any
) –z (
Any
) –z0 (
Any
) –dir (
str
) –
- Return type:
float
- count_ops()¶
- class DataBuffer(name, rows=None)¶
Bases:
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,
a DictBasic
a Python dictionary
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
- scope(scope: str) Iterator[None] ¶
- Parameters:
scope (
str
) –- Return type:
Iterator
[None
]
- class Complex(real, imag)[source]¶
Bases:
Group
A complex number is a number that can be expressed in the form a + bi, where a and b are real numbers, and i is a solution of the equation x**2 = -1. Because no real number satisfies this equation, i is called an imaginary number. For the complex number a + bi, a is called the real part, and b is called the imaginary part. Despite the historical nomenclature “imaginary”, complex numbers are regarded in the mathematical sciences as just as “real” as the real numbers, and are fundamental in many aspects of the scientific description of the natural world.
A complex number is also a convenient way to store a two-dimensional rotation.
References
https://en.wikipedia.org/wiki/Complex_number
- Parameters:
real (
float
) –imag (
float
) –
- __init__(real, imag)[source]¶
Construct from a real and imaginary scalar.
- Parameters:
real (Scalar) –
imag (Scalar) –
- 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:
- 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:
- squared_norm()[source]¶
Squared norm of the two-vector.
- Returns:
real**2 + imag**2
- Return type:
Scalar
- __truediv__(scalar)¶
Scalar element-wise division.
- Parameters:
scalar (Scalar) –
- Return type:
- class DualQuaternion(real_q, inf_q)[source]¶
Bases:
Group
Dual quaternions can be used for rigid motions in 3D. Similar to the way that rotations in 3D space can be represented by quaternions of unit length, rigid motions in 3D space can be represented by dual quaternions of unit length. This fact is used in theoretical kinematics, and in applications to 3D computer graphics, robotics and computer vision.
References
https://en.wikipedia.org/wiki/Dual_quaternion
- Parameters:
real_q (
Quaternion
) –inf_q (
Quaternion
) –
- __init__(real_q, inf_q)[source]¶
Construct from two quaternions - a real one and an infinitesimal one.
- Parameters:
real_q (
Quaternion
) –inf_q (
Quaternion
) –
- 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:
- compose(other)[source]¶
Apply the group operation with other.
- Parameters:
other (
DualQuaternion
) –- Return type:
- __mul__(right)[source]¶
Left-multiply with another dual quaternion.
- Parameters:
right (
DualQuaternion
) –- Return type:
- __truediv__(scalar)¶
Scalar division.
- Parameters:
scalar (
float
) –- Return type:
- squared_norm()[source]¶
Squared norm when considering the dual quaternion as 8-tuple.
- Return type:
float
- 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 = ~StorageT¶
- __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
- __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:
Storage
Matrix type that wraps the SymPy Matrix class. Care has been taken to allow this class to create fixed-size child classes like
Matrix31
. Anytime__new__()
is called, the appropriate fixed size class is returned rather than the type of the arguments. The API is meant to parallel the way Eigen’s C++ matrix classes work with dynamic and fixed sizes, as well as internal use cases within SymPy and SymEngine.Examples:
1) Matrix32() # Zero constructed Matrix32 2) Matrix(sm.Matrix([[1, 2], [3, 4]])) # Matrix22 with [1, 2, 3, 4] data 3A) Matrix([[1, 2], [3, 4]]) # Matrix22 with [1, 2, 3, 4] data 3B) Matrix22([1, 2, 3, 4]) # Matrix22 with [1, 2, 3, 4] data (must matched fixed shape) 3C) Matrix([1, 2, 3, 4]) # Matrix41 with [1, 2, 3, 4] data - column vector assumed 4) Matrix(4, 3) # Zero constructed Matrix43 5) Matrix(2, 2, [1, 2, 3, 4]) # Matrix22 with [1, 2, 3, 4] data (first two are shape) 6) Matrix(2, 2, lambda row, col: row + col) # Matrix22 with [0, 1, 1, 2] data 7) Matrix22(1, 2, 3, 4) # Matrix22 with [1, 2, 3, 4] data (must match fixed length)
References
https://docs.sympy.org/latest/tutorial/matrices.html https://eigen.tuxfamily.org/dox/group__TutorialMatrixClass.html https://en.wikipedia.org/wiki/Vector_space
Matrix does not implement the group or lie group concepts using instance/class methods directly, because we want it to represent the group R^{NxM}, not GL(n), which leads to the
identity
andinverse
methods being confusingly named. For the group ops and lie group ops, usesymforce.ops.group_ops.GroupOps
andsymforce.ops.lie_group_ops.LieGroupOps
respectively, which use the implementation insymforce.ops.impl.vector_class_lie_group_ops
of the R^{NxM} group under matrix addition. For the identity matrix and inverse matrix, seeMatrix.eye()
andMatrix.inv()
respectively.- Parameters:
args (
Any
) –kwargs (
Any
) –
- MatrixT = ~MatrixT¶
- 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. See the Matrix docstring for a summary of the construction options.
- Parameters:
args (
Any
) –kwargs (
Any
) –
- Return type:
- 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 from_storage(vec)[source]¶
Construct from a flat list representation. Opposite of
to_storage()
.- Parameters:
cls (_T.Type[MatrixT]) –
vec (_T.Union[_T.Sequence[_T.Scalar], Matrix]) –
- Return type:
MatrixT
- 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_tangent(vec, epsilon=0.0)[source]¶
- Parameters:
cls (_T.Type[MatrixT]) –
vec (_T.Sequence[_T.Scalar]) –
epsilon (_T.Scalar) –
- Return type:
MatrixT
- classmethod zero()[source]¶
Matrix of zeros.
- Parameters:
cls (_T.Type[MatrixT]) –
- Return type:
MatrixT
- classmethod zeros(rows, cols)[source]¶
Matrix of zeros.
- Parameters:
cls (_T.Type[MatrixT]) –
rows (int) –
cols (int) –
- Return type:
MatrixT
- classmethod one()[source]¶
Matrix of ones.
- Parameters:
cls (_T.Type[MatrixT]) –
- Return type:
MatrixT
- classmethod ones(rows, cols)[source]¶
Matrix of ones.
- Parameters:
cls (_T.Type[MatrixT]) –
rows (int) –
cols (int) –
- Return type:
MatrixT
- classmethod diag(diagonal)[source]¶
Construct a square matrix from the diagonal.
- Parameters:
cls (_T.Type[MatrixT]) –
diagonal (_T.Sequence[_T.Scalar]) –
- Return type:
MatrixT
- 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
- classmethod block_matrix(array)[source]¶
Constructs a matrix from block elements.
For example:
[[Matrix22(...), Matrix23(...)], [Matrix11(...), Matrix14(...)]]
constructs a
Matrix35
with elements equal to given blocks
- 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:
- 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:
- 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:
- lower_triangle()[source]¶
Returns the lower triangle (including diagonal) of self
self must be square
- Parameters:
self (MatrixT) –
- Return type:
MatrixT
- dot(other)[source]¶
Dot product, also known as inner product.
Only supports mapping
1 x n
orn 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.0)[source]¶
Norm of a vector (square root of magnitude).
- Parameters:
epsilon (
float
) –- Return type:
float
- normalized(epsilon=0.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.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 ifmax_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.
Unlike sympy, for 1D matrices the submatrix slice is returned as a 1D matrix instead of as a list.
- Parameters:
item (
Any
) –- Return type:
Any
- __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
- 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))
- __truediv__(right)¶
Divide a matrix by a scalar or a matrix (which takes the inverse).
- static are_parallel(a, b, tolerance)[source]¶
Returns 1 if a and b are parallel within tolerance, and 0 otherwise.
- to_numpy(scalar_type=<class 'numpy.float64'>)[source]¶
Convert to a numpy array.
- Parameters:
scalar_type (
type
) –- Return type:
ndarray
- class Matrix11(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (1, 1)¶
- class Matrix21(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (2, 1)¶
- property x: float¶
The entry self[0, 0]
- Return type:
float
- property y: float¶
The entry self[1, 0]
- Return type:
float
- class Matrix31(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (3, 1)¶
- property x: float¶
The entry self[0, 0]
- Return type:
float
- property y: float¶
The entry self[1, 0]
- Return type:
float
- property z: float¶
The entry self[2, 0]
- Return type:
float
- class Matrix41(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (4, 1)¶
- class Matrix51(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (5, 1)¶
- class Matrix61(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (6, 1)¶
- class Matrix71(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (7, 1)¶
- class Matrix81(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (8, 1)¶
- class Matrix91(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (9, 1)¶
- class Matrix12(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (1, 2)¶
- class Matrix22(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (2, 2)¶
- class Matrix32(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (3, 2)¶
- class Matrix42(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (4, 2)¶
- class Matrix52(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (5, 2)¶
- class Matrix62(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (6, 2)¶
- class Matrix72(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (7, 2)¶
- class Matrix82(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (8, 2)¶
- class Matrix92(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (9, 2)¶
- class Matrix13(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (1, 3)¶
- class Matrix23(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (2, 3)¶
- class Matrix33(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (3, 3)¶
- class Matrix43(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (4, 3)¶
- class Matrix53(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (5, 3)¶
- class Matrix63(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (6, 3)¶
- class Matrix73(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (7, 3)¶
- class Matrix83(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (8, 3)¶
- class Matrix93(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (9, 3)¶
- class Matrix14(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (1, 4)¶
- class Matrix24(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (2, 4)¶
- class Matrix34(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (3, 4)¶
- class Matrix44(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (4, 4)¶
- class Matrix54(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (5, 4)¶
- class Matrix64(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (6, 4)¶
- class Matrix74(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (7, 4)¶
- class Matrix84(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (8, 4)¶
- class Matrix94(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (9, 4)¶
- class Matrix15(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (1, 5)¶
- class Matrix25(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (2, 5)¶
- class Matrix35(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (3, 5)¶
- class Matrix45(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (4, 5)¶
- class Matrix55(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (5, 5)¶
- class Matrix65(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (6, 5)¶
- class Matrix75(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (7, 5)¶
- class Matrix85(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (8, 5)¶
- class Matrix95(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (9, 5)¶
- class Matrix16(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (1, 6)¶
- class Matrix26(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (2, 6)¶
- class Matrix36(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (3, 6)¶
- class Matrix46(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (4, 6)¶
- class Matrix56(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (5, 6)¶
- class Matrix66(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (6, 6)¶
- class Matrix76(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (7, 6)¶
- class Matrix86(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (8, 6)¶
- class Matrix96(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (9, 6)¶
- class Matrix17(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (1, 7)¶
- class Matrix27(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (2, 7)¶
- class Matrix37(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (3, 7)¶
- class Matrix47(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (4, 7)¶
- class Matrix57(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (5, 7)¶
- class Matrix67(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (6, 7)¶
- class Matrix77(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (7, 7)¶
- class Matrix87(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (8, 7)¶
- class Matrix97(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (9, 7)¶
- class Matrix18(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (1, 8)¶
- class Matrix28(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (2, 8)¶
- class Matrix38(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (3, 8)¶
- class Matrix48(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (4, 8)¶
- class Matrix58(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (5, 8)¶
- class Matrix68(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (6, 8)¶
- class Matrix78(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (7, 8)¶
- class Matrix88(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (8, 8)¶
- class Matrix98(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (9, 8)¶
- class Matrix19(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (1, 9)¶
- class Matrix29(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (2, 9)¶
- class Matrix39(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (3, 9)¶
- class Matrix49(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (4, 9)¶
- class Matrix59(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (5, 9)¶
- class Matrix69(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (6, 9)¶
- class Matrix79(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (7, 9)¶
- class Matrix89(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (8, 9)¶
- class Matrix99(*args, **kwargs)[source]¶
Bases:
Matrix
- Parameters:
args (
Any
) –kwargs (
Any
) –
- SHAPE = (9, 9)¶
- matrix_type_from_shape(shape)[source]¶
Return a fixed size matrix type (like
Matrix32
) given a shapeEither uses the statically defined ones or dynamically creates a new one if not available.
- Parameters:
shape (
Tuple
[int
,int
]) –- Return type:
Type
[Matrix
]
- 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:
ClassStorageOps
,AbstractVectorLieGroupOps
[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:
LieGroup
Group of two-dimensional rigid body transformations - R2 x SO(2).
The storage space is a complex (real, imag) for rotation followed by a position (x, y).
The tangent space is one angle for rotation followed by two elements for translation in the non-rotated frame.
For Lie group enthusiasts: This class is on the PRODUCT manifold. On this class, the group operations (e.g. compose and between) operate as you’d expect for a Pose or SE(2), but the manifold operations (e.g. retract and local_coordinates) operate on the product manifold SO(2) x R2. This means that:
retract(a, vec) != compose(a, from_tangent(vec))
local_coordinates(a, b) != to_tangent(between(a, b))
There is no hat operator, because from_tangent/to_tangent is not the matrix exp/log
If you need a type that has these properties in symbolic expressions, you should use
symforce.geo.unsupported.pose2_se2.Pose2_SE2
. There is no runtime equivalent ofPose2_SE2
, see the docstring on that class for more information.- Pose2T = ~Pose2T¶
- rotation()[source]¶
Accessor for the rotation component
Does not make a copy. Also accessible as
self.R
- Return type:
- position()[source]¶
Accessor for the position component
Does not make a copy. Also accessible as
self.t
- Return type:
- 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:
- 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:
- 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:
- tangent_D_storage()[source]¶
Note: generated from
symforce/notebooks/tangent_D_storage.ipynb
- Return type:
- retract(vec, epsilon=0.0)[source]¶
Applies a tangent space perturbation vec to self. Often used in optimization to update nonlinear values from an update step in the tangent space.
Conceptually represents
self + vec
if self is a vector.Implementation retracts the R and t components separately, which is different from
compose(self, from_tangent(vec))
. See the class docstring for more information.
- 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.
Tangent space perturbation that conceptually represents
b - self
if self is a vector.Implementation takes local_coordinates of the R and t components separately, which is different from
to_tangent(between(self, b))
. See the class docstring for more information.- Parameters:
self (Pose2T) –
b (Pose2T) –
epsilon (T.Scalar) –
- Return type:
T.List[T.Scalar]
- class Pose3(R=None, t=None)[source]¶
Bases:
LieGroup
Group of three-dimensional rigid body transformations - SO(3) x R3.
The storage is a quaternion (x, y, z, w) for rotation followed by position (x, y, z).
The tangent space is 3 elements for rotation followed by 3 elements for translation in the non-rotated frame.
For Lie group enthusiasts: This class is on the PRODUCT manifold. On this class, the group operations (e.g. compose and between) operate as you’d expect for a Pose or SE(3), but the manifold operations (e.g. retract and local_coordinates) operate on the product manifold SO(3) x R3. This means that:
retract(a, vec) != compose(a, from_tangent(vec))
local_coordinates(a, b) != to_tangent(between(a, b))
There is no hat operator, because from_tangent/to_tangent is not the matrix exp/log
If you need a type that has these properties in symbolic expressions, you should use
symforce.geo.unsupported.pose3_se3.Pose3_SE3
. There is no runtime equivalent ofPose3_SE3
, see the docstring on that class for more information.- Pose3T = ~Pose3T¶
- rotation()[source]¶
Accessor for the rotation component
Does not make a copy. Also accessible as
self.R
- Return type:
- position()[source]¶
Accessor for the position component
Does not make a copy. Also accessible as
self.t
- Return type:
- 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 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:
- tangent_D_storage()[source]¶
Note: generated from
symforce/notebooks/tangent_D_storage.ipynb
- Parameters:
self (Pose3T) –
- Return type:
- retract(vec, epsilon=0.0)[source]¶
Applies a tangent space perturbation vec to self. Often used in optimization to update nonlinear values from an update step in the tangent space.
Conceptually represents
self + vec
if self is a vector.Implementation retracts the R and t components separately, which is different from
compose(self, from_tangent(vec))
. See the class docstring for more information.- Parameters:
self (Pose3T) –
vec (T.Sequence[T.Scalar]) –
epsilon (T.Scalar) –
- Return type:
Pose3T
- local_coordinates(b, epsilon=0.0)[source]¶
Computes a tangent space perturbation around self to produce b. Often used in optimization to minimize the distance between two group elements.
Tangent space perturbation that conceptually represents
b - self
if self is a vector.Implementation takes local_coordinates of the R and t components separately, which is different from
to_tangent(between(self, b))
. See the class docstring for more information.- Parameters:
self (Pose3T) –
b (Pose3T) –
epsilon (T.Scalar) –
- Return type:
T.List[T.Scalar]
- class Quaternion(xyz, w)[source]¶
Bases:
Group
Unit quaternions, also known as versors, provide a convenient mathematical notation for representing orientations and rotations of objects in three dimensions. Compared to Euler angles they are simpler to compose and avoid the problem of gimbal lock. Compared to rotation matrices they are more compact, more numerically stable, and more efficient.
Storage is (x, y, z, w).
References
https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation
- Parameters:
xyz (
Matrix31
) –w (
float
) –
- __init__(xyz, w)[source]¶
Construct from a real scalar and an imaginary unit vector.
- Parameters:
xyz (
Matrix31
) –w (
float
) –
- property x: float¶
- Return type:
float
- property y: float¶
- Return type:
float
- property z: float¶
- Return type:
float
- 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:
- 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:
- compose(other)[source]¶
Apply the group operation with other.
- Parameters:
other (
Quaternion
) –- Return type:
- __mul__(right)[source]¶
Quaternion multiplication.
- Parameters:
right (Quaternion) –
- Return type:
- __add__(right)[source]¶
Quaternion addition.
- Parameters:
right (Quaternion) –
- Return type:
- __truediv__(scalar)¶
Scalar division.
- Parameters:
scalar (Scalar) –
- Return type:
- squared_norm()[source]¶
Squared norm when considering the quaternion as 4-tuple.
- Return type:
Scalar
- class Rot2(z=None)[source]¶
Bases:
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) –
- 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:
- 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:
- 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:
- 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:
- tangent_D_storage()[source]¶
Note: generated from
symforce/notebooks/tangent_D_storage.ipynb
- Return type:
- classmethod from_angle(theta)[source]¶
Create a Rot2 from an angle
theta
in radiansThis is equivalent to
from_tangent([theta])
- Parameters:
theta (
float
) –- Return type:
- class Rot3(q=None)[source]¶
Bases:
LieGroup
Group of three-dimensional orthogonal matrices with determinant +1, representing rotations in 3D space. Backed by a quaternion with (x, y, z, w) storage.
- Parameters:
q (
Optional
[Quaternion
]) –
- __init__(q=None)[source]¶
Construct from a unit quaternion, or identity if none provided.
- Parameters:
q (
Optional
[Quaternion
]) –
- 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:
- 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:
- 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:
- 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:
- tangent_D_storage()[source]¶
Note: generated from
symforce/notebooks/tangent_D_storage.ipynb
- Return type:
- 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:
- classmethod from_angle_axis(angle, axis)[source]¶
Construct from an angle in radians and a (normalized) axis as a 3-vector.
- 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.
- class Unit3(rot3=None)[source]¶
Bases:
LieGroup
Direction in R^3, represented as a
Rot3
that transforms [0, 0, 1] to the desired direction.The storage is therefore a quaternion and the tangent space is 2 dimensional. Most operations are implemented using operations from
Rot3
.Note: an alternative implementation could directly store a unit vector and define its boxplus manifold as described in Appendix B.2 of [Hertzberg 2013]. This can be done by finding the Householder reflector of x and use it to transform the exponential map of delta, which is a small perturbation in the tangent space (R^2). Namely:
x.retract(delta) = x [+] delta = Rx * Exp(delta), where Exp(delta) = [sinc(||delta||) * delta, cos(||delta||)], and Rx = (I - 2 vv^T / (v^Tv))X, v = x - e_z != 0, X is a matrix negating 2nd vector component = I , x = e_z
[Hertzberg 2013] Integrating Generic Sensor Fusion Algorithms with Sound State Representations through Encapsulation of Manifolds
- Parameters:
rot3 (
Optional
[Rot3
]) –
- E_Z = [0] [0] [1] ¶
- __init__(rot3=None)[source]¶
Construct from a
Rot3
, or identity if none provided.- Parameters:
rot3 (
Optional
[Rot3
]) –
- 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:
- 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:
- 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:
- to_tangent(epsilon=0.0)[source]¶
Mapping from this element to the tangent space vector about identity.
- Parameters:
epsilon (
float
) –- Return type:
List
[float
]
- class ATANCameraCal(focal_length, principal_point, omega)[source]¶
Bases:
CameraCal
ATAN camera with 5 parameters [fx, fy, cx, cy, omega]. (fx, fy) representing focal length, (cx, cy) representing principal point, and omega representing the distortion parameter.
See here for more details: https://hal.inria.fr/inria-00267247/file/distcalib.pdf
- Parameters:
focal_length (
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:
- 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
], …]
- 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 = ~CameraT¶
- __init__(calibration, image_size=None)[source]¶
- Parameters:
calibration (
CameraCal
) –image_size (
Optional
[Sequence
[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 (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
- class CameraCal(focal_length, principal_point, distortion_coeffs=())[source]¶
Bases:
Storage
Base class for symbolic camera models.
- Parameters:
focal_length (
Sequence
[float
]) –principal_point (
Sequence
[float
]) –distortion_coeffs (
Sequence
[float
]) –
- CameraCalT = ~CameraCalT¶
- NUM_DISTORTION_COEFFS = 0¶
- __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
], …]
- 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
- 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.
- 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 methodcamera_ray_from_pixel()
, andFalse
otherwise.- Return type:
bool
- class DoubleSphereCameraCal(focal_length, principal_point, xi, alpha)[source]¶
Bases:
CameraCal
Camera model where a point is consecutively projected onto two unit spheres with centers shifted by
xi
, then projected into the image plane using the pinhole model shifted byalpha / (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
- 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:
- 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
], …]
- class EquirectangularCameraCal(focal_length, principal_point, distortion_coeffs=())[source]¶
Bases:
CameraCal
Equirectangular camera model with parameters [fx, fy, cx, cy].
(fx, fy) representing focal length; (cx, cy) representing principal point.
- Parameters:
focal_length (
Sequence
[float
]) –principal_point (
Sequence
[float
]) –distortion_coeffs (
Sequence
[float
]) –
- NUM_DISTORTION_COEFFS = 0¶
- class LinearCameraCal(focal_length, principal_point, distortion_coeffs=())[source]¶
Bases:
CameraCal
Standard pinhole camera w/ four parameters [fx, fy, cx, cy].
(fx, fy) representing focal length; (cx, cy) representing principal point.
- Parameters:
focal_length (
Sequence
[float
]) –principal_point (
Sequence
[float
]) –distortion_coeffs (
Sequence
[float
]) –
- NUM_DISTORTION_COEFFS = 0¶
- static project(point, epsilon=0.0)[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 pointepsilon (
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.
- unit_depth_from_pixel(pixel)[source]¶
Convert point in pixel coordinates to unit-depth image plane by applying K_inv.
- class PolynomialCameraCal(focal_length, principal_point, distortion_coeffs=(0.0, 0.0, 0.0), critical_undistorted_radius=None, max_fov=2.0943951023931953)[source]¶
Bases:
CameraCal
Polynomial camera model in the style of OpenCV
Distortion is a multiplicative factor applied to the image plane coordinates in the camera frame. Mapping between distorted image plane coordinates and image coordinates is done using a standard linear model.
The distortion function is a 6th order even polynomial that is a function of the radius of the image plane coordinates:
r = (p_img[0] ** 2 + p_img[1] ** 2) ** 0.5 distorted_weight = 1 + c0 * r^2 + c1 * r^4 + c2 * r^6 uv = p_img * distorted_weight
- Parameters:
focal_length (
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:
- 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.
- 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
) –
- 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:
- class PosedCamera(pose, calibration, image_size=None)[source]¶
Bases:
Camera
Camera with a given pose, camera calibration, and an optionally specified image size.
If the image size is specified, we use it to check whether pixels (either given or computed by projection of 3D points into the image frame) are in the image frame and thus valid/invalid.
- PosedCameraT = ~PosedCameraT¶
- 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 pixelepsilon (
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 camerainverse_range (
float
) – Inverse distance along the ray to the global pointtarget_cam (
PosedCamera
) – Camera to project global point intoepsilon (
float
) –
- Returns:
Pixel in the target camera is_valid: 1 if given point is valid in source camera and target camera
- Return type:
pixel
- 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:
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 viewfocal_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:
- 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
], …]
- 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:
- 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: