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