Frequently asked questions

If you are using 3dsmax then WorldViz highly recommends you use the OSG exporter for 3ds Max which is freely available on our downloads page. It will export models to Vizards native format, which supports more features than any other format. Choose between the text format (.osgt) or the binary format (.osgb). The binary format loads very quickly and embeds all texture data inside it. The exporter also has an option to compress textures, which further reduces the size and loading time of the binary file.

1.2 How do I create or get models for Vizard?

While Vizard has some facility for creating content (e.g., 2D & 3D text, primitives and shapes), most likely your project's completion will require you to provide your own content either by creating it using 3rd party software or by leveraging content created by others. The finding models online page lists some sites where you can purchase and download free models.

3ds Max exports to Vizard's native OSG format and is the best modeler for Vizard. WorldViz uses 3ds Max internally for creating assets and supports the workflow through this software. Even if you're not creating content, it's useful for exporting models found online to the OSG format.

There are a number of other applications that export to Vizard compatible formats, some of the more commonly used are Google SketchUp and Blender. The following knowledge base article describes the SketchUp workflow:

http://kb.worldviz.com/articles/1413

1.3 Is there a way to remove objects from the world?

All objects added to the scene have a remove command, which permanently deletes the object.

Example:

object = viz.add('world.ive')
.
.
.
object.remove()

To remove all objects from a scene, you can use the following:

children = viz.MainScene.getChildren()
for child in children:
child.remove()

1.4 I want to position a model at a certain location in the scene. What's the easiest way to determine the coordinates of that location?

Load the model used to create the scene (e.g. room, house, city etc.) into Inspector, right click on the location and copy the coordinates.

1.5 Instead 'absolute' rotate, I need to 'relative' rotate a 3d model.

The following example will rotate a model 45 degrees along the parent's y axis:

model.setEuler(45,0,0,viz.REL_PARENT)

The following example will rotate a model 45 degrees along its local y axis:

model.setEuler(45,0,0,viz.REL_LOCAL)

If you need more advanced control you could use the Transform class. Here's a simple example:

import vizmat
X = vizmat.Transform()
X.makeAxisAngle(0,1,0,90)
X.postAxisAngle(0,1,0,45)
model.setMatrix(X)

1.6 Does Vizard support mipmaps, LOD? If so, how do I get this to work? I want to conserve resources and have models further away show less detail.

As soon as any image is loaded into Vizard mipmaps are automatically generated.

If you are using 3ds Max and exporting to the OSG format you can specify LODs. From 3ds Max, in the create tab of the Command panel, go to helpers, then select OpenSceneGraph from the dropdown list. You should see an option along the lines of "OSG LOD" where you can set the LODs. When you export the model make sure 'Helpers' is one of the options checked.

1.7 My model is negatively affecting performance? How can I fix this?

This can be due to high polygon counts or textures. Most often textures are the cause of this. Use Inspector to view polycount and texture information for your model.

When loading models into Vizard on an average system (as used for current PC games), you should strive to keep the polygon count of the entire scene under 500,000 triangles for stereo viewing. For mono viewing, the polygon count can be doubled. Without any other overhead, an average system can handle 10,000,000 triangles, but you usually have to allow for slowdowns from textures, programming, real-time lighting, animation, etc. If you are working with model intensive scenes, it is recommended that you export models of various densities and run them in Vizard to test the limitations of your system.

The total texture budget in megabytes (MB) is determined by the video memory of your graphics card. The MB footprint of the texture is based on its uncompressed size (e. g. when it is saved as a TGA). For example, a 1024x1024 texture has a 3MB footprint. On a card with 500MB of video memory you can potentially fit 166 of them. The only compression schemes that will reduce this footprint are the various flavors of DXT compression, which can be selected upon export of the model if you're using the OSG exporter. You should generally shoot for staying at least 50MB under the video card capacity. If you go over, textures have to be transferred between the hard disk and the video card, causing a noticeable drop in frame rate.

1.8 When should <node3d>.copy and <node3d>.clone be used?

A copy will have the appearance of the original object when it was created. Any future changes to the original object's appearance will not affect the copy. There is a unique instance for each model but only one file needs to be loaded thereby reducing the load time.

