se(2) twist

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

Bases: 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.8.18/x64/lib/python3.8/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.8.18/x64/lib/python3.8/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
Return type:: None

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.

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

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.

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

Return type:

None

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

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.11456, 0.27586, -1.1546, 2.257, -0.48928, -0.026245])
>>> S.inv()
Twist3([-0.11456, -0.27586, 1.1546, -2.257, 0.48928, 0.026245])
>>> S * S.inv()
Twist3([5.5511e-17, 1.1102e-16, 8.3267e-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: List[ndarray[Any, dtype[ScalarType]]] | ndarray[Any, dtype[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