\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{solveTrans}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{solveTrans}},
{\tt \manName{solveChain}},
{\tt \manName{solveInvChain}}
-- solve RCCL position equations.

}
\manSection{USAGE}
\cverbatim
#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;

@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt tr} --}
{\tt 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 {\tt allocTrans()} routines.
\manItem{{\tt p} --}
Position equation to be solved.
\manItem{{\tt t1} --}
A transform being solved for. 
Must be a component transform
of {\tt pos}, including {\tt T6}.
\manItem{{\tt tb} --}
First transform of a chain being solved for.
Must be a component
transform of {\tt pos}, including {\tt T6}.
\manItem{{\tt t2} --}
Last transform of a chain being solved for.
Must be a component
transform of {\tt pos}, including {\tt T6}.
\manItem{{\tt tx} --}
Instantiation value for {\tt T6}. This argument
is necessary if the portion of the position equation being
solved for contains {\tt T6} (because {\tt T6} has no particular value).
Otherwise, this argument may
be specified as {\tt NULL}.
\manSection{DESCRIPTION}
These routines solve
parts of a position equation.

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

{\bf Example:}

In the examples below we assume that we have an equation
\manIfTeX
$$
{\rm T6} \; {\rm TOOL} \;=\; {\rm A} \; {\rm B} \; {\rm C}
$$
\manElse
\cverbatim
                T6 TOOL = A B C
@endcverbatim
\manFi
that was created with the following call to {\tt makePosition()}:
\cverbatim
   p = makePosition ("P", T6, tool, EQ, a, b, c, TL, tool); @endcverbatim
\noindent
We also assume that we have a manipulator object {\tt mnp}.

To solve for B given the T6 value associated with
{\tt mnp}, we can make the call
\cverbatim
   solveTrans (tr, p, b, mnp->t6); @endcverbatim

\medskip
The routine {\tt solveChain()} evaluates a segment of a position
equation, 
starting with the transform {\tt tb} and proceeding 
counter-clockwise around the kinematic loop, post-multiplying adjacent
transforms into an accumulated result, up to and including {\tt 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 {\tt tx} unless the portion of the loop
being evaluated contains the special transform {\tt T6}.

{\bf Example:}

With respect to the position defined earlier, the call
\cverbatim
   solveChain (tr, p, tool, b, (TRSF*)NULL); @endcverbatim
will produce the result:
\manIfTeX
$$
{\rm TR} \;=\; {\rm TOOL} \; {\rm C}^{-1} \; {\rm B}^{-1}
$$      
\manElse
\cverbatim
                           -1  -1
                TR = TOOL C   B 
@endcverbatim
\manFi     
\medskip

{\tt solveInvChain()} is identical in function to {\tt 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 {\tt solveInvChain()} is the inverse
of the result produced by {\tt solveChain()} if the arguments
{\tt tb} and {\tt te} are exchanged.

{\bf Example:}

With respect to the position defined earlier, the call
\cverbatim
   solveChain (tr, p, T6, c, mnp->t6); @endcverbatim
will produce the result:
\manIfTeX
$$
{\rm TR} \;=\; {\rm T6}^{-1} \; {\rm A} \; {\rm B} \; {\rm C}
$$      
\manElse
\cverbatim
                       -1 
                TR = T6   A B C
@endcverbatim
\manFi     
\medskip
where T6 is the manipulator transform associated with {\tt mnp}.
Notice that this is equivalent to solving for TOOL, and hence equivalent to
the call
\cverbatim
   solveTrans(tr, p, tool, mnp->t6); @endcverbatim

\manSection{DIAGNOSTICS}
These routines return {\tt NULL} 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 EBadArg} --}
The variable transform {\tt tx} was not provided when needed.
\manItem{{\tt ERange} --}
One of the transforms {\tt t1}, {\tt tb}, or {\tt te} is not
contained in the position equation {\tt p}.
\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt makePosition(3)}, {\tt updatePosition(3)}, {\tt manip(3)}, {\tt
rcclSetOptions(3)}, {\tt errorStack(3)}.
\manEnd
\end