If your script does not require a unique instance for each model, then you can use the clone command. Clones share the appearance of all the other clones. Changing the appearance of any one clone will change the appearance of all the others (although all their position, orientation, and scale transforms will be independent). In addition to reducing load time, memory is conserved as there is only one instance in memory for all the clones.

1.9 Does Vizard provide basic primitives and shapes?

Vizard allows you to create basic geometric objects (e.g. points, lines, triangles) on-the-fly. These objects are defined by creating vertices and then connecting those vertices with lines or surfaces. After an object is created it's vertices can be manipulated.

The vizshape library allows you to add more complex shapes (e.g. cubes, cylinders, cones). Unlike the on-the-fly objects you create with basic primitives you will not be able to access or manipulate individual vertices.

Once you've added either an on-the-fly or vizshape object, you can treat it as you would any other 3D object (e.g. set it's position, color, visibility etc.)

1.10 Can objects be made transparent or semi-transparent?

Yes, see the Transparency page for a discussion on this topic and to learn workarounds for issues that can arise when transparent objects are combined in the same scene.

2. Avatars

2.1 What avatar formats are supported?

Vizard supports the Cal3D avatar format. The Cal3D exporter for Max is available from the WorldViz download page. This Cal3D tutorial describes how to use the exporter.

2.2 Is it possible to change the included avatar's clothing or scale individual body parts?

Unless you've purchased the Complete Character set with the Max files you won't be able to make these types of modifications to the avatars. You'll need the Max files to make the changes and export a new Cal3D avatar.

2.3 How can I stop the avatar from walking through objects?

The vizact.walkTo action will not take into account objects along the walking path. You can create a series of walkTo actions to avoid an obstacle.

If you need to generate random walking actions then use proximity sensors to find out if the avatar is close to an object. If it is, end the walk action on the avatar and add a new one.

2.4 Is it possible to detect a collision with an individual body part?

You cannot perform collision on bones, only the entire avatar mesh. An alternative is to create an empty group node with a collision shape similar to the bone or avatar area where you want to detect collisions. Then link the group node to the bone. The Avatar Collisions knowledge base article provides some example code.

2.5 How do I create a custom animation for an avatar?

This is possible if you own the Complete Character set which comes with all the associated 3ds Max files for the avatars. This set already includes many animations you don't see with the built-in avatars and may have what you are looking for. For custom animations you can either develop them using keyframe animation or with a motion capture system. Both will require you have the original max files and that you export the finished animation to Cal3D, Vizard's native avatar format.

2.6 What facial expressions are included and how can I add new ones?

The HD Complete Characters include facial bones that you can manipulate to create expressions.

For the standard Complete Characters, it's necessary to create a morph target in 3ds Max for each facial expression you want. The morphs that are included with the characters allow for blinking, speaking, and eyebrow raising. Take a look at the Blinking Avatars tech tip for example code to control these morphs in Vizard.

You can also use an avatar creation tool like Facegen to create a new head which includes expressions. Import the head and all the morphs into Peoplemaker and save this to the PeopleMaker format. In Vizard, the Complete Character head can be replaced with the PeopleMaker head.

2.7 How can I attach a prop to an avatar?

There is an example file called linkbones.py. It can be found in your installation path under examples/avatar.

2.8 How can I make the avatar keep eye contact with the user?

Using the <bone>.lookAt command you can orient the avatar's neck and head bones to face the user. The Animating Bones tutorial shows how to use this command to maintain eye contact. If you need more advanced behaviour, such as having the avatar's head smoothly turn and then make contact, try the WatchNode example code.

3. Flow control and animations

3.1 I have a series of events that I want to occur one after the other. How do I do this?

A lot can happen between the beginning and the ending of a virtual world. Tasks (created with the viztask module) are useful for controlling the order of events. They are functions that can pause and wait for a condition to be met, like a key press or an action to end, before they proceed. While the task function is waiting, the rest of the program runs uninterrupted. An example would be an interaction with an avatar where the avatar would speak, wait for a user response and then walk away.

Tasks are also helpful for splitting up your program into different periods of activity. For example, if you have a training simulation or experiment with various phases you can use a task function to wait until one phase is done and then set another in motion.

For more information on viztask, look under Flow control in both the tutorial and reference sections of the Vizard help. The Program flow section in Vizard Teacher in a Book (available as a free download) also has a description of this module with example code.

3.2 What options are there for animating a model in Vizard?

The vizact library includes a variety of actions you can use to easily animate models and avatars.

