vmm3d.core3D

Class Transform3D

java.lang.Object

vmm3d.core.Transform

vmm3d.core3D.Transform3D

All Implemented Interfaces:

java.lang.Cloneable

public class Transform3D
extends Transform

A transform that encodes a 3D view of an exhibit and the projection of that view onto a 2D view plane. This class inherits the window-to-viewport transformation from its superclass, and adds a 3D viewing transformation.

The projection is defined by three unit vectors: ViewDirection, ImagePlaneYDirection, and ImagePlaneXDirection. The ViewDirection is determined by the viewpoint that is specified for the view; ViewDirection is a unit vector that points in the direction from the viewpoint towards (0,0,0). The ViewDirection determines the viewing plane, which is a plane through (0,0,0) normal to the view direction. The ImagePlaneYDirection vector is obtained by projecting a "view up" vector onto the viewing plane, and then normalizing the projection. Initially, the view up vector is (0,0,1) or, if (0,0,1) almost normal to the view plane, (0,1,0). When the viewpoint is modified, the new ImagePlaneYDirection is obtained by using the previous ImagePlaneYDirection as the view up vector, if possible. After the ViewDirection and ImagePlaneYDirection are determined, the ImagePlaneXDirection is simply the cross product of these two vectors.

The transform also has an associated "focalLength" which is set to the distance of the viewpoint from the origin, and a clipDistance, which is set to 25% of the focal length.

A Transform3D fires a ChangeEvent when any part of the data that determines a 3D view is changed, such as the viewpoint.

(Note that in the default view, the yz-plane projects onto the screen, and the x-axis is perpendicular to the screen. Nevertheless, the screen is thought of as being the xy-plane.) TODO: Possibly add support for using a point other than (0,0,0) as the view reference point; check how clip distance and focal length should be changed when viewpoint is changed.

Constructor Summary

Constructors

Constructor and Description
Transform3D() Creates a Transform3D object with default viewpoint (20,0,0) and a default window with x and y ranges from -5 to 5.
Transform3D(Transform tr) Construct a Transform3D with the same transform data as a specified transform.
Transform3D(Vector3D viewPoint) Creates a Transform3D object with a specified viewpoint and a default window with x and y ranges from -5 to 5.
Transform3D(Vector3D viewPoint, double nominalGraphicScale) Creates a Transform3D with a specifed viewpoint and with an xy-window determined by a given "graphic scale"
Transform3D(Vector3D viewPoint, double xmin, double xmax, double ymin, double ymax) Construct a Transform3D with specified viewpoint and xy-window.

Method Summary

