/*
 *   VirtualSphere -- A class that implements the Virtual Sphere or Arc Ball algorithm for 3D rotation.
 *   
 *   Copyright (C) 2001-2023 by Joseph A. Huwaldt.
 *   All rights reserved.
 *   
 *   This library is free software; you can redistribute it and/or
 *   modify it under the terms of the GNU Lesser General Public
 *   License as published by the Free Software Foundation; either
 *   version 2.1 of the License, or (at your option) any later version.
 *   
 *   This library is distributed in the hope that it will be useful,
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *   Lesser General Public License for more details.
 *
 *   You should have received a copy of the GNU Lesser General Public License
 *   along with this program; if not, write to the Free Software
 *   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 *   Or visit:  http://www.gnu.org/licenses/lgpl.html
 */
package jahuwaldt.j3d;

import org.jogamp.java3d.exp.swing.JCanvas3D;
import org.jogamp.java3d.utils.behaviors.mouse.*;
import java.awt.*;
import java.awt.event.ComponentAdapter;
import java.awt.event.ComponentEvent;
import java.awt.event.MouseEvent;
import java.awt.event.MouseWheelEvent;
import java.awt.image.BufferedImage;
import static java.lang.Math.*;
import java.util.ArrayList;
import java.util.Enumeration;
import java.util.Iterator;
import java.util.List;
import static java.util.Objects.requireNonNull;
import org.jogamp.java3d.*;
import org.jogamp.vecmath.*;

/**
 * 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.
 * <p>
 * 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.
 * </p>
 * <p>
 * To use this utility, first create a transform group that this mouse input behavior will
 * operate on. Then,
 * <blockquote><pre>
 *
 *   VirtualSphere behavior = new VirtualSphere(canvas3D);
 *   behavior.setTransformGroup(objTrans);
 *   objTrans.addChild(behavior);
 *   behavior.setSchedulingBounds(bounds);
 *
 *</pre></blockquote>
 * 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.
 * </p>
 *
 * <p> Modified by: Joseph A.Huwaldt </p>
 * 
 * @author Joseph A. Huwaldt, Date: Feburary 19, 2001
 * @version June 4, 2023
 */
public class VirtualSphere extends MouseBehavior {

    //  The angular size in degrees of the virtual sphere overlay cue "cross-hair".

    private static final int CROSSHAIR_SIZE = 20;

    //  Temporary storage objects used in calculations.
    private final Vector3d _op = new Vector3d();
    private final Vector3d _oq = new Vector3d();
    private final Vector3d _av = new Vector3d();
    private final AxisAngle4d _a1 = new AxisAngle4d();
    private final Transform3D _mouseMtx = new Transform3D();
    private final Vector3d _translation = new Vector3d();

    //  The zoom scale factor being used.
    private double _zoomScale = 1;

    //  Scale factors used for translation and for zooming.
    private double _xTransFactor = .001;
    private double _yTransFactor = .001;
    private double _zoomFactor = 0.04;
    private double _wheelZoomFactor = 0.1;

    //  The point on the Canvas3D that represents the center of the canvas.
    //  This is the center of the virutal sphere.
    private final Point _cueCenter = new Point();

    //  The radius of the virtual sphere in pixels on the canvas.
    private int _cueRadius;

    //  The canvas this virtual sphere is associated with.
    private final Component _canvas;

    //  Used to track the mouse position over the canvas.
    private Point _prevMouse;

    //  An Overlay that displays a screen representation of the virtual sphere.
    private VSOverlay _overlay = null;

    //  The color used to render the overlay graphics.
    private Paint _overlayPaint = new Color(Color.BLACK.getRed() / 255F, Color.BLACK.getGreen() / 255F,
            Color.BLACK.getBlue() / 255F, 0.25F);

    private MouseBehaviorCallback _callback = null;

    //  A list of TransformChangeListeners.
    private final List<TransformChangeListener> _transformListeners = new ArrayList();

    //  Flag indicating that the view is currently being rotated.
    private boolean _isRotating = false;

