# 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}\left(\varphi \right)=\left[\begin{array}{ccc}1& 0& 0\\ 0& \mathrm{cos}\varphi & \mathrm{sin}\varphi \\ 0& -\mathrm{sin}\varphi & \mathrm{cos}\varphi \end{array}\right]$, ${R}_{y}\left(\psi \right)=\left[\begin{array}{ccc}\mathrm{cos}\psi & 0& \mathrm{sin}\psi \\ 0& 1& 0\\ -\mathrm{sin}\psi & 0& \mathrm{cos}\psi \end{array}\right]$, ${R}_{z}\left(\theta \right)=\left[\begin{array}{ccc}\mathrm{cos}\theta & -\mathrm{sin}\theta & 0\\ \mathrm{sin}\theta & \mathrm{cos}\theta & 0\\ 0& 0& 1\end{array}\right]$

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.$rotation=\left[\begin{array}{ccc}1& 0& 0\\ 0& 1& 0\\ 0& 0& 1\end{array}\right]$```
````rotation = so3(rotation)` creates an SO(3) rotation representing a pure rotation defined by the orthonormal rotation `rotation`.$rotation=\left[\begin{array}{ccc}{r}_{11}& {r}_{12}& {r}_{13}\\ {r}_{11}& {r}_{22}& {r}_{23}\\ {r}_{31}& {r}_{32}& {r}_{33}\end{array}\right]$```
````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

example

````rotation = so3(euler,"eul")` creates an SO(3) rotation from the rotations defined by the Euler angles `euler`.```
````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 `angles` 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

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)`

Homogeneous transformation, specified as a 4-by-4 matrix, a 4-by-4-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, 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 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`

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:

${R}_{x}\left(\varphi \right)=\left[\begin{array}{ccc}1& 0& 0\\ 0& \mathrm{cos}\varphi & \mathrm{sin}\varphi \\ 0& -\mathrm{sin}\varphi & \mathrm{cos}\varphi \end{array}\right]$, ${R}_{y}\left(\psi \right)=\left[\begin{array}{ccc}\mathrm{cos}\psi & 0& \mathrm{sin}\psi \\ 0& 1& 0\\ -\mathrm{sin}\psi & 0& \mathrm{cos}\psi \end{array}\right]$, ${R}_{z}\left(\theta \right)=\left[\begin{array}{ccc}\mathrm{cos}\theta & -\mathrm{sin}\theta & 0\\ \mathrm{sin}\theta & \mathrm{cos}\theta & 0\\ 0& 0& 1\end{array}\right]$

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}\left(\varphi \right)·{R}_{y}\left(\psi \right)·{R}_{z}\left(\theta \right)$`

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`

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`

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`

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 to rotate, specified as one of these options:

• `"rotx"` — Rotate about the x-axis:

`${R}_{x}\left(\varphi \right)=\left[\begin{array}{ccc}1& 0& 0\\ 0& \mathrm{cos}\varphi & \mathrm{sin}\varphi \\ 0& -\mathrm{sin}\varphi & \mathrm{cos}\varphi \end{array}\right]$`

• `"roty"` — Rotate about the y-axis:

`${R}_{y}\left(\psi \right)=\left[\begin{array}{ccc}\mathrm{cos}\psi & 0& \mathrm{sin}\psi \\ 0& 1& 0\\ -\mathrm{sin}\psi & 0& \mathrm{cos}\psi \end{array}\right]$`

• `"rotz"` — Rotate about the z-axis:

`${R}_{z}\left(\theta \right)=\left[\begin{array}{ccc}\mathrm{cos}\theta & -\mathrm{sin}\theta & 0\\ \mathrm{sin}\theta & \mathrm{cos}\theta & 0\\ 0& 0& 1\end{array}\right]$`

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

 `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
 `interp` Interpolate between transformations `dist` Calculate distance between transformations `normalize` Normalize transformation or rotation matrix `transform` Apply rigid body transformation to points
 `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
 `se3` SE(3) homogeneous transformation `quaternion` Create quaternion array

## Examples

collapse all

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 ```

expand all

## Version History

Introduced in R2022b

expand all