\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{setDistance}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{setDistance}}
-- offset the target position of an RCCL motion (transform specification).

}
\manSection{USAGE}
\cverbatim
#include <rccl.h>

setDistance (mnp, tr)
  MANIP *mnp;
  TRSF *tr;
@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt mnp} --}
Manipulator reference structure.
\manItem{{\tt tr} --}
Offset transformation.
\manSection{RESTRICTIONS}
This routine must be called from the planning level.
\manSection{DESCRIPTION}
This routine adds an offset to the target position of an RCCL
motion (except for those initiated with {\tt movej()} requests). 
It is useful for doing successive relative motions. Its companion
routine, {\tt distance()} (q.v.), does the same thing using a 
format-string, var-args specification. 

The routine causes the target position of the next motion request
to be offset by {\tt tr} such that
\manIfTeX
$$
{\rm T6} \; {\rm TOOL} \;=\; {\rm TARGET} \; {\rm TR}
$$
\manElse
\cverbatim
                T6 TOOL = TARGET TR     @endcverbatim
\manFi
The offset is valid for the next motion only. Relative motions can be achieved
by using {\tt setDistance()} in
conjunction with the postion equation {\tt last}, which is built into the {\tt
MANIP} structure. This equation describes the manipulator's location
at the end of the previous motion, and has the form
\manIfTeX
$$
{\rm T6} \;=\; {\rm HERE}.
$$
\manElse
\cverbatim
                T6 = HERE .@endcverbatim
\manFi
HERE is the value of T6 at the end of the previous motion.
To move by some relative displacement TR, then, we wish to
satisfy the equation
\manIfTeX
$$
{\rm T6} \;=\; {\rm HERE} \; {\rm TR}
$$
\manElse
\cverbatim
                T6 = HERE TR @endcverbatim
\manFi
which can be done with the following construction:
\cverbatim
        setDistance (mnp, tr);
        move (mnp, mnp->last); @endcverbatim

{\tt setDistance()} affects only {\tt move()} requests;
the specification is ignored by {\tt stop()} requests
and cancelled by {\tt movej()} requests.
\manSection{DIAGNOSTICS}
The routine will abort the program if called from the control level.
\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt distance(3)}, {\tt limit(3)}, {\tt move(3)}, {\tt rcclSetOptions(3)}.
\manEnd
\end
