Rotation
Symbolic Rotation¶
This module provides symbolic representations of rotation matrices. They can be used interchangeably with numerical rotation matrices.
The word matrix is used a lot in this module, but it is important to note that
the symbolic rotations are not necessarily represented as matrices internally.
They can always be converted to a matrix form, however, using the matrix() method.
The numerical rotations module is analogous to this one.
axis_angle(axis, *, degrees=None, radians=None)
¶
Return a symbolic rotation matrix from an axis-angle representation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
axis
|
AnyAxis
|
The axis of rotation. Can be any vector (does not need to be normalized). |
required |
degrees
|
Optional[Symbolic]
|
The rotation angle in degrees. Cannot be specified together with radians. |
None
|
radians
|
Optional[Symbolic]
|
The rotation angle in radians. Cannot be specified together with degrees. |
None
|
Returns:
| Type | Description |
|---|---|
Rotation[Symbol]
|
A symbolic rotation matrix representing the specified axis-angle rotation. |
Example
Create a rotation around the Z-axis by \(\theta\) radians:
from core import rotation, symbol
theta = symbol('theta')
R = rotation.sym.axis_angle([0, 0, 1], radians=theta)
print(R)
# Matrix([[cos(theta), -sin(theta), 0], [sin(theta), cos(theta), 0], [0, 0, 1]])
Create a rotation around a non-unit vector by 45 degrees:
from core import rotation
R = rotation.sym.axis_angle([1, 1, 1], degrees=45)
print(R)
# Matrix([[1/3 + sqrt(2)/3, -sqrt(6)/6 - sqrt(2)/6 + 1/3, ..., 1/3 + sqrt(2)/3]])
cardan(*, degrees=None, radians=None)
¶
Return a symbolic rotation matrix from Cardan angles.
The rotation follows the XYZ convention, i.e., the rotation is performed as a sequence of three elementary rotations around the X, Y, and Z axes, respectively. This is also known as the roll-pitch-yaw convention.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
degrees
|
Angles | None
|
The Cardan angles in degrees (alpha, beta, gamma). Mutually exclusive with radians. |
None
|
radians
|
Angles | None
|
The Cardan angles in radians (alpha, beta, gamma). Mutually exclusive with degrees. |
None
|
Returns:
| Type | Description |
|---|---|
Rotation[Symbol]
|
A symbolic rotation matrix representing the Cardan rotation. |
Example
from core import rotation, symbols
alpha, beta, gamma = symbols('alpha', 'beta', 'gamma')
R = rotation.sym.cardan(radians=(alpha, beta, gamma))
print(R)
# Matrix([[cos(beta)*cos(gamma), ..., cos(alpha)*cos(beta)]])
elementary(axis, *, degrees=None, radians=None)
¶
Return an elementary symbolic rotation matrix around a specified axis.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
axis
|
Axis
|
The principal axis around which to rotate (X, Y, or Z). |
required |
degrees
|
Optional[Symbolic]
|
The rotation angle in degrees. Must not be used together with |
None
|
radians
|
Optional[Symbolic]
|
The rotation angle in radians. Must not be used together with |
None
|
Returns:
| Type | Description |
|---|---|
Rotation[Symbol]
|
A symbolic rotation matrix representing the elementary rotation. |
Example
Rotation around the X-axis by 30 degrees:
from core import rotation, s, Axis
R = rotation.elementary(Axis.X, degrees=30)
print(R)
# Matrix([[1, 0, 0], [0, sqrt(3)/2, -1/2], [0, 1/2, sqrt(3)/2]])
Rotation around the Y-axis by π/4 radians:
from core import rotation, s, Axis
R = rotation.elementary(Axis.Y, radians=s.pi/4)
print(R)
# Matrix([[sqrt(2)/2, 0, sqrt(2)/2], [0, 1, 0], [-sqrt(2)/2, 0, sqrt(2)/2]])
Notes
The rotation matrices follow the right-hand rule
- X-axis: rotation in the y-z plane
- Y-axis: rotation in the x-z plane
- Z-axis: rotation in the x-y plane
euler(*, degrees=None, radians=None, tolerance=1e-05)
¶
Return a symbolic rotation matrix from Euler angles.
The rotation follows the ZYZ convention, i.e., the rotation is performed as a sequence of three elementary rotations around the Z, Y, and Z axes, respectively.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
degrees
|
Angles | None
|
The Euler angles in degrees (roll, pitch, yaw). Mutually exclusive with radians. |
None
|
radians
|
Angles | None
|
The Euler angles in radians (roll, pitch, yaw). Mutually exclusive with degrees. |
None
|
tolerance
|
float
|
The tolerance level for considering values as zero or equal. Defaults to 1e-5. |
1e-05
|
Returns:
| Type | Description |
|---|---|
Rotation[Symbol]
|
A 3x3 symbolic rotation matrix representing the given Euler angles. |
Example
Euler angles in degrees:
from core import rotation, pi, symbol
alpha = symbol('alpha')
R = rotation.sym.euler(degrees=(30, 45, alpha))
print(R)
# Matrix([[-sin(pi*alpha/180)/2 + sqrt(6)*cos(pi*alpha/180)/4, ..., sqrt(2)/2]])
Euler angles in radians:
from core import rotation, s, pi, symbol
beta = symbol('beta')
R = rotation.sym.euler(radians=(s.pi/6, s.pi/4, beta))
print(R)
# Matrix([[-sin(beta)/2 + sqrt(6)*cos(beta)/4, ..., sqrt(2)/2]])
identity()
¶
Return the symbolic identity rotation matrix.
Returns:
| Type | Description |
|---|---|
Rotation[Symbol]
|
A symbolic rotation matrix representing the identity rotation. |
Example
from core import rotation
R = rotation.sym.identity()
print(R)
# Matrix([[1, 0, 0], [0, 1, 0], [0, 0, 1]])
matrix(*args)
¶
matrix(
row_1: Row[Symbolic],
row_2: Row[Symbolic],
row_3: Row[Symbolic],
) -> Rotation[Symbol]
matrix(matrix: SMatrix) -> Rotation[Symbol]
Return a symbolic rotation matrix from the specified input.
This function can be used in two ways:
- By passing three rows of the rotation matrix as separate arguments, or
- By passing a sympy matrix directly.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
args
|
SMatrix | Row[Symbolic]
|
|
()
|
Returns:
| Type | Description |
|---|---|
Rotation[Symbol]
|
A symbolic rotation matrix. |
Example
Using individual rows:
from core import rotation, s
R = rotation.sym.matrix(
[1, 0, 0],
[0, s.sqrt(3)/2, -1/2],
[0, 1/2, s.sqrt(3)/2]
)
print(R)
# Matrix([[1, 0, 0], [0, sqrt(3)/2, -1/2], [0, 1/2, sqrt(3)/2]])
Using a sympy matrix:
from sympy import Matrix, symbols
from core import rotation
a, b, c = symbols('a b c')
R = rotation.sym.matrix(Matrix([[a, b, c], [1, 2, 3], [4, 5, 6]]))
print(R)
# Matrix([[a, b, c], [1, 2, 3], [4, 5, 6]])
quaternion(scalar, vector)
¶
Normalizes a quaternion and returns the corresponding symbolic rotation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scalar
|
Symbolic
|
The scalar/real component (\(s\)) of the quaternion \(q = s + xi + yj + zk\) |
required |
vector
|
tuple[Symbolic, Symbolic, Symbolic]
|
The vector/imaginary components (\(x,y,z\)) of the quaternion |
required |
Returns:
| Type | Description |
|---|---|
Rotation[Symbol]
|
A normalized symbolic quaternion rotation object |
Example
Create a general symbolic quaternion:
from core import rotation, symbols
s, x, y, z = symbols('s x y z')
R = rotation.sym.quaternion(s, (x, y, z))
print(R)
# Matrix([[2*s**2/(s**2 + x**2 + y**2 + z**2) + 2*x**2/(s**2 + x**2 + y**2 + z**2) - 1, ...]])
Create a symbolic quaternion with a numerical scalar component:
from core import rotation, symbols
x, y, z = symbols('x y z')
R = rotation.sym.quaternion(1, (x, y, z))
print(R)
# Matrix([[2*x**2/(x**2 + y**2 + z**2 + 1) - 1 + 2/(x**2 + y**2 + z**2 + 1), ...]])
Notes
The quaternion is normalized to ensure that the quaternion has a unit magnitude.