Package com.openinventor.inventor.viewercomponents.nodes

Class SceneOrbiter

  • All Implemented Interfaces:
    SafeDisposable
    public class SceneOrbiter
extends SceneInteractor
    (Preview Feature) Tool class for building a basic interactive OpenInventor application with mode-less scene "orbiter" viewing behavior.

    Preview Feature means this class is fully supported and can be used in Open Inventor applications. Being tagged as a Preview Feature just means that the implementation is still subject to API changes and adjustments based on feedback from early adopters. Please be also aware that source compatibility might be broken regardless of the Open Inventor compatibility changes policy due to our commitment to bring needed changes to make sure that the specifications of this Preview Feature match the expectations of our customers.

    The SceneOrbiter is an extension of the SceneInteractor node that provides camera and headlight manipulations like panning, zooming and orbiting similar to the SceneExaminer (in Orbit navigation mode).

    The SceneOrbiter provides a "mode-less" viewer which is very convenient for users. The SceneExaminer viewers are always in either viewing mode (mouse events control the camera) or in selection mode (mouse events are sent to the scene graph and objects can be selected). This often requires the user to frequently switch between viewing and selection mode (for example by pressing the ESC key) while interacting with the scene. SceneOrbiter does not have modes. For example, a mouse click without moving the mouse is interpreted as a selection and the event is sent to the scene graph, but a mouse click and "drag" is interpreted as controlling the camera.

    The SceneOrbiter provides two different methods to control the rotation of the camera around the scene : trackball and turntable, see SceneOrbiter.RotationMethods enum.
    The trackball method allows the camera to move along any circular orbit around the scene and look in the direction of its center. The orbit orientation can change at any time while interpreting a mouse drag. Thus the trackball is known as an unconstrained orbiting mode. The trackball is the unique method used by the historical examiner viewer and by the SceneExaminer.
    The additional turntable method is a more constrained orbiting mode. It allows the camera to move only along vertical orbits such as the earth meridians, and along horizontal circles such as the earth parallels. The vertical orbits and horizontal circles are related to an up axis, that can be changed calling setUpAxis(Axis). The horizontal circles are centered around this up axis, and the vertical orbits share their south and north pole on this up axis. As the camera cannot move along any other circle, this mode is more constrained compared to the trackball mode. However, that gives a more natural navigation experience when viewing a scene that has strong vertical and horizontal references. For instance, when orbiting in turntable mode around a scene representing the Eiffel tower, this one always looks vertical on your screen. Compared to the trackball mode, the turntable mode does not need any tedious small mousemove correction to keep the scene well aligned with the borders of the screen.

    The 'headlight', an SoDirectionalLight node, is automatically aligned with the camera's view direction.

    An SoViewingCube node is automatically added to the scene. The viewing cube can be hidden by calling the enableViewingCube(boolean) method.
    Note that the up axis of the viewing cube is synchronized with the up axis of the SceneOrbiter.

    See parent class SceneInteractor for more details about the structure of the internal scene graph.
    The SceneOrbiter uses an instance of SoCameraInteractor to manipulate the camera in response to OpenInventor events.

    Notes:

    • Window system integration
      The SceneOrbiter needs a component that integrates the Open Inventor 3D rendering window with the native window system. System dependent tasks include creating a window, placing the window in the application's user interface, initializing OpenGL and processing the native event/message loop. System independent support for this is provided by the SoRenderAreaCore class. Example components are provided for AWT and SWT toolkits.
    • Event handling
      The SceneOrbiter needs a component that builds OpenInventor events (SoEvent) from native system events. System independent support for this is provided by the SoEventBuilder class. Example components are provided for AWT and SWT toolkits: AWTEventToSoEvent and SWTEventToSoEvent.
    • Library
      A basic version of SceneOrbiter is a supported part of the Open Inventor API and a prebuilt jar is provided.
    • Source code
      The basic version of SceneOrbiter is also provided as source code in the sources folder to allow applications to customize and build their own interactive tool class.
      See $OIVJHOME/source/com/openinventor/inventor/viewercomponents/nodes.
    • Scene graph
      The application scene graph should be the last child of the SceneOrbiter. The initial application scene graph can be added by simply calling the inherited method addChild(). But note that if you need to replace the application scene graph, for example loading a new data set, do not call removeAllChildren(). That would also remove the SceneOrbiter's camera, headlight and event handler nodes. Add an SoSeparator to the SceneOrbiter to serve as the "scene graph holder", then add and remove the application scene graph from this node.
    • Clip planes
      SceneOrbiter automatically adjusts the 'near' and 'far' clipping planes when events modifying the camera are handled. This adjustment, based on the bounding box of the scene, ensures that shapes will not be clipped as the camera orbits and also that depth buffer precision is maximized.
      Note: Updating clipping planes after a camera move can be insufficient. If the scene graph is modified or if a dragger or a rendered shape is moved, they can disappear or become partially clipped. A classic implementation of a render area must adjust clipping planes before each rendering by calling the provided method SceneInteractor.adjustClippingPlanes(SbViewportRegion). See render area's implementations available in $OIVJHOME/examples/inventor/viewercomponents/awt and $OIVJHOME/examples/inventor/viewercomponents/swt folders for examples of adjustClippingPlanes use.
    • Compatibility with classical viewers
      Please note that some interaction behaviors are different than the classic Open Inventor viewer classes :
      • Left Mouse + Shift does Zoom in/out.
      • Mouse wheel performs a dolly relative to the cursor position, not the center of the viewport.

      • The classic ESC key behavior is not implemented.
        (Not necessary because viewing and selection are supported without separate modes.)
      • The classic Alt key behavior is not implemented. This key is reserved for application use.
      • The Right Mouse button does not display a pop-up menu. This button is reserved for application use.
      • Seek mode is not supported.
    • Compatibility with SceneExaminer
      • Only the left mouse button has defined behaviors.
        Pan and zoom behaviors require pressing a keyboard key while dragging the mouse.
      • Touch events are not currently handled.

    Usage:

    • Left Mouse: Rotate the scene
    • Left Mouse + Ctrl: Pan the scene.
    • Left Mouse + Shift: Zoom in/out the scene.
    • Mouse Wheel: Zoom in/out (zoom center is the mouse cursor location).