Main Content

dist

Angular distance in radians

Since R2021a

collapse all in page

Syntax

distance = dist(quatA,quatB)

Description

distance = dist(quatA,quatB) returns the angular distance in radians between two quaternions, quatA and quatB.

example

Examples

collapse all

Open Live Script

Calculate the quaternion distance between a single quaternion and each element of a vector of quaternions. Define the quaternions using Euler angles.

q = quaternion([0,0,0],"eulerd","ZYX","frame")
q = quaternion
     1 + 0i + 0j + 0k


qArray = quaternion([0,45,0;0,90,0;0,180,0;0,-90,0;0,-45,0],"eulerd","ZYX","frame")
qArray = 5x1 quaternion array
       0.92388 +         0i +   0.38268j +         0k
       0.70711 +         0i +   0.70711j +         0k
    6.1232e-17 +         0i +         1j +         0k
       0.70711 +         0i -   0.70711j +         0k
       0.92388 +         0i -   0.38268j +         0k


quaternionDistance = rad2deg(dist(q,qArray))
quaternionDistance = 5×1

   45.0000
   90.0000
  180.0000
   90.0000
   45.0000

If both arguments to dist are vectors, the quaternion distance is calculated between corresponding elements. Calculate the quaternion distance between two quaternion vectors.

angles1 = [30,0,15; ...
           30,5,15; ...
           30,10,15; ...
           30,15,15];
angles2 = [30,6,15; ...
           31,11,15; ...
           30,16,14; ...
           30.5,21,15.5];

qVector1 = quaternion(angles1,"eulerd","ZYX","frame");
qVector2 = quaternion(angles2,"eulerd","ZYX","frame");

rad2deg(dist(qVector1,qVector2))
ans = 4×1

    6.0000
    6.0827
    6.0827
    6.0287

Note that a quaternion represents the same rotation as its negative. Calculate a quaternion and its negative.

qPositive = quaternion([30,45,-60],"eulerd","ZYX","frame")
qPositive = quaternion
     0.72332 - 0.53198i + 0.20056j +  0.3919k


qNegative = -qPositive
qNegative = quaternion
    -0.72332 + 0.53198i - 0.20056j -  0.3919k

Find the distance between the quaternion and its negative.

dist(qPositive,qNegative)
ans = 
0

The components of a quaternion may look different from the components of its negative, but both expressions represent the same rotation.

Input Arguments

collapse all

Quaternions to calculate distance between, specified as comma-separated quaternion objects or arrays of quaternion objects of any dimensionality. quatA and quatB must have compatible sizes:

  • size(quatA) == size(quatB), or

  • numel(quatA) == 1, or

  • numel(quatB) == 1, or

  • if [Adim1,…,AdimN] = size(quatA) and [Bdim1,…,BdimN] = size(quatB), then for i = 1:N, either Adimi==Bdimi or Adim==1 or Bdim==1.

    If one of the quaternion arguments contains only one quaternion, then this function returns the distances between that quaternion and every quaternion in the other argument.

Output Arguments

collapse all

Angular distance in radians, returned as a numeric scalar or numeric array. The dimensions are the maximum of the union of size(quatA) and size(quatB).

Data Types: single | double

Algorithms

The dist function returns the angular distance between two quaternions.

A quaternion may be defined by an axis (ub,uc,ud) and angle of rotation θq: q=cos(θq2)+sin(θq2)(ubi+ucj+udk).

Angle Rotation

Given a quaternion in the form, q=a+bi+cj+dk, where a is the real part, you can solve for the angle of q as θq=2cos−1(a).

Consider two quaternions, p and q, and the product z=p*conjugate(q). As p approaches q, the angle of z goes to 0, and z approaches the unit quaternion.

The angular distance between two quaternions can be expressed as θz=2cos−1(real(z)).

Using the quaternion data type syntax, the angular distance is calculated as:

angularDistance = 2*acos(abs(parts(p*conj(q))));

Extended Capabilities

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

Version History

Introduced in R2021a

See Also

Functions

Objects