so3

SO(3) rotation

Since R2022b

Description

The so3 object represents an SO(3) rotation in 3-D in a right-handed Cartesian coordinate system.

The SO(3) rotation is a 3-by-3 orthonormal rotation matrix. For example, these are orthonormal rotation matrices for rotations of ϕ, ψ, and θ about the x-, y-, and z-axis, respectively:

$R_{x} (ϕ) = [\begin{matrix} 1 & 0 & 0 \\ 0 & \cos ϕ & \sin ϕ \\ 0 & - \sin ϕ & \cos ϕ \end{matrix}]$ , $R_{y} (ψ) = [\begin{matrix} \cos ψ & 0 & \sin ψ \\ 0 & 1 & 0 \\ - \sin ψ & 0 & \cos ψ \end{matrix}]$ , $R_{z} (θ) = [\begin{matrix} \cos θ & - \sin θ & 0 \\ \sin θ & \cos θ & 0 \\ 0 & 0 & 1 \end{matrix}]$

For more information, see the 3-D Orthonormal Rotation Matrix section.

This object acts like a numerical matrix, enabling you to compose rotations using multiplication and division.

Creation

Syntax

rotation = so3

rotation = so3(rotation)

rotation = so3(quaternion)

rotation = so3(transformation)

rotation = so3(euler,"eul")

rotation = so3(euler,"eul",sequence)

rotation = so3(quat,"quat")

rotation = so3(axang,"axang")

rotation = so3(angle,axis)

Description

3-D Rotation Representations

rotation = so3 creates an SO(3) rotation representing an identity rotation with no translation.

$r o t a t i o n = [\begin{matrix} 1 & 0 & 0 \\ 0 & 1 & 0 \\ 0 & 0 & 1 \end{matrix}]$

rotation = so3(rotation) creates an SO(3) rotation representing a pure rotation defined by the orthonormal rotation rotation.

$r o t a t i o n = [\begin{matrix} r_{11} & r_{12} & r_{13} \\ r_{11} & r_{22} & r_{23} \\ r_{31} & r_{32} & r_{33} \end{matrix}]$

rotation = so3(quaternion) creates an SO(3) rotation from the rotations defined by the quaternion quaternion.

rotation = so3(transformation) creates an SO(3) rotation from the SE(3) transformation transformation.

Other Numeric 3-D Rotation Representations

rotation = so3(euler,"eul") creates an SO(3) rotation from the rotations defined by the Euler angles euler.

example

rotation = so3(euler,"eul",sequence) specifies the sequence of the Euler angle rotations sequence. For example, the sequence "ZYX" rotates the z-axis, then the y-axis and x-axis.

rotation = so3(quat,"quat") creates an SO(3) rotation from the rotations defined by the numeric quaternions quat.

rotation = so3(axang,"axang") creates an SO(3) rotation from the rotations defined by the axis-angle rotation axang.

rotation = so3(angle,axis) creates an SO(3) rotation from the rotations angle about the rotation axis axis.

Note

If any inputs contain more than one rotation, then the output rotation is an N-element array of so3 objects corresponding to each of the N input rotations.

Input Arguments

expand all

`rotation` — Orthonormal rotation
3-by-3 matrix | 3-by-3-by-N matrix | `so3` object | N-element array of `so3` objects

Orthonormal rotation, specified as a 3-by-3 matrix, a 3-by-3-byN array, a scalar so3 object, or an N-element array of so3 objects. N is the total number of rotations.

If rotation is an array, the resulting number of created so3 objects in the output array is equal to N.

Example: eye(3)

`transformation` — Homogeneous transformation
4-by-4 matrix | 4-by-4-by-N array | `se3` object | N-element array of `se3` objects

Homogeneous transformation, specified as a 4-by-4 matrix, a 4-by-4-by-N array, a scalar se3 object, or an N-element array of se3 objects. N is the total number of transformations specified.

If transformation is an array, the resulting number of created so3 objects is equal to N.

Example: eye(4)

Data Types: single | double

`quaternion` — Quaternion
`quaternion` object | N-element array of `quaternion` objects

Quaternion, specified as a scalar quaternion object or as an N-element array of quaternion objects. N is the total number of specified quaternions.

If quaternion is an N-element array, the resulting number of created so3 objects is equal to N.

Example: quaternion(1,0.2,0.4,0.2)

`euler` — Euler angles
N-by-3 matrix

Euler angles, specified as an N-by-3 matrix, in radians. Each row represents one set of Euler angles with the axis-rotation sequence defined by the sequence argument. The default axis-rotation sequence is ZYX.

If euler is an N-by-3 matrix, the resulting number of created so3 objects is equal to N.

Example: [pi/2 pi pi/4]

Data Types: single | double

`sequence` — Axis-rotation sequence
`"ZYX"` (default) | `"ZYZ"` | `"ZXY"` | `"ZXZ"` | `"YXY"` | `"YZX"` | `"YXZ"` | `"YZY"` | `"XYX"` | `"XYZ"` | `"XZX"` | `"XZY"`

Axis-rotation sequence for the Euler angles, specified as one of these string scalars:

