\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{printTrsf}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{printTrsf}},
{\tt \manName{fprintTrsf}}
-- RCI routines for printing $4\times4$ transforms.

}
\manSection{USAGE}
\cverbatim
#include <stdio.h>
#include <robotTypes.h> /* included as part of <rccl.h> */

printTrsf (fmt, tr)
  const char *fmt;
  TRSF *tr;

fprintTrsf (fp, fmt, tr)
  FILE *fp;
  const char *fmt;
  TRSF *tr;
@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt fmt} --}
Format string describing how the transform should be printed.
\manItem{{\tt tr} --}
Pointer to the transform.
\manItem{{\tt fp} --}
File stream.
\manSection{RESTRICTIONS}
These routines must be called from the planning level. 
{\tt rciPrintTrsf()} is available for the control level.
\manSection{DESCRIPTION}
These routines provide formatted output of the data type {\tt TRSF},
which represents a 4x4 homogeneous transform. 

The format string {\tt fmt} controls how the transform should be 
printed. It is possible to print various components of the transform
in different ways (Euler angles, quaternions, matrix form, etc.).
The format string has the general form
\cverbatim

        " ... %<spec1> ... %<spec2> ... ... %<specn> ... "@endcverbatim
\noindent
where each specification {\tt spec} causes some part of the transform to be
printed in a particular fashion (if this description gets confusing, skip to
the examples).
Illegal specifications are ignored as
if they were not present. Characters between specifications (including
newlines) are output verbatim.

Each specification has the form
\cverbatim

   %[<width>][.<prec1>][.<prec2>][.<prec3>][<qualifer>]<item> @endcverbatim
\noindent
and invokes the printing of a specific item.
An item may be either the whole transform or a component of it.
Each item is printed as a sequence of numbers,
each with a uniform field width, seperated
by one space. The field width modifier
{\tt <width>}, if specified, sets the base field width $F$ for each number.
The default field width is 8, and the minimum field width is 5.
The modifiers {\tt <prec1>}, {\tt <prec2>}, and {\tt <prec3>} define
values used in formatting the output. 
How these modifiers are used, and what
their default values are if they are not specified,
depends on the item
being printed. Usually they determine the precision
of the numbers printed
(i.e., the number of places printed to the right of
the decimal point). 
{\tt prec2} and {\tt prec3} are used only when the entire matrix is
being printed.
It is possible to specify  {\tt width}, {\tt prec1}, {\tt prec2}, 
or {\tt prec3} individually by preceding them with the appropriate
number of periods and omitting the intermediate values.
For instance, to specify a {\tt prec2} value of 4, and defaults
for the other values, one could use the construction
\cverbatim

        "..5" @endcverbatim

The {\tt qualifier} is optional, and is one character long.
Only one qualifier is currently implemented:

\manItem{{\tt L} --}
Preceed each printed item with a label indicating what it is.
The labels are printed in a string which has the same field width as
the numbers being printed. Labels for the different items
are:
\cverbatim

                QTRN:           -- quaternion
                 RPY:           -- roll, pitch, yaw
                 XYZ:           -- x, y, and z translations
                 EUL:           -- Euler angles @endcverbatim
\noindent
No label is printed when the item is the entire $4\times4$ matrix.

In the following descriptions, $F$ indicates the base field
width for each number.

The {\tt item} is a single character describing what part
of the transform should be printed, and in what format:

\manItem{{\tt m} --}
Matrix form. The 12 significant elements of the $4\times4$ matrix are
printed out over three lines. The precision of the
translational elements is given by {\tt prec1}, with a
default value of 2. The precision of the rotational elements
is given by {\tt prec2}, with a default value of 
$F - 3$.
{\tt prec3} gives the field width of the translational components
of the transform, and has a default value equal to $F$.

\manItem{{\tt r} --}
Roll-pitch-yaw.
The rotational component of the transform is printed
as the three roll, pitch, and yaw angles, in degrees.
The precision is given by
{\tt prec1}, with a default value of $F - 5$.
{\tt prec2} and {\tt prec3} are ignored.

\manItem{{\tt e} --}
Euler angles.
The rotational component of the transform is printed
as the three Euler angles phi, theta, and psi, in degrees.
The precision is given by
{\tt prec1}, with a default value of $F - 5$.
{\tt prec2} and {\tt prec3} are ignored.

\manItem{{\tt q} --}
Quaternion.
The rotational component of the transform
is printed as a four element unit quaternion.
The precision is given by
{\tt prec1}, with a default value of $F - 3$.
{\tt prec2} and {\tt prec3} are ignored.

\manItem{{\tt p} --}
Translation vector.
The translational component of the transform is printed
as the x, y, and z elements.
The precision is given by
{\tt prec1}, which has a default value of 2.
{\tt prec2} and {\tt prec3} are ignored.

\manSection{EXAMPLES:}
Assume we have a transform {\tt tr} whose elements are:
\cverbatim

        1.000   0.000   0.000   10.00
        0.000   0.000  -1.000   20.00
        0.000   1.000   0.000   30.00 @endcverbatim
\noindent

The call
\cverbatim
        printTrsf ("\%m\\n", &tr);
@endcverbatim
would produce the output
\cverbatim

 1.00000  0.00000  0.00000    10.00
 0.00000  0.00000 -1.00000    20.00
 0.00000  1.00000  0.00000    30.00
@endcverbatim

The call
\cverbatim
        printTrsf ("\%Lp\\n\%Lr\\n", &tr);
@endcverbatim
would produce the output:
\cverbatim

    XYZ:    10.00    20.00    30.00
    RPY:    0.000    0.000   90.000
@endcverbatim

As an example of playing with field widths, the format
string {\tt "\%13.3.10.8m\\n"} would
yield the output:
\cverbatim

 1.0000000000  0.0000000000  0.0000000000   10.000
 0.0000000000  0.0000000000 -1.0000000000   20.000
 0.0000000000  1.0000000000  0.0000000000   30.000
@endcverbatim

Finally, one can play with field widths to get things to line up nicely,
as well as do one's own labeling. The format string
\cverbatim
"Matrix:       %..3m\nEuler angles: %e\n" @endcverbatim
produces the output
\cverbatim

Matrix:          1.000    0.000    0.000    10.00
                 0.000    0.000   -1.000    20.00
                 0.000    1.000    0.000    30.00
Euler angles:  -90.000   90.000   90.000
@endcverbatim
        
The function {\tt fprintTrsf()} is identical to {\tt printTrsf()} except that
it places its output on the stream {\tt fp}.
\manSection{DIAGNOSTICS}
Calling these routines from the control level will cause the program to crash.
\raggedright
\manEnd
\end
