com.orsoncharts.graphics3d

## Class ViewPoint3D

- java.lang.Object
- - com.orsoncharts.graphics3d.ViewPoint3D

- All Implemented Interfaces:
    java.io.Serializable

      public class ViewPoint3D
      extends java.lang.Object
      implements java.io.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 and 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.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and 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(java.lang.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).
    `double` | `getPhi()` Returns the angle of the viewing point down from the z-axis.
    `Point3D` | `getPoint()` Returns the location of the view point.
    `double` | `getRho()` Returns the distance of the viewing point from the origin.
    `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.
    `double` | `getX()` Returns the x-coordinate of the viewing point.
    `double` | `getY()` Returns the y-coordinate of the viewing point.
    `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(java.awt.geom.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.
    `java.lang.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.
    `java.awt.geom.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 Detail

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

  - ### Method Detail

    - #### 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 java.awt.geom.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(java.awt.geom.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 java.lang.String toString()

      Returns a string representation of this instance, primarily for debugging purposes.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        A string.

    - #### equals

          public boolean equals(java.lang.Object obj)

      Tests this view point for equality with an arbitrary object.
      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `obj` - the object (`null` permitted).
      Returns:
        A boolean.