Modifier and Type	Method and Description
void	applyTransvection(Vector3D e1, Vector3D e2) Rotates vector e1 onto vector e2, resulting in a change of view.
java.lang.Object	clone() Creates a copy of this Transform3D.
boolean	equals(java.lang.Object obj) Tests whether obj is a Transform3D with the same transform data as this transform, that is, both Transform.hasSameViewTransform(Transform) and hasSameProjection(Transform3D) are true.
double	getClipDistance() Returns the clip distance.
double	getFocalLength() Gets the focal length, which is just the distance from the viewpoint to the origin.
Vector3D	getImagePlaneXDirection() Gets the current ImagePlaneXDirection, one of the three unit vectors that determine the projection.
Vector3D	getImagePlaneYDirection() Gets the current ImagePlaneYDirection, one of the three unit vectors that determine the projection.
double	getObjectDisplacementNormalToScreen() Get the amount by which object coordinates are displaed normal to the screen.
boolean	getOrthographicProjection() Returns true if the projection is an orthographic projection, or false if it is a perspective projection.
Vector3D	getViewDirection() Gets the current ViewDirection, one of the three unit vectors that determine the projection.
Vector3D	getViewPoint() Returns the current viewpoint of the transformation.
boolean	hasSameProjection(Transform3D tr) Tests whether tr has the same projection from 3D to the view plane as this transform (but not necessarily the same window and viewport).
java.awt.geom.Point2D	objectToDrawingCoords(Vector3D objectPoint) Transform a point given in world coordinates to a 2D point that can be used for drawing on the view plane.
void	objectToDrawingCoords(Vector3D objectPoint, java.awt.geom.Point2D drawingCoords) Transform a point given in world coordinates to a 2D point that can be used for drawing on the view plane.
Vector3D	objectToViewCoords(Vector3D objectPoint) Transform a point in world coordinates to viewing coodinates.
void	objectToViewCoords(Vector3D objectPoint, Vector3D viewCoords) Transform a point from object coordinates to viewing coordinates.
double	objectToViewZ(Vector3D objectPoint) Compute just the z-coordinate of a given point in view coordinates.
java.awt.geom.Point2D	objectToXYWindowCoords(Vector3D objectPoint) Project a world-coordinate point onto the view plane.
void	objectToXYWindowCoords(Vector3D objectPoint, java.awt.geom.Point2D p) Project a world-coordinate point onto the view plane.
void	setClipDistance(double clipDistance) Set the clip distance.
void	setImagePlaneYDirection(Vector3D viewUp) Sets both the imagePlaneYDirection and imagePlaneXDirection so that these two vectors and the viewDirection (which points to the viewpoint) form an orthonomal system.
void	setObjectDisplacementNormalToScreen(double objectDisplacementNormalToScreen) Set the amount by which object coordinates are displaed normal to the screen.
void	setOrthographicProjection(boolean orthographicProjection) Sets whether the projection from 3D onto the viewplane should be a perspective projection or an orthographic projection.
void	setViewPoint(Vector3D viewPoint) Sets the viewpoint of the transformation.

Methods inherited from class vmm3d.core.Transform

addChangeListener, appliedTransform2D, finishDrawing, getDefaultStrokeSize, getGraphics, getHeight, getPixelHeight, getPixelWidth, getUntransformedGraphics, getWidth, getX, getXmax, getXmaxRequested, getXmin, getXminRequested, getY, getYmax, getYmaxRequested, getYmin, getYminRequested, hasSameViewTransform, removeChangeListener, setLimits, setUpDrawInfo, viewportToWindow, windowToDrawingCoords, windowToViewport

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Transform3D

public Transform3D()

Creates a Transform3D object with default viewpoint (20,0,0) and a default window with x and y ranges from -5 to 5.

Transform3D

public Transform3D(Vector3D viewPoint)

Creates a Transform3D object with a specified viewpoint and a default window with x and y ranges from -5 to 5.

Parameters:

viewPoint - the viewpoint of the transformation. If null, the default, (20,0,0), is used.

Transform3D

public Transform3D(Vector3D viewPoint,
                   double nominalGraphicScale)

Creates a Transform3D with a specifed viewpoint and with an xy-window determined by a given "graphic scale"

Parameters:

viewPoint - the viewpoint of the transformation. If null, the default, (20,0,0), is used.

nominalGraphicScale - number of pixels per unit along the x- and y-axes, assuming that the size of the window is "normal". The normal size is given by a private constant NORMAL_SIZE, which is set to 600 at the time this comment was written.

Transform3D

public Transform3D(Vector3D viewPoint,
                   double xmin,
                   double xmax,
                   double ymin,
                   double ymax)

Construct a Transform3D with specified viewpoint and xy-window. The transformation is not fully determined until a viewport in the viewing plane is also specified; this is done when Transform#setUpDrawInfo(Graphics2D, int, int, int, int, boolean, boolean) is called. Note that when that method is called with its preserveAspect option set to true, the requested xmin, xmax, ymin, and ymax values might be adjusted to make the aspect ratio of the xy-window match the aspect ratio of the viewport.

Parameters:

viewPoint - The viewpoint of the transformation; if null, the default, (20,0,0), is used.

xmin - the requested mimimum x-value for the transformation

xmax - the requested maximum x-value for the transformation

ymin - the requested mimimum y-value for the transformation

ymax - the requested maximum y-value for the transformation

Transform3D

public Transform3D(Transform tr)

