se(2) twist

class Twist2(arg=None, w=None, check=True)[source]

Bases: spatialmath.twist.BaseTwist

classmethod Alloc(n=1)

Construct an instance with N default values (BasePoseList superclass method)

Parameters: n (int, optional) – Number of values, defaults to 1
Return type: Self
Returns: pose instance with n default values

X.Alloc(N) creates an instance of the pose class X with N default values, ie. len(X) will be N.

X can be considered a vector of pose objects, and those elements can be referenced X[i] or assigned to X[i] = ....

Note

The default value depends on the pose class and is the result of the empty constructor. For SO2, SE2, SO3, SE3 it is an identity matrix, for a twist class Twist2 or Twist3 it is a zero vector, for a UnitQuaternion or Quaternion it is a zero vector.

Example:

>>> x = X.Alloc(10)
>>> len(x)
10

where X is any of the SMTB classes.

classmethod Empty()

Construct an empty instance (BasePoseList superclass method)

Return type: Self
Returns: pose instance with zero values

Example:

>>> x = X.Empty()
>>> len(x)
0

where X is any of the SMTB classes.

SE2(theta=1, unit='rad')[source]

Convert 2D twist to SE(2) matrix

Returns: an SE(2) representation
Return type: SE3 instance

S.SE2() is an SE2 object representing the homogeneous transformation equivalent to the Twist2. This is the exponentiation of the twist vector.

Example:

  File "<input>", line 1, in <module>
NameError: name 'S' is not defined

Seealso: Twist3.exp()

classmethod Tx(x)[source]

Create a new 2D twist for pure translation along the X-axis

Parameters: x (float) – translation distance along the X-axis
Returns: 2D twist vector
Return type: Twist2 instance

Twist2.Tx(x) is an se(2) translation of x along the x-axis

Example:

  File "/opt/hostedtoolcache/Python/3.7.17/x64/lib/python3.7/site-packages/spatialmath/twist.py", line 1822, in <listcomp>
    ["  [{:.5g}, {:.5g}, {:.5g}}]".format(*list(tw.S)) for tw in self]
ValueError: Single '}' encountered in format string

Seealso: transl2()
SymPy: supported

classmethod Ty(y)[source]

Create a new 2D twist for pure translation along the Y-axis

Parameters: y (float) – translation distance along the Y-axis
Returns: 2D twist vector
Return type: Twist2 instance

Twist2.Ty(y) is an se(2) translation of ``y` along the y-axis

Example:

  File "/opt/hostedtoolcache/Python/3.7.17/x64/lib/python3.7/site-packages/spatialmath/twist.py", line 1822, in <listcomp>
    ["  [{:.5g}, {:.5g}, {:.5g}}]".format(*list(tw.S)) for tw in self]
ValueError: Single '}' encountered in format string

Seealso: transl2()
SymPy: supported

classmethod UnitPrismatic(a)[source]

Construct a new 2D primsmatic unit twist

Parameters: a (array-like(2)) – Displacment
Returns: 2D prismatic twist
Return type: Twist2 instance

Twist2.Prismatic(a) is a 2D Twist object representing 2D-translation in the direction a.

Example:

classmethod UnitRevolute(q)[source]

Construct a new 2D revolute unit twist

Parameters: q (array_like(2)) – Point on the line of action
Returns: 2D prismatic twist
Return type: Twist2 instance

Twist2.Revolute(q) is a 2D Twist object representing rotation about the 2D point q.

Example:

__eq__(right)

Overloaded == operator (superclass method)

Returns: Equality of two operands
Return type: bool or list of bool

S1 == S2 is True if S1` is elementwise equal to ``S2.

Example:

  File "<input>", line 1, in <module>
NameError: name 'Twist3' is not defined
Traceback (most recent call last):
  File "<input>", line 1, in <module>
NameError: name 'S1' is not defined
Traceback (most recent call last):
  File "<input>", line 1, in <module>
NameError: name 'Twist3' is not defined
Traceback (most recent call last):
  File "<input>", line 1, in <module>
