\input manualMacros.tex
\manBegin
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{robotsim}{1}
\manSection{NAME}
{\tt \manName{robotsim}}
-- RCI robot simulation program.
\manSection{USAGE}
\cverbatim
robotsim [-s] [-i] [-r <interval>] [-noauto]
         [-ng] [-X11] [-bg <background>] [-fg <foreground>] [-wf]
         [-nocfg] [-f <configFile>] [-pendant]
         [ <robotName> [-nc] [-p <position>] 
           [-clf <CartesianLogFile>] [-jlf <jointLogFile>] ]
@endcverbatim
\manSection{DESCRIPTION}
This is the RCCL/RCI robot simulator program. It is used to simulate
robots controlled by RCCL/RCI programs, and is useful for debugging 
such programs at the trajectory control level.

\manInset{{\bf NOTE:}
The current version of {\tt robotsim} described here is still in a 
state of development, and is likely to undergo considerable changes
in the future.}

The simulator program runs as a separate process that emulates 
one or more robots and their controllers.  
Starting up the simulator program is equivalent to ``switching
on the controllers'', and the simulator will continue to run for the duration
of multiple RCCL/RCI programs, retaining a consistent notion of each
robot's state between these programs.
The simulator starts up with each robot in a known 
position. There are options for displaying
joint angles and other state information as the simulator runs, 
and there is also an interactive keyboard mode that allows single step
operation.  The latter is particularly useful for debugging applications.

At the present time, the simulator does only 3D graphic/kinematic
simulation; it does not calculate robot dynamics
(except, in some cases, for gravity loading), and does not do
collision detection. The simulator has been designed, however,
to allow introduction of these features at a later date.

The operational characteristics of the simulator can be controlled
through a combination of command line arguments and specifications
contained in a configuration file. The command
line arguments normally take precedence over the configuration
file. The default configuration file is
called {\tt .robotsim}, and the program looks for this file first in the
current directory, then in the user's home directory, and finally in the the
directory {\filefont \$RCCL/conf}. A configuration file with a different name
can be specified using the {\tt -f} option.

\manSubSection{Graphics Support}

The simulator supports graphics output for X windows,
SunView, and the SGI graphics library ``GL''. 
On X windows and SunView, a wireframe display is produced, while
under GL there is support for both wire frame and solid shaded
graphics. Normally, {\tt robotsim} will
attempt to create a graphics window at startup time unless it is
given the command line option {\tt -ng}. The type of graphics 
window is chosen according to the following sequence of rules:

\manItem{o}
X windows will always be chosen if the command line option {\tt -X11} is
given. The environment variable {\tt DISPLAY} must be set appropriately in
order for this to work.

\manItem{o}
GL will be chosen next, if it is available. Solid shaded graphics will be
selected unless the command line option {\tt -wf} (wire frame)
is given.

\manItem{o}
X windows will be chosen if the environment variable {\tt DISPLAY}
is set.

\manItem{o}
SunView will be chosen if the environment variable {\tt WINDOW_PARENT}
is set (this may not be the most reasonable way to determine if
SunView is active; please advise the authors if you know of a better way).

\manSubSection{Connecting to the Simulator}

RCCL/RCI programs connect to the simulator using the special device driver
{\TT sim}, defined in the {\TT drivers} directory. This is an
RCI I/O device (see IOdevice(7)) which works
by setting up a socket connection to the simulator process rather
than accessing some robot interface on an I/O bus.

To get an RCCL/RCI program to connect to
the simulator, instead of a real robot, it must be run in simulator mode.
There are different ways of doing this. The utility programs ({\tt move},
{\tt pumacal}, etc.) will run in simulator mode if the option {\tt -sim} is
given to them. All RCCL programs will run in simulator mode if the 
{\tt simulate} keyword is set in the {\tt RCCL} parameter set of the
{\tt .rciparams} file. An RCCL program can also be made
to run in simulation mode using the routine {\tt rcclSetSimulator()}.

The simulator works using TCP/IP. It is therefore possible to
connect an RCCL/RCI program to a simulator running on a remote machine.
When a simulator is started on a particular machine, it gives itself a name
(which is usually the user name
under which the simulator is running) and registers itself, and the names of
all the robots it is simulating, with a server daemon. The server
daemon, called {\tt RCISimMuxd}, is a separate task which is spawned if
necessary.  Other RCCL/RCI programs can then connect to a ``robot'' provided
by the simulator by specifying the name of the robot, the name of the
simulator, and an Internet address for the machine where the simulator
is running. The full syntax for
specifying this is a string that looks like

\cverbatim
        <robotName>:<simulatorName>@@<hostName> @endcverbatim

It is not usually necessary for the user of an RCCL/RCI program
to specify this entire string. For instance, in the case of an
RCCL program, a simulator connection is often specified by
setting the {\tt simulate} parameter in the {\tt .rciparams} file.
If this is set to {\tt 1}, as in

