# se3

SE(3) homogeneous transformation

Since R2022b

## Description

The `se3` object represents an SE(3) transformation as a 3-D homogeneous transformation matrix consisting of a translation and rotation:

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

## Creation

### Syntax

``transformation = se3``
``transformation = se3(rotation)``
``transformation = se3(rotation,translation)``
``transformation = se3(transformation)``
``transformation = se3(euler,"eul")``
``transformation = se3(euler,"eul",sequence)``
``transformation = se3(quat,"quat")``
``transformation = se3(axang,"axang")``
``transformation = se3(angle,axis)``
``transformation = se3(___,translation,"trvec")``
``transformation = se3(translation,"trvec")``
``transformation = se3(pose,"xyzquat")``

### Description

#### Rotation Matrices, Translation Vectors, and Transformation Matrices

````transformation = se3` creates an SE(3) transformation representing an identity rotation with no translation.$transformation=\left[\begin{array}{cccc}1& 0& 0& 0\\ 0& 1& 0& 0\\ 0& 0& 1& 0\\ 0& 0& 0& 1\end{array}\right]$```
````transformation = se3(rotation)` creates an SE(3) transformation representing a pure rotation defined by the orthonormal rotation `rotation` with no translation. The rotation matrix is represented by the elements in the top left of the `transformation` matrix.$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]$$transformation=\left[\begin{array}{cccc}{r}_{11}& {r}_{12}& {r}_{13}& 0\\ {r}_{21}& {r}_{22}& {r}_{23}& 0\\ {r}_{31}& {r}_{32}& {r}_{33}& 0\\ 0& 0& 0& 1\end{array}\right]$```
````transformation = se3(rotation,translation)` creates an SE(3) transformation representing a rotation defined by the orthonormal rotation `rotation` and the translation `translation`. The function applies the rotation matrix first, then translation vector to create the transformation.$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]$, $translation=\left[\begin{array}{c}{t}_{1}\\ {t}_{2}\\ {t}_{3}\end{array}\right]$$transformation=\left[\begin{array}{cccc}{r}_{11}& {r}_{12}& {r}_{13}& {t}_{1}\\ {r}_{21}& {r}_{22}& {r}_{23}& {t}_{2}\\ {r}_{31}& {r}_{32}& {r}_{33}& {t}_{3}\\ 0& 0& 0& 1\end{array}\right]=\left[\begin{array}{cccc}1& 0& 0& {t}_{1}\\ 0& 1& 0& {t}_{2}\\ 0& 0& 1& {t}_{3}\\ 0& 0& 0& 1\end{array}\right]·\left[\begin{array}{cccc}{r}_{11}& {r}_{12}& {r}_{13}& 0\\ {r}_{21}& {r}_{22}& {r}_{23}& 0\\ {r}_{31}& {r}_{32}& {r}_{33}& 0\\ 0& 0& 0& 1\end{array}\right]$```
````transformation = se3(transformation)` creates an SE(3) transformation representing a translation and rotation as defined by the homogeneous transformation `transformation`.```

#### Other 3-D Rotation Representations

````transformation = se3(euler,"eul")` creates an SE(3) transformation from the rotations defined by the Euler angles `euler`.```
````transformation = se3(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.```
````transformation = se3(quat,"quat")` creates an SE(3) transformation from the rotations defined by the numeric quaternions `quat`.```
````transformation = se3(axang,"axang")` creates an SE(3) transformation from the rotations defined by the axis-angle rotation `axang`.```
````transformation = se3(angle,axis)` creates an SE(3) transformation from the rotations `angles` about the rotation axis `axis`.```

example

````transformation = se3(___,translation,"trvec")` creates an SE(3) transformation from the translation vector `translation` along with any other type of rotation input arguments.```

#### Other Translations and Transformation Representations

````transformation = se3(translation,"trvec")` creates an SE(3) transformation from the translation vector `translation`.```
````transformation = se3(pose,"xyzquat")` creates an SE(3) transformation from the 3-D compact pose `pose`.```

Note

If any inputs contain more than one rotation, translation, or transformation, then the output `transformation` is an N-element array of `se3` objects corresponding to each of the N input rotations, translations, or transformations.

### Input Arguments

expand all

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

If `rotation` contains more than one rotation and you also specify `translation` at construction, the number of translations in `translation` must be one or equal to the number of rotations in `rotation`. The resulting number of transformation objects is equal to the value of the `translation` or `rotation` argument, whichever is larger.

Example: `eye(3)`

Data Types: `single` | `double`

Translation, specified as a three-element row vector or an N-by-3 array. N is the total number of translations and each translation is of the form [x y z].

If `translation` contains more than one translation, the number of rotations in `rotation` must be one or equal to the number of translations in `translation`. The resulting number of created transformation objects is equal to the value of the `translation` or `rotation` argument, whichever is larger.

Example: `[1 4 3]`

Data Types: `single` | `double`

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 `se3` 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 `se3` 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 `se3` 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 `se3` 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: `se3([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 `se3(pi/2,"rotz") * se3(pi/3,"roty") * se3(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 `se3` objects is equal to N.

Note

The `se3` 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 `se3` 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 `se3` object creates an `se3` object for each angle.

If `angle` is an N-by-M matrix, the resulting number of created `se3` 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 = se3(phi,"rotx");`

Example: `Ry = se3(psi,"roty");`

Example: `Rz = se3(theta,"rotz");`

Data Types: `string` | `char`

3-D compact pose, specified as an N-by-7 matrix, where N is the total number of compact poses. Each row is a pose, comprised of a xyz position and quaternion, in the form [x y z qw qx qy qz]. x, y, and z are the positions in the x-, y-, and z-axes, respectively. qw, qx, qy, and qz together are the quaternion rotation in w, x, y, and z, respectively.

If `pose` is an N-by-7 matrix, the resulting number of created `se3` objects is equal to N.

Data Types: `single` | `double`

## 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
 `so3` SO(3) rotation `quaternion` Create quaternion array

## Examples

collapse all

Define an Euler-angle rotation of `[pi/2 0 pi/7]` with a `"XYZ"` rotation sequence, and a xyz translation of `[6 4 1]`.

```angles = [pi/2 0 pi/7]; trvec = [6 4 1];```

Create an SE(3) transformation using the Euler angles and the translation.

`TF = se3(angles,"eul","XYZ",trvec)`
```TF = se3 0.9010 -0.4339 0 6.0000 0.0000 0.0000 -1.0000 4.0000 0.4339 0.9010 0.0000 1.0000 0 0 0 1.0000 ```

expand all

## Version History

Introduced in R2022b

expand all