Animation paths allow you specify points in time where a change in position, size, or orientation occurs for the object travelling along the path.

Callback functions can be used to update an object's transform or other property frame by frame (Generally there is no need for this because one of the methods described above can be used instead).

3.3 How do I disable a callback function?

To disable a callback that has been registered using the vizact library use <EventFunction>.setEnabled(viz.OFF).

#The callback function.
def myCallback(word):
print word

#Register a keydown event.
event_handle = vizact.onkeydown( ' ', myCallback, 'key event')

#Disable the event with another key down event.
vizact.onkeydown(viz.KEY_END, event_handle.setEnabled, viz.OFF )

Otherwise, disable a callback by setting the function to the value 0. For example, you would use the following code to disable a joystick button callback:

viz.callback(vizjoy.BUTTONDOWN_EVENT,0)

To resume the callback set the function back to the original value:

viz.callback(vizjoy.BUTTONDOWN_EVENT,joydown)

3.4 What's the difference between task and director functions?

The viztask module and viz.director functions have similar functionality; however, there are important differences. Calling viz.director actually creates a new thread, while scheduling a task does not. This means that calling a long blocking operation in a task will block the Vizard update loop as well and the frame rate will go to zero. However, in most cases, tasks should be used because they are much more CPU/memory efficient and are non-preemptive so synchronization locks are not necessary. Director functions should only be used for performing IO operations that would otherwise halt the rendering of the world or the execution of other code (e.g. reading data from a large file, downloading a file from the Internet)

3.5 How can I stop all my timers without closing my world?

To stop all the timers but keep the world open, use viz.pause(). To resume the timers, use viz.play().

4. Media

4.1 Why are my models too big or too small (or not showing up at all )?

In Vizard, it is important to note that the linear unit of measurement is meters. This is especially important to remember when obtaining 3D models from 3rd party sources because their units may not be in meters, in which case the objects may appear extremely large or small when imported into Vizard.

3DMax users should set the units (under the customize menu) to "generic" to avoid automatic unit conversions.

4.2 Objects are rendered pure white (textures not showing up).

This is often a result of trying to use a texture map that exceed the maximum 2D image resolution of Vizard. See the chapter on Multimedia to learn about these restrictions.

4.3 I have a media file that won't play in Vizard.

Vizard supports any video or sound file format for which your system has a codec. One of the most common problem with media files is not having the correct codec (compression/decompression algorithm) installed on your system. Often updating your Windows Media Player or possibly updating your overall system files will bring you up-to-date on current codecs and solve the problem.

4.4 Can I make movies of my worlds?

Yes, there are several ways.

Vizard comes with a built-in movie recorder. Pressing CTRL F12 starts the recorder. Your window will be resized to 640x480 during the recording process. Your captured video will appear as an uncompressed AVI in your project folder. Beware that these files sizes grow huge fast.

Another excellent solution is a tool called Fraps. Take a look at the following link where you can download a 30 day trial version.

http://www.fraps.com/

4.5 How can I do picture in picture showing the user and their Vizard perspective?

With a webcam and a few lines of code added to your script, a user can be displayed alongside the virtual scene they are viewing. By recording it all with software like Fraps, you can easily create a picture-in-picture video demo.

The following code shows the Vizard gallery with webcam video mapped to a texture quad in the corner of the screen:

import viz
viz.go(viz.FULLSCREEN)

#define height of texture quad in pixels to display video
HEIGHT = 300

#get webcam video
video = viz.add('VideoCamera.dle')
cam = video.addWebcam()

#get aspect ratio of video and calculate width of quad
size = cam.getSize()
ratio = float(size[0])/float(size[1])
WIDTH = ratio*HEIGHT

#add texture quad to the viz.ORTHO layer and link to upper left
quad = viz.addTexQuad(parent=viz.ORTHO,texture=cam,scale=[WIDTH,HEIGHT,1],align=viz.ALIGN_LEFT_TOP)
viz.link(viz.LeftTop,quad)

gallery = viz.addChild('gallery.ive')

4.6 3DMax and lighting in Vizard.

Take a look at the following tutorial which goes over a method of light baking, or storing lighting information in a map, and then exports the model with this information for use in Vizard.

http://kb.worldviz.com/articles/1222

4.7 Why does Vizard scale my textures?