\cverbatim
        simulate=1 @endcverbatim
\noindent
the RCCL program will try to connect its robots to a simulator running
under the same user name, and on the same host machine, as itself. 
To attach to a simulator running under the same user name, but on
a different machine, one would set

\cverbatim
        simulate=@@<hostName> @endcverbatim
\noindent
where {\tt <hostName>} is an appropriate Internet address.

The {\tt -sim} option to the utility programs ({\tt move}, {\tt pumacal},
{\tt free}) can be set similarly.

For more details on the address string format for
a simulator, see the manual page {\tt simAddress(5)}.

\manInset{Notice from the above description that simply specifying
{\tt simulate = 1} will {\bf not} enable a program to connect to
a simulator running under a different user name. This was done
in order to allow simulator processes to be more or less ``private''
to a given user.
}

\manSection{COMMAND LINE ARGUMENTS}

\manSubSection{Basic Arguments}

{\tt robotsim} accepts the following command line arguments:

\manItem{{\tt -s} --}
Silent mode. This option causes all messages concerning robot activity
to be suppressed. It is 
useful when the program is being run on the same terminal/window as the
RCI/RCCL program.

\manItem{{\tt -i} --}
Interactive mode. This option invokes
a Ctree-matcher shell that allows the user to set various simulated I/O
conditions, single or multi-step the control cycle interaction, and examine
variables. This mode is described in detail in the OPERATION section.

\manItem{{\tt -r <interval>} --}
Sample rate. The base simulated sample rate  is set to {\tt interval}
milliseconds.

\manItem{{\tt -noauto} --}
Start the simulator up with autocycling disabled. This means
that the simulator cycles can be controlled using
the {\tt step} command in interactive keyboard mode.

\manItem{{\tt -ng} --}
No graphics. Do not attempt to open a graphics window.

\manItem{{\tt -X11} --}
Use X11 graphics.

\manItem{{\tt -bg <background>} -- }
Background color. Set the background color as specified by the integer
{\tt background}; see the section ``Specifying Colors''. On black and
white displays, setting this to a non-zero value creates a reverse
video display.

\manItem{{\tt -fg <foreground>} -- }
Foreground color. Set the foreground color as specified by the integer
{\tt foreground}; see the section ``Specifying Colors''. This hasn't been
completely implemented yet.

\manItem{{\tt -wf} --}
Use wire frame graphics.

\manItem{{\tt nocfg} --}
No config file. Do not attempt to read in a configuration file. This will
override the {\tt -f} option.

\manItem{{\tt -f <filename>} --}
Configuration file. Read in the configuration file specified by {\tt
<filename>} instead of the default {\tt .rciparams} file. 

\manItem{{\tt -pendant} --}
Create a simulated teach pendant for the robots which are being
simulated. See the section TEACH PENDANT, below.

\manSubSection{Robot Arguments}

{\tt robotsim} also accepts the following arguments describing the
robots it is simulating. Each of these arguments applies to the robot most
recently specified on the command line.

\manItem{{\tt <robotName>} --}
Name of a robot to be simulated. The program will simulate the 
specified robot. The ``name'' must be a robot known to RCI, with the
appropriate configuration files set up in {\filefont \$RCCL/conf}.

\manItem{{\tt -nc} --}
Start the program with the robot uncalibrated. This option is the closest
you can get to simulating ``turning the controller on''; it is then
necessary to ``calibrate'' the robot before running applications.

\manItem{{\tt -p <position>} --}
Gives the name of a position which the simulator will use as
the robot's initial position. 
The {\tt <positionName>} should be the name of one of the
robot positions defined in the file {\filefont conf/<robotName>.pos}.

\manItem{{\tt -jlf <jointLogFile>} --}
Maintains a log file containing the joint coordinate values for each control
cycle. Each line in the file contains a number indicating the cycle
number for the current control session, followed by the joint values (see
the description of the keyboard command {\tt open joint log}, below).
The file will
remain open until it is closed with the keyboard command
{\tt close joint log}.

\manItem{{\tt -clf <CartesianLogFile>} --}
Maintains a log file containing the Cartesian coordinate values for each
control cycle. Each line in the file contains a number indicating the cycle
number for the current control session, followed by a string indicating
the robot configuration, three numbers describing the translational
component of the T6 transform, and four numbers forming a unit quaternion
representing the rotational component of the T6 transform.
(see the description of the keyboard command {\tt open cartesian log}, 
below). The file will remain open until it is closed with the 
keyboard command {\tt close cartesian log}.

\manSection{CONFIGURATION FILE}

Conceptually, the configuration file contains a set of declarative statements
that control what the simulator displays and how it displays them. Most of the
information in the configuration file is related to the graphics
simulation. 

\manSubSection{Structure}

