gov/nasa/worldwind/view/OrbitView.java

   1 /*
   2 Copyright (C) 2001, 2006 United States Government as represented by
   3 the Administrator of the National Aeronautics and Space Administration.
   4 All Rights Reserved.
   5 */
   6 package gov.nasa.worldwind.view;
   7
   8 import gov.nasa.worldwind.geom.*;
   9 import gov.nasa.worldwind.View;
  10
  11 /**
  12  * <code>OrbitView</code> provides an interface for communicating viewing state in polar coordinates. For example
  13  * calling {@link #getLatitude} and {@link #setLatitude} will get and set the View latitude coordinate.
  14  *
  15  * @author dcollins
  16  * @version $Id: OrbitView.java 3461 2007-11-08 19:41:10Z dcollins $
  17  */
  18 public interface OrbitView extends View
  19 {
  20     /**
  21      * Gets the <code>View</code> eye latitude position.
  22      *
  23      * @return the current eye latitude positon.
  24      */
  25     Angle getLatitude();
  26
  27     /**
  28      * Sets the <code>View</code> eye point to the new latitude coordinate.
  29      *
  30      * @param newLatitude the new latitude position.
  31      * @return true when the set is successful; false otherwise.
  32      * @throws IllegalArgumentException if <code>newLatitude</code> is null.
  33      */
  34     boolean setLatitude(Angle newLatitude);
  35
  36     /**
  37      * Gets the <code>View</code> eye longitude position.
  38      *
  39      * @return the current eye longitude positon.
  40      */
  41     Angle getLongitude();
  42
  43     /**
  44      * Sets the <code>View</code> eye point to the new longitude coordinate.
  45      *
  46      * @param newLongitude the new longitude position.
  47      * @return true when the set is successful; false otherwise.
  48      * @throws IllegalArgumentException if <code>newLongitude</code> is null.
  49      */
  50     boolean setLongitude(Angle newLongitude);
  51
  52     /**
  53      * Gets the <code>View</code> eye altitude above the analytical globe radius.
  54      *
  55      * @return the <code>View's</code> altitude above the globe radius.
  56      */
  57     double getAltitude();
  58
  59     /**
  60      * Sets the <code>View</code> eye point to the new altitude above the analytical globe radius.
  61      *
  62      * @param newAltitude the new eye altitude above the globe radius.
  63      * @return true when the set is successful; false otherwise.
  64      */
  65     boolean setAltitude(double newAltitude);
  66
  67     /**
  68      * Sets the <code>View</code> eye point to the new (latitude, longitude) coordinate. This has the effect of calling
  69      * {@link #setLatitude} and {@link #setLongitude}.
  70      *
  71      * @param newLatLon the latitude and longitude coordinate of the eye point.
  72      * @return true when the set is successful; false otherwise.
  73      */
  74     boolean setLatLon(LatLon newLatLon);
  75
  76     /**
  77      * Sets the <code>View</code> eye point to the new (latitude, longitude, elevation) coordinate. This has the effect
  78      * of calling {@link #setLatitude}, {@link #setLongitude} and {@link #setAltitude}.
  79      *
  80      * @param newPosition the latitude, longitude and elevation coordinate of the eye point.
  81      * @return true when the set is successful; false otherwise.
  82      */
  83     boolean setLatLonAltitude(Position newPosition);
  84
  85     /**
  86      * Gets the <code>View's</code> angle from true North.
  87      *
  88      * @return the angle from true North.
  89      */
  90     Angle getHeading();
  91
  92     /**
  93      * Sets the <code>View's</code> angle to true North.
  94      *
  95      * @param newHeading the new angle to true North.
  96      * @return true when the set is successful; false otherwise.
  97      * @throws IllegalArgumentException if <code>newHeading</code> is null.
  98      */
  99     boolean setHeading(Angle newHeading);
 100
 101     /**
 102      * Gets the <code>View's</code> angle from the plane tangent to the surface.
 103      *
 104      * @return the angle from the surface tangent plane.
 105      */
 106     Angle getPitch();
 107
 108     /**
 109      * Sets the <code>View's</code> angle to the plane tangent to the surface.
 110      *
 111      * @param newPitch the new angle to the surface tangent plane.
 112      * @return true when the set is successful; false otherwise.
 113      * @throws IllegalArgumentException if <code>newPitch</code> is null.
 114      */
 115     boolean setPitch(Angle newPitch);
 116
 117     /**
 118      * Gets the <code>View's</code> translation in its forward direction.
 119      *
 120      * @return translation along the forward direction.
 121      */
 122     double getZoom();
 123
 124     /**
 125      * Sets the <code>View's</code> translation in its forward direction.
 126      *
 127      * @param newZoom translation along the forward direction.
 128      * @return true when the set is successful; false otherwise.
 129      */
 130     boolean setZoom(double newZoom);
 131
 132     /**
 133      * Gets the latitude at the center of the screen.
 134      *
 135      * @return the current center latitude position.
 136      */
 137     Angle getLookAtLatitude();
 138
 139     /**
 140      * Gets the longitude at the center of the screen.
 141      *
 142      * @return the current center longitude position.
 143      */
 144     Angle getLookAtLongitude();
 145
 146     /**
 147      * Sets the latitude coordinate of the center of the screen.
 148      *
 149      * @param newLatitude the new latitude screen center.
 150      * @return true when the set is successful; false otherwise.
 151      * @throws IllegalArgumentException if <code>newLatitude</code> is null.
 152      */
 153     boolean setLookAtLatitude(Angle newLatitude);
 154
 155     /**
 156      * Sets the longitude coordinate of the center of the screen.
 157      *
 158      * @param newLongitude the new longitude screen center.
 159      * @return true when the set is successful; false otherwise.
 160      * @throws IllegalArgumentException if <code>newLongitude</code> is null.
 161      */
 162     boolean setLookAtLongitude(Angle newLongitude);
 163
 164     /**
 165      * Sets coordinate at the center of the screen. This has the effect of calling
 166      * {@link #setLookAtLatitude} and {@link #setLookAtLatitude}.
 167      *
 168      * @param newLatLon the latitude and longitude coordinate of the center of the screen.
 169      * @return true when the set is successful; false otherwise.
 170      */
 171     boolean setLookAtLatLon(LatLon newLatLon);
 172
 173     /**
 174      * Gets the <code>View</code> eye rotation about the <code>Globe</code> origin as a <code>Quaternion</code>.
 175      *
 176      * @return the eye rotation about the <code>Globe</code> origin.
 177      */
 178     Quaternion getRotation();
 179
 180     /**
 181      * Sets the <code>View</code> eye rotation about the <code>Globe</code> origin.
 182      *
 183      * @param newRotation the rotation to set.
 184      * @return true when the set is successful; false otherwise.
 185      * @throws IllegalArgumentException if <code>newRotation</code> is null.
 186      */
 187     boolean setRotation(Quaternion newRotation);
 188
 189     /**
 190      * Returns a <code>Quaternion</code> rotation that will rotate the <code>OrbitView</code> to move
 191      * <code>beginPosition</code> to <code>endPosition</code>. The <code>Quaternion</code> is suitable for use as
 192      * the parameter to {@link #setRotation}.
 193      *
 194      * @param beginPosition the virtual position that will be moved.
 195      * @param endPosition   the virtual position to move to.
 196      * @return a <code>Quaternion</code> transforming <code>beginPosition</code> to <code>endPosition</code>.
 197      * @throws IllegalArgumentException if <code>beginPosition</code> or <code>endPosition</code> are null.
 198      */
 199     Quaternion createRotationBetweenPositions(Position beginPosition, Position endPosition);
 200
 201     /**
 202      * Returns a <code>Quaternion</code> rotation that will rotate the <code>OrbitView</code> in the viewer's
 203      * forward direction.
 204      *
 205      * @param amount the amount to move.
 206      * @return a <code>Quaternion</code> transforming <code>amount</code> degrees along the forward direction.
 207      * @throws IllegalArgumentException if <code>amount</code> is null.
 208      */
 209     Quaternion createRotationForward(Angle amount);
 210
 211     /**
 212      * Returns a <code>Quaternion</code> rotation that will rotate the <code>OrbitView</code> in the viewer's
 213      * right direction.
 214      *
 215      * @param amount the amount to move.
 216      * @return a <code>Quaternion</code> transforming <code>amount</code> degrees along the right direction.
 217      * @throws IllegalArgumentException if <code>amount</code> is null.
 218      */
 219     Quaternion createRotationRight(Angle amount);
 220 }