rotateframe

Quaternion frame rotation

Since R2023b

Syntax

rotationResult = rotateframe(quat,cartesianPoints)

Description

rotationResult = rotateframe(quat,cartesianPoints) rotates the frame of reference for the Cartesian points using the quaternion, quat. The elements of the quaternion are normalized before use in the rotation.

Examples

Rotate Frame Using Quaternion Vector

Define a point in three dimensions. The coordinates of a point are always specified in the order x, y, and z. For convenient visualization, define the point on the x-y plane.

x = 0.5;
y = 0.5;
z = 0;
plot(x,y,"ko")
hold on
axis([-1 1 -1 1])

Create a quaternion vector specifying two separate rotations, one to rotate the frame 45 degrees and another to rotate the point -90 degrees about the z-axis. Use rotateframe to perform the rotations.

quat = quaternion([0,0,pi/4; ...
                   0,0,-pi/2],"euler","XYZ","frame");
               
rereferencedPoint = rotateframe(quat,[x,y,z])

rereferencedPoint = 2×3

    0.7071   -0.0000         0
   -0.5000    0.5000         0

Plot the re-referenced points.

plot(rereferencedPoint(1,1),rereferencedPoint(1,2),"bo")
plot(rereferencedPoint(2,1),rereferencedPoint(2,2),"go")

Re-reference Group of Points using Quaternion

Define two points in three-dimensional space. Define a quaternion to re-reference the points by first rotating the reference frame about the z-axis 30 degrees and then about the new y-axis 45 degrees.

a = [1,0,0];
b = [0,1,0];
quat = quaternion([30,45,0],"eulerd","ZYX","point");

Use rotateframe to reference both points using the quaternion rotation operator. Display the result.

rP = rotateframe(quat,[a;b])

rP = 2×3

    0.6124   -0.3536    0.7071
    0.5000    0.8660   -0.0000

Visualize the original orientation and the rotated orientation of the points. Draw lines from the origin to each of the points for visualization purposes.

plot3(a(1),a(2),a(3),"bo");

hold on
grid on
axis([-1 1 -1 1 -1 1])
xlabel("x")
ylabel("y")
zlabel("z")

plot3(b(1),b(2),b(3),"ro");
plot3(rP(1,1),rP(1,2),rP(1,3),"bd")
plot3(rP(2,1),rP(2,2),rP(2,3),"rd")

plot3([0;rP(1,1)],[0;rP(1,2)],[0;rP(1,3)],"k")
plot3([0;rP(2,1)],[0;rP(2,2)],[0;rP(2,3)],"k")
plot3([0;a(1)],[0;a(2)],[0;a(3)],"k")
plot3([0;b(1)],[0;b(2)],[0;b(3)],"k")

Input Arguments

quat — Quaternion that defines rotation

quaternion object | vector of quaternion objects

Quaternion that defines rotation, specified as a quaternion object or a vector of quaternion objects. quat and cartesianPoints must have compatible sizes:

• length(quat) == size(cartesianPoints,1), or

• length(quat) == 1, or

• size(cartesianPoints,1) == 1

cartesianPoints — Three-dimensional Cartesian points

1-by-3 numeric vector | N-by-3 numeric matrix

Three-dimensional Cartesian points, specified as a 1-by-3 numeric vector representing a single point or an N-by-3 numeric matrix representing N points. quat and cartesianPoints must have compatible sizes:

• length(quat) == size(cartesianPoints,1) or

• length(quat) == 1, or

• size(cartesianPoints,1) == 1

Data Types: single | double

Output Arguments

rotationResult — Re-referenced Cartesian points

1-by-3 numeric vector | numeric matrix

Cartesian points defined in reference to rotated reference frame, returned as a 1-by-3 numeric vector or a numeric matrix.

rotationResult is a 1-by-3 vector when quat is a scalar quaternion object and cartesianPoints is a 1-by-3 vector representing a single point. Otherwise, rotationResult is an M-by-3 matrix, where M is the maximum of length(quat) and size(cartesianPoints,1).

Data Types: single | double

Algorithms

Quaternion frame rotation re-references a point specified in R³ by rotating the original frame of reference according to a specified quaternion:

$$L_q\left(u\right)=q^{*}uq$$

where q is the quaternion, * represents conjugation, and u is the point to rotate, specified as a quaternion.

For convenience, the rotateframe function takes a point in R³ and returns a point in R³. Given a function call with some arbitrary quaternion, q = a + bi + cj + dk, and arbitrary coordinate, [x,y,z],

point = [x,y,z];
rereferencedPoint = rotateframe(q,point)

the rotateframe function performs the following operations:

1. Converts point [x,y,z] to a quaternion:

   $$u_q=0+xi+yj+zk$$

2. Normalizes the quaternion, q:

   $$q_n=\frac{q}{\sqrt{a^2+b^2+c^2+d^2}}$$

3. Applies the rotation:

   $$v_q=q^{*}{u}_{q}q$$

4. Converts the quaternion output, v_q, back to R³

Extended Capabilities

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

Version History

Introduced in R2023b