    /**
     * Creates a <code>VirtualSphere</code> behavior associated with the specified canvas.
     *
     * @param canvas The Java3D canvas to associate this virtual sphere with.
     */
    public VirtualSphere(Canvas3D canvas) {
        super(0);
        _canvas = requireNonNull(canvas, "canvas == null");

        //  Set the initial size for the virtual sphere.
        updateCueSize(canvas);

        //  Add a component resize listener to the canvas.
        canvas.addComponentListener(new ComponentAdapter() {
            @Override
            public void componentResized(ComponentEvent e) {
                updateCueSize(e.getComponent());
            }
        });

    }

    /**
     * Creates a <code>VirtualSphere</code> behavior associated with the specified canvas.
     *
     * @param canvas The Java3D canvas to associate this virtual sphere with.
     */
    public VirtualSphere(JCanvas3D canvas) {
        super(0);
        _canvas = requireNonNull(canvas, "canvas == null");

        //  Set the initial size for the virtual sphere.
        updateCueSize(canvas);

        //  Add a component resize listener to the canvas.
        canvas.addComponentListener(new ComponentAdapter() {
            @Override
            public void componentResized(ComponentEvent e) {
                updateCueSize(e.getComponent());
            }
        });

    }

    /**
     * Initializes the behavior.
     */
    @Override
    public void initialize() {
        super.initialize();
        if ((this.flags & INVERT_INPUT) == INVERT_INPUT) {
            this.invert = true;
            _xTransFactor *= -1;
            _yTransFactor *= -1;
            _zoomFactor *= -1;
            _wheelZoomFactor *= -1;
        }
    }

    /**
     * Return the x-axis translation multiplier.
     *
     * @return The x-axis translation multiplier.
     */
    public double getXTranslationFactor() {
        return _xTransFactor;
    }

    /**
     * Return the y-axis translation multiplier.
     *
     * @return The y-axis translation multiplier.
     */
    public double getYTranslationFactor() {
        return _yTransFactor;
    }

    /**
     * Return the mouse zoom multiplier.
     *
     * @return The mouse zoom multiplier.
     */
    public double getMouseZoomFactor() {
        return _zoomFactor;
    }

    /**
     * Return the scroll wheel zoom multiplier.
     *
     * @return The scroll wheel zoom multiplier.
     */
    public double getWheelZoomFactor() {
        return _wheelZoomFactor;
    }

    /**
     * Set the X-axis and Y-axis translation multiplier factor.
     *
     * @param factor The factor to set the X & Y axis translation multiplier to.
     */
    public void setTranslationFactor(double factor) {
        _xTransFactor = _yTransFactor = factor;
    }

    /**
     * Set the X-axis and Y-axis translation multiplier with xFactor and yFactor
     * respectively.
     *
     * @param xFactor The X-axis translation multiplier factor.
     * @param yFactor The Y-axis translation multiplier factor.
     */
    public void setTranslationFactor(double xFactor, double yFactor) {
        _xTransFactor = xFactor;
        _yTransFactor = yFactor;
    }

    /**
     * Set the mouse zoom multiplier factor.
     *
     * @param factor The mouse zoom multiplier.
     */
    public void setMouseZoomFactor(double factor) {
        _zoomFactor = factor;
    }

    /**
     * Set the scroll wheel zoom multiplier with factor.
     *
     * @param factor The scroll wheel zoom multiplier.
     */
    public void setWheelZoomFactor(double factor) {
        _wheelZoomFactor = factor;
    }