NameError: name 'S1' is not defined

Seealso: __ne__()

__init__(arg=None, w=None, check=True)[source]

Construct a new 2D Twist object

type a

2-element array-like

return

2D prismatic twist

rtype

Twist2 instance

Twist2(R) is a 2D Twist object representing the SO(2) rotation expressed as a 2x2 matrix.

Twist2(T) is a 2D Twist object representing the SE(2) rigid-body motion expressed as a 3x3 matrix.

Twist2(X) if X is an SO2 instance then create a 2D Twist object representing the SO(2) rotation, and if X is an SE2 instance then create a 2D Twist object representing the SE(2) motion

Twist2(V) is a 2D Twist object specified directly by a 3-element array-like comprising the moment vector (1 element) and direction vector (2 elements).

References

Robotics, Vision & Control for Python, Section 2.2.2.4, P. Corke, Springer 2023.
Modern Robotics, Lynch & Park, Cambridge 2017

Note

Compared to Lynch & Park this module implements twist vectors with the translational components first, followed by rotational components, ie. \([\omega, \vec{v}]\).

__mul__(right)[source]

Overloaded * operator

Parameters

left – left multiplicand
right – right multiplicand

Returns

product

Raises

ValueError

X * Y compounds the twists X and Y
X * s performs elementwise multiplication of the elements of X by s
s * X performs elementwise multiplication of the elements of X by s

Multiplicands		Product
left	right	type	operation
Twist2	Twist2	Twist2	product of exponentials
Twist2	scalar	Twist2	element-wise product
scalar	Twist2	Twist2	element-wise product
Twist2	SE2	Twist2	exponential x SE2

Note

scalar x Twist is handled by __rmul__

#. scalar multiplication is commutative but the result is not a group operation so the result will be a matrix #. Any other input combinations result in a ValueError.

For pose composition the left and right operands may be a sequence

len(left)	len(right)	len	operation
1	1	1	`prod = left * right`
1	M	M	`prod[i] = left * right[i]`
N	1	M	`prod[i] = left[i] * right`
M	M	M	`prod[i] = left[i] * right[i]`

__ne__(right)

Overloaded != operator (superclass method)

Return type: bool

