distance(3)

NAME
distance -- specify offset to RCCL motion target (format string version).

USAGE
distance (mnp, axes, value1 ... [, valuen])
  MANIP *mnp;
  char *axes;
  float value1, ... valuen;

ARGUMENTS

mnp --
    Manipulator reference structure.

axes --
    String specifying the offset components. This string should be a combination of the following character pairs, separated by spaces:

    "dx", "dy", "dz", "rx", "ry", "rz"

    These specify offsets either along (d) or about (t) the x, y, and z axes of the manipulator TOOL frame.

value --
    Value corresponding to one of the components indicated in the string axes. The units are millimeters for distance, and degrees for rotation.

RESTRICTIONS
This routine must be called from the planning level.

DESCRIPTION
distance() is an RCCL primitive that offsets the target of the next motion (and the next motion only). The routine affects only move() requests; the specification is ignored by stop() requests and cancelled by movej() requests.

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 dx, dy, or dz components, and then the rotation is built by considering any rz, ry, or rx components to describe a set of roll-pitch-yaw angles.

As an example, consider a motion to a hypothetical point P0. To the alter the destination by +10 mm. in the z direction and -5 degrees about the x axis (in the tool frame), one could issue the command sequence
        distance (mnp, "dz rz", 10.0, -5.0);
        move (mnp, P0);

One may also specify target offsets with the routine setDistance() (q.v.), which allows the offset transform to be specified directly.

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

ESyntax --
    Syntax error in the string axes.

The routine will abort the program if called from the control level.

SEE ALSO
setDistance(3), move(3), rcclSetOptions(3), errorStack(3).