OpenGL requires that the width and height of a texture be a power of two.

4.8 I have a large texture that doesn't work. Why?

The size of the texture might be larger than the maximum texture size allowed by your graphics card (usually 2048 or 4096). If you want to use a very large texture, split it up into smaller textures and tile the textures on your object.

4.9 Why aren't transparent textures transparent within Vizard?

You will need to use alpha masks in order for transparency to work in Vizard. The jpg image format does not support alpha masks, so if you're using a jpg you will need to convert the image to some other format, such as tif or png. Within the appropriate format, give the black areas an alpha value of 0. Microsoft Office comes with a handy program call Microsoft Photo Editor. You can open your image with this program and use the "Set Transparent Color" tool to make the black areas transparent. Then make sure you save the image to tif or png format.

4.10 My objects have the appropriate textures in 3DMax, but when I bring them into Vizard those textures are gone.

When you apply a texture material in 3DMax you should only use UVW modifiers to adjust the texture parameters. Adjusting them directly within the material editor does not carry through to Vizard.

5. Display

5.1 What settings should be adjusted to get the best stereoscopic effect on a monitor or screen?

For viewing on an external display (e.g 3D monitor, shutterglasses) screen distance is important. WorldViz suggests that you correctly set the screen distance to your display(see <window>.screenDistance), the vertical field-of-view of the display (see viz.fov), and the user's ipd (see viz.ipd) when creating compelling and accurate 3D visualizations.

If you want to exaggerate the stereo effect you can change the window.fusionDistance setting. This command is not normally used for setting up correct 3D viewing. If you want an object to pop out of the screen more, then you would use a higher fusion distance value. This causes all objects less than that amount of distance from the virtual viewpoint to appear in front of the screen in 3D. By default, the fusion distance value will be the same as the screen distance value.

For a full discussion of stereoscopic rendering and HMD versus external displays, refer to the Stereoscopic Rendering page.

5.2 How do I get Vizard to display in stereo with shutter glasses?

If you video card supports quad buffered stereo and the stereo setting is enabled use:

viz.go(viz.QUAD_BUFFER)

to initialize this stereo mode in your Vizard program.

5.3 How do I setup Vizard to work with a powerwall or CAVE?

The vizcave documentation includes example scripts for setting up both a powerwall and multi-wall CAVE in Vizard.

5.4 What is the fov of the Vizard display?

The default vertical FOV for the Vizard display is 40 degrees; the aspect ratio is automatically computed based on the window size. To change this, use viz.fov(verticleFOV, aspect ration).

5.5 How do I reverse left/right eye channels?

Use the viz.ipd(IPD) command. Instead of the default interpupillary distance of 0.06 meters, specify the distance as -0.06 meters.

5.6 What is clipping range?

Most 3D graphics programs that rely on hardware accelerated hidden surface removal always have a finite depth range. Vizard uses hardware z-buffering exclusively for hidden surface removal, as do most other rendering APIs.

As such, you can use the viz.clip() command to fine tune the range. Keep in mind your depth resolution (the minimum distance the computer can distinguish in depth) will be spread over this range. You're noticing that far objects are disappearing. Try increasing the far range:

viz.clip(0.5, 1000)

that sets the nearest range to .5 and the farthest to 1000 meters. If that's still not far enough, increase the far (e.g., to 5000). If you will never view an object closer than say 2 meters, then you'll get better z-buffer performance if you then correspondingly increase your near distance (e.g., viz.clip(2.0, 5000)).

If you set the range to be too wide (e.g., viz.clip(0.001, 1000000000)), you'll notice jagged slices through all your objects because the algorithms cannot exactly distinguish which objects are closer to viewpoint than others.

5.7 How can I display an object to a specific eye in stereo?

You can prevent a node from rendering to a specific eye in stereo using the <node3D>.disable command with either the viz.RENDER_RIGHT or viz.RENDER_LEFT flag. In the following example, a ball is displayed to only the left eye by disabling right eye rendering:

import viz
viz.go(viz.STEREO_HORZ)

court = viz.addChild('court.ive')

ball = viz.addChild('ball.wrl',pos=[0,2,5])
ball.disable(viz.RENDER_RIGHT)

6. Viewpoint and Navigation

6.1 How do I manually move the viewpoint?

Access the viewpoint in your script using the following code:

view = viz.MainView