S1 == S2 is True if S1` is not elementwise equal to ``S2.

Example:

>>> from spatialmath import Twist3
>>> S1 = Twist3([1,2,3,4,5,6])
>>> S2 = Twist3([1,2,3,4,5,6])
>>> S1 != S2
False
>>> S2 = Twist3([1,2,3,4,5,7])
>>> S1 != S2
True

Seealso: __ne__()

__truediv__(right)

append(item)

Append a value to an instance (BasePoseList superclass method)

Parameters: x (Quaternion or UnitQuaternion instance) – the value to append
Raises: ValueError – incorrect type of appended object

Appends the argument to the object’s internal list of values.

Example:

>>> x = X.Alloc(10)
>>> len(x)
10
>>> x.append(X())   # append to the list
>>> len(x)
11

where X is any of the SMTB classes.

Return type: None

clear() → None -- remove all items from S

exp(theta=1, unit='rad')[source]

Exponentiate a 2D twist

Parameters

theta (float, optional) – rotation magnitude, defaults to None
unit (str, optional) – rotational units, defaults to ‘rad’

Returns

SE(2) matrix

Return type

SE2 instance

X.exp() is the homogeneous transformation equivalent to the twist, \(e^{[S]}\)
X.exp(θ) as above but with a rotation of ``θ about the twist axis, \(e^{\theta[S]}\)

Example:

>>> from spatialmath import SE2, Twist2
>>> T = SE2(1, 2, 0.3)
>>> S = Twist2(T)
>>> S.exp(0)
SE2(array([[1., 0., 0.],
           [0., 1., 0.],
           [0., 0., 1.]]))
>>> S.exp(1)
SE2(array([[ 0.9553, -0.2955,  1.    ],
           [ 0.2955,  0.9553,  2.    ],
           [ 0.    ,  0.    ,  1.    ]]))

Note

For the second form, the twist must, if rotational, have a unit rotational component.

Seealso: spatialmath.smb.trexp2()

extend(iterable)

Extend sequence of values in an instance (BasePoseList superclass method)

Parameters: x (instance of same type) – the value to extend
Raises: ValueError – incorrect type of appended object

Appends the argument’s values to the object’s internal list of values.

Example:

>>> x = X.Alloc(10)
>>> len(x)
10
>>> x.append(X.Alloc(5))   # extend the list
>>> len(x)
15

where X is any of the SMTB classes.

Return type: None

insert(i, item)

Insert a value to an instance (BasePoseList superclass method)

Parameters

i (int) – element to insert value before
item (instance of same type) – the value to insert

Raises

ValueError – incorrect type of inserted value

Inserts the argument into the object’s internal list of values.

Example:

>>> x = X.Alloc(10)
>>> len(x)
10
>>> x.insert(0, X())   # insert at start of list
>>> len(x)
11
>>> x.insert(10, X())   # append to the list
>>> len(x)
11

where X is any of the SMTB classes.

Note

If i is beyond the end of the list, the item is appended to the list

Return type: None

inv()

Inverse of Twist (superclass method)

Returns: inverse
Return type: Twist instance

Compute the inverse of each of the values within the twist instance. The inverse is the negative of the twist vector.

Example:

>>> from spatialmath import Twist3
>>> S = Twist3(SE3.Rand())
>>> S
Twist3([0.079776, -0.083173, 0.71509, 2.4785, -0.661, -0.58477])
>>> S.inv()
Twist3([-0.079776, 0.083173, -0.71509, -2.4785, 0.661, 0.58477])
>>> S * S.inv()
Twist3([0, 5.5511e-17, -1.3878e-17, 0, 0, 0])

static isvalid(v, check=True)[source]

Test if matrix is valid twist

Parameters: x (ndarray) – array to test
Returns: Whether the value is a 3-vector or a valid 3x3 se(2) element
Return type: bool

A twist can be represented by a 6-vector or a 4x4 skew symmetric matrix, for example:

  File "<input>", line 1, in <module>
NameError: name 'a' is not defined
Traceback (most recent call last):
  File "<input>", line 1, in <module>
NameError: name 'a' is not defined

pop(i=- 1)

Pop value from an instance (BasePoseList superclass method)

Parameters: i (int) – item in the list to pop, default is last
Returns: the popped value
Return type: instance of same type
Raises: IndexError – if there are no values to pop

Removes a value from the value list and returns it. The original instance is modified.

Example:

>>> x = X.Alloc(10)
>>> len(x)
10
>>> y = x.pop()  # pop the last value x[9]
>>> len(x)
9
>>> y = x.pop(0)  # pop the first value x[0]
>>> len(x)
8

where X is any of the SMTB classes.

printline(**kwargs)[source]

prod()

Product of twists (superclass method)

Returns: Product of elements
Return type: Twist2 or Twist3

For a twist instance with N values return the matrix product of those elements \(\prod_i=0^{N-1} S_i\).

Example:

>>> from spatialmath import Twist3
>>> S = Twist3.Rx([0.2, 0.3, 0.4])
>>> len(S)
3
>>> S.prod()
Twist3([0, 0, 0, 0.9, 0, 0])
>>> Twist3.Rx(0.9)
Twist3([0, 0, 0, 0.9, 0, 0])

reverse(): S.reverse() – reverse IN PLACE

skewa()[source]

Convert 2D twist to se(2)

Returns: An se(2) matrix
Return type: ndarray(3,3)

X.skewa() is the twist as a 3x3 augmented skew-symmetric matrix belonging to the group se(2). This is the Lie algebra of the corresponding SE(2) element.

Example:

unit()[source]

Unit twist

S.unit() is a Twist2 object representing a unit twist aligned with the Twist S.

Example:

  File "<input>", line 1, in <module>
NameError: name 'Twist2' is not defined
Traceback (most recent call last):
  File "<input>", line 1, in <module>
NameError: name 'S' is not defined

property A: Union[List[numpy.ndarray[Any, numpy.dtype[numpy.typing._generic_alias.ScalarType]]], numpy.ndarray[Any, numpy.dtype[numpy.typing._generic_alias.ScalarType]]]

Array value of an instance (BasePoseList superclass method)

Returns: NumPy array value of this instance
Return type: ndarray

X.A is a NumPy array that represents the value of this instance, and has a shape given by X.shape.

Note

This assumes that len(X) == 1, ie. it is a single-valued instance.

property N

Dimension of the object’s group

Returns: dimension
Return type: int

Dimension of the group is 2 for Twist2 and corresponds to the dimension of the space (2D in this case) to which these rigid-body motions apply.

Example:

>>> from spatialmath import Twist2
>>> x = Twist2()
>>> x.N
2

property S

Twist as a vector (superclass property)

Returns: Twist vector
Return type: ndarray(N)

X.S is a 3-vector if X is a Twist2 instance, and a 6-vector if X is a Twist3 instance.

Note

the vector is the unique elements of the se(N) representation.
the vector is sometimes referred to as the twist coordinate vector.
if len(X) > 1 then return a list of vectors.

property ad

Twist2.ad Logarithm of adjoint

S.ad() is the logarithm of the adjoint matrix of the corresponding homogeneous transformation.

Example:

  File "<input>", line 1, in <module>
NameError: name 'Twist2' is not defined
Traceback (most recent call last):
  File "<input>", line 1, in <module>
NameError: name 'S' is not defined

Seealso: SE3.Ad.

property isprismatic

Test for prismatic twist (superclass property)

Returns: Whether twist is purely prismatic
Return type: bool

A prismatic twist has \(\vec{\omega} = 0\).

Example:

>>> from spatialmath import Twist3
>>> x = Twist3.UnitPrismatic([1,2,3])
>>> x.isprismatic
True
>>> x = Twist3.UnitRevolute([1,2,3], [4,5,6])
>>> x.isprismatic
False

property isrevolute

Test for revolute twist (superclass property)

Returns: Whether twist is purely revolute
Return type: bool

A revolute twist has \(\vec{v} = 0\).

Example:

>>> from spatialmath import Twist3
>>> x = Twist3.UnitPrismatic([1,2,3])
>>> x.isrevolute
False
>>> x = Twist3.UnitRevolute([1,2,3], [0,0,0])
>>> x.isrevolute
True

property isunit

Test for unit twist (superclass property)

Returns: Whether twist is a unit-twist
Return type: bool

A unit twist is one with a norm of 1, ie. \(\| S \| = 1\).

Example:

  File "<input>", line 1, in <module>
TypeError: 'bool' object is not callable

property pole

Pole of a 2D twist

Returns: the pole of the twist
Return type: ndarray(2)

X.pole() is a point on the twist axis. For a pure translation this point is at infinity.

Example:

  File "<input>", line 1, in <module>
NameError: name 'Twist2' is not defined
Traceback (most recent call last):
  File "<input>", line 1, in <module>
NameError: name 'S' is not defined

property shape

Shape of the object’s interal array representation

Returns: (3,)
Return type: tuple

property theta

Twist angle (superclass method)

Returns: magnitude of rotation (1x1) about the twist axis in radians
Return type: float

property v

Moment vector of twist

Returns: Moment vector
Return type: ndarray(2)

X.v is a 2-vector representing the moment vector of the twist.

Example:

>>> from spatialmath import Twist2
>>> t = Twist2([1, 2, 3])
>>> t.v
array([1, 2])

property w

Direction vector of twist

Returns: Direction vector
Return type: float

X.w is a scalar representing the direction “vector” of the twist.

Example:

>>> from spatialmath import Twist2
>>> t = Twist2([1, 2, 3])
>>> t.w
3