How to add objects into Viz

When adding an object, you will specify its:

• name: all object are referred by names, so later if you want to change its color (using changeColor, for instance, you'll need to remember the object name).
• parent: if object1 is a child of object2, it inherits object2's characteristics such as color, scale, position. Specifying characteristics of object1 will overwrite the parent's (object2's) default. Position and orientation of object1 are treated as relative position from object2. The reseved name world is used as a top-level parent object.
• URL: this field is used to tell Viz what to add. We have added more options to the standard URL. Here are the different options:
• "<URL>": the standard way to load a file by specifying its URL (VRML-1 or IV format).

Example:
"/myaccount/models/myModel.wrl" will load a local file, "http://img.arc.nasa.gov/~nguyen/viz/trov1.iv" will load a file through the web.
• "shape:<primitive>": adds a shape in Viz. Available primitives are: cube, cone, cylinder, sphere.

Example:
"shape:cube" will add a cube (you can later change its scale, if necessary).
• "line:<x1>,<y1>,<z1>,<x2>,<y2>,<z2>": creates a line from Point 1 (x1,y1,z1) to Point 2 (x2,y2,z2).

Example:
"line:0,0,0,1,1,1" creates a line from (0,0,0) to (1,1,1).
• "text2d:<text string>": creates a 2D text string in Viz. The 2D text always remain the same size no matter how far or close you're looking at it. It also always faces the viewpoint. Use it to label things, so that you'll always see the labels.
• "text3d:<text string>": creates a 3D text string in Viz. Unlike the text2d strings, text3d are 3d objects in Viz and you might not be able to look at it, depending on how is your viewpoint.
• "vrml:<VRML string>": allows you to enter the content of a VRML (or IV) file directly here, without having to write into a file and have Viz load it. Warning: the current implementation of Viz limits the URL field to 2048 characters !

Example:
"vrml: Cube {height 1 width 2}" creates a box.
• "billboard:<image filename>": creates a billboard. A billboard is a 2D image textured on a rectangle which is placed in a 3D world. For instance, to build a Stop sign in viz, you would make a pole and add a billboard with an image of STOP on it. Currently Viz only supports RGB images (SGI image format).

Example:
"billboard:myImage.rgb"
This is an image of a landscape. It is textured on a billboard and we showed a red cube to show how it can be placed in 3D.  
• "use:<VRML named node>": uses the designated object as a geometry. Whenever you want to create multiple objects of the same geometry, use this to avoid instantiating the geometry multiple times. This is the equivalent of using DEF and USE in VRML.

Example:
Let's say you want to add a cube. Later on, you want to add another cube centered in (1,0,0), but reuse the same cube you've added before. In VRML you would write your file like this:

DEF myCube Cube {}
[whatever VRML stuff you want to do here...]
Translation { translation 1 0 0 }
DEF myOtherCube USE myCube

In Viz, at run-time, you can take advantage of the object you've added before, therefore you would do:

add('myCube','world','shape:cube',(0,0,0),(0,0,0),1)

And later on:

add('myOtherCube','world','use:myCube',(1,0,0),(0,0,0),1)

Note that the argument of use:, namely <VRML named node>, can be any VRML node that was DEF'ed when loaded into Viz, and not just any named Viz object. For instance:

add('myWeirdShape','world','vrml: Separator { DEF myCube Cube{} Sphere {} } ',(0,0,0),(0,0,0),1)

... will add a Cube and a Sphere. The node Cube has been named myCube.

add('myOtherCube','world','use:myCube',(0,0,0),(0,0,0),1)

... will reuse that Cube.
 

• Position: this is the relative XYZ position to the parent.
• Orientation: this is the orientation relative to the parent parent coordinate frame. The Orientation is defined as an array of 3 floats:

(alphaX, alphaY, alphaZ). Before it is rendered, an object will be rotated first around its X axis of alphaX radians, then around its Y axis of alphaY radians, then around its Z axis of alphaZ radians. So what are the X, Y and Z axes of an object ? They form the world coordinate frame if the object's parent is world. Otherwise, they form the local coordinate frame is the object is a child of another object.
• visible flag: 0 (zero) if the object to be added must be hidden, 1 if it is visible. Why isn't it always 1, since you obviously always want to show the object whenever you create it ? Let's assume you want to add a small Cube. The standard way to do this in Viz is to use the add message, and then the changeScale message. However, the changeScale message might not be processed fast enough, so you would see a cube appearing in Viz which would suddenly become smaller. In order to avoid this effect:
• use add with visible set to 0: this will add a hidden cube
• use changeScale to set the cube to the right dimensions. Or any possible Viz message to change the cube properties.
• use show to make the cube visible.