The basic structural element of the configuration file is the {\it set},
which is a list of elements enclosed within angle brackets ({\tt < >}).
Elements can be numbers (integer or floating point), strings, or
other sets. Integers are given by sequences of digits, which can be
prefixed with {\tt 0x} to indicate hex, {\tt 0o} or {\tt 0} to indicate
octal, or {\tt 0b} to indicate binary. Floats are denoted by either
a decimal point or an exponent {\tt e}. Strings are enclosed with quotes ({\tt
""}).  There is generally no need to separate set entries with anything 
except white space, although commas can be used if desired; this is
sometimes necessary to disambiguate set elements that involve expressions.

A set element can also be {\it tagged} with a name. The usual format for this
is 

\cverbatim
        tagName=element @endcverbatim
\noindent
where {\tt tagName} is composed of alphanumeric or underscore characters
and does not begin with a digit. Tag names are case sensitive.
White space may be placed around the
{\tt =}, if desired. Another form of tag uses a colon ({\tt :}), as in

\cverbatim
        tagName:element @endcverbatim
\noindent
In the simulator config file, colon tagging is only used for the top level of
declarations. 

Comments can be introduced with the {\tt \#} character: all characters 
between {\tt \#} and the end of the current line are ignored. A subset of the
C-preprocessor directives is also implemented: {\tt \#if 0}, {\tt \#if 1},
{\tt \#else}, and {\tt \#endif}. As with the C-preprocessor, these must be
placed at the beginning of line. They can be used to comment out unwanted
declarations, as in

\cverbatim
        #if 0
          ... stuff to ignore ...
        #endif @endcverbatim
\noindent
or to introduce different declarations, as in

\cverbatim
        #if 1
          ... use these declarations ...
        #else
          ... instead of these ...
        #endif @endcverbatim

Variables can be declared using the notation {\tt :=}, as in

\cverbatim
        foo := 12 @endcverbatim
\noindent
Legal variable types are floating point numbers, integers, strings, and
sets. If declared within a set, then the variable definition is local to that
set. Variable names have the same composition requirements as element tags:
they must consist of alphanumeric or underscore characters, are case 
sensitive, and cannot begin with a digit. Once declared, a variable can be
used in place of a literal.

Simple arithmetic expressions are supported, with the operators
{\tt +}, {\tt -}, {\tt *}, and {\tt /}, and parentheses ({\tt ()}).
Expressions 
are not currently defined for sets or strings. If all of the components
of an expression are integer, then the expression evaluates to an
integer; otherwise, the expression evaluates to a float.
Expressions can be used in any place that would normally accept a
number, including sets or variable definitions. The config file parser
is greedy, in that it will attempt to create as long an expression as
possible. For instance, in the construction

\cverbatim
        < 1  -1 2 2> @endcverbatim
\noindent
the first two tokens would be combined into an expression $(1-1)$, so that
the parsed result would be the set {\tt <0, 2, 2>}. If necessary, these
situations can be disambiguated using commas, so that

\cverbatim
        < 1, -1 2 2> @endcverbatim
\noindent
would parse to {\tt <1, -1, 2, 2>}.

The character {\tt ?} can be used to indicate an empty set element. In some
instances, this can be used to indicate a default value. 

A set consisting exclusively of numbers (float or integer), and possibly
the empty element {\tt ?}, is considered to be a {\it vector}.

\manSubSection{Specifying Colors}

Some of the options described below will involve setting color values. In
general, these can be specified as an integer where the red intensity is given
by the first 8 bits, the green intensity is given by the second 8 bits, and
the blue intensity is given by the third 8 bits. So for example,
{\tt 0xff0000} would describe a full intensity blue, {\tt 0xffffff} would
describe white, {\tt 0x808080} would describe a medium gray, and {\tt 0x0}
would describe black. When applicable to black and white displays, a color
description will often be interpreted such that zero indicates black and a
non-zero value indicates white.

\manSubSection{Specifying Locations}

Some of the options described below require the setting of spatial locations.
In general, these are specified by a vector of numbers. The first part
of this vector consists of up to six untagged
numbers, where the first three numbers represent the $x$, $y$, and $z$ values
of a translation vector, and the next three numbers represent 
successive rotations 
about the $z$, $y$, and $x$ axes. Each rotation is given in degrees and is
applied relative to the previous coordinate frame. If the
vector has a length of less than six, or if any of the elements are specified
by an empty character ({\tt ?}), then the missing values default to zero.

After the untagged numbers, it is possible to add additional numbers
tagged with {\tt tx=}, {\tt ty=}, {\tt tz=}, {\tt rx=}, {\tt ry=}, or 
{\tt rz=}. These taggings denote a translation or rotation operation
about the $x$, $y$, or $z$ axes, respectively. Rotations are given 
in degrees. Each operation is applied relative to the previous frame.
So for instance,

\cverbatim
        < 10 20 rx=10 ry=60 tz=6 rx=90> @endcverbatim
\noindent
describes a location formed by an initial translation along the vector 
$(10,20,0)$, followed by a rotation of $10$ degrees about the $x$ axis, a
rotation of $60$ degrees about the new $y$ axis, a translation of $6$ along
the new $z$ axis, and finally a rotation of $90$ degrees about the new $x$
axis. There is no set limit to the number of operations that may be
specified. 

\manSubSection{Location Functions}

Location functions provide a way to allow an object to move around
while the simulator is running. Basically, a location function is 
specified by a string that identifies a function compiled into the 
program. The function is called with the following arguments:

\cverbatim
        locfxn (trsf, com, arg, ptr)
        TRSF *trsf;
        int com, arg;
        void *ptr;
        {
           ...
        } @endcverbatim
\noindent
{\tt trsf} is a pointer to a transform data structure for which the
function should provide values. {\tt com}, {\tt arg}, and {\tt ptr} are
arguments that are normally prespecified inside the program
binary, although it is possible to specify the {\tt arg} parameter
from within the config file.

If an object has a location function defined, then the transform
${\bf T}$ set by the location function defines the location of the object
with respect to (a) simulator world coordinates, 
if the object is defined at
the top level, or (b) the coordinate frame of the parent object,
if the object is an element of a compound object (compound
objects are discussed below). If an explicit location ${\bf L}$ has also been
specified for the object (using the {\tt loc} parameter in the config 
file), then this is premultiplied by the final value of the functional
transform ${\bf T}$, 
so that the total position of the object is given by ${\bf T} {\bf L}$.

User-defined location functions can be added to {\tt robotsim} by
declaring them in the table {\tt locFxnTable}, defined in the file 
{\filefont robotsim/simFxns.c}, along with
appropriate values for the {\tt com}, {\tt arg}, and {\tt ptr}
arguments. The simulator program must then be rebuilt with the new table
and the new functions.

There are several built-in location functions that can be useful
for returning dynamic locations associated with the robots.
Each built-in function is prefixed with the name of a 
robot ({\tt <robot>}), followed
by a dot ({\tt .}), and finally followed by a suffix that explains what the
function does. The following location functions are defined:

\manItem{\tt <robot>.T<n>}
Returns the current value of the transform for link $n$ of the robot {\tt
<robot>}. For instance, the function specified by {\tt frank.T5} would return
the link 5 transform of the robot {\tt frank}.

\manItem{{\tt <robot>.HandTX}, {\tt <robot>.HandTY}, {\tt <robot>.HandTZ}}
Defines a transform in which the translation component along the
$x$, $y$, or $z$ axis 
is set to the value of the robot's hand. Other components of
the transform are set to the identity. For instance, {\tt Zeus.HandTY}
specifies a function that sets the $y$ translation component to 
the hand value for the robot Zeus. If the {\tt arg} parameter is
specified, this is used to scale the final value.

\manItem{{\tt <robot>.HandRX}, {\tt <robot>.HandRY}, {\tt <robot>.HandRZ}}
Defines a transform in which the rotation component about the
$x$, $y$, or $z$ axis is set to the value of the robot's 
hand (in degrees). Other components of
the transform are set to the identity. 
If the {\tt arg} parameter is
specified, this is used to scale the final value.

The built-in location functions can be used to specify
a compound object as the end effector for a particular robot.
The base location of the compound object can be specified
with the function {\tt <robot>.T6}, and appropriate sub-object
components can be tied to the hand position functions.

Within the config file, a location function is specified by a parameter set
having up to two elements. The first element is a string describing the name
of the function; this must match either one of the built-in functions
or one of the user-defined functions in {\tt locFxnTable}.
The second argument is an optional integer which specifies the value of the
{\tt arg} parameter. 

As an example, a specification for a location function
{\tt foo}, with an argument value of {\tt 1200}, would look like:

\cverbatim
        < "foo", 1200 > @endcverbatim
\noindent
(remember that the commas are optional). As another example, a
specification for the built-in function {\tt HandTX}, applied with respect to
a robot called {\tt Zeus} and with an argument value of 10, would
look like:
\cverbatim
        < "Zeus.HandTX", 10 > @endcverbatim

\manSection{TOP LEVEL CONFIG DECLARATIONS}

The configuration file is itself a set, which accepts the following
tagged elements:

\manItem{{\tt windowPos = < x y w h >}}
A set of four integers describing, in pixels, the initial placement 
of the graphics window on the screen. {\tt x} and {\tt y} give
the coordinates of the lower left corner or the window, and {\tt w}
and {\tt h} give its width and height. Not all graphics implementations
respond to this completely.

\manItem{{\tt viewWindow = < l r b t n f >}}
A set of floats describing the graphics ``viewing pyramid'', in eye
coordinates. Eye coordinates are defined so that, as the viewer
looks at the screen, the $x$ axis points to the right, the $y$ axis
points up, and the $z$ axis points toward the viewer. The viewing
pyramid is therefore located entirely in the half space corresponding 
to $z < 0$. The
{\tt l}, {\tt r}, {\tt b}, and {\tt t} describe the left, right, bottom, and
top coordinates of the near face of the pyramid (the one closest 
to the viewer). {\tt n} and {\tt f} describe the distances (along the $-z$
axis) of the near and far faces.

\manItem{{\tt ortho = on}}
An integer which if set to a true (non-zero) value enables orthographic
instead of perspective projection.

\manItem {{\tt viewTrans = < locationSpec > }}
A location specification describing the transformation from eye coordinates
to the simulator world coordinates with respect to which the locations of
all objects and robots are defined (see the section ``Specifying Locations'').

\manItem {{\tt bgColor = colorSpec}}
An integer which specifies the color of the background
(see the section ``Specifying Colors''). For black and white displays,
setting this to a non-zero value creates a reverse-video effect.

\manItem {{\tt fgColor = colorSpec}}
An integer which specifies the color of the foreground
(see the section ``Specifying Colors''). This hasn't been
completely implemented yet.

\manItem {{\tt ROBOT : < robot params >}}
A set of parameters that specifies characteristics for a
particular robot. See the section ROBOT DECLARATIONS.

\manItem {{\tt OBJECT : < object params >}}
A set of parameters that define an object. An object is a solid shape
that can be added to the graphics display.
See the section OBJECT DECLARATIONS.

\manItem {{\tt MATERIAL : < material params >}}
A set of parameters that define a material. A material is a set of
reflecting and light emitting properties that are used to define the
shaded illumination behaviour of an object.

\manItem {{\tt LIGHT : < light params >}}
A set of parameters that define a light source. Light sources 
provide the illumination for the object materials. If no light sources 
are specified, some default sources will be set up.

\manSection {ROBOT DECLARATIONS}

Each parameter set {\tt ROBOT:} must have as its first parameter
an untagged string that gives the name of the robot. This must be
a robot which is defined in the RCI database; i.e., it must have
{\tt .jls} and {\tt .kyn} files defined in {\filefont \$RCCL/conf}, etc. 
The parameter set
can then include the following tagged parameters, in any order:

\manItem{{\tt loc = < locationSpec > }}
Defines the location of the robot with respect to the simulator world
frame. See the section ``Specifying Locations''.

\manItem{{\tt locfxn = < locationFxnSpec > }}
Defines a location function that modifies the location of
the robot. See the section ``Location Functions''.

\manItem{{\tt drawEndEffector = on}}
An integer which if set true (non-zero) indicates that the robot
display code should draw an end effector for the robot. This will
usually be some standard sort of gripper, and may not be too 
interesting. If you want to define your own gripper object, 
then you should specify this variable as false.
The default value for this parameter is true.

\manItem{{\tt angles = < angles >}}
A vector of floats describing the initial joint angles for the
manipulator. The default values for these angles are taken
from the {\tt parkAngles} field of the manipulator {\tt JLS}
structure. If the vector is shorter than the number of robot angles,
or if any of the elements are specified as {\tt ?}, then the default values
are used for the unspecified angles.

\manSection {OBJECT DECLARATIONS}

Each parameter set {\tt OBJECT:} must have as its first parameter
an untagged string that identifies the type of the object. Then depending
on the object type, different tagged parameters may be used to
define the object geometry.

Planar objects are defined with respect to the $x-y$ plane, and
prismatic objects are defined so that their bottom face lies in the
$x-y$ plane. Objects can be relocated from their defining frame by
including a {\tt loc} specification in their definition.

The different object types and their parameters currently include:

\manSubSection {"box"}

Defines a rectangular box. 

\manItem{{\tt dimen = < w h l>}}
A vector of three floats giving the dimensions of the box. {\tt w}, 
{\tt h}, and {\tt l} give the dimensions 
along the $x$, $y$, and $z$ axes, respectively. This parameter must
be specified.

\manSubSection {"disc"}

Defines a circular disc.

\manItem {{\tt rad = float}}
The radius of the disc. This parameter must be specified.

\manItem {{\tt depth = float}}
The height of the disc (along the $z$ axis). This parameter must be specified.

\manItem {{\tt nsides = int}}
The number of polygonal faces used to form the curved part of
the disc. This parameter is optional.

\manSubSection {"cone"}

Defines a cone; this is basically a disc where the radii of the
top and bottom faces differ.

\manItem {{\tt rtop = float}}
The radius of the top face of the cone. This parameter must be specified.

\manItem {{\tt rbot = float}}
The radius of the bottom face of the cone. This parameter must be specified.

\manItem {{\tt depth = float}}
The height of the cone (along the $z$ axis). This parameter must be specified.

\manItem {{\tt nsides = int}}
The number of polygonal faces used to form the curved part of
the cone. This parameter is optional.

\manSubSection {"sphere"}

Defines a sphere, centered at the origin.

\manItem {{\tt rad = float}}
The radius of the sphere. This parameter must be specified.

\manSubSection {"polygon"}

Defines a convex planar polygon. It is possible to define either
a regular polygon, using the parameters {\tt size} and {\tt nsides}, or
an arbitrary polygon, using the parameter {\tt face}.

\manItem {{\tt size = float}}
The length of one of the sides of a regular polygon. This
parameter must be specified when defining a regular polygon.

\manItem {{\tt nsides = int}}
The number of sides of a regular polygon. This
parameter must be specified when defining a regular polygon.

\manItem {{\tt face = < x1 y1 x2 y2 ... > }}
A vector of floats listing the $x$ and $y$ coordinates of the vertices of an
arbitrary polygon, in counter-clockwise order. The number of elements in this
vector must be 
even (since each vertex has two components) and must be greater than or equal
to six (corresponding to a three sided polygon).
This parameter must be specified if an arbitrary polygon is being defined.

\manSubSection {"lines"}

Defines a set of line segments lying in the $x-y$ plane.

\manItem {{\tt vtxs = < < x1 y1 x2 y2 > < x1 y1 x2 y2 > ... >}}
A set of four element vectors, where each vector gives
the $x$ and $y$ coordinates of the beginning and end points 
of a line segment. There is no set limit to the number of line
segments that can be specified. This parameter must be specified.

\manSubSection {"prism"}

Defines a general prism. This is an convex object with two parallel polygonal
faces, each with the same number of sides. Each face is parallel to
the $x-y$ plane, with the bottom face lying on the plane.

\manItem {{\tt depth = float}}
The depth of the prism, or the distance between the two faces.
This can also be interpreted as the height of the prism along the
$z$ axis. This parameter must be specified.

\manItem {{\tt botface = < x1 y1 x2 y2 ... > }}
A vector of floats defining the $x$ and $y$ coordinates of the 
bottom face polygon, in counter-clockwise order as seen from above
(i.e., $z > 0$).
The number of elements in this vector must be
even (since each vertex has two components) and must be greater 
than or equal to six (corresponding to a three sided polygon).
This parameter must be specified.

\manItem {{\tt topface = < x1 y1 x2 y2 ... > }}
A vector of floats defining the $x$ and $y$ coordinates of the 
top face polygon, in counter-clockwise order as seen from above
(i.e., $z > 0$). 
This parameter is optional. If
not specified, then the top 
face polygon is assumed to be identical to the bottom face polygon. If a top
face polygon is specified, then it must have the same number of vertices as
the bottom polygon.

\manItem {{\tt smooth = string}}
A string of digits, either {\tt "0"} or {\tt "1"}, with each digit
corresponding to a vertex in the top or bottom polygons (recall
that the top and bottom polygons must have the same number of vertices).
If the digit is {\tt "1"}, then the edge connecting the top polygon vertex
with the corresponding bottom polygon vertex is assumed to be ``smooth'';
i.e., part of a smooth surface. In the case of a wire frame display, the edge
will not be 
drawn. In the case of a shaded illumination display, continuous shading will
be applied across the edge. This parameter is optional. If it is omitted, then
all edges in the prism are assumed {\bf not} to be smooth.

\manSubSection {"compound"}

In addition to standard objects, it is possible to recursively define compound
objects. A compound object is given by a set of strings or parameter sets.
A string should give the name of a previously defined object (names 
can be given to all objects; see the section on generic parameters, below).
A parameter set should be one which defines an object, although the
top level {\tt OBJECT:} tag should be omitted.

\manSubSection {Generic parameters}

The following parameters may be specified for all objects:

\manItem{{\tt loc = < locationSpec > }}
Defines the location of the object with respect to its base frame
(see the section ``Specifying Locations''). For an object defined at the 
top level, the base frame is the simulator world coordinate frame. For an
object 
which is an element of a compound object, the base frame is the 
frame of the parent object.

\manItem{{\tt locfxn = < locationFxnSpec > }}
Defines a location function that modifies the location of
the object. See the section ``Location Functions''.

\manItem{{\tt name = string}}
Defines a name for the object. This name may be used to reference the
object later when a compound object is defined.

\manItem{{\tt mat = materialSpec}}
Defines a material for the object, which controls the object's illumination
characteristics. Material definitions are effectively ignored in the case of
a wire frame display. The material specification may be either an actual
parameter set defining a material (see MATERIAL DECLARATIONS), or it may be
the name of a material already defined. If a material is not defined, then a
top level object gets a default material, while a member of a compound object
inherits the material of its parent.

\manSection{MATERIAL DECLARATIONS}

The parameters which are used to define a material are adopted from the
conventions used by the Silicon Graphics ``GL'' library. A material may be
defined with a parameter set containing one or more of the following elements.
If not specified, each of these elements has a default value of $0$.

\manItem{{\tt diffuse = colorSpec}}
An integer defining the diffuse lighting characteristics of the material.
Light of this color is reflected depending on the angle of the object
with respect to the light sources.

\manItem{{\tt ambient = colorSpec}}
An integer defining the ambient lighting characteristics of the material.
Light of this color is reflected depending on the amount of ambient, or
background, light created by the light sources.

\manItem{{\tt emission = colorSpec}}
An integer defining the emission characteristics of the material. The material
will ``glow'' with this color, independent of the surrounding light sources.

\manItem{{\tt specular = colorSpec}}
An integer defining the color of the specular component of the material. Light
will be reflected depending on the relationship between the object faces,
the light source, and the viewer. This parameter works in conjunction with
the shininess parameter.

\manItem{{\tt shine = float}}
A floating point number from 0 to 1 that defines the actual shininess of the
material. If set to 0, there will be no specular reflection.

\manItem{{\tt alpha = float}}
Used in applications involving transparent objects. Not implemented.

\manSection{LIGHT DECLARATIONS}

The first parameter in a light declaration is a vector of three
floating point numbers, which gives the $x$, $y$, and $z$ 
components of a vector defining the direction of the light source with respect
to the simulator world coordinate frame. This parameter is required. The other
parameters are optional, and are set to $0$ if not specified:

\manItem{{\tt color = colorSpec}}
An integer defining the color of the directional
light associated with the source (see the section ``Specifying Colors'').

\manItem{{\tt ambient = color}}
An integer defining the color of the ambient light associated with the
source.

\manSection{KEYBOARD OPERATION}

In interactive keyboard mode, program
commands are entered using the
{\it C-tree matcher}, an automatic command completion utility.
Full documentation on the C-tree matcher is given in the file
{\filefont doc/CtreeMatch.doc}.

Some commands
apply to the entire simulator program, while other commands apply only to a
specific robot, which is selected using the command {\tt robot}.

\manSubSection{Simulator-Wide Commands}

\manItem{\tt quit}
Quit the program.

\manItem{\tt autocycling (on | off)}
Enable or disable autocycling. The simulator emulates real time
using a fixed sample rate, to which all robot interactions are
slaved. When autocycling is enabled (which is true by default), 
then one time cycle automatically follows another. If autocycling is
disabled, then time cycles can be single-stepped using the
{\tt step} command. This is useful for interactive debugging.

\manItem{\tt step <num>}
This command enables the execution of {\tt <num>} time cycles
when autocycling is disabled.

\manItem{\tt show sim}
Prints out information about the general state of the simulator,
such as the current cycle number.

\manItem{\tt show graphics}
If graphics is enabled, then this prints out information about the 
graphics state, including the current parameters for the
view transform and viewing pyramid.

\manItem{\tt postscript ( eps | idraw ) <width> <height> <file>}
If wire frame graphics are being run, then this command executes
full hidden line removal for the current image and writes a
PostScript description of it to {\tt <file>}. The parameters
{\tt <width>} and {\tt <height>} are floats which describe, in inches,
the final size of the output PostScript image. With the {\tt eps}
option, encapsulated PostScript is generated. With the {\tt idraw}
option, a set of PostScript macros are generated that can be read
by the X11 drawing program {\tt idraw}.

\manItem{\tt robot <name>}
Selects the robot to which subsequent robot-specific commands should
be applied. It is also possible to select this robot from
the graphic teach pendant interface (see {\tt TEACH PENDANT}, below).

\manSubSection{Robot Specific Commands}

Most of the robot specific commands are intended to allow the
user to set values associated with the various sensor I/O options
supported by the simulated robot controller. They can be helpful
in debugging RCCL/RCI applications that depend on sensor input,
although they can also be rather awkward to use. Some of this
stuff should be replaced with graphical/mouse interaction. 
The teach pendant simulation is particularly ridiculous.

\manItem{\tt set tool}
Sets the TOOL frame which is used in determining where applied forces and
displacements occur. The default TOOL frame is the identity matrix.

\manItem{\tt set force}
Sets a bias force to be applied at the TOOL frame. This force will
affect both joint torques and the Cartesian forces returned to RCI.
It is possible to set the value along a specific axis, or
all six axes ({\tt all}).

\manItem{\tt set displacement}
Sets a Cartesian displacement bias in the TOOL frame. Robot setpoints will be
offset by this amount in the TOOL frame. It is possible to set the 
value along a specific axis, or all six axes ({\tt all}).

\manItem{\tt pioIn <channel> <value>}
Sets the values of the parallel input port {\tt channel} to {\tt value}, where
{\tt value} is given in hex.

\manItem{\tt ADC <channel> <value>}
Sets the value of an ADC channel to the indicated signed value.

\manItem{\tt joystick}
Sets the value associated with input from a 6 DOF joystick. It is possible to
set either an individual joystick axis, or all axes ({\tt all}).

\manItem{\tt clear tool}
Sets the TOOL frame to the identity matrix.

\manItem{\tt clear force}
Clears any applied force in the TOOL frame.

\manItem{\tt clear displacement}
Clears any displacement bias in the TOOL frame.

\manItem{\tt pendant reset}
Resets the state of the teach pendant input (releases all the buttons).

\manItem{\tt pendant release}
Releases a button being pushed on the teach pendant.

\manItem{\tt pendant button <button>}
Simulates the pushing of any of a large number of teach pendant buttons.
Once this command is entered, the indicated ``button'' will be pushed until
the {\tt pendant release} command is entered.

\manItem{\tt show tool}
Prints the default robot TOOL transform.

\manItem{\tt show force}
Prints the force being applied in the TOOL frame.

\manItem{\tt show displacement}
Prints the displacement bias in the TOOL frame.

\manItem{\tt show pendant}
Prints a bit map of the teach pendant showing what buttons have been pushed.
This bit map is equivalent to the map returned to the {\tt pendant} field
of the RCI {\tt HOW} structure.

\manItem{\tt show pio} 
Prints the bit settings of the input and output channels of the parallel
ports.

\manItem{\tt show ADC/DAC}
Prints the values of the ADC and DAC channels.

\manItem{\tt show options}
Prints the sensor I/O options available on the simulator.

\manItem{\tt show controller}
Prints states and control modes associated with the simulated ``controller''.

\manItem{\tt show robot}
Displays all robot joint variables, including torques, angles, and hand
position.

\manItem{\tt open cartesian log <filename>}
Opens a log file in which the Cartesian (T6) position of the robot will be
printed for all subsequent control cycles until the file is either closed
or the program exits. 
Any Cartesian log file which was previously open is closed.
Each T6 position will be printed in the
file, one line per entry, according to the following format:

\cverbatim
                    cycleNum conf px py pz qc qs1 qs2 qs3
@endcverbatim
\manItem{}
{\tt cycleNum} is the cycle number in the current control session. {\tt conf}
is a string describing the robot configuration. {\tt px}, {\tt py}, and {\tt
pz} are the T6 translational values. The {\tt q} numbers are the 4 values of a
unit quaternion describing the rotational component of T6. They are
obtained from T6 using the function {\tt trsfToQtrn}.

\manItem{\tt open joint log <filename>}
Opens a log file in which the joint angles of the robot will be
printed for all subsequent control cycles until the file is either closed 
or the program exits.
Any joint log file which was previously open is closed.
The joint angles are printed in the
file, one line per entry, according to the following format:

\cverbatim
                    cycleNum j1 j2 j3 j4 j5 j6
@endcverbatim
\manItem{}
{\tt cycleNum} is the cycle number in the current control session, and
{\tt j1} through {\tt j6} are the joint angles.

\manItem{close cartesian log}
Closes the Cartesian log file.

\manItem{close joint log}
Closes the joint log file.

\manSection{TEACH PENDANT}

If {\tt robotsim} is given the command line option
{\tt -pendant} and is run with a graphics display, then a 
simple simulated teach pendant will be created within the graphic
display control panel at the right edge of the window.

Hitting a button on this ``teach pendant'' is done by moving the
mouse cursor over the desired button and pressing the left mouse
button. 

If more than one robot is being simulated, the teach pendant
must be shared between them. The name of the robot which
currently ``owns'' the teach pendant is displayed on an illuminated
button above the pendant. Clicking this button will
cause ownership of the pendant to pass from one robot to the next.
The robot that owns the pendant is the same robot
selected for interative keyboard commands, so pendant ownership
can also be changed using the keyboard command {\tt robot}.

The teach pendant layout is patterned roughly after that used on Unimation
robot controllers. It should be noted that hitting a teach pendant button
will not cause a robot to move per-se, but will simply send back information
to the RCCL/RCI application program describing which button(s) are pressed.
(This information appears in the {\tt pendantInput} field of the robot's {\tt
HOW} structure.) It is then up to the application to move the robot.
Moving the robot under teach pendant control thus requires
running an appropriate RCCL/RCI program, such as {\tt teachdemo}. 
Delays may be noticable in some teach pendant interactions,
due to the nature of the connection between the teach pendant and the
application program.

It might be reasonable to build a teach pendant trajectory generator
directly into the simulator program, so that the arm could be moved
about locally without requiring an attached RCCL/RCI application.

\manSection{BUGS}

The full hidden line removal algorithm used by the wire frame graphics
does not work if any of the defined objects intersect.
However, full hidden line removal is generally used only when producing
PostScript output.

\manEnd
\end
