Module org.jfree.chart3d
Package org.jfree.chart3d.graphics3d

# Class ViewPoint3D

java.lang.Object
org.jfree.chart3d.graphics3d.ViewPoint3D

All Implemented Interfaces:
  `Serializable`

public class ViewPoint3D extends Object implements Serializable
Specifies the location and orientation of the view point in 3D space. Assumes the eye looks towards the origin in world coordinates.
There are four basic operations to move the view point:

- `panLeftRight(double)` - rotates around the scene horizontally from the perspective of the viewer;
- `moveUpDown(double)` - rotates around the scene vertically from the perspective of the viewer;
- `roll(double)` - maintains the same viewing location but rolls by the specified angle (like tilting a camera);
- `setRho(double)` - sets the distance of the view location from the center of the 3D scene (zoom in and out).

NOTE: This class is serializable, but the serialization format is subject to change in future releases and should not be relied upon for persisting instances of this class.

See Also:
  - Serialized Form

## Constructor Summary

Constructors
Constructor
Description
`ViewPoint3D(double theta, double phi, double rho, double orientation)`
Creates a new viewing point.
`ViewPoint3D(Point3D p, double orientation)`
Creates a new instance using the specified point and orientation.
`ViewPoint3D(ViewPoint3D vp)`
Creates a new instance that is an exact copy of the supplied viewpoint.

## Method Summary

Modifier and Type
Method
Description
`double`
`calcRollAngle()`
Returns the roll angle (orientation) for the view point.
`static ViewPoint3D`
`createAboveLeftViewPoint(double rho)`
Creates and returns a view point for looking at a chart from the front and above and to the left.
`static ViewPoint3D`
`createAboveRightViewPoint(double rho)`
Creates and returns a view point for looking at a chart from the front and above and to the right.
`static ViewPoint3D`
`createAboveViewPoint(double rho)`
Creates and returns a view point for looking at a chart from the front and above.
`boolean`
`equals(Object obj)`
Tests this view point for equality with an arbitrary object.
`Point3D`
`getHorizontalRotationAxis()`
Returns a vector at right angles to the viewing direction and the "up" vector (this axis can be used to rotate forward and backwards).
`final double`
`getPhi()`
Returns the angle of the viewing point down from the z-axis.
`final Point3D`
`getPoint()`
Returns the location of the view point.
`final double`
`getRho()`
Returns the distance of the viewing point from the origin.
`final double`
`getTheta()`
Returns the angle of rotation from the x-axis about the z-axis, in radians.
`Point3D`
`getVerticalRotationAxis()`
Returns the vector that points "up" in relation to the orientation of the view point.
`final double`
`getX()`
Returns the x-coordinate of the viewing point.
`final double`
`getY()`
Returns the y-coordinate of the viewing point.
`final double`
`getZ()`
Returns the z-coordinate of the viewing point.
`void`
`moveUpDown(double delta)`
Moves the viewing point up or down on the viewing sphere.
`float`
`optimalDistance(Dimension2D target, Dimension3D dim3D, double projDist)`
Calculate the distance that would render a box of the given dimensions within a screen area of the specified size.
`void`
`panLeftRight(double delta)`
Moves the viewing point left or right around the 3D scene.
`void`
`roll(double delta)`
Rolls the view while leaving the location of the view point unchanged.
`void`
`setRho(double rho)`
Sets the distance of the viewing point from the origin.
`String`
`toString()`
Returns a string representation of this instance, primarily for debugging purposes.
`Point3D`
`worldToEye(Point3D p)`
Converts a point in world coordinates to a point in eye coordinates.
`Point2D`
`worldToScreen(Point3D p, double d)`
Calculates and returns the screen coordinates for the specified point in (world) 3D space.

### Methods inherited from class java.lang.Object

`clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

## Constructor Details

### ViewPoint3D

public ViewPoint3D(double theta, double phi, double rho, double orientation)
Creates a new viewing point.

Parameters:
  `theta` - the rotation of the viewing point from the x-axis around the z-axis (in radians)
  `phi` - the rotation of the viewing point up and down (from the XZ plane, in radians)
  `rho` - the distance of the viewing point from the origin.
  `orientation` - the angle of rotation.

### ViewPoint3D

public ViewPoint3D(Point3D p, double orientation)
Creates a new instance using the specified point and orientation.

Parameters:
  `p` - the viewing point.
  `orientation` - the orientation.

### ViewPoint3D

public ViewPoint3D(ViewPoint3D vp)
Creates a new instance that is an exact copy of the supplied viewpoint.

Parameters:
  `vp` - the view point (`null` not permitted).
Since:
  1.6.1

## Method Details

### createAboveViewPoint

public static ViewPoint3D createAboveViewPoint(double rho)
Creates and returns a view point for looking at a chart from the front and above.

Parameters:
  `rho` - the distance.
Returns:
  A view point.

### createAboveLeftViewPoint

public static ViewPoint3D createAboveLeftViewPoint(double rho)
Creates and returns a view point for looking at a chart from the front and above and to the left.

Parameters:
  `rho` - the distance.
Returns:
  A view point.

### createAboveRightViewPoint

public static ViewPoint3D createAboveRightViewPoint(double rho)
Creates and returns a view point for looking at a chart from the front and above and to the right.

Parameters:
  `rho` - the distance.
Returns:
  A view point.

### getTheta

public final double getTheta()
Returns the angle of rotation from the x-axis about the z-axis, in radians. This attribute is set via the constructor and updated via the `panLeftRight(double)` and `moveUpDown(double)` methods - there is no setter method, you cannot update it directly.

Returns:
  The angle (in radians).

### getPhi

public final double getPhi()
Returns the angle of the viewing point down from the z-axis. This attribute is set via the constructor and updated via the `panLeftRight(double)` and `moveUpDown(double)` methods - there is no setter method, you cannot update it directly.

Returns:
  The angle of the viewing point down from the z-axis. (in radians).

### getRho

public final double getRho()
Returns the distance of the viewing point from the origin.

Returns:
  The distance of the viewing point from the origin.
See Also:
  - `setRho(double)`

### setRho

public void setRho(double rho)
Sets the distance of the viewing point from the origin.

Parameters:
  `rho` - the new distance.

### getX

public final double getX()
Returns the x-coordinate of the viewing point. This value is calculated from the spherical coordinates.

Returns:
  The x-coordinate of the viewing point.

### getY

public final double getY()
Returns the y-coordinate of the viewing point. This value is calculated from the spherical coordinates.

Returns:
  The y-coordinate of the viewing point.

### getZ

public final double getZ()
Returns the z-coordinate of the viewing point. This value is calculated from the spherical coordinates.

Returns:
  The z-coordinate of the viewing point.

### getPoint

public final Point3D getPoint()
Returns the location of the view point. Note that a new instance of `Point3D` is created each time this method is called.

Returns:
  The viewing point (never `null`).

### calcRollAngle

public double calcRollAngle()
Returns the roll angle (orientation) for the view point. This is calculated by reference to second point on the sphere that is a quarter turn from the view point location (this second point defines the "up" direction for the view).

Returns:
  The roll angle (in radians).

### panLeftRight

public void panLeftRight(double delta)
Moves the viewing point left or right around the 3D scene.

Parameters:
  `delta` - the angle (in radians).

### moveUpDown

public void moveUpDown(double delta)
Moves the viewing point up or down on the viewing sphere.

Parameters:
  `delta` - the angle delta (in radians).

### roll

public void roll(double delta)
Rolls the view while leaving the location of the view point unchanged.

Parameters:
  `delta` - the angle (in radians).

### worldToEye

public Point3D worldToEye(Point3D p)
Converts a point in world coordinates to a point in eye coordinates.

Parameters:
  `p` - the point (`null` not permitted).
Returns:
  The point in eye coordinates.

### worldToScreen

public Point2D worldToScreen(Point3D p, double d)
Calculates and returns the screen coordinates for the specified point in (world) 3D space.

Parameters:
  `p` - the point.
  `d` - the projection distance.
Returns:
  The screen coordinate.

### optimalDistance

public float optimalDistance(Dimension2D target, Dimension3D dim3D, double projDist)
Calculate the distance that would render a box of the given dimensions within a screen area of the specified size.

Parameters:
  `target` - the target dimension (`null` not permitted).
  `dim3D` - the dimensions of the 3D content (`null` not permitted).
  `projDist` - the projection distance.
Returns:
  The optimal viewing distance.

### getVerticalRotationAxis

public Point3D getVerticalRotationAxis()
Returns the vector that points "up" in relation to the orientation of the view point. This vector can be used to rotate the viewing point around the 3D scene (pan left / right).

Returns:
  The vector (never `null`).

### getHorizontalRotationAxis

public Point3D getHorizontalRotationAxis()
Returns a vector at right angles to the viewing direction and the "up" vector (this axis can be used to rotate forward and backwards).

Returns:
  A vector (never `null`).

### toString

public String toString()
Returns a string representation of this instance, primarily for debugging purposes.

Overrides:
  `toString` in class `Object`
Returns:
  A string.

### equals

public boolean equals(Object obj)
Tests this view point for equality with an arbitrary object.

Overrides:
  `equals` in class `Object`
Parameters:
  `obj` - the object (`null` permitted).
Returns:
  A boolean.