makePosition(3)

NAME
makePosition -- RCCL routine to define position equations.

USAGE
#include <rccl.h>

POS *makePosition (name, L1 [, Lm] ... , `EQ',
                   R1 [, Rn] ... [, `TL', tl] , NULL)
  const char *name;
  TRSF *L1, ... *Lm, *R1, ... *Rn, *tl;

ARGUMENTS

name --
    Name of the position. This argument is optional, and may be given as NULL.

L1  ... Lm --
    Transforms comprising the left-hand (clockwise) side of the equation.

R1  ... Rm --
    Transforms comprising the right-hand (counterclockwise) side of the equation.

EQ --
    Keyword denoting the "equal" sign in the equation.

T6, TRANS --
    Keywords denoting a manipulator T6 transform. This is the transform that must be solved for when this position is used to specify the target of a manipulator motion. This keyword is optional.

TL --
    Keyword denoting the TOOL frame of the equation, applicable only to positions which contain a T6 transform. This keyword is optional; if omitted, the TOOL frame will be set equal to the T6 frame.

RESTRICTIONS
This routine must be called from the planning level.

DESCRIPTION
makePosition() builds a position equation out of a set of transforms. It allocates space for, and returns a pointer to, a structure describing the transform equation specified by the argument list. This equation is of the form
     L_1 ... L_m = R_1 ... R_n

where Li are the transformations on the left-hand side, and Ri are the transformations on the right-hand side. The position of the equal sign is denoted by placing the predefined keyword EQ in the argument list at the appropriate point, and the argument list is terminated with a NULL pointer. If the resulting equation is represented as a directed circular graph, then the transforms on the left-hand side are assumed to be directed clockwise and those on the right-hand side are directed counterclockwise.

The first argument to makePosition() may be used to give the position equation a name. This can be used, in conjunction with the routine getPostionByName(), to get a pointer to the position from another part of the program.

All of the transforms which comprise the position equation must be allocated using one of the allocTrans() routines. There is no real limit on the number of terms that an equation may contain, although a "sanity check" limit of 100 is currently imposed.

If a position equation is used to specify the target of a motion request, then it must also contain a T6 transform. This can be specified by placing either of the two synomymous keywords T6 or TRANS at the appropriate place in the argument list.

When used to specified the target of a manipulator motion, the trajectory generator will resolve the position equation into the following canonical form:
     T6 TOOL = COORD

TOOL defines the transform (or set of transforms) that lie between T6 and the manipulator TOOL frame. This is the frame, which, among other things, the trajectory generator uses when computing a Cartesian straight line motion to the target.

By default, makePosition() sets the TOOL frame to be the same as the T6 frame (i.e., it assumes that TOOL = I). Specifying a different TOOL frame can be done by placing two more arguments at the end of the routine call: the special argument TL, followed by a pointer to whichever transform (already listed in the equation definition) immediately preceeds the TOOL frame. The TOOL component of the equation is then taken to be the product of this transform, plus all others leading back to the T6 transform. If the transform indicated by TL occurs more than once in the equation definition, then the one closest to T6 defines the TOOL frame. If TL is followed by the special argument T6, then the TOOL frame is assumed to be equivalent to the T6 frame, as in the default case.

When a call to makePosition() contains a TL tool specification at the end, the final NULL argument may be omitted.

A position equation allocated with makePosition() is a global memory object and can be accessed from any part of the RCCL program using getPositionByName() or getPositionByAddr(). If referenced from a different CPU, it will generally be necessary to build a local copy of it (using copyPosition()) before it can be used with other routines. It is possible to solve for individual transforms or components of a position equation by using the routines solveTrans(), solveChain(), and solveInvChain().

DIAGNOSTICS
This routine returns NULL 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 position specification.

EDuplicate --
    Another position equation already exists with the same name.

EMemory --
    Out of program memory.

ETooMany --
    Too many transforms specified in the equation. This limit is defined by the parameter MAX_TERMS in the source file for makePosition(); at the time of this writing, MAX_TERMS is set to 100. The reason for putting this limit on is to trap cases where delimiter keywords are accidentally omitted.

EDescriptor --
    One of the specified transforms was not allocated using one of the allocTrans() routines. This error can also occur when the function call is not properly terminated with a NULL or TL sequence.

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

BUGS
The format for the loop equation is not very general. It might be nice to be able to specify "special" frames (like the TOOL frame) more easily.

SEE ALSO
copyPosition(3), solveTrans(3), allocTrans(3), allocTransXyz(3), rcclSetOptions(3), errorStack(3).