org.j3d.renderer.java3d.navigation
Class NavigationProcessor

java.lang.Object
  org.j3d.renderer.java3d.navigation.NavigationProcessor

Direct Known Subclasses:

NavigationHandler

public class NavigationProcessor

extends java.lang.Object

A listener and handler responsible for executing all navigation commands from mice and keyboards to move a viewpoint around a scene.

This class does not contain any direct event handling. Instead it assumes that another class with either derive from it or delegate to it to do the actual movement processing. This allows it to be used as a standard AWT event listener or a Java3D behaviour as required by the software.

The class works like a standard VRML browser type navigation system. Press the mouse button and drag to get the viewpoint moving. The more you drag the button away from the start point, the faster the movement. The handler does not recognize the use of the Shift key as a modifier to produce an accelerated movement.

This class will not change the cursor on the canvas in response to the current mouse and navigation state. It will only notify the state change listener. It is the responsibility of the listener to do this work.

Separate states are allowed to be set for each button. Once one button is pressed, all the other button presses are ignored. By default, all the buttons start with no state set. The user will have to explicitly set the state for each button to get them to work.

The handler does not currently implement the Examine mode.

Terrain Following

When doing terrain following, the handler will project a ray from the current viewpoint position to the ground position. It will then offset the current position by the new position that we should be going to. If the distance in the overall Y axis is less than the step height, the translation will be allowed to proceed and the height adjusted to the new value. If it is greater, then it will set the Z component to zero, allowing no forward movement. Thus, if the next translation also has a sideways component, it will simply shift sideways and not move forward.

If there is no terrain under the current eye position, or the next eye position, it will not change the Y axis value at all.

If you do not wish to have terrain following for all modes, then pass a null value for the terrain parameter to setWorldInfo().

Collision Detection

Collision detection is based on using a fixed point representation of the avatar - we do not have a volumetric body for it. A ray is cast in the direction that we are looking that is the length of the avatarSize plus the amount that we are due to move this next frame.

If you do not wish to have collision detection for all modes, then pass a null value for the collidables parameter to setWorldInfo().

Navigation Modes

NONE

All navigation is disabled. We ignore any requests from mouse or keyboard to move the viewpoint.

EXAMINE

The viewpoint is moved around the center of rotation provided by the user. There is no collision detection or terrain following in this mode.

For movement input, direction is treated as the direction in the local coordinates on the surface of a sphere formed around the rotation origin. The scale represents the movement along the vector and then each component defines the proportion used to move in that direction. [0] is left/right, [1] is up/down, [2] is zoom in out where +Z is zoom out.

FLY

The user moves through the scene that moves the eyepoint in forward, reverse and side to side movements. There is collision detection, but no terrain following.

For movement input the direction controls the scale of the input to translate and rotate about. [0] controls left/right rotation, [1] controls pitch and [2] controls the amount of forward movement.

WALK

The user moves through the scene with left/right options and forward reverse, but they are bound to the terrain and have collision detection.

For movement input, the direction controls only two of the axes as gravity is used to constrain in the local Y axis. [0] is the amount of rotation left/right to perform each frame and [2] controls the forward/reverse movement.

PAN

The camera moves in a sliding fashion along the given axis - the local X or Z axis. There is not collision detection or terrain following.

Move the viewpoint left/right/up/down while maintaining the current viewing direction. [0] is used for left/right and [1] is used for up/down. [2] is not used.

TILT

The camera rotates around the local axis in an up/down, left/right fashion. It stays anchored in the one place and does not have terrain following or collision detection.

Movement input controls how the tilt is performed and is an absolute value that controls total tilt. [0] controls rotation of the camera in the X-Z plane, [1] controls rotation in the Y-Z plane. TODO

The collision vector does not move according to the direction that we are travelling rather than the direction we are facing. Allows us to walk backwards through objects when we shouldn't.

Implement Examine mode handling

Version:

$Revision: 1.6 $

Author:

per-frame movement algorithms by Halden VR Centre, Institute for Energy Technology
Terrain/Collision implementation by Justin Couch Replaced the Swing timer system with J3D behavior system: Morten Gustavsen. Modified the tilt navigation mode : Svein Tore Edvardsen.

Field Summary

static int	AVATAR_CYLINDER The avatar representation is a cylinder
static int	AVATAR_POINT The avatar representation is a floating eyeball
static int	AVATAR_SHOULDERS The avatar representation is two shoulder rays

