NAME
make_object - make render object from file description
PROTOTYPE
unitptr make_object( char *fileid, unitptr host)
ARGUMENTS
- char *fileid
- name of object definition file
- unitptr host
- host unit for newly created instance
RETURN VALUE:
- unitptr u
- ptr to created instance
INTERFACE OF CREATED UNIT:
- X_in[nr]:
- joint angle of link with id=nr of
created object
RETURN VALUE:
- unitptr u:
- pointer to newly created unit
DESCRIPTION:
Reads a data file with filename fileid that specifies a
multi-link robot and creates a unit from this specification,
so that execution of the unit will render the robot. The
unit has a single input field with one pin for each joint
angle of the robot. The data file is a text file and must
have the following format: The first entry is the number nr
of robot links. This entry must be followed by nr entries,
each of which describes the geometry of one of the nr links
and consists of the following items:
str id (id number (0..MAXLINKS-1) of this link)
str rotz, roty, rotx (rotation relative to parent link)
str tx, ty, tz (translation relative to parent link)
str th0 (joint angle, if input at pin is zero)
str nc (number of child links)
str id1, id2, ... idnc (identifiers of all child links)
str np (# of parts making up shape of link)
str t1, argc, arg1, arg2 ... arg_a1 (part type, # of parameters
and parameters for first part of link shape)
...
str t_np, argc, arg1, .... arg_a_np (part type, # of parameters
and parameters for last part of link shape)
In each line, str is an arbitrary comment string (single
token, not interrupted by white space) which MUST be
present, followed by a number of parameters. The text in
brackets MUST NOT be present in the data file, it is only
for commenting purposes here.
Each link is identified by a number id (range 0..MAXLINKS-1)
and can be composed of a number np of visible parts. For
these parts, several different construction elements are
available that can be selected with the token ti, i=1..np,
that follows str. Each part definition consists of a parameter
list argc,arg1, ..argn, where the first element argc
specifies the nr of the remaining parameters arg1..argn that
will follow.
Several primitives ("part types") are available as construction
elements (these include cylinders and prisms as special
cases). In addition to the visible construction elements,
there exist a number of invisible, "virtual" construction
elements. A virtual construction element does not contribute
a geometrical part of the shape; instead, it changes drawing
attributes or makes information about positions of points or
coordinate frames accessible by causing the insertion of an
additional output field. A brief description of the avail-
able construction elements follows:
Available construction elements:
Currently, all tokens ti that select a construction element
are single letters. The following choices are provided
(x0,x1... denote the parameters expected for each choice):
- 0:
- (argc=1 parameter required) This will
render a right handed, cartesian coordi-
nate frame that coincides with the
current coordinate system. The z-axis
is indicated by its longer arrow head.
The single parameter arg1 specifies the
length of each coordinate axis. One use
of this facility is to visualize how the
various coordinate systems are oriented
in the object.
- 1,2,3:
- (argc=9 parameters required) Part types
1,2 and 3 correspond to the parts that
are generated by the routines
make_link1..make_link3. Each of these
parts has 9 parameters that must follow
the specifier 1,2,3. The meaning of
these parameters is explained in the
documentation of these routines.
- A:
- (argc=5 parameters required) Render an
arrow with vector components of
arg1,arg2,arg3, width arg4 of arrow
shaft (in units of its length) and
length arg5 of arrow tip (again in units
of arrow length). This uses the
make_arrow unit, and more details on the
parameters can be found there.
- C:
- (argc=3 parameters required) Render a
cone of radii arg1 and arg2 and height
arg3. Uses the make_cone unit, i.e.,
origin of cone is set at half height of
its axis.
- F:
- (argc=3 parameters required) Render a
cubical 3d-coord frame centered at the
current point. arg1,arg2,arg3 specify nr
of subintervals per tick mark, a value
at which a tick mark is placed, and a
tick mark spacing. For details, see the
frame3d unit.
- P:
- (argc=5 parameters required) Render a
pyramid. Parameters arg1,arg2 specify
width and height of the bottom rectangle,
arg3,arg4 specify width and height
of the top rectangle, and arg5 specifies
the height of the pyramid. Uses the
make_pyramid unit, i.e. origin of
pyramid is taken to be center of its
bottom face.
- m:
- (argc=1-9 parameters) Defines a choice
for a new "material": switches to a new
material. All subsequently processed
parts will be rendered using this new
material, unless further parts of type c
are encountered. If the number numarg of
arguments is specified to be one, the
single argument (i.e. the third entry in
the line) must be in the range
0..MAXMATERIALS-1 and selects one of the
predefined materials. If the number of
arguments is specified to be in the
range 2..9, the specified number numarg
of arguments is read and used to specify
values for the first numarg of the
following material properties: red_d,
green_d, blue_d, red_a, green_a, blue_a,
red_s, green_s, blue_s) Here, d,a,s
stand for diffuse, ambient and specular
reflectivity and a value of 1.0 indi-
cates maximal intensity of the
corresponding reflectivity.
- p:
- (argc=3 parameters required) Marks a
point on an object and compute
coordinates. The point is selected by
specifying three arguments arg1,arg2,arg3
(i.e. the whole entry must have the form
comment: p 3 arg1 arg2 arg3),
where arg1,arg2,arg3 denote the
(x,y,z)-location of the point with
respect to the current object coordinate
frame of the link (this coordinate system
is termed S'' and explained in more
detail below). For each point marked in
this way (i.e. for each occurrence of a
part of type p in the definition file),
the created unit will have an output
field of 3 pins. The values of these
pins will be the xyz-coordinates of the
corresponding marked point, but specified
in world coordinates. This provides
an easy way to track the location of
selected points on the object.
- f:
- [NOT IMPLEMENTED] "Frame": The whole
entry must have the form comment: f 0)
and causes the creation of a packed (for
f) or unpacked (for F) output field of
16 pins at which the current viewing
matrix is available (in row-wise order).
- v:
- [NOT IMPLEMENTED] "Vector": as p, but
the subsequent arg1,arg2,arg3 are
transformed as a vector, i.e. not
subjected to any translations. Again, the
capital letter version provides a packed
field.
Coordinate Systems:
Each link has its own coordinate system relative to which
the positions and orientations of all its parts are defined.
Links may be joined in a tree-like fashion, i.e. more than
one "child link" may be attached to each link.
rotx, roty, rotz , tx, ty, tz define the orientation and the
position of a link relative to the coordinate origin of its parent
link. For an explanation of these parameters see below.
The parent link of the first link (i.e. the link with id=0)
is the world, with z-axis pointing upward. The joint axis
between two links is always the z-axis of the parent link.
If a different axis is desired, on can insert a partless
(i.e. np=0) "auxiliary link" oriented such that its z-axis
coincides with the desired joint axis (note that this will
introduce an additional input pin for the control of the
"auxiliary joint" between the original parent link and the
auxiliary link)
The coordinate system S'' of the link whose orientation and
position is defined by rotx..tz is obtained from the coordinate
system of its parent link by means of the following operations:
1. A rotation R1 about the positive z-axis of the parent
link coordinate system through an angle of rotz/10 degrees.
The resulting coordinate system is denoted by S'.
2. A rotation R2 about the positive y'-axis of S' by roty/10
degrees. Let us denote the resulting frame by S''.
3. A rotation R3 about the positive x''-axis of S'' by rotx/10
degrees. Let us denote the resulting frame by S'''.
4. A translation of S''' by (tx,ty,tz), where the three
components refer to the axis directions of S"'.
(the use of tenths of degrees for the rotation angle specificiations
in the data file is for compatibility reasons.
Note, however, that the joint angles to be specified at the
pins of the created unit have to be specified in full
degrees).
SEE ALSO:
make_link1, make_link2, make_link3, use_material
EXAMPLE:
A simple example definition file is given here:
#
# object definition file for a simple 2x2x2 cube with
# one marker point at one of its top corners:
#
Nr-of-links: 1
# definition entry for link 0:
Id-Nr: 0
Rotation: 0 0 0
Translation: 0 0 0
JointAngleOri: 0
Child-Links: 0
Nr-of-Parts: 2
cube: P 5 2 2 2 2 2
marker: p 3 1 1 2
# [note that (0,0,0) = center of bottom face]
# end of definition entry for link 0
Note that lines starting with a '#' are treated as comments
and are ignored. A more sophisticated example is provided by
the program hand.c. It uses a data file hand.object that
contains an example of the specification of a four-fingered
hand with 10 links and 10 joints.
FILE
/local/homes/rhaschke/nst7/man/../o.linx86//../foldersrc/nst_solid.c