\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{dspl}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{trsfToDspl}},
{\tt \manName{dsplToTrsf}},
{\tt \manName{scaleDspl}},
{\tt \manName{extrapTrsfByDspl}},
{\tt \manName{unitDspl}}
-- RCCL routines associated with the {\tt DSPL} data type.

}
\manSection{USAGE}
\cverbatim
#include <robotTypes.h> /* included as part of <rccl.h> */

DSPL *trsfToDspl (dr, t1)
  DSPL *dr;
  TRSF *t1;

TRSF *dsplToTrsf (tr, d1)
  TRSF *tr;
  DSPL *d1;

DSPL *scaleDspl (dr, s, d1)
  DSPL *dr;
  float s;
  DSPL *d1;

TRSF *extrapTrsfByDspl (tr, s, d1)
  TRSF *tr;
  float s;
  DSPL *d1;

DSPL *unitDspl (dr, d1)
  DSPL *dr, *d1;
@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt dr} --}
Result displacement.
\manItem{{\tt tr} --}
Result transform.
\manItem{{\tt d1} --}
Input displacement.
\manItem{{\tt t1} --}
Input transform.
\manItem{{\tt s} --}
Scaling constant.
\manSection{DESCRIPTION}
A {\tt DSPL} data type represents a general displacement in
Cartesian coordinates as
a translation followed by a rotation about an axis. The components
of {\tt DSPL} include a translation vector {\bf p}, a unit vector {\bf u}
describing the axis of rotation, and the rotation angle
$a$ (in radians).
To avoid ambiquities, the angle $a$ is defined to be positive,
since negative rotations can be obtained by changing the direction of {\bf u}.
Routines which return a {\tt DSPL}
enforce this convention.

The following routines perform operations on the {\tt DSPL} data type.

{\tt trsfToDspl()} converts a transform {\tt t1} into the corresponding
displacment {\tt dr}. If the resulting value of $a$ is zero, then {\bf u} is
set to zero as well.

{\tt dsplToTrsf()} converts a displacement {\tt d1} into the corresponding
transform {\tt tr}.

{\tt scaleDspl()} scales the displacment
{\tt d1} by {\tt s}, and returns the result in {\tt dr}. The scale is
applied to the translation vector and the rotation angle $a$. If
the resulting value of $a$ is negative, then it is changed to a positive
value and the direction of {\bf u} is reversed.

{\tt extrapTrsfByDspl()} is a combination of {\tt scaleDspl()} and
{\tt dsplToTrsf()}: it scales the displacement {\tt d1} by {\tt s}, and
then converts this into the transform {\tt tr}. 

{\tt unitDpsl()} copies {\tt d1} into {\tt dr}, normalizing
the value of $a$ (and changing the direction of {\bf u}, if necessary)
so that $a \le 0 \le \pi$. If $a = 0$, then {\bf u} is set to
zero as well.

Each of these routines returns a pointer to its result argument.

\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt multTrsf(3)}.

\manEnd
\end
