\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{setAccel}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{setCartAccel}},
{\tt \manName{setJointAccel}},
{\tt \manName{setAccelScale}}
-- set accelerations for RCCL motions.

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

setCartAccel (mnp, taccel, raccel)
  MANIP *mnp;
  float taccel, raccel;
  
setJointAccel (mnp, jaccel)
  MANIP *mnp;
  JNTS *jaccel;

float setAccelScale (mnp, scale)
  MANIP *mnp;
  float scale;
@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt mnp} --}
Manipulator reference structure.
\manItem{{\tt taccel} --}
Translational acceleration (mm. per second$\;^2$).
\manItem{{\tt raccel} --}
Rotational acceleration (degrees per second$\;^2$).
\manItem{{\tt jaccel} --}
Joint level accelerations (degrees or mm. per second$\;^2$).
\manItem{{\tt scale} --}
Acceleration scale factor (nominal value is 1.0)
\manSection{RESTRICTIONS}
These routines must be called from the planning level.
{\tt setJointAccel()} is not defined for virtual manipulators.
\manSection{DESCRIPTION}
These routines set the acceleration limits associated with
a particular manipulator.

The RCCL trajectory generator
creates a transition interval which smoothly connects different motion 
path segments.
The length of the transition
interval is computed dynamically for each manipulator based on its current
acceleration limits. The higher the acceleration limit, the smaller the
transition interval. Cartesian motions are constrained
by two seperate acceleration limits, one for translation and one for
rotation. Joint interpolated motions are constrained by a set
of acceleration limits, one per joint. For the details on
how the transition time is computed from the acceleration
limit, consult the document ``Trajectory Generation in Multi-RCCL''.

{\tt setCartAccel()} sets the translational and rotational acceleration
limits used by
Cartesian interpolated motions. If either {\tt taccel} or {\tt raccel}
is specified as {\tt F_UNDEF}, then the existing value is not changed.
Specifying either value as {\tt F_DEFAULT} causes the corresponding
default acceleration to be set.
Specifying any other non-positive value is
illegal. The specification takes effect at the beginning of the next requested
motion, and is valid for all subsequent motions.

Default values for the accelerations are chosen when the manipulator is
created with {\tt rcclCreate()}. For virtual manipulators, the
accelerations are set to the defined constants {\tt DEFAULT_TRANS_ACCEL} and
{\tt DEFAULT_ROT_ACCEL}. If the 
manipulator is a real robot, then the accelerations are computed from the
nominal joint accelerations described in the {\tt nominalAcc} field of the
robot's {\tt JLS} data structure. This is done using the 
manipulator Jacobian evaluated at the
position {\tt bestAngles}, which is also defined in the {\tt JLS} structure.

{\tt setJointAccel()} sets the accelerations for
joint interpolated motions. Acceleration values are placed in
the {\tt v} field of {\tt jaccel}. If any of these
are specified as {\tt F_UNDEF} then the corresponding
joint acceleration value is not changed.
Specifying any value as {\tt F_DEFAULT} causes the default
acceleration to be set for the corresponding joint.
Specifying any other non-positive value is
illegal. The specification takes effect at the end of the next requested
motion, and is valid for all subsequent motions.
This call is not legal for virtual manipulators.

Default values for the joint accelerations are chosen when the
the manipulator is created with {\tt rcclCreate()}. These are taken
from the values defined in the {\tt nominalAcc} field of the
robot's {\tt JLS} structure.

{\tt setAccelScale()} specifies a scale factor that is
applied to both the Cartesian and joint level acceleration limits.
The default value for this scale factor is 1. A
value less than 1 will cause transition times to increase,
while a value greater than 1 will cause transition times to decrease,
without having to change the primary limits set
by {\tt setCartAccel()} and {\tt setJointAccel()}. The routine
returns the previous scale value.

One use of these routines is to set the acceleration characteristics of a
virtual manipulator to be equal to that of a real robot. This may be
necessary if the virtual manipulator is being used to drive one or
more real robots as a slave.
\manSection{DIAGNOSTICS}
These routines return {\tt -1} (or {\tt -1.0}) in the event of an error.
They 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 ERange} --}
A non-positive value not equal
to {\tt F_UNDEF} or {\tt F_DEFAULT} was specified in one of the {\it set}
routines. 

{\tt setJointAccel()} may also set the following:

\manItem{{\tt ENotDefined} --}
The routine was called for a virtual manipulator.

These routines will abort the program if called from the control level.
\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt rcclCreate(3)}, {\tt setSpeed(3)}, {\tt move(3)},
{\tt JLS(3)}, {\tt rcclSetOptions(3)}, {\tt
errorStack(3)} 
\manEnd
\end
