VirtualSphere

java.lang.Object
- MouseBehavior
- - jahuwaldt.j3d.VirtualSphere

```
public class VirtualSphere
extends MouseBehavior
```
VirtualSphere is a Java3D behavior object that lets users control the orientation, translation and scale of an object via a mouse. This class implements the virtual sphere algorithm for 3D rotation using a 2D input device. This is a much simpler implementation than that described in the reference paper. This is also known by as the "virtual track ball", "cue ball", or "arc ball" interface. This implementation is designed to work with Java3D.
Reference: Chen, Michael, Mountford, S. Jay, Sellen, Abigail, "A Study in Interactive 3-D Rotation Using 2-D Control Devices," ACM Siggraph '88 Proceedings, Volume 22, Number 4, August 1988.

To use this utility, first create a transform group that this mouse input behavior will operate on. Then,
```
   VirtualSphere behavior = new VirtualSphere(canvas3D);
   behavior.setTransformGroup(objTrans);
   objTrans.addChild(behavior);
   behavior.setSchedulingBounds(bounds);
```
The above code will add the virtual sphere behavior to the transform group. The user can then rotate, translate and scale any object attached to the objTrans. This class implements mouse rotation, translation, scaling and mouse wheel scaling actions.

Modified by: Joseph A.Huwaldt
Version:

September 15, 2016

Author:

Joseph A. Huwaldt, Date: Feburary 19, 2001

Constructor Summary

Constructors
Constructor and Description
`VirtualSphere(Canvas3D canvas)` Creates a `VirtualSphere` behavior associated with the specified canvas.
`VirtualSphere(JCanvas3D canvas)` Creates a `VirtualSphere` behavior associated with the specified canvas.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addTransformChangeListener(TransformChangeListener listener)` Add a `TransformChangeListener` to this object.
`BGFGImage`	`getFeedbackOverlay()` Returns an `BGFGImage` for use in an `BGFGCanvas3D` that displays a visual representation of the Virtual Sphere for user feedback.
`double`	`getMouseZoomFactor()` Return the mouse zoom multiplier.
`java.awt.Paint`	`getOverlayPaint()` Returns the `Paint` used to render the virtual sphere overlay graphics.
`double`	`getWheelZoomFactor()` Return the scroll wheel zoom multiplier.
`double`	`getXTranslationFactor()` Return the x-axis translation multiplier.
`double`	`getYTranslationFactor()` Return the y-axis translation multiplier.
`double`	`getZoomScale()` Return the zoom scale.
`void`	`initialize()` Initializes the behavior.
`void`	`processStimulus(java.util.Enumeration criteria)` Processes the MouseBehavior stimulus.
`void`	`removeTransformChangeListener(TransformChangeListener listener)` Remove a `TransformChangeListener` from this object.
`void`	`setMouseZoomFactor(double factor)` Set the mouse zoom multiplier factor.
`void`	`setOverlayPaint(java.awt.Paint paint)` Sets the `Paint` used to render the virtual sphere overlay graphics.
`void`	`setRotation(Matrix3d rotationMatrix)` Change the current rotation matrix to the one specified.
`void`	`setRotationCenter(Point3d rotationCenter)` Set the center of rotation on the model for the virtual sphere.
`void`	`setRotationCenter(Point3d rotationCenter, double zoomScale)` Set the center of rotation on the model and the zoom scale for the virtual sphere.
`void`	`setTranslationFactor(double factor)` Set the X-axis and Y-axis translation multiplier factor.
`void`	`setTranslationFactor(double xFactor, double yFactor)` Set the X-axis and Y-axis translation multiplier with xFactor and yFactor respectively.
`void`	`setupCallback(MouseBehaviorCallback callback)` The transformChanged method in the callback class will be called every time the transform is updated
`void`	`setWheelZoomFactor(double factor)` Set the scroll wheel zoom multiplier with factor.
`void`	`setZoomScale(double zoomScale)` Set the zoom scale.
`void`	`transformChanged(Transform3D transform)` Users can overload this method which is called every time the Behavior updates the transform.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - VirtualSphere
```
public VirtualSphere(Canvas3D canvas)
```
    Creates a VirtualSphere behavior associated with the specified canvas.
    
    Parameters:
    
    canvas - The Java3D canvas to associate this virtual sphere with.
  - VirtualSphere
```
public VirtualSphere(JCanvas3D canvas)
```
    Creates a VirtualSphere behavior associated with the specified canvas.
    
    Parameters:
    
    canvas - The Java3D canvas to associate this virtual sphere with.
- Method Detail
  - initialize
```
public void initialize()
```
    Initializes the behavior.
  - getXTranslationFactor
```
public double getXTranslationFactor()
```
    Return the x-axis translation multiplier.
    
    Returns:
    
    The x-axis translation multiplier.
  - getYTranslationFactor
```
public double getYTranslationFactor()
```
    Return the y-axis translation multiplier.
    
    Returns:
    
    The y-axis translation multiplier.
  - getMouseZoomFactor
```
public double getMouseZoomFactor()
```
    Return the mouse zoom multiplier.
    
    Returns:
    
    The mouse zoom multiplier.
  - getWheelZoomFactor
```
public double getWheelZoomFactor()
```
    Return the scroll wheel zoom multiplier.
    
    Returns:
    
    The scroll wheel zoom multiplier.
  - setTranslationFactor
```
public void setTranslationFactor(double factor)
```
    Set the X-axis and Y-axis translation multiplier factor.
    
    Parameters:
    
    factor - The factor to set the X & Y axis translation multiplier to.
  - setTranslationFactor
```
public void setTranslationFactor(double xFactor,
                                 double yFactor)
