solveTrans(3)

NAME
solveTrans, solveChain, solveInvChain -- solve RCCL position equations.

USAGE
#include <rccl.h>

TRSF *solveTrans (tr, p, t1, tx)
  TRSF *tr, *t1, *tx;
  POS *p;

TRSF *solveChain (tr, p, tb, te, tx)
  TRSF *tr, *t1, *t2, *tx;
  POS *p;

TRSF *solveInvChain (tr, p, tb, te, tx)
  TRSF *tr, *t1, *t2, *tx;
  POS *p;

ARGUMENTS

tr --
    TRSF structure in which to place the result. This can be any transform structure; it does not have to be allocated with one of the allocTrans() routines.

p --
    Position equation to be solved.

t1 --
    A transform being solved for. Must be a component transform of pos, including T6.

tb --
    First transform of a chain being solved for. Must be a component transform of pos, including T6.

t2 --
    Last transform of a chain being solved for. Must be a component transform of pos, including T6.

tx --
    Instantiation value for T6. This argument is necessary if the portion of the position equation being solved for contains T6 (because T6 has no particular value). Otherwise, this argument may be specified as NULL.

DESCRIPTION
These routines solve parts of a position equation.

solveTrans() solves for the transform t1 in the position pos and returns the result in tr. Unless t1 is itself the special transform T6, it is necessary to provide (through tx) a transform containing a value for T6. This can be any transform, including, of course, the T6 transform of a MANIP structure.

Example:

In the examples below we assume that we have an equation
                T6 TOOL = A B C

that was created with the following call to makePosition():
   p = makePosition ("P", T6, tool, EQ, a, b, c, TL, tool);

We also assume that we have a manipulator object mnp.

To solve for B given the T6 value associated with mnp, we can make the call
   solveTrans (tr, p, b, mnp->t6);

The routine solveChain() evaluates a segment of a position equation, starting with the transform tb and proceeding counter-clockwise around the kinematic loop, post-multiplying adjacent transforms into an accumulated result, up to and including te. If the direction of an encountered transform T is counter-clockwise (i.e., that transform is on the right-hand side of the equation), then the accumulated result is post-multiplied by the inverse of T. It is not necessary to provide tx unless the portion of the loop being evaluated contains the special transform T6.

Example:

With respect to the position defined earlier, the call
   solveChain (tr, p, tool, b, (TRSF*)NULL);

will produce the result:
                           -1  -1
                TR = TOOL C   B

solveInvChain() is identical in function to solveChain(), except that it runs around the loop clockwise. If an encountered transform T has a counter-clockwise direction (i.e., it is on the left-hand side of the equation), then the accumulated result is post-multiplied by the inverse of T. The result produced by solveInvChain() is the inverse of the result produced by solveChain() if the arguments tb and te are exchanged.

Example:

With respect to the position defined earlier, the call
   solveChain (tr, p, T6, c, mnp->t6);

will produce the result:
                       -1
                TR = T6   A B C

where T6 is the manipulator transform associated with mnp. Notice that this is equivalent to solving for TOOL, and hence equivalent to the call
   solveTrans(tr, p, tool, mnp->t6);

DIAGNOSTICS
These routines return NULL in the event of an error. They 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:

EBadArg --
    The variable transform tx was not provided when needed.

ERange --
    One of the transforms t1, tb, or te is not contained in the position equation p.

SEE ALSO
makePosition(3), updatePosition(3), manip(3), rcclSetOptions(3), errorStack(3).