Construct a Transform3D with the same transform data as a specified transform. If the specfied transform is not a Transform3D, only the xy-window is copied; if it is a Transform3D, the 3D transformation data is also copied.

Parameters:

tr - the non-null transform whose data is to be copied.

Method Detail

getOrthographicProjection

public boolean getOrthographicProjection()

Returns true if the projection is an orthographic projection, or false if it is a perspective projection.

See Also:

setOrthographicProjection(boolean)

setOrthographicProjection

public void setOrthographicProjection(boolean orthographicProjection)

Sets whether the projection from 3D onto the viewplane should be a perspective projection or an orthographic projection.

Parameters:

orthographicProjection - "true" to use an orthographic projection; "false" to use a perspective projection.

setViewPoint

public void setViewPoint(Vector3D viewPoint)

Sets the viewpoint of the transformation. Note that when this method is called, a new transformation is defined which has a viewDirection specified by the viewpoint. This method then sets ImagePlaneYDirection and ImagePlaneXDirection by calling setImagePlaneYDirection(Vector3D) with the current ImagePlaneYDirection as parameter. In addition, the focal length is set to the distance of the viewpoint from (0,0,0), the clip distance is set to 0.25 times the focal length, and the ViewDirection is set to be a unit vector that points from the viewpoint towards (0,0,0).

Parameters:

viewPoint - the new viewpoint; if null, the default, (20,0,0), is used. The viewpoint cannot be (0,0,0), or the result will be an undefined transformation. Note that a copy of the viewPoint parameter is made (if it is non-null). (Note: Also turns off left/right eye selection, if in use.)

getViewPoint

public Vector3D getViewPoint()

Returns the current viewpoint of the transformation.

Returns:

a non-null vector that is the curent viewpoint.

getClipDistance

public double getClipDistance()

Returns the clip distance.

See Also:

setClipDistance(double)

setClipDistance

public void setClipDistance(double clipDistance)

Set the clip distance. This value is also set when the viewpoint is modified by setViewPoint(Vector3D). That method sets the clipDistance to 0.25 times the distance from the viewpoint to the origin.

getFocalLength

public double getFocalLength()

Gets the focal length, which is just the distance from the viewpoint to the origin.

getObjectDisplacementNormalToScreen

public double getObjectDisplacementNormalToScreen()

Get the amount by which object coordinates are displaed normal to the screen.

See Also:

setObjectDisplacementNormalToScreen(double)

setObjectDisplacementNormalToScreen

public void setObjectDisplacementNormalToScreen(double objectDisplacementNormalToScreen)

Set the amount by which object coordinates are displaed normal to the screen. Value is clamped so that its absolute value is less than or equal to 3/4 of the focal length. Before the object-to-view coordinate transformation is applied to any point, that point is displaced in the direction of the viewDirection vector by an amount equal to the setting of objectDisplacementNormalToScreen. The default value is zero. (In View3D, the amount is always 0 in monocular view modes, but can be chaned for the stereo views. BasicMouseTask3D allows the user to adjust this value for anaglyph views by holding down the shift key while dragging with the middle mouse button or by holding down the shift and option/ALT keys while dragging.) A ChangeEvent is generated when the value of this property is changed.

getImagePlaneXDirection

public Vector3D getImagePlaneXDirection()

Gets the current ImagePlaneXDirection, one of the three unit vectors that determine the projection.

See Also:

setImagePlaneYDirection(Vector3D)

getImagePlaneYDirection

public Vector3D getImagePlaneYDirection()

Gets the current ImagePlaneYDirection, one of the three unit vectors that determine the projection.

See Also:

setImagePlaneYDirection(Vector3D)

getViewDirection

public Vector3D getViewDirection()

Gets the current ViewDirection, one of the three unit vectors that determine the projection.

See Also:

setViewPoint(Vector3D), setImagePlaneYDirection(Vector3D)

setImagePlaneYDirection

public void setImagePlaneYDirection(Vector3D viewUp)