Constructor Summary

NavigationProcessor()
Create a new mouse handler with no view information set.

Method Summary

int	getNavigationState() Callback to ask the listener what navigation state it thinks it is in.
void	getPosition(javax.vecmath.Vector3d pos) Get the current user position in world coordinates.
javax.media.j3d.Behavior	getTimerBehavior() Fetch the behaviour used to do the timer management for scenegraph updates during navigation.
void	move(float[] direction, float scale) Update the user movement to be going in this absolute direction.
void	orient(float[] direction) Orient the viewer direction to this position, but do not change their movement direction.
void	processNextFrame() Call to update the user position now based on the difference in time between the last call and this call.
void	setAvatarInfo(float height, float size, float stepHeight) Set the information about the avatar that is used for collisions and navigation information.
void	setCenterOfRotation(float[] center, float[] lookPos) Set the center of rotation explicitly to this place.
void	setCollisionListener(CollisionListener l) Set the listener for collision notifications.
void	setFrameUpdateListener(FrameUpdateListener l) Set the listener for frame update notifications.
void	setNavigationSpeed(float newSpeed) Set the navigation speed to the new value.
void	setNavigationState(int state) Set the ability to use a given state within the handler for a specific mouse button (up to 3).
void	setOrbitTime(float time) Set the time it takes in seconds to make one 360 degree rotation of the center position when in examine mode.
void	setViewInfo(javax.media.j3d.View view, javax.media.j3d.TransformGroup tg) Set the view and it's related transform group to use.
void	setViewInfo(javax.media.j3d.View view, javax.media.j3d.TransformGroup tg, javax.media.j3d.SceneGraphPath path) Set the view and it's related transform group to use and the path to get there from the root of the scene.
void	setViewPath(javax.media.j3d.SceneGraphPath path) Change the currently set scene graph path for the world root to this new path without changing the rest of the view setup.
void	setWorldInfo(javax.media.j3d.BranchGroup terrainGroup, javax.media.j3d.BranchGroup worldGroup) Set the branchgroups to use for terrain and collision information.
void	startMove() Start the user moving in the current direction.
void	stopMove() Halt the current movement being processed.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

AVATAR_POINT

public static final int AVATAR_POINT

The avatar representation is a floating eyeball

See Also:

Constant Field Values

AVATAR_CYLINDER

public static final int AVATAR_CYLINDER

The avatar representation is a cylinder

See Also:

Constant Field Values

AVATAR_SHOULDERS

public static final int AVATAR_SHOULDERS

The avatar representation is two shoulder rays

See Also:

Constant Field Values

Constructor Detail

NavigationProcessor

public NavigationProcessor()

Create a new mouse handler with no view information set. This handler will not do anything until the view transform references have been set and the navigation modes for at least one mouse button.

Method Detail

getTimerBehavior

public javax.media.j3d.Behavior getTimerBehavior()

Fetch the behaviour used to do the timer management for scenegraph updates during navigation. This behaviour is needed if you want to have automatic navigation from the mouse input. If you wish to do your own management of when to update the navigation, then you should not call this method, and instead call the processNewFrame() method.

If this behavior is not fetched and you do want automatic handling of navigation, navigation will not happen! A single instance of the behaviour is used during the entire lifetime of this instance.

Returns:

The behavior used to control updates

setCenterOfRotation

public void setCenterOfRotation(float[] center,
                                float[] lookPos)

Set the center of rotation explicitly to this place. Coordinates must be in the coordinate space of the current view transform group. The provided array must be of least length 3. Center of rotation is used in examine mode.

Parameters:

center - The new center to use

lookPos - The position to look from. NULL is the current user position.

setViewInfo

public void setViewInfo(javax.media.j3d.View view,
                        javax.media.j3d.TransformGroup tg)

Set the view and it's related transform group to use. The transform group must allow for reading the local to Vworld coordinates so that we can accurately implement terrain following.

Parameters:

view - is the View object that we're modifying.

tg - The transform group above the view object that should be used

Throws:

java.lang.IllegalArgumentException - One of the values is null and the other is not

java.lang.IllegalStateException - The transform group does not allow reading of the vworld transforms or does not allow it to be set

setViewInfo

