File Exchange

## Dual quaternion toolbox

version 1.3.0.0 (217 KB) by Guillaume Leclercq

### Guillaume Leclercq (view profile)

This toolbox provides dual quaternion methods, focusing on 3D kinematics for points and lines.

Updated 26 Mar 2014

The toolbox provides functions to (see the related journal article: http://www.frontiersin.org/Behavioral_Neuroscience/10.3389/fnbeh.2013.00007/abstract) :
- encode dual quaternions: a point position, velocity, a line position, velocity, a rotation, a translation, a screw,...
- do operations on dual quaternions: the dual quaternion multiplication, the dual quaternion conjugates, the inverse,...
- retrieve parameters from a dual quaternion: finding the parameters of a rotation dual quaternion, or a screw dual quaternion,...
- easily going back and forth between Fick rotation coordinates, 3*3 rotation matrices, rotation dual quaternions, angular vector
- find the shortest rotation between two unitary vectors
- find the shortest screw motion between two lines (it answers if two lines intersect, and if relevant, what the intersection point is)
The toolbox also provides one example file (example_forward_kinematics.m) (see also the file "html/example_forward_kinematics.html"). This
example describes the forward kinematics of the end-effector of a two- or three-link arm in 3D space. The user can choose between two methods
(alternating rotation and translation dual quaternions, or using screw motion dual quaternions) to encode the forward kinematics: the results are
identical, whatever the method which is used. Furthermore, for the three-link arm, the orientation of the end-effector is also taken into account
(via line transformations).

For each of these methods and example, the user will find an extensive documentation by typing HELP NAME_OF_THE_FUNCTION in the MATLAB environment

### Cite As

Guillaume Leclercq (2020). Dual quaternion toolbox (https://www.mathworks.com/matlabcentral/fileexchange/39288-dual-quaternion-toolbox), MATLAB Central File Exchange. Retrieved .

Wenjie Li

Kyl Stanfield

Thomas Watts

### Thomas Watts (view profile)

Thanks for this! However...

***WARNING TO ROBOTICISTS***

The unconventional quaternion multiplication (with negated cross product term) used in this toolbox caused me much head-scratching... Reading comments below I see I'm also not the first.

Changing calls to the Qmult function (which is in the private directory) to MATLAB's quatmultiply seemed to sort out the problems I was experiencing.

Juntang Yang

### Juntang Yang (view profile)

Hi, really thanks for the dual quaternion toolbox.
I have some feedback for this toolbox. Actually I had the same problem about the function "dquat2screw" reported on 16 Sep 2016 by Ettore Pennestri.
I find that the function works if I write the code as "dquat2screw([dq,dq])". It seems that "dquat2screw" can not deal with dual quaternion vector with the size of 8 by 1.

Ettore Pennestri'

### Ettore Pennestri' (view profile)

The following example does not work on Matlab 2016:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Test of Dual quaternion toolbox v.3 by G. Leclercq
%
% Author: pennestri@mec.uniroma2.it
% Sept.19th 2016 (Matlab 2016)
axis=[0 0 1]; % Screw axis
axispoint=[0 2 0]; % Point on screw axis
d=1.0; % Translation along screw axis
theta=90. % Rotation angle
% Generate the dual quaternion (the result is correct)
dq = screw2dquat(theta,d,axis,axispoint)
% Obtain screw parameters from the previously generated dual quaternion:
[theta,d,axis,axispoint] = dquat2screw(dq)
%------------------------------

Error using ./
Matrix dimensions must agree.

Error in dquat2screw (line 87)
axis(:,ind2) = 2*dq(6:8,ind2)./repmat(d(ind2),3,1);

Error in test_problem (line 9)
[theta,d,axis,axispoint] = dquat2screw(dq)

Sun TongYang

Fritz

### Fritz (view profile)

In dquat2screw I've changed line 87 to:
if ~isempty(ind2); axis(:,ind2) = 2*dq(6:8,ind2)./repmat(d(ind2),3,1); end

otherwise I get an error: Error using ./ Matrix dimensions must agree.

Walter Markus

### Walter Markus (view profile)

Good toolbox.

Is shortestRotation not handling (anti)parallel vectors for a reason?

If no, then you could add something like
what is done in rotationTo() in src/gl-matrix/quat.js on
https://github.com/toji/gl-matrix

Guillaume Leclercq

### Guillaume Leclercq (view profile)

Thanks for noticing this bug.
I just updated the rotMatrix2dquat function. Now it deals with 180deg angles, and it implements the efficient method in Funda et al. (1990) such that the method is accurate and efficient even for angles close to 0 or 180 deg.

Raviteja Vemulapalli

### Raviteja Vemulapalli (view profile)

In the file rotMatrix2dquat, when DQ0 is zero, the quaternion has Inf values (because of division by DQ0).

Hanfucius

### Hanfucius (view profile)

I did not get direct answer in your paper and thus got confused.
Surely I've read many geometric algebra books and I know that quaternion is isomorphic to G+3,0,0 and i,j,k is indeed another representation 2-blade bases of this geometric algebra. However,never did I paid attention to handedness of the coordinates.
Though we use the same mathematical tool,we use different mathematical conventions in your bio science and my robotics. I think this is the reason why gap happens.

Guillaume Leclercq

### Guillaume Leclercq (view profile)

It is true that in many books, it is indeed a + instead of a - just before the cross product. However, this is because the historical basis for quaternions is a left-handed basis (the famous i, j, k and their relationship).

Here, we use a right-handed basis, that's why the sign is different (thus this is not a mistake). Actually, you can find a proof of the derivation of this expression in the article http://www.frontiersin.org/Behavioral_Neuroscience/10.3389/fnbeh.2013.00007/abstract : at p3 of the paper, we explain the quaternion product and refer to appendix A where we derive the expression from the concepts of geometric algebra.

Actually, using the left-handed basis (and thus the + sign), you have to exchange the dual quaterniopn and its conjugate in the kinematics expression to retrieve the same results.

Hanfucius

### Hanfucius (view profile)

I think you have made a mistake.
In function Qmult,line 49,I refered many books,

sv = repmat(r0,3,1).*qv+repmat(q0,3,1).*rv-cross(qv,rv);

should be

sv = repmat(r0,3,1).*qv+repmat(q0,3,1).*rv+cross(qv,rv);

Hanfucius

### Hanfucius (view profile)

Sorry to have done such stupid things as modify your code and redistribute it. I have delete all of them.

Guillaume Leclercq

### Guillaume Leclercq (view profile)

For details on the example, you can read section 3.2.1 of the article that you can freely download here: http://www.frontiersin.org/Behavioral_Neuroscience/10.3389/fnbeh.2013.00007/abstract
In particular, take a look on equation 18 (p10). Actually we can not simply reverse the conjugates as we like (thus it is quite normal that you obtain a different result): You may want to read sections 2.4 and 2.5 of the same article, for more details about the kinematic transformations.

Hanfucius

### Hanfucius (view profile)

In kinematics example file, why the total transformation is multiplied in reverse order?
Also why DQconj comes first?
S_tot = DQmult(R_LU,T_ES,R_UB);
P_BS_dq = DQmult(DQconj(S_tot),P_LE_dq,S_tot);

I tried this :
S_tot = DQmult(R_UB,T_ES,R_LU);
P_BS_dq = DQmult(S_tot,P_LE_dq,DQconj(S_tot));

Guillaume Leclercq

### Guillaume Leclercq (view profile)

That's because you need to specify two output arguments. I modified this file such that an error is generated if the wrong number of output arguments is specified: it should be here in a few days (once Matlab will have reviewed it).

Hanfucius

### Hanfucius (view profile)

Why function dquat2line loses a vector?

>> line2dquat([1 2 3],[4 5 6])

ans =

0
0.2673
0.5345
0.8018
0
0.8018
-1.6036
0.8018

>> dquat2line(ans)

ans =

0.2673
0.5345
0.8018

Guillaume Leclercq

### Guillaume Leclercq (view profile)

Thanks.
The toolbox is not intended for symbolic computing. However, feel free to inspire from the toolbox to develop your own symbolic toolbox

Hanfucius

### Hanfucius (view profile)

This is very useful and I use it a lot.
The question is, can this toolbox be used in the area of symbolic computing?

 26 Mar 2014 1.3.0.0 function rotMatrix2dquat updated, such that it deals with 180 deg rotations and implements the method described in https://www.researchgate.net/publication/3298038_On_homogeneous_transforms_quaternions_and_computationalefficiency 5 Sep 2013 1.2.0.0 I modified the following files: - dquat2line - dquat2linevel - dquat2screw - rotMatrix2fick such that these functions return an error if the wrong number of output arguments is specified by the user. 2 Sep 2013 1.1.0.0 I provided the link (in the description) towards the journal publication linked to these methods.
##### MATLAB Release Compatibility
Created with R2010a
Compatible with any release
##### Platform Compatibility
Windows macOS Linux