"ZYX" (default)
"ZYZ"
"ZXY"
"ZXZ"
"YXY"
"YZX"
"YXZ"
"YZY"
"XYX"
"XYZ"
"XZX"
"XZY"

These are orthonormal rotation matrices for rotations of ϕ, ψ, and θ about the x-, y-, and z-axis, respectively:

When constructing the rotation matrix from this sequence, each character indicates the corresponding axis. For example, if the sequence is "XYZ", then the so3 object constructs the rotation matrix R by multiplying the rotation about x-axis with the rotation about the y-axis, and then multiplying that product with the rotation about the z-axis:

$R = R_{x} (ϕ) \cdot R_{y} (ψ) \cdot R_{z} (θ)$

Example: so3([pi/2 pi/3 pi/4],"eul","ZYZ") rotates a point by pi/4 radians about the z-axis, then rotates the point by pi/3 radians about the y-axis, and then rotates the point by pi/2 radians about the z-axis. This is equivalent to so3(pi/2,"rotz") * so3(pi/3,"roty") * so3(pi/4,"rotz")

Data Types: string | char

`quat` — Numeric quaternion
N-by-4 matrix

Numeric quaternion, specified as an N-by-4 matrix. N is the number of specified quaternions. Each row represents one quaternion of the form [qw qx qy qz], where qw is a scalar number.

If quat is an N-by-4 matrix, the resulting number of created so3 objects is equal to N.

Note

The so3 object normalizes the input quaternions before converting the quaternions to a rotation matrix.

Example: [0.7071 0.7071 0 0]

Data Types: single | double

`axang` — Axis-angle rotation
N-by-4 matrix

Axis-angle rotation, specified as an N-by-4 matrix in the form [x y z theta]. N is the total number of axis-angle rotations. x, y, and z are vector components from the x-, y-, and z-axis, respectively. The vector defines the axis to rotate by the angle theta, in radians.

If axang is an N-by-4 matrix, the resulting number of created so3 objects is equal to N.

Example: [.2 .15 .25 pi/4] rotates the axis, defined as 0.2 in the x-axis, 0.15 along the y-axis, and 0.25 along the z-axis, by pi/4 radians.

Data Types: single | double

`angle` — Single-axis-angle rotation
N-by-M matrix

Single-axis-angle rotation, specified as an N-by-M matrix. Each element of the matrix is an angle, in radians, about the axis specified using the axis argument, and the so3 object creates an so3 object for each angle.

If angle is an N-by-M matrix, the resulting number of created so3 objects is equal to N.

The rotation angle is counterclockwise positive when you look along the specified axis toward the origin.

Data Types: single | double

`axis` — Axis to rotate
`"rotx"` | `"roty"` | `"rotz"`

Axis to rotate, specified as one of these options:

"rotx" — Rotate about the x-axis:

$R_{x} (ϕ) = [\begin{matrix} 1 & 0 & 0 \\ 0 & \cos ϕ & \sin ϕ \\ 0 & - \sin ϕ & \cos ϕ \end{matrix}]$
"roty" — Rotate about the y-axis:

$R_{y} (ψ) = [\begin{matrix} \cos ψ & 0 & \sin ψ \\ 0 & 1 & 0 \\ - \sin ψ & 0 & \cos ψ \end{matrix}]$
"rotz" — Rotate about the z-axis:

$R_{z} (θ) = [\begin{matrix} \cos θ & - \sin θ & 0 \\ \sin θ & \cos θ & 0 \\ 0 & 0 & 1 \end{matrix}]$

Use the angle argument to specify how much to rotate about the specified axis.

Example: Rx = so3(phi,"rotx");

Example: Ry = so3(psi,"roty");

Example: Rz = so3(theta,"rotz");

Data Types: string | char

Object Functions

expand all

Mathematical Operations

`mtimes, *`	Transformation or rotation multiplication
`mrdivide, /`	Transformation or rotation right division
`rdivide, ./`	Element-wise transformation or rotation right division
`times, .*`	Element-wise transformation or rotation multiplication

Utilities

`interp`	Interpolate between transformations
`dist`	Calculate distance between transformations
`normalize`	Normalize transformation or rotation matrix
`transform`	Apply rigid body transformation to points

Numerical Conversions

`axang`	Convert transformation or rotation into axis-angle rotations
`eul`	Convert transformation or rotation into Euler angles
`rotm`	Extract rotation matrix
`quat`	Convert transformation or rotation to numeric quaternion
`trvec`	Extract translation vector
`tform`	Extract homogeneous transformation
`xyzquat`	Convert transformation or rotation to compact 3-D pose representation

Object Conversions

`se3`	SE(3) homogeneous transformation
`quaternion`	Create quaternion array

Examples

collapse all

Convert SO(3) Rotation to Euler Angles

Open Live Script

Create SO(3) rotation defined by a Euler angles.

eul1 = [pi/4 pi/3 pi/8]

eul1 = 1×3

    0.7854    1.0472    0.3927

R = so3(eul1,"eul")

R = so3
    0.3536   -0.4189    0.8364
    0.3536    0.8876    0.2952
   -0.8660    0.1913    0.4619

