Main Content


Angular distance in radians



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


collapse all

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


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; ...
angles2 = [30,6,15; ...
           31,11,15; ...
           30,16,14; ...

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

ans = 4×1


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.

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


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=2cos1(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=2cos1(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 R2018b