\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{distance}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{distance}}
-- specify offset to RCCL motion target (format string version).

}
\manSection{USAGE}
\cverbatim
distance (mnp, axes, value1 ... [, valuen])
  MANIP *mnp;
  char *axes;
  float value1, ... valuen;@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt mnp} --}
Manipulator reference structure.
\manItem{{\tt axes} --}
String specifying the offset components.
This string should be a combination of the 
following character pairs, separated by spaces:
\manItem{}
\qquad ``{\tt dx}'', ``{\tt dy}'', ``{\tt dz}'', ``{\tt rx}'', 
``{\tt ry}'', ``{\tt rz}''
\manItem{}
These specify offsets either along ({\tt d}) or about ({\tt t})
the $x$, $y$, and $z$ axes of the manipulator TOOL frame.
\manItem{{\tt value} --}
Value corresponding to one of the components indicated in
the string {\tt axes}.
The units are millimeters for distance, and degrees for rotation.
\manSection{RESTRICTIONS}
This routine must be called from the planning level.
\manSection{DESCRIPTION}
{\tt distance()} is an RCCL primitive that offsets
the target of the next motion (and the next motion only).
The routine affects only {\tt move()} requests;
the specification is ignored by {\tt stop()} requests
and cancelled by {\tt movej()} requests.

{\tt distance()} uses a format-string/var-args interface to
describe the components of an offset transform that is applied 
to the target in the position's TOOL frame. When the offset transform
is formed, the translational part is first built
from any {\tt dx}, {\tt dy}, or {\tt dz} components, and then the
rotation is built by considering any {\tt rz}, {\tt ry}, or {\tt rx} 
components to describe a set of roll-pitch-yaw angles.

As an example, consider a motion to
a hypothetical point {\tt P0}. To the alter the destination by
$+10$ mm. in the $z$ direction and $-5$ degrees about the
$x$ axis (in the {\it tool} frame), one could issue the command sequence
\cverbatim
        distance (mnp, "dz rz", 10.0, -5.0);
        move (mnp, P0); 
@endcverbatim
One may also specify target offsets with the routine {\tt setDistance()}
(q.v.), which allows the offset transform to be specified directly.

\manSection{DIAGNOSTICS}
This routine returns {\tt -1} in the event of an error.
It will automatically abort the program if the option {\tt RCCL_ERROR_EXIT} is
set (see {\tt rcclSetOptions(3)}).
Error codes and messages are placed on the {\it errorStack} (q.v.). 
The following error codes may be set:

\manItem{{\tt ESyntax} --}
Syntax error in the string {\tt axes}.

The routine will abort the program if called from the control level.
\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt setDistance(3)}, {\tt move(3)}, {\tt rcclSetOptions(3)}, 
{\tt errorStack(3)}. 
\manEnd
\end
