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

/amnt/loge/users/nistaff02/nistaff/rhaschke/nst7/man/../o.linux//../foldersrc/nst_solid.c