Get the Euler angles from the transformation.

eul2 = eul(R)

eul2 = 1×3

    0.7854    1.0472    0.3927

Algorithms

expand all

3-D Orthonormal Rotation Matrix

SO(3) rotation matrices are 3-by-3 orthonormal matrices that represent any rotation in 3-D Euclidean space. SO(3) rotations have many special properties. For example, SO(3) rotation matrices are in the 3-D special orthogonal group, so the product of two SO(3) rotation matrices is an SO(3) rotation matrix. This enables you to compose rotations from multiple rotations. For example, these are orthonormal rotation matrices for rotations of ϕ, ψ, and θ about the x-, y-, and z-axis, respectively:

Depending on the order in which you multiply these x-, y-, and z-axis rotations, you can construct compound matrices that represent any rotation in 3-D Euclidean space.

These are other properties of SO(3) rotations:

Each column is both orthogonal and a unit vector, meaning that none of the columns are multiples of each other.
The determinant of the matrix is positive 1.
The inverse of the matrix is the same as the transpose of the matrix: R^-1 = R^T.

Extended Capabilities

expand all

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

Introduced in R2022b

expand all

R2023a: New methods and syntaxes

so3 supports new methods and syntaxes for converting to and from other transformations and rotations.

The new methods are:

so3

Description

Creation

Syntax

Description

3-D Rotation Representations

Other Numeric 3-D Rotation Representations

Input Arguments

`rotation` — Orthonormal rotation
3-by-3 matrix | 3-by-3-by-N matrix | `so3` object | N-element array of `so3` objects

`transformation` — Homogeneous transformation
4-by-4 matrix | 4-by-4-by-N array | `se3` object | N-element array of `se3` objects

`quaternion` — Quaternion
`quaternion` object | N-element array of `quaternion` objects

`euler` — Euler angles
N-by-3 matrix

`sequence` — Axis-rotation sequence
`"ZYX"` (default) | `"ZYZ"` | `"ZXY"` | `"ZXZ"` | `"YXY"` | `"YZX"` | `"YXZ"` | `"YZY"` | `"XYX"` | `"XYZ"` | `"XZX"` | `"XZY"`

`quat` — Numeric quaternion
N-by-4 matrix

`axang` — Axis-angle rotation
N-by-4 matrix

`angle` — Single-axis-angle rotation
N-by-M matrix

`axis` — Axis to rotate
`"rotx"` | `"roty"` | `"rotz"`

Object Functions

Mathematical Operations

Utilities

Numerical Conversions

Object Conversions

Examples

Convert SO(3) Rotation to Euler Angles

Algorithms

3-D Orthonormal Rotation Matrix

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

R2023a: New methods and syntaxes

See Also

Functions

Objects

so3

Description

Creation

Syntax

Description

3-D Rotation Representations

Other Numeric 3-D Rotation Representations

Input Arguments

rotation — Orthonormal rotation 3-by-3 matrix | 3-by-3-by-N matrix | so3 object | N-element array of so3 objects

transformation — Homogeneous transformation 4-by-4 matrix | 4-by-4-by-N array | se3 object | N-element array of se3 objects

quaternion — Quaternion quaternion object | N-element array of quaternion objects

euler — Euler angles N-by-3 matrix

sequence — Axis-rotation sequence "ZYX" (default) | "ZYZ" | "ZXY" | "ZXZ" | "YXY" | "YZX" | "YXZ" | "YZY" | "XYX" | "XYZ" | "XZX" | "XZY"

quat — Numeric quaternion N-by-4 matrix

axang — Axis-angle rotation N-by-4 matrix

angle — Single-axis-angle rotation N-by-M matrix

axis — Axis to rotate "rotx" | "roty" | "rotz"

Object Functions

Mathematical Operations

Utilities

Numerical Conversions

Object Conversions

Examples

Convert SO(3) Rotation to Euler Angles

Algorithms

3-D Orthonormal Rotation Matrix

Extended Capabilities

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

Version History

R2023a: New methods and syntaxes

See Also

Functions

Objects

`rotation` — Orthonormal rotation
3-by-3 matrix | 3-by-3-by-N matrix | `so3` object | N-element array of `so3` objects

`transformation` — Homogeneous transformation
4-by-4 matrix | 4-by-4-by-N array | `se3` object | N-element array of `se3` objects

`quaternion` — Quaternion
`quaternion` object | N-element array of `quaternion` objects

`euler` — Euler angles
N-by-3 matrix

`sequence` — Axis-rotation sequence
`"ZYX"` (default) | `"ZYZ"` | `"ZXY"` | `"ZXZ"` | `"YXY"` | `"YZX"` | `"YXZ"` | `"YZY"` | `"XYX"` | `"XYZ"` | `"XZX"` | `"XZY"`

`quat` — Numeric quaternion
N-by-4 matrix

`axang` — Axis-angle rotation
N-by-4 matrix

`angle` — Single-axis-angle rotation
N-by-M matrix

`axis` — Axis to rotate
`"rotx"` | `"roty"` | `"rotz"`

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.