Reference: 3D models

3D model transform basics

A slew of commands within Vizard's node3d library allow you to change the position, rotation, color, visibility, and scale of the 3D models you've created or imported. Note: if you want to render these transformations as a process instead of an instantaneous change (if you want to show an object moving as opposed to simply popping up elsewhere), go to the section on actions and animation paths. To work directly with the matrix transformations that underlay the position and orientation of an object, check out the section on matrix transforms. To make your objects behave more like they would in the physical world (with collision, friction, etc.), check out the section on Physics.

Positioning an object

Once you've added a 3d object to your world, you'll want to place it in the appropriate position using x, y, and z coordinates. Anytime you set the position of an object, you do so with reference to a coordinate system. Also, the values you provide can either be "absolute" or "relative to the object's current position." Together these parameters make up the transformation mode (see section below).

#Add an object.
object = viz.add('wheelbarrow.ive')
#Move the object to 1 meter above the origin.
object.setPosition( 0 , 1, 0 )
#Move the object 1 meter over from its current position.
object.setPosition( 1, 0, 0 , viz.REL_LOCAL )

Rotating an object

3D objects rotate around the x, y, and z axes. Rotations around the x axis are changes in pitch, rotations around the y axis are changes in yaw, and rotations around the z axis are changes in roll. For more about these terms, check out the section on Understanding Coordinate Systems.  

When you're rotating an object in Vizard, you can do so by providing axis angles, eulers, or quaternions.  When you use axis angles to specify a rotation, you provide the axis of rotation and the number of degrees which you want to rotate about that axis. When you use eulers, you provide yaw, pitch and roll rotations for the object in degrees and the rotations are applied in that order (first yaw, then pitch, then roll). You can also specify rotations using quaternions, which define a rotation using a vector and a value for rotation about that vector.  

Anytime you set the orientation of an object, you do so with reference to a coordinate system. The rotation can either be absolute or relative to the object's current orientation. Together these parameters make up the transformation mode (see section below).

#Rotate an object 90 degrees yaw, and 10 degrees pitch.
object.setEuler( [ 90, 10, 0 ] )
#Rotate an object 90 degrees around the x axis.
object.setAxisAngle( [1, 0, 0 , 90] )
#Rotate an object 90 degrees around the x axis.
object.setQuat([1,0,0,.2])

Transformation modes

When you're specifying the position or orientation of an object, those transformations are relative to either the global coordinate system, the object's own local coordinate system, or the object's parent's coordinate system. Within one of those coordinate systems, you can either change relative to the object's current position and orientation or in absolute terms. Together these options comprise five transformation modes: relative change within the local coordinate system (viz.REL_LOCAL), relative change within the parent coordinate system (viz.REL_PARENT), absolute change within the parent coordinate system (viz.ABS_PARENT), relative change within the global coordinate system (viz.REL_GLOBAL), and absolute change within the global coordinate system (viz.ABS_GLOBAL).  

#Pitch the object upwards 30 degrees.
object.setAxisAngle( [1,0,0,-30], viz.ABS_GLOBAL )
#Move the object 3 meters along its local y axis.
object.setPosition( [0,3,0], viz.REL_LOCAL )

Scaling an object

Objects can be scaled in all three dimensions, so when you scale an object you must specify which dimensions you want to scale it in. So, to change the size uniformly, you would apply the same sized scale to each dimension. To stretch the object in one direction or the other, you would apply scaling differently to the x, y, or z dimension.  A scale value of 1 will scale the object to its original size. Numbers between 0 and 1 will shrink the object, while numbers larger the one will make increase its size.

#Scale the object to half its size in all dimensions.
object.setScale( .5, .5, .5 )

Note: Non-uniform scaling can result in strange rotations.  Avoid performing non-uniform scale operations if you will also be performing complex rotations.  You are better off modifying the object in a professional 3D modeling package.

Changing the center of an object

When you translate, scale or rotate an object, those transformations have different effects depending on where the pivot center of the object is located. Most objects are made so that their pivot centers are literally in the middle of the object or at the bottom center of the object, which makes them easy to move around a world. You can, however, place an object's pivot center anywhere within the object, or even outside of the object. So, if you wanted to rotate a ball around its side instead of its middle, you could place the pivot center on the outer edge of the ball before applying the rotation.

#Add an object.
object = viz.add('wheelbarrow.ive')
#Change the center of the object to 1m away from the origin.
object.center( 1, 0, 0 )
#Spin the object around the new center.
object.addAction( vizact.spin(0,1,0,90) )

Hierarchical relationships and linking

3D geometry nodes can have parent/child type hierarchical relationships. In these relationships, the child object inherits the transforms of the parent. You also have the option of applying transforms to the child within the parent's coordinate system.  So, for example, if you want to move a duck around in a wheelbarrow, make the duck a child of the wheelbarrow.

#Add a parent.
parent = viz.add( 'wheelbarrow.ive' )
#Add a child to that parent.
child = parent.add( 'duck.wrl' )
#Set the position of the child.
child.setPosition( 0,.35, -.05, viz.ABS_PARENT )
#Spin the parent around in a circle.
parent.center(1,0,0)
parent.addAction(vizact.spin(0,1,0,90,viz.FOREVER))

3D geometry nodes can also be linked. When one "destination" object is linked to another "source" object, transforms applied to the source object are also applied to the destination object.  For more information, check out the section on linking.

Billboarding

Sometimes you may want to have an object always facing the viewer or always facing a specific point. The <node3d>.billboard and <node3d>.lookAt commands in the node3d library accomplish these goals.

Billboarding is particularly handy when you've got 3D text or textured planes that you always want to face the viewer. If, for example, you have a set of trees that are actually only texture quads, you can apply billboarding so that the viewer will never have a chance to see behind them. Billboarding can also be set so that it rotates along all axes or just along the y axis (yaw).

viz.add('tut_ground.wrl')
#Add an object.
object = viz.add('duck.wrl')
#Set it to billboard, but only about the y axis.
object.billboard(viz.BILLBOARD_YAXIS)

See also

In this section:

3D model transform basics

3D model transforms command table

Other sections:

Appearance and texturing basics

3D text basics

Creating 3D models on-the-fly-- the basics

Linking basics

Action basics

Example scripts:

Rotation

Translation

Hierarchical

Matrix transformations