public void setViewInfo(javax.media.j3d.View view,
                        javax.media.j3d.TransformGroup tg,
                        javax.media.j3d.SceneGraphPath path)

Set the view and it's related transform group to use and the path to get there from the root of the scene. The transform group must allow for reading the local to Vworld coordinates so that we can accurately implement terrain following. A null value for the path is permitted.

Parameters:

view - is the View object that we're modifying.

tg - The transform group above the view object that should be used

path - The path from the root to the transform to use or null

Throws:

java.lang.IllegalArgumentException - One of the values is null and the other is not

java.lang.IllegalStateException - The transform group does not allow reading of the vworld transforms or does not allow it to be set

setViewPath

public void setViewPath(javax.media.j3d.SceneGraphPath path)

Change the currently set scene graph path for the world root to this new path without changing the rest of the view setup. Null will clear the current path set.

Parameters:

path - The new path to use for the viewpoint

setWorldInfo

public void setWorldInfo(javax.media.j3d.BranchGroup terrainGroup,
                         javax.media.j3d.BranchGroup worldGroup)

Set the branchgroups to use for terrain and collision information. The two are treated separately for the different processes. The caller may choose to make them the same reference, but the code internally treats them separately.

Note For picking purposes, the code currently assumes that both groups do not have any parent transforms. That is, their world origin is the same as the transform group presented in the view information.

Parameters:

terrainGroup - The geometry to use as terrain for following

worldGroup - The geometry to use for collisions

setAvatarInfo

public void setAvatarInfo(float height,
                          float size,
                          float stepHeight)

Set the information about the avatar that is used for collisions and navigation information.

Parameters:

height - The heigth of the avatar above the terrain

size - The distance between the avatar and collidable objects

stepHeight - The height that an avatar can step over

setNavigationSpeed

public void setNavigationSpeed(float newSpeed)

Set the navigation speed to the new value. The speed must be a non-negative number.

Parameters:

newSpeed - The new speed value to use

Throws:

java.lang.IllegalArgumentException - The value was negative

setOrbitTime

public void setOrbitTime(float time)

Set the time it takes in seconds to make one 360 degree rotation of the center position when in examine mode. The time must be a non-negative number.

Parameters:

time - The time value to use

Throws:

java.lang.IllegalArgumentException - The value was <= 0

setNavigationState

public void setNavigationState(int state)

Set the ability to use a given state within the handler for a specific mouse button (up to 3). This allows the caller to control exactly what states are allowed to be used and with which buttons. Note that it is quite legal to set all three buttons to the same navigation state

Parameters:

state - The navigation state to use for that button

setCollisionListener

public void setCollisionListener(CollisionListener l)

Set the listener for collision notifications. By setting a value of null it will clear the currently set instance

Parameters:

l - The listener to use for updates

getNavigationState

public int getNavigationState()

Callback to ask the listener what navigation state it thinks it is in.

Returns:

The state that the listener thinks it is in

processNextFrame

public void processNextFrame()

Call to update the user position now based on the difference in time between the last call and this call. This is to be called when the user wishes to manually control the navigation process rather than relying on the inbuilt timer. The user should not be using both mechanisms at the same time although the code takes no steps to enforce this. If you do try to do manual updates while also having the automated system, the results are undefined.

startMove

public void startMove()

Start the user moving in the current direction. Initialises all the internal timers but does not actually start the movement.

stopMove

public void stopMove()

Halt the current movement being processed. Any move input after this will be ignored and the user will stop moving.

move

public void move(float[] direction,
                 float scale)

Update the user movement to be going in this absolute direction. Scale gives a proportion of the set speed value to move in that direction. The interpretation of the 3 components of the vector are described in the class header documentation.

Parameters:

direction - The new direction to move the user

scale - fractional value of the set speed to use [0, inf)

orient

public void orient(float[] direction)

Orient the viewer direction to this position, but do not change their movement direction. The direction is a normalised 3D vector relative to the current movement. 0,0,0 means always look where the movement is taking you.

Parameters:

direction - 3D vector where the user should be looking

getPosition

public void getPosition(javax.vecmath.Vector3d pos)

Get the current user position in world coordinates.

Parameters:

pos - The position vector to fill in

setFrameUpdateListener

public void setFrameUpdateListener(FrameUpdateListener l)

Set the listener for frame update notifications. By setting a value of null it will clear the currently set instance

Parameters:

l - The listener to use for this transition