gov/nasa/worldwind/ElevationModel.java

   1 /*
   2 Copyright (C) 2001, 2006 United States Government
   3 as represented by the Administrator of the
   4 National Aeronautics and Space Administration.
   5 All Rights Reserved.
   6 */
   7 package gov.nasa.worldwind;
   8
   9 import gov.nasa.worldwind.geom.*;
  10
  11 /**
  12  * <p/>
  13  * Provides the elevations of all points on a {@link Globe} . Every <code>Globe</code> has an elevation model
  14  * implementing this interface.
  15  * <p/>
  16  * Elevations are organized by {@link Sector}. Elevation models return an {@link Elevations} object for requested
  17  * sectors. This object is then used to query elevations at latitude/longitude positions within that sector.
  18  * <p/>
  19  * An <code>ElevationModel</code> typically approximates elevations at multiple levels of spatial resolution. For any
  20  * given viewing position the model determines an appropriate target resolution. That target resolution may not be
  21  * immediately achievable, however, because the corresponding elevation data might not be locally available and must be
  22  * retrieved from a remote location. When this is the case, the <code>Elevations</code> object returned for a sector
  23  * holds the resolution achievable with the data currently available. That resolution may not be the same as the target
  24  * resolution. The target resolution and the actual resolution are made available in the interface so that users of this
  25  * class may use the resolution values to compare previously computed elevation sectors with newly computed ones, and
  26  * thereby enable effective caching of elevations computed for the sector.
  27  * <p/>
  28  *
  29  * @author Tom Gaskins
  30  * @version $Id: ElevationModel.java 2211 2007-07-03 22:15:13Z tgaskins $
  31  */
  32 public interface ElevationModel extends WWObject
  33 {
  34     boolean isEnabled();
  35
  36     void setEnabled(boolean enable);
  37
  38     /**
  39      * Returns the maximum elevation contained in the elevevation model. This value is the height of the highest point
  40      * on the globe.
  41      *
  42      * @return The maximum elevation of the model
  43      */
  44     double getMaximumElevation();
  45
  46     /**
  47      * Returns the minimum elevation contained in the elevevation model. This value is the height of the lowest point on
  48      * the globe. It may be negative, indicating a value below mean surface level. (Sea level in the case of Earth.)
  49      *
  50      * @return The minimum elevation of the model
  51      */
  52     double getMinimumElevation();
  53
  54     /**
  55      * Computes and returns an {@link Elevations} object for the specified {@link Sector} and target resolution. If the
  56      * target resolution can not currently be achieved, the best available elevations are returned.
  57      * <p/>
  58      * Implementing classes of <code>ElevationModel</code> interpret <code>resolution</code> in a class-specific way.
  59      * See the descriptions of those classes to learn their use of this value. The elevations returned are in the form
  60      * of an {@link Elevations} object. Specific elevations are returned by that object.
  61      *
  62      * @param sector     the sector to return elevations for.
  63      * @param resolution a value interpreted in a class-specific way by implementing classes.
  64      * @return An object representing the elevations for the specified sector. Its resolution value will be either the
  65      *         specified resolution or the best available alternative.
  66      */
  67     Elevations getElevations(Sector sector, int resolution);
  68
  69     /**
  70      * Returns the resolution appropriate to the given {@link Sector} and view parameters. The view parameters are read
  71      * from the specified {@link DrawContext}. Implementing classes of <code>ElevationModel</code> interpret
  72      * <code>resolution</code> in class-specific ways. See the descriptions of subclasses to learn their use of this
  73      * value. This method is used to determine the resolution the model will use if all resources are available to
  74      * compute that resolution. It is subsequently passed to {@link #getElevations(Sector, int)} when a sector's
  75      * resolutions are queried.
  76      *
  77      * @param dc     the draw context to read the view and rendering parameters from.
  78      * @param sector the {@link Sector} to compute the target resolution for.
  79      * @return The appropriate resolution for the sector and draw context values.
  80      */
  81     int getTargetResolution(DrawContext dc, Sector sector, int density);
  82
  83     double getElevation(Angle latitude, Angle longitude);
  84
  85     Elevations getBestElevations(Sector sector);
  86
  87     Elevations getElevationsAtResolution(Sector sector, int resolution);
  88
  89     /**
  90      * The <code>Elevations</code> interface provides elevations at specified latitude and longitude positions. Objects
  91      * implementing this interface are created by {@link ElevationModel#getElevations(Sector, int)}.
  92      */
  93     public interface Elevations
  94     {
  95         /**
  96          * Indicates whether the object contains useful elevations. An <code>Elevations</code> instance may exist
  97          * without holding any elevations. This can occur when the resources needed to determine elevations are not yet
  98          * local. This method enables the detection of that case. Callers typically use it to avoid time-consuming
  99          * computations that require valid elevations.
 100          *
 101          * @return <code>true</code> if a call to {@link #getElevation(double, double)} will return valid elevations,
 102          *         otherwise <code>false</code> indicating that the value 0 will always be returned from that method.
 103          */
 104         boolean hasElevations();
 105
 106         /**
 107          * Returns the elevation at a specific latitude and longitude, each specified in radians.
 108          *
 109          * @param latRadians the position's latitude in radians, in the range [-&pi;/2, +&pi;/2].
 110          * @param lonRadians the position's longitude in radians, in the range [-&pi;, +&pi;].
 111          * @return The elevation at the given position, or 0 if elevations are not available.
 112          */
 113         double getElevation(double latRadians, double lonRadians);
 114
 115         /**
 116          * Returns the resolution value of the elevations. The meaning and use of this value is defined by subclasses of
 117          * <code>ElevationModel</code>.
 118          *
 119          * @return the resolution associated with <code>this</code>.
 120          */
 121         int getResolution();
 122
 123         /**
 124          * Returns the {@link Sector} the elevations pertain to.
 125          *
 126          * @return The sector the elevations pertain to.
 127          */
 128         Sector getSector();
 129     }
 130 }