For relative movement of the viewpoint, use view.move(). For movement within the world's coordinates, use view.setPosition([x,y,z]). For relative rotations, use view.setEuler() with the viz.REL_PARENT flag. For rotations within the world's coordinate system, use view.setEuler().

6.2 Is it possible to do real time collision detection with the viewpoint and the scene in Vizard?

Yes. Turn on built-in collision detection by adding the following line to your script:

viz.collision(viz.ON)

Vizard will automatically check for collisions between the viewer and the world. If the viewer collides with an object it will stop the viewer from moving past it.

6.3 Can I rotate the viewer's head and body independently?

The command <viewpoint>.setEuler will rotate the head (and not the body) by default. You can however, rotate the body (and the head will rotate with it). To do so, use the flag below:

view.setEuler([90,0,0], viz.BODY_ORI)

6.4 Is there a way to disable the default behaviour of using the mouse to move around the scene?

The following should disable mouse navigation:

viz.mouse(viz.OFF)

6.5 Mouse navigation speed is too slow or too fast. Can it be changed?

Try the viz.mouse.setScale command. It let's you change the gain for both navigation translation and rotations. To just go faster forward but keep the same turn feel, try something like:

viz.mouse.setScale(3,1)

This will triple your translation speed but keep your rotations untouched.

7. Vizard IDE

7.1 Can I use a 3rd party Python IDE to run Vizard scripts?

Yes, you just need to configure the IDE to run the Vizard script using winviz.exe, which is located in the Vizard bin directory. Our knowledge base contains step-by-step instructions on how to configure some of the more popular Python IDEs to run Vizard scripts.

7.2 Can I run a script and pass arguments to it from the command-line?

Yes, the following knowledge base article describes how to do this:

http://kb.worldviz.com/articles/1106

8. Hardware

8.1 I use an InertiaCube and a PPT for 6DOF tracking; sometimes when I start a session, the movement seems to be off by 5-70 degrees. How do I fix this?

You must make sure that Intersense's coordinate system is aligned with PPT's coordinate system. If that's not the case, your movement direction will be off by the degree of the initial offset. The following article describes several ways to perform the alignment:

http://kb.worldviz.com/articles/1355

8.2 How do I add a second Intersense in my script?

When adding your Intersense, specify the COM port the device is connected to.

isense = viz.add('intersense.dle')

tracker1 = isense.addTracker(port=1)
tracker2 = isense.addTracker(port=2)

8.3 Does Vizard work with Nvidia's 3D Vision glasses?

An Nvidia Quadro card is required to use the 3D Vision glasses with Vizard. The drivers do not support using 3D Vision with OpenGL applications on GeForce cards.

If you have an nvidia Quadro card and meet all the 3D Vision requirements then use the following in Vizard to initialize stereo:

viz.go(viz.QUAD_BUFFER)

8.4 What graphics cards does WorldViz recommend?

Worldviz generally recommends the high end Nvidia GeForce cards. If you need frame sequential stereo then we recommend an Nvidia Quadro card.

8.5 How much memory can Vizard address and is it a 64 bit compatible program?

Vizard is compatible with 64 bit environments but it is a 32 bit process. On 64 bit OS one instance of Vizard can utilize a maximum of 4 GB RAM regardless of how much memory is installed. On 32 bit OS Vizard cannot access more than 3 GB RAM.

8.6 Can I run multiple instances of Vizard, and how much memory will be available?

You can build a cluster on the same machine and thus leverage multiple GPUs. Under this scenario, each cluster instance can access a total amount of RAM according to the description in FAQ 8.5. Keep this in mind when running two GPUs—you may well need a machine that has 8 or more GB RAM to render full throttle. The supported GPU configurations are NVidia Quadro and AMD Radeon / FireGL.

8.7 How can I improve the performance of my Vizard script?

There are a variety of factors that can affect performance such as graphics content, hardware, and Windows settings. Take a look at the Performance page for more on this topic.

9. Add-ons

9.1 Can I use wxPython with Vizard?

Yes. Go here for details on how to do it:

http://kb.worldviz.com/articles/72

9.2 Is it possible to do voice recognition in Vizard?

Yes, you can use the 3rd party pywin32 library along with the Microsoft Speech SDK to perform voice recognition in Python. The following knowledge base article describes how to do this.

http://kb.worldviz.com/articles/1401