Repository

Topics

j3d.org

Using the Navigation Utilities

The navigation utilities code come from a wide range of capabilities. You may just use simple mouse orientation capabilities to a full navigation system that includes user interface components, cursor changing and more.

Philosophy

Not everyone wants to do their navigation the same way. However, for a lot of cases a set of simple capabilities that just works as expected is really useful. That's the aim of the navigation utilities - to provide a componentised navigation framework that allows you to decide how you are going to add and display navigation to the end user. You may have everything from simple processing of mouse events passed to you, to full cursor changing and Swing GUI toolbars.

The original impetus for this code came from a donation from the Halden VR center, Institute for Energy Technology. This provided a very simple VRML based framework for loading and navigating VRML worlds. With this very basic capability, we have extended the code to work with many more navigation modes. All of the modes presented here follow the VRML standards - FLY, WALK, EXAMINE etc.

 

Setting up

Setup for the navigation utilities depends on the capabilities that you require.

Code and Classpath

Firstly, you need to import the right package. Everything is contained in the org.j3d.ui.navigation package.

If you wish to use any of the other tools such as toolbars and cursors, then you will also need to make sure that the config/images directory is in your classpath. Currently the makefiles do not build a JAR file with the images in it, so you have to either build one by hand or make the classpath point in the right direction.

Simple Navigation Utilities

For this level, we are assuming that you want to use the raw navigation tools with none of the user interface. This means you have the choice of creating your own input handler and passing the events directly to the NavigationHandler or using AWT based behaviors with MouseViewHandler or Java3D based Behaviors with MouseViewBehavior

To set up for using the raw handler, you create an instance of NavigationHandler. The constructor does not take any arguments. If you would like feedback information from the handler you are free to set one of the collection of listeners available.

To use AWT based information, create an instance of MouseViewHandler. Again, this takes no arguments, but in order to have the navigation work, you must supply it with an instance of a Canvas3D so that we may add listeners to it for the appropriate mouse events.

To use Java 3D based behaviors, create an instance of MouseViewBehavior This has the option of either using a default instance of the navigation handler or you can create one and pass it in yourself.

Navigation Modes

Next we need to choose what modes we would like to navigate in. This list shows you all of the options available. You can set any mouse button to using these modes. It is quick fine to have button 1 set to walk, button 2 to fly and button 3 to examine for example.
NONE
All navigation is disabled. We ignore any requests from mouse or keyboard to move the viewpoint.
EXAMINE
The viewpoint is moved around the local origin provided by the View transform group. The view will then rotate around that object looking at the origin all the time. Note that if the local transform does not have any transformation information set, this will result in undefined behaviour (probably exceptions internally). There is no collision detection or terrain following in this mode.
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.
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.
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.
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.

 

Setting up view information

Before we can navigate around the scene you must provide the system with something to actually manipulate. For maximum flexibility, the code requests a TransformGroup rather than a ViewPlatform. There are two reasons for this - firstly to move the camera around the scene you will need a transform group anyway and secondly, you may acutally want to move something other than a view around (eg other objects or have the view deeply embedded in a HUD structure).

The other item required for view information is an instance of a View object. We use this to determine a few performance criteria and adjust the navigation to cope with this.

To disable navigation handling all you have to do is remove the transform and view by calling the setViewInfo() method with null parameter values.

Providing geometry for navigation

If you intend to use one of the states that uses collision detection or terrain following then you need to provide us with information about what we can collide with and what is terrain. For performance reasons, we allow you to provide two different scene graph structures for collisions and terrain following.

To set the structures for collisions and terrain, you use the setWorldInfo() method. The two parameters control what geometry we query for these two operations. For example, say we have a BranchGroup that contains our geometry for the terrain called terrain and another for the collidable objects called walls then we can set these as follows 

    navHandler.setWorldInfo(terrain, walls);
Any geometry that is not part of either of these groups will not be used in any calculations. That allows you to build parts of the scene that the user can walk through and parts that are solid with no additional effort.

Using User Interfaces

TBD

 

Moving About

Once you have set the system up, all of the navigation is self contained. Internally events are recieved and the code will update the view transforms to automatically move the view transform according to the selected navigation mode. There are also controls over how and what functionality is to be used.

Mouse Actions to move about

The user interface to move about rely on click and drag actions. To initiate a move you press the mouse button down. To move in a given direction, drag the mouse in that direction. The amount that you drag the mouse relative to it's starting position determines the speed to move at. A small drag will cause slow movement, while a large drag will cause fast movement. Holding the mouse steady with the button pressed will have a constant speed. Once you release the mouse, the movement will stop.

Selecting a navigation mode

Navigation modes are selected with the setButtonNavigation() method. This method takes the button that we want to use and the navigation state that you want to use.

The button to use is one of the values defined in java.awt.MouseEvent which the navigation state is defined in the NavigationStates interface. 

  navHandler.setButtonNavigation(MouseEvent.BUTTON1_MASK,
                                 NavigationState.WALK_STATE);
This means that whenever button 1 is pressed on the mouse we will move around according to the rules of the WALK state - ie terrain following and collision detection.

Disabling Functionality

If you decide that you don't want to have one of collision detection or terrain following, then you can disable it fairly easily. As the setWorldInfo() method does the setup of the scenegraph used for these operations, it can also be used to disable it. If you provide a null parameter value then that action will not be used. For example, if there is no terrain branchgroup provided we will not perform terrain following.

 
[ Home ] [ License ] [ javadoc ] [ Online Examples ] [ Download ]
[ j3d.org ] [ Aviatrix3D ] [ Code Repository ] [ Java3D ] [ OpenGL ] [ Books ] [ Contact Us ]
Last Updated: $Date: 2010-01-27 21:36:00 -0800 (Wed, 27 Jan 2010) $