    /**
     * Return the zoom scale. This is the scale factor applied to the model to zoom in/out
     * before the model is displayed.
     *
     * @return The zoom scale.
     */
    public double getZoomScale() {
        return _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.
     *
     * @param zoomScale The zoom scale to set.
     */
    public void setZoomScale(double zoomScale) {
        if (zoomScale <= 0)
            return;

        //  Get the current transform.
        this.transformGroup.getTransform(this.currXform);

        //  Remove the current zoom transformation.
        doZoom(this.currXform, 1.0 / _zoomScale);

        //  Store the new zoom scale.
        _zoomScale = zoomScale;

        //  Zoom the transformation matrix.
        doZoom(this.currXform, zoomScale);

        //  Update the transform.
        this.transformGroup.setTransform(this.currXform);

        //  Notify any transform listeners.
        fireTransformChanged(TransformChangeEvent.Type.ZOOM, this.currXform);
    }

    /**
     * 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.
     *
     * @param rotationCenter The point about which the model should be rotated in virtual
     *                       world coordinates.
     */
    public void setRotationCenter(Point3d rotationCenter) {
        requireNonNull(rotationCenter, "rotationCenter == null");

        //  Get the current transform.
        this.transformGroup.getTransform(this.currXform);

        //  Get the current translation.
        this.currXform.get(_translation);

        //  Get the change in rotation center.
        double dx = rotationCenter.x;
        double dy = rotationCenter.y;
        double dz = rotationCenter.z;

        //  Change the translation to point to the new location.
        _translation.x -= dx;
        _translation.y -= dy;
        _translation.z -= dz;
        this.currXform.setTranslation(_translation);

        //  Update the transform.
        this.transformGroup.setTransform(this.currXform);

        //  Notify any transform listeners.
        fireTransformChanged(TransformChangeEvent.Type.TRANSLATE, this.currXform);
    }

    /**
     * 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.
     *
     * @param rotationCenter The point about which the model should be rotated in virtual
     *                       world coordinates.
     * @param zoomScale      The scale factor used to zoom the model.
     * @see #setZoomScale
     */
    public void setRotationCenter(Point3d rotationCenter, double zoomScale) {
        requireNonNull(rotationCenter, "rotationCenter == null");

        //  Get the current transform.
        this.transformGroup.getTransform(this.currXform);

        //  Get the change in rotation center.
        double dx = rotationCenter.x;
        double dy = rotationCenter.y;
        double dz = rotationCenter.z;

        //  Get the current translation.
        this.currXform.get(_translation);

        //  Change the translation to point to the new location.
        _translation.x -= dx;
        _translation.y -= dy;
        _translation.z -= dz;
        this.currXform.setTranslation(_translation);

        //  Remove the current zoom transformation.
        doZoom(this.currXform, 1.0 / _zoomScale);

        //  Store the new zoom scale.
        _zoomScale = zoomScale;

        //  Apply the new zoom scale.
        doZoom(this.currXform, zoomScale);

        //  Update the transform.
        this.transformGroup.setTransform(this.currXform);

        //  Notify any transform listeners.
        fireTransformChanged(TransformChangeEvent.Type.TRANSLATE, this.currXform);
        fireTransformChanged(TransformChangeEvent.Type.ZOOM, this.currXform);
    }

    /**
     * Change the current rotation matrix to the one specified.
     *
     * @param rotationMatrix The rotation matrix to be used.
     */
    public void setRotation(Matrix3d rotationMatrix) {
        requireNonNull(rotationMatrix, "rotationMatrix == null");

        //  Get the current transform.
        this.transformGroup.getTransform(this.currXform);

        //  Remove the current rotation.
        Matrix3d rotation = new Matrix3d();
        this.currXform.get(rotation);
        this.transformX.set(rotation);
        this.transformX.invert();
        this.currXform.mul(this.transformX, this.currXform);

        //  Change to the new orientation.
        this.transformX.set(rotationMatrix);
        this.currXform.mul(this.transformX, this.currXform);

        //  Update the transform.
        this.transformGroup.setTransform(this.currXform);

        //  Notify any transform listeners.
        fireTransformChanged(TransformChangeEvent.Type.ROTATE, this.currXform);
    }

    /**
     * Add a {@link TransformChangeListener} to this object.
     *
     * @param listener The listener to add.
     */
    public void addTransformChangeListener(TransformChangeListener listener) {
        _transformListeners.add(requireNonNull(listener, "listener == null"));
    }

    /**
     * Remove a {@link TransformChangeListener} from this object.
     *
     * @param listener The listener to add.
     */
    public void removeTransformChangeListener(TransformChangeListener listener) {
        _transformListeners.remove(requireNonNull(listener, "listener == null"));
    }

    /**
     * Returns an {@link BGFGImage} for use in an {@link 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.
     *
     * @return The Virtual Sphere feedback image.
     */
    public BGFGImage getFeedbackOverlay() {
        if (_overlay == null)
            _overlay = new VSOverlay();
        return _overlay;
    }

    /**
     * Returns the <code>Paint</code> used to render the virtual sphere overlay graphics.
     *
     * @return The Paint used to render the virtual sphere overlay graphics.
     */
    public Paint getOverlayPaint() {
        return _overlayPaint;
    }

    /**
     * Sets the <code>Paint</code> used to render the virtual sphere overlay graphics.
     *
     * @param paint The paint to use for the virtual sphere overlay graphics.
     */
    public void setOverlayPaint(Paint paint) {
        requireNonNull(paint, "paint == null");
        _overlayPaint = paint;
    }

    /**
     * An overlay that displays a visual representation of the virtual sphere for user
     * feedback.
     */
    private final class VSOverlay implements BGFGImage {

        private BufferedImage _bufIm = null;
        private Graphics2D _g2d = null;
        private int _xcue = 0;
        private int _ycue = 0;
        private int _cueDiameter = 0;

        public VSOverlay() {
            //  Initialize the image buffer.
            updateBufferSize(_canvas);
        }

        /**
         * Updates the size of the image buffer if the canvas size has changed.
         */
        public synchronized void updateBufferSize(Component canvas) {
            int width = canvas.getWidth();
            int height = canvas.getHeight();

            if (width == 0 || height == 0) {
                _cueDiameter = 0;
                _xcue = 0;
                _ycue = 0;

            } else {
                int newDiameter = min(width - 20, height - 20);
                if (newDiameter != _cueDiameter) {
                    _cueDiameter = newDiameter;
                    ++newDiameter;
                    //  Note:  Using BufferedImage.TYPE_4BYTE_ABGR is faster, but then the
                    //  canvas can not be resized.  This workaround seems to solve that problem
                    //  at the price of a little performance.
                    _bufIm = new BufferedImage(newDiameter, newDiameter, BufferedImage.TYPE_INT_ARGB);
                    _g2d = _bufIm.createGraphics();
                }
                _xcue = (width - _cueDiameter) / 2;
                _ycue = (height - _cueDiameter) / 2;
            }
        }

        /**
         * Returns the image overlay for use by an OverlayCanvas3D. The feedback image is
         * rendered here.
         */
        @Override
        public synchronized BufferedImage getImage() {
            if (_isRotating) {
                //  Clear the buffer and set the pen color.
                clearSurface(_g2d);

                //  Draw a circle around the perimeter of the virtual sphere.
                _g2d.drawOval(0, 0, _cueDiameter, _cueDiameter);

                //  Draw a cross-hair where the mouse touches the virtual sphere.
                drawMouseCue(_g2d);

                return _bufIm;
            }

            return null;
        }

        /**
         * Clears the buffered image to be 100% transparent.
         */
        private void clearSurface(Graphics2D drawg2d) {
            drawg2d.setComposite(AlphaComposite.getInstance(AlphaComposite.CLEAR, 0.0f));
            drawg2d.fillRect(0, 0, _cueDiameter + 1, _cueDiameter + 1);
            drawg2d.setComposite(AlphaComposite.getInstance(AlphaComposite.SRC_OVER, 1.0f));
            drawg2d.setPaint(_overlayPaint);
        }

        /**
         * Draws the mouse cue symbol.
         */
        private void drawMouseCue(Graphics2D g2d) {
            //  Get the mouse location relative to the cue center.
            int mouseX = _prevMouse.x - _cueCenter.x;
            int mouseY = _prevMouse.y - _cueCenter.y;
            int mouseX2 = mouseX * mouseX;
            int mouseY2 = mouseY * mouseY;
            int cueRadius2 = _cueRadius * _cueRadius;

            // Draw the mouse cue if we are over the sphere.
            if (mouseX2 + mouseY2 < cueRadius2) {

                // Draw the vertical cue line.
                if (abs(mouseX) > 2) {
                    //  Draw a vertical elliptical arc through the mouse point.
                    double a = sqrt(mouseX2 / (1 - mouseY2 / (double)cueRadius2));
                    double newMouseX = mouseX * _cueRadius / a;
                    int angle = (int)(-atan2(mouseY, newMouseX) * 180 / PI);

                    //  Draw a piece of an ellipse.
                    int x = _cueRadius - (int)a;
                    g2d.drawArc(x, 0, (int)(a * 2), _cueDiameter, angle - CROSSHAIR_SIZE / 2, CROSSHAIR_SIZE);

                } else {
                    //  Mouse X near zero is a special case, just draw a vertical line.
                    double vy = mouseY / (double)_cueRadius;
                    double vy2 = vy * vy;
                    double vz = sqrt(1 - vy2);
                    double angle = atan2(vy, vz) - CROSSHAIR_SIZE * PI / 180 / 2;
                    double length = sqrt(vy2 + vz * vz) * _cueRadius;
                    int yl = (int)(length * sin(angle)) + _cueRadius;
                    int yh = (int)(length * sin(angle + CROSSHAIR_SIZE * PI / 180)) + _cueRadius;

                    //  Render the line.
                    int x = _prevMouse.x - _xcue;
                    g2d.drawLine(x, yl, x, yh);
                }

                //  Draw the horizontal cue line.
                if (abs(mouseY) > 2) {
                    //  Draw a horizontal elliptical arc through the mouse point.
                    double a = sqrt(mouseY2 / (1 - mouseX2 / (double)cueRadius2));
                    double newMouseY = mouseY * _cueRadius / a;
                    int angle = (int)(-atan2(newMouseY, mouseX) * 180 / PI);

                    //  Draw a piece of an ellipse.
                    int y = _cueRadius - (int)a;
                    g2d.drawArc(0, y, _cueDiameter, (int)(a * 2), angle - CROSSHAIR_SIZE / 2, CROSSHAIR_SIZE);

                } else {
                    //  Mouse Y near zero is a special case, just draw a horizontal line.
                    double vx = mouseX / (double)_cueRadius;
                    double vx2 = vx * vx;
                    double vz = sqrt(1 - vx2);
                    double angle = atan2(vx, vz) - CROSSHAIR_SIZE * PI / 180 / 2;
                    double length = sqrt(vx2 + vz * vz) * _cueRadius;
                    int xl = (int)(length * sin(angle)) + _cueRadius;
                    int xh = (int)(length * sin(angle + CROSSHAIR_SIZE * PI / 180)) + _cueRadius;

                    //  Render the line.
                    int y = _prevMouse.y - _ycue;
                    g2d.drawLine(xl, y, xh, y);
                }
            }
        }

        /**
         * Returns the X coordinate of the upper left corner of the image.
         */
        @Override
        public int getImageX() {
            return _xcue;
        }

        /**
         * Returns the Y coordinate of the upper left corner of the image.
         */
        @Override
        public int getImageY() {
            return _ycue;
        }
    }

    /**
     * Method that updates the cue center and cue radius based on the current size of the
     * canvas.
     */
    private void updateCueSize(Component canvas) {
        int width = canvas.getWidth();
        int height = canvas.getHeight();

        if (width == 0 || height == 0) {
            _cueCenter.x = 0;
            _cueCenter.y = 0;
            _cueRadius = 0;

        } else {
            _cueCenter.x = width / 2;
            _cueCenter.y = height / 2;
            _cueRadius = min(width - 20, height - 20) / 2;
        }

        if (_overlay != null)
            _overlay.updateBufferSize(canvas);
    }

    /**
     * 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.
     *
     * @param criteria An enumeration of triggered wakeup criteria for this behavior.
     */
    @Override
    @SuppressWarnings("SynchronizeOnNonFinalField")
    public void processStimulus(Iterator<WakeupCriterion> criteria) {
        requireNonNull(criteria, "criteria == null");
        WakeupCriterion wakeup;
        AWTEvent[] events;
        MouseEvent evt;

        while (criteria.hasNext()) {
            wakeup = criteria.next();
            if (wakeup instanceof WakeupOnAWTEvent) {
                events = ((WakeupOnAWTEvent)wakeup).getAWTEvent();
                if (events.length > 0) {
                    evt = (MouseEvent)events[events.length - 1];
                    doProcess(evt);
                }
            } else if (wakeup instanceof WakeupOnBehaviorPost) {
                while (true) {
                    // access to the queue must be synchronized
                    synchronized (mouseq) {
                        if (mouseq.isEmpty())
                            break;
                        evt = (MouseEvent)mouseq.remove(0);
                        // consolidate MOUSE_DRAG events
                        while ((evt.getID() == MouseEvent.MOUSE_DRAGGED)
                                && !mouseq.isEmpty()
                                && (((MouseEvent)mouseq.get(0)).getID() == MouseEvent.MOUSE_DRAGGED)) {
                            evt = (MouseEvent)mouseq.remove(0);
                        }
                        // consolidate MOUSE_WHEEL events
                        while ((evt.getID() == MouseEvent.MOUSE_WHEEL)
                                && !mouseq.isEmpty()
                                && (((MouseEvent)mouseq.get(0)).getID() == MouseEvent.MOUSE_WHEEL)) {
                            evt = (MouseEvent)mouseq.remove(0);
                        }
                    }
                    doProcess(evt);
                }
            }

        }
        wakeupOn(mouseCriterion);
    }

    /**
     * Processes the provided mouse event doing the right thing for each type.
     *
     * @param evt The mouse event to be processed.
     */
    protected void doProcess(MouseEvent evt) {

        processMouseEvent(requireNonNull(evt));
        int id = evt.getID();
        if ((id == MouseEvent.MOUSE_WHEEL)) {
            //  Mouse wheel event.
            int units = 0;

            MouseWheelEvent wheelEvent = (MouseWheelEvent)evt;
            if (wheelEvent.getScrollType() == MouseWheelEvent.WHEEL_UNIT_SCROLL)
                units = wheelEvent.getUnitsToScroll();

            handleWheelZoom(units);

        } else if (((this.buttonPress) && ((this.flags & MANUAL_WAKEUP) == 0))
                || ((this.wakeUp) && ((this.flags & MANUAL_WAKEUP) != 0))) {
            //  Mouse drag with mouse button pressed event.
            if (id == MouseEvent.MOUSE_DRAGGED) {
                if (!evt.isMetaDown() && !evt.isAltDown() && !evt.isControlDown()) {
                    _isRotating = true;
                    handleMouseRotate(evt);

                } else if (!evt.isAltDown() && evt.isMetaDown())
                    handleMouseTranslate(evt);

                else if (evt.isAltDown() && !evt.isMetaDown())
                    handleMouseZoom(evt);

            } else if (id == MouseEvent.MOUSE_PRESSED) {
                _prevMouse = evt.getPoint();
            }

        } else if (id == MouseEvent.MOUSE_RELEASED) {
            _isRotating = false;

            //  Redraw the overlay if the mouse is released.
            if (_overlay != null)
                fireTransformChanged(TransformChangeEvent.Type.ROTATE, this.currXform);
        }
    }

    /**
     * Handles the user dragging the mouse across the canvas to rotate the transform.
     */
    private void handleMouseRotate(MouseEvent evt) {
        Point newMouse = evt.getPoint();

        if (newMouse.x != _prevMouse.x || newMouse.y != _prevMouse.y) {
            if (!this.reset) {
                //  Get the current transform.
                this.transformGroup.getTransform(this.currXform);

                //  Calculate incremental transform due to mouse movement.
                makeRotationMtx(_prevMouse, newMouse, _cueCenter, _cueRadius, _mouseMtx);

                //  Rotate to the new orientation.
                this.currXform.mul(_mouseMtx, this.currXform);

                //  Update the transform.
                this.transformGroup.setTransform(this.currXform);

                //  Notify any transform listeners.
                fireTransformChanged(TransformChangeEvent.Type.ROTATE, this.currXform);

            } else {
                this.reset = false;
            }

            //  Update the mouse position.
            _prevMouse = newMouse;
        }

    }

    /**
     * Handles the user dragging the mouse across the canvas to translate the transform.
     */
    private void handleMouseTranslate(MouseEvent evt) {
        Point newMouse = evt.getPoint();

        if (newMouse.x != _prevMouse.x || newMouse.y != _prevMouse.y) {
            int dx = newMouse.x - _prevMouse.x;
            int dy = newMouse.y - _prevMouse.y;

            if ((!this.reset) && ((abs(dy) < 50) && (abs(dx) < 50))) {
                //  Get the current transform.
                this.transformGroup.getTransform(this.currXform);

                //  Create a translation matrix.
                _translation.x = dx * _xTransFactor;
                _translation.y = -dy * _yTransFactor;
                _translation.z = 0;
                this.transformX.set(_translation);

                //  Translate to the new orientation.
                if (this.invert) {
                    this.currXform.mul(this.currXform, this.transformX);
                } else {
                    this.currXform.mul(this.transformX, this.currXform);
                }

                //  Update the transform.
                this.transformGroup.setTransform(this.currXform);

                //  Notify any transform listeners.
                fireTransformChanged(TransformChangeEvent.Type.TRANSLATE, this.currXform);

            } else {
                this.reset = false;
            }

            //  Update the mouse position.
            _prevMouse = newMouse;
        }

    }

    /**
     * Handles the user dragging the mouse across the canvas to zoom the transform.
     */
    private void handleMouseZoom(MouseEvent evt) {
        Point newMouse = evt.getPoint();

        if (newMouse.y != _prevMouse.y) {

            if (!this.reset) {
                int dy = newMouse.y - _prevMouse.y;

                //  Get the current transform.
                this.transformGroup.getTransform(this.currXform);

                //  Determine the zoom scale amount.
                double factor = _zoomFactor * dy + 1;
                if (factor < 0.5)
                    factor = 0.5;
                else if (factor > 2)
                    factor = 2;

                //  Zoom the transformation matrix.
                doZoom(this.currXform, factor);
                _zoomScale *= factor;

                //  Update the transform.
                this.transformGroup.setTransform(this.currXform);

                //  Notify any transform listeners.
                fireTransformChanged(TransformChangeEvent.Type.ZOOM, this.currXform);

            } else {
                this.reset = false;
            }

            //  Update the mouse position.
            _prevMouse = newMouse;
        }

    }

    /**
     * Handles the user rolling the mouse scroll wheel.
     *
     * @param units The amount that the scroll wheel has been moved.
     */
    private void handleWheelZoom(int units) {
        if (units != 0) {
            if (!this.reset) {
                //  Get the current transform.
                this.transformGroup.getTransform(this.currXform);

                //  Determine the zoom screen Z translation amount.
                double factor = _wheelZoomFactor * units + 1;
                if (factor < 0.5)
                    factor = 0.5;
                else if (factor > 2)
                    factor = 2;

                //  Zoom the transformation matrix.
                doZoom(this.currXform, factor);
                _zoomScale *= factor;

                //  Update the transform.
                this.transformGroup.setTransform(this.currXform);

                //  Notify any transform listeners.
                fireTransformChanged(TransformChangeEvent.Type.ZOOM, this.currXform);

            } else {
                this.reset = false;
            }
        }
    }

    /**
     * Method that modifies the input transform by applying the specified scale factor to
     * the specified transform.
     *
     * @param t3d       The transform to be scaled to represent the zoom. This transform
     *                  is modified in place for output.
     * @param zoomScale The scale factor to apply to the transform. Value must be > 0 or
     *                  it will be ignored.
     */
    private void doZoom(Transform3D t3d, double zoomScale) {
        if (zoomScale <= 0)
            return;

        //  Create a transform representing the uniform scale.
        this.transformX.set(zoomScale);

        //  Zoom to the new scale.
        if (this.invert) {
            t3d.mul(t3d, this.transformX);
        } else {
            t3d.mul(this.transformX, t3d);
        }

    }

    /**
     * Fire a transform changed event to notify any listeners of changes in the
     * transformation.
     */
    private void fireTransformChanged(TransformChangeEvent.Type type, Transform3D transform) {
        //  First call the transformChanged() method.
        transformChanged(transform);

        //  Then notify the callback if it exists.
        if (_callback != null) {
            int typeCode = MouseBehaviorCallback.ROTATE;
            if (type.equals(TransformChangeEvent.Type.TRANSLATE))
                typeCode = MouseBehaviorCallback.TRANSLATE;
            else if (type.equals(TransformChangeEvent.Type.ZOOM))
                typeCode = MouseBehaviorCallback.ZOOM;

            _callback.transformChanged(typeCode, transform);
        }

        //  Now notify listeners.
        TransformChangeEvent event = new TransformChangeEvent(this, type, transform);
        for (TransformChangeListener listener : _transformListeners) {
            listener.transformChanged(event);
        }
    }

    /**
     * Users can overload this method which is called every time the Behavior updates the
     * transform.
     *
     * This default implementation does nothing.
     *
     * @param transform The new 3D transform.
     */
    public void transformChanged(Transform3D transform) {
    }

    /**
     * The transformChanged method in the callback class will be called every time the
     * transform is updated
     *
     * @param callback The mouse behavior callback. May pass null for no callback.
     */
    public void setupCallback(MouseBehaviorCallback callback) {
        _callback = callback;
    }

    /**
     * Calculate a rotation matrix based on the axis and angle of rotation from the last 2
     * locations of the mouse relative to the VirtualSphere cue circle.
     *
     * @param pnt1      The 1st mouse location in the window.
     * @param pnt2      The 2nd mouse location in the window.
     * @param cueCenter The center of the virtual sphere in the window.
     * @param cueRadius The radius of the virtual sphere.
     * @param rotMatrix Preallocated rotation matrix to be filled in by this method. This
     *                  matrix will be overwritten by this method.
     * @return A reference to the input rotMatrix is returned with the elements filled in.
     */
    private Transform3D makeRotationMtx(Point pnt1, Point pnt2, Point cueCenter, int cueRadius,
            Transform3D rotMatrix) {

        // Vectors "op" and "oq" are defined as class variables to avoid wastefull memory allocations.
        // Project mouse points to 3-D points on the +z hemisphere of a unit sphere.
        pointOnUnitSphere(pnt1, cueCenter, cueRadius, _op);
        pointOnUnitSphere(pnt2, cueCenter, cueRadius, _oq);

        /* Consider the two projected points as vectors from the center of the 
         *  unit sphere. Compute the rotation matrix that will transform vector
         *  op to oq.  */
        setRotationMatrix(rotMatrix, _op, _oq);

        return rotMatrix;
    }

    /**
     * Project a 2D point on a circle to a 3D point on the +z hemisphere of a unit sphere.
     * If the 2D point is outside the circle, it is first mapped to the nearest point on
     * the circle before projection. Orthographic projection is used, though technically
     * the field of view of the camera should be taken into account. However, the
     * discrepancy is negligible.
     *
     * @param p         Window point to be projected onto the sphere.
     * @param cueCenter Location of center of virtual sphere in window.
     * @param cueRadius The radius of the virtual sphere.
     * @param v         Storage for the 3D projected point created by this method.
     */
    private static void pointOnUnitSphere(Point p, Point cueCenter, int cueRadius, Vector3d v) {

        /* Turn the mouse points into vectors relative to the center of the circle
         *  and normalize them.  Note we need to flip the y value since the 3D coordinate
         *  has positive y going up.  */
        double vx = (p.x - cueCenter.x) / (double)cueRadius;
        double vy = (cueCenter.y - p.y) / (double)cueRadius;
        double lengthSqared = vx * vx + vy * vy;

        /* Project the point onto the sphere, assuming orthographic projection.
         *  Points beyond the virtual sphere are normalized onto 
         *  edge of the sphere (where z = 0).  */
        double vz = 0;
        if (lengthSqared < 1)
            vz = sqrt(1.0 - lengthSqared);

        else {
            double length = sqrt(lengthSqared);
            vx /= length;
            vy /= length;
        }

        v.x = vx;
        v.y = vy;
        v.z = vz;
    }

    /**
     * Computes a`ap (rotate) vectors op onto oq. The rotation is about an axis
     * perpendicular to op and oq. Note this routine won't work if op or oq are zero
     * vectors, or if they are parallel or antiparallel to each other.
     *
     * <p>
     * Modification of Michael Pique's formula in Graphics Gems Vol. 1. Andrew Glassner,
     * Ed. Addison-Wesley.</p>
     *
     * @param rotationMatrix The rotation matrix to be filled in.
     * @param op             The 1st 3D vector.
     * @param oq             The 2nd 3D vector.
     */
    private void setRotationMatrix(Transform3D rotationMatrix, Vector3d op, Vector3d oq) {

        // Vector "av" is defined as a class variable to avoid wastefull memory allocations.
        _av.cross(op, oq);          //  av = op X oq
        double cosA = op.dot(oq);   //  cosA = op * oq

        //  Set the axis angle object.
        _a1.set(_av, acos(cosA));

        //  Set the rotation matrix.
        rotationMatrix.set(_a1);
    }

}