printTrsf(3)

NAME
printTrsf, fprintTrsf -- RCI routines for printing 4X4 transforms.

USAGE
#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;

ARGUMENTS

fmt --
    Format string describing how the transform should be printed.

tr --
    Pointer to the transform.

fp --
    File stream.

RESTRICTIONS
These routines must be called from the planning level. rciPrintTrsf() is available for the control level.

DESCRIPTION
These routines provide formatted output of the data type TRSF, which represents a 4x4 homogeneous transform.

The format string 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
        " ... <spec1> ... <spec2> ... ... <specn> ... "

where each specification 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
   [<width>][.<prec1>][.<prec2>][.<prec3>][<qualifer>]<item>

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 <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 <prec1>, <prec2>, and <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). prec2 and prec3 are used only when the entire matrix is being printed. It is possible to specify width, prec1, prec2, or prec3 individually by preceding them with the appropriate number of periods and omitting the intermediate values. For instance, to specify a prec2 value of 4, and defaults for the other values, one could use the construction
        "..5"

The qualifier is optional, and is one character long. Only one qualifier is currently implemented:

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:
                    QTRN:           -- quaternion
                     RPY:           -- roll, pitch, yaw
                     XYZ:           -- x, y, and z translations
                     EUL:           -- Euler angles

    No label is printed when the item is the entire 4X4 matrix.

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

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

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

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 prec1, with a default value of F - 5. prec2 and prec3 are ignored.

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 prec1, with a default value of F - 5. prec2 and prec3 are ignored.

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

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

EXAMPLES:
Assume we have a transform tr whose elements are:
        1.000   0.000   0.000   10.00
        0.000   0.000  -1.000   20.00
        0.000   1.000   0.000   30.00

The call
        printTrsf (", &tr);

would produce the output
 1.00000  0.00000  0.00000    10.00
 0.00000  0.00000 -1.00000    20.00
 0.00000  1.00000  0.00000    30.00

The call
        printTrsf ("

would produce the output:
    XYZ:    10.00    20.00    30.00
    RPY:    0.000    0.000   90.000

As an example of playing with field widths, the format string "13.3.10.8m would yield the output:
 1.0000000000  0.0000000000  0.0000000000   10.000
 0.0000000000  0.0000000000 -1.0000000000   20.000
 0.0000000000  1.0000000000  0.0000000000   30.000

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
"Matrix:       ..3muler angles: e

produces the output
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

The function fprintTrsf() is identical to printTrsf() except that it places its output on the stream fp.

DIAGNOSTICS
Calling these routines from the control level will cause the program to crash.