## Class Transform3D

- java.lang.Object
- vmm3d.core.Transform
- vmm3d.core3D.Transform3D

- All Implemented Interfaces:
- Cloneable

public class Transform3Dextends 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

Methods Modifier and Type Method and Description `void`

**applyTransvection**(Vector3D e1, Vector3D e2)Rotates vector e1 onto vector e2, resulting in a change of view.`Object`

**clone**()Creates a copy of this Transform3D.`boolean`

**equals**(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).`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, 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.`Point2D`

**objectToXYWindowCoords**(Vector3D objectPoint)Project a world-coordinate point onto the view plane.`void`

**objectToXYWindowCoords**(Vector3D objectPoint, 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`

### 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.

#### 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.

#### 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(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.

#### 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).

#### 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, 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 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, 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 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.

**SCaVis 2.0 © jWork.ORG**