Sets both the imagePlaneYDirection and imagePlaneXDirection so that these two vectors and the viewDirection (which points to the viewpoint) form an orthonomal system. (Note: Also turns off left/right eye selection, if in use.)

Parameters:

viewUp - the new imagePlaneYDirection, which will point upwards on the screen.

applyTransvection

public void applyTransvection(Vector3D e1,
                              Vector3D e2)

Rotates vector e1 onto vector e2, resulting in a change of view. A ChangeEvent is generated

equals

public boolean equals(java.lang.Object obj)

Tests whether obj is a Transform3D with the same transform data as this transform, that is, both Transform.hasSameViewTransform(Transform) and hasSameProjection(Transform3D) are true.

Overrides:

equals in class Transform

hasSameProjection

public boolean hasSameProjection(Transform3D tr)

Tests whether tr has the same projection from 3D to the view plane as this transform (but not necessarily the same window and viewport).

clone

public java.lang.Object clone()

Creates a copy of this Transform3D.

Overrides:

clone in class Transform

objectToViewCoords

public void objectToViewCoords(Vector3D objectPoint,
                               Vector3D viewCoords)

Transform a point from object coordinates to viewing coordinates. After this method, the x- and y- coordinates of the resulting vector are coordinates for the viewing plane, while the z-coordinate encodes the distance of the object point from the viewing plane.

Parameters:

objectPoint - The non-null point whose coordinates are to be transformed. This vector is not modified.

viewCoords - The non-null vector that will contain the result after this method is called. The previous components of this vector are replaced with the transformed version of objectPoint.

objectToViewCoords

public Vector3D objectToViewCoords(Vector3D objectPoint)

Transform a point in world coordinates to viewing coodinates. This is done by calling objectToViewCoords(Vector3D, Vector3D) with a newly created vector as its second argument, and then returning that vector.

Parameters:

objectPoint - The non-null point that is to be transformed

Returns:

The transformed version of objectPoint

objectToXYWindowCoords

public void objectToXYWindowCoords(Vector3D objectPoint,
                                   java.awt.geom.Point2D p)

Project a world-coordinate point onto the view plane. This is the same as taking just the x- and y-coordinate from the vector computed by objectToViewCoords(Vector3D, Vector3D).

Parameters:

objectPoint - a non-null vector whose corrdinates are to be transformed

p - a non-null point whose coordinates will be set to the projected (x,y) point.

objectToXYWindowCoords

public java.awt.geom.Point2D objectToXYWindowCoords(Vector3D objectPoint)

Project a world-coordinate point onto the view plane. This is done by calling objectToDrawingCoords(Vector3D, Point2D) with a newly created Poin2D as its second parameter, and then returning that point.

objectToDrawingCoords

public void objectToDrawingCoords(Vector3D objectPoint,
                                  java.awt.geom.Point2D drawingCoords)

Transform a point given in world coordinates to a 2D point that can be used for drawing on the view plane. If the Transform.appliedTransform2D property is true, the result is the same as the result of objectToXYWindowCoords(Vector3D, Point2D), since regular xy window coordinates can be used for drawing directly. If the Transform.appliedTransform2D property is false, then the xy-coordinates are further transformed to the viewport (pixel) coordintates that are needed for drawing.

Parameters:

objectPoint - The point whose coordinates are to be projeted and transformed.

drawingCoords - A pre-allocated non-null point to contain the result.

objectToDrawingCoords

public java.awt.geom.Point2D objectToDrawingCoords(Vector3D objectPoint)

Transform a point given in world coordinates to a 2D point that can be used for drawing on the view plane. This is done by applying objectToDrawingCoords(Vector3D, Point2D) to a newly allocated Point2D, and then returning that point.

objectToViewZ

public double objectToViewZ(Vector3D objectPoint)

Compute just the z-coordinate of a given point in view coordinates. This is the same as the z value in the vector that would be returned by objectToViewCoords(Vector3D)

Parameters:

objectPoint - the untransformed point in object coordinates

Returns:

the z-coordinate of the transformed point.