Shout3D™ 2.5 - User Guide

Using the Examine and Walk Applets

Your Shout3D installation comes with two custom applets that provide user interactivity features of wide applicability. For many projects, these applets will offer all the features you need. Because these applets are extended from the basic Shout3DApplet, they necessarily support all of its parameters, most of which can be set as Publishing Options in the Shout3D Wizard.

NOTE: You can learn a great deal about Java programming with the Shout 3D API by studying the source code for these two applets in the applets directory

ExamineApplet.java
ExaminePanel.java
WalkApplet.java
WalkPanel.java

The ExamineApplet

The ExamineApplet makes it easy for users to examine objects from all sides. Drag the mouse horizontally and vertically to rotate the camera around the object. To zoom in or out, hold down the <CONTROL> key and drag vertically. To pan (move the object left, right, up or down) hold down the <SHIFT> key and drag. The ExamineApplet is used in many of the demos in your Shout3D installation.

By default, the ExamineApplet computes the center of a bounding box containing the entire scene, and uses it as the center of rotation. It also computes an initial viewing distance that captures all objects in the scene.

You can choose between two interactive dragging styles. The default "by speed" option allows the user to control the speed of animated zooming, rotation and panning, for a smooth "power steering" feel. The examine_demo demo illustrates this dragging style. The optional "by offset" approach provides a more manual feel, with mouse drags directly effecting any movement or rotation. The examine_demo_offset_style demo illustrates this alternative dragging style. In fact, you can compare both styles in one applet in the examineWithButtonsDemo.

The standard settings for the ExamineApplet can't possibly make sense for all scenes, but you're not stuck with "one size fits all." You can easily customize the ExamineApplet to a particular scene by setting the following parameters directly in the <APPLET> tag. (Note how using applet parameters makes it easy to tailor a general applet to a specific use by experimenting with different values.)

dragStyle: "by speed" or "by offset" The default is "by speed."
rotationCenter: Use this parameter to override the computed center of rotation (the center of the bounding box). The value must be (x,y,z) coordinates in world space. For example:; <param name="rotationCenter" value="5.7 66.23 0">; The examine_demo_offcenter demo illustrates a center of rotation that has been set away center of the scene.
backupSlack: Adjusts the initial viewing distance. A value of 0 sets the distance so as to precisely frame the scene. The default value of .1 backs the camera up another 10 percent, to leave some empty space surrounding the scene.
bySpeedZoomDragFactor: Used to set the zooming velocity when the "by speed" dragStyle is used. The default value is .05, which means that the zoom speed will be 5 meters per second if the user drags the mouse a distance of 100 pixels.
bySpeedPanDragFactor: Used to set the panning velocity when the "by speed" dragStyle is used. The default value is .025, which means that the pan speed will be 2.5 meters per second if the user drags the mouse a distance of 100 pixels.
bySpeedRotateDragFactor: Used to set the rotational velocity when the "by speed" dragStyle is used. The default value is .033, which means that the pan speed will be 3.3 radians (189 degrees) per second if the user drags the mouse a distance of 100 pixels.
byOffsetZoomDragFactor: Used to set the zoom response when the "by offset" dragStyle is used. The default value is .01, which means that camera will zoom 1 meter for every 100 pixels that the mouse is dragged.
byOffsetPanDragFactor: Used to set the pan response when the "by offset" dragStyle is used. The default value is .005, which means that camera will pan .5 meters for every 100 pixels that the mouse is dragged.
byOffsetRotateDragFactor: Used to set the rotational response when the "by offset" dragStyle is used. The default value is .016, which means that camera will rotate 1.6 radians (91.5 degrees) for every 100 pixels that the mouse is dragged in either horizontal or vertical directions.

The WalkApplet

The WalkApplet allows users to navigate through the 3D space of a scene. Dragging the mouse vertically moves the camera forward and backwards. Dragging horizontally rotates the camera around its vertical axis. Holding the SHIFT key down as you drag doubles your walk speed. To look around in all directions from a stopped position, use the right mouse button (or left mouse button + CTRL key). When you release the right button (or the CTRL key), the camera snaps back to a straight-ahead view.

The WalkApplet comes complete with collision detection (so users won't walk through walls) and optional terrain following (to walk up and down stairs and ramps).

Check out the following demos:

Like the ExamineApplet, the WalkApplet is designed to be customized to the needs of any particular project by setting the following parameters directly in the <APPLET> tag.

avatarHeight

This parameter sets the height of the camera (the Viewpoint node). The default value is 2 meters. The significance of this value depends on whether terrain following is being used. If the terrainFollowing is parameter is set to true (the default), the camera will maintain this height above the terrain in the y direction of its local coordinate system. If terrain following is off, the camera will maintain a constant height in the y direction of its local coordinate system. In either case, the local coordinate system need not be the same as the world coordinate system. (You could walk up walls!).

avatarRadius

This parameter sets the cushion for collision detection. The default value is 2. Thus the camera will not move closer to a wall than 2 meters.

collideHeight

This parameter sets the height for collision detection. The default value is .25. Thus objects less than this height will not stop the camera from moving forward. If terrain following is on, the camera will climb on top of the object. If it is off, the camera will "step over" it.

forwardDragSpeed

Specifies amount of forward velocity (in meters/second) per pixel dragged. The default value is .05. Thus dragging 100 pixels set the forward velocity to 5 meters per second.

rotateDragSpeed

Specifies amount of rotational velocity (in radians/second) per pixel dragged. The default value is .0025. Thus dragging 100 pixels set the rotational velocity to .25 radians (14.3 degrees) per second.

terrainFollowing

The default is true. Causes camera to rise and fall with vertical changes in terrain.

gravity

If terrain following is on, this value determines the speed at which the camera will drop when passing over a ledge. The default is –9.8 meters/second², the acceleration of gravity on the surface of the earth.

maxClimbAngle

If terrain following is on, this value determines the maximum steepness that can be climbed. Steeper slopes are treated as walls. The default is 0.785 radians (about 45 degrees).