```
    Set the X-axis and Y-axis translation multiplier with xFactor and yFactor respectively.
    
    Parameters:
    
    xFactor - The X-axis translation multiplier factor.
    
    yFactor - The Y-axis translation multiplier factor.
  - setMouseZoomFactor
```
public void setMouseZoomFactor(double factor)
```
    Set the mouse zoom multiplier factor.
    
    Parameters:
    
    factor - The mouse zoom multiplier.
  - setWheelZoomFactor
```
public void setWheelZoomFactor(double factor)
```
    Set the scroll wheel zoom multiplier with factor.
    
    Parameters:
    
    factor - The scroll wheel zoom multiplier.
  - getZoomScale
```
public double getZoomScale()
```
    Return the zoom scale. This is the scale factor applied to the model to zoom in/out before the model is displayed.
    
    Returns:
    
    The zoom scale.
  - setZoomScale
```
public void setZoomScale(double zoomScale)
```
    Set the zoom scale. This is the scale factor applied to the model to zoom in/out before the model is displayed. The value must be > 0 or nothing happens.
    
    Parameters:
    
    zoomScale - The zoom scale to set.
  - setRotationCenter
```
public void setRotationCenter(Point3d rotationCenter)
```
    Set the center of rotation on the model for the virtual sphere. The transform will be adjusted to move center the specified point on the screen and the virtual sphere will rotate about it.
    
    Parameters:
    
    rotationCenter - The point about which the model should be rotated in virtual world coordinates.
  - setRotationCenter
```
public void setRotationCenter(Point3d rotationCenter,
                              double zoomScale)
```
    Set the center of rotation on the model and the zoom scale for the virtual sphere. The transform will be adjusted to move center the specified point on the screen and the virtual sphere will rotate about it. The zoom scale will also be adjusted.
    
    Parameters:
    
    rotationCenter - The point about which the model should be rotated in virtual world coordinates.
    
    zoomScale - The scale factor used to zoom the model.
    
    See Also:
    
    setZoomScale(double)
  - setRotation
```
public void setRotation(Matrix3d rotationMatrix)
```
    Change the current rotation matrix to the one specified.
    
    Parameters:
    
    rotationMatrix - The rotation matrix to be used.
  - addTransformChangeListener
```
public void addTransformChangeListener(TransformChangeListener listener)
```
    Add a TransformChangeListener to this object.
    
    Parameters:
    
    listener - The listener to add.
  - removeTransformChangeListener
```
public void removeTransformChangeListener(TransformChangeListener listener)
```
    Remove a TransformChangeListener from this object.
    
    Parameters:
    
    listener - The listener to add.
  - getFeedbackOverlay
```
public BGFGImage getFeedbackOverlay()
```
    Returns an BGFGImage for use in an BGFGCanvas3D that displays a visual representation of the Virtual Sphere for user feedback. This overlay is specific to the canvas that was used to create this virtual sphere and should not be used with any other canvas.
    
    Returns:
    
    The Virtual Sphere feedback image.
  - getOverlayPaint
```
public java.awt.Paint getOverlayPaint()
```
    Returns the Paint used to render the virtual sphere overlay graphics.
    
    Returns:
    
    The Paint used to render the virtual sphere overlay graphics.
  - setOverlayPaint
```
public void setOverlayPaint(java.awt.Paint paint)
```
    Sets the Paint used to render the virtual sphere overlay graphics.
    
    Parameters:
    
    paint - The paint to use for the virtual sphere overlay graphics.
  - processStimulus
```
public void processStimulus(java.util.Enumeration criteria)
```
    Processes the MouseBehavior stimulus. This method is invoked if the Behavior's wakeup criteria are satisfied and an active ViewPlatform's activation volume intersects with the Behavior's scheduling region.
    
    Parameters:
    
    criteria - An enumeration of triggered wakeup criteria for this behavior.
  - transformChanged
```
public void transformChanged(Transform3D transform)
```
    Users can overload this method which is called every time the Behavior updates the transform. This default implementation does nothing.
    
    Parameters:
    
    transform - The new 3D transform.
  - setupCallback
```
public void setupCallback(MouseBehaviorCallback callback)
```
    The transformChanged method in the callback class will be called every time the transform is updated
    
    Parameters:
    
    callback - The mouse behavior callback. May pass null for no callback.

Class VirtualSphere

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

VirtualSphere

VirtualSphere

Method Detail

initialize

getXTranslationFactor

getYTranslationFactor

getMouseZoomFactor

getWheelZoomFactor

setTranslationFactor

setTranslationFactor

setMouseZoomFactor

setWheelZoomFactor

getZoomScale

setZoomScale

setRotationCenter

setRotationCenter

setRotation

addTransformChangeListener

removeTransformChangeListener

getFeedbackOverlay

getOverlayPaint

setOverlayPaint

processStimulus

transformChanged

setupCallback