Package gov.nasa.worldwind.terrain

Class HighResolutionTerrain

  • All Implemented Interfaces:
    AVList, MessageListener, Terrain, WWObject, java.beans.PropertyChangeListener, java.util.EventListener
    public class HighResolutionTerrain
extends WWObjectImpl
implements Terrain
    Provides operations on the best available terrain. Operations such as line/terrain intersection and surface point computation use the highest resolution terrain data available from the globe's elevation model. Because the best available data may not be available when the operations are performed, the operations block while they retrieve the required data from either the local disk cache or a remote server. A timeout may be specified to limit the amount of time allowed for retrieving data. Operations fail if the timeout is exceeded.

    • Field Detail

      • DEFAULT_CACHE_CAPACITY

        protected static final long DEFAULT_CACHE_CAPACITY
        See Also:
        Constant Field Values

      • globe

        protected Globe globe

      • sector

        protected Sector sector

      • verticalExaggeration

        protected double verticalExaggeration

      • timeout

        protected java.lang.Long timeout

      • density

        protected int density

      • targetResolution

        protected double targetResolution

      • latTileSize

        protected double latTileSize

      • lonTileSize

        protected double lonTileSize

      • numRows

        protected int numRows

      • numCols

        protected int numCols

      • startTime

        protected java.lang.ThreadLocal<java.lang.Long> startTime

      • useCachedElevationsOnly

        protected boolean useCachedElevationsOnly
        Indicates whether cached elevations are used exclusively. When this flag is true this high resolution terrain instance uses ElevationModel.getUnmappedLocalSourceElevation(Angle, Angle) to retrieve elevations. This assumes that the highest-resolution elevations for the elevation model are cached locally.

    • Constructor Detail

      • HighResolutionTerrain

        public HighResolutionTerrain​(Globe globe,
                             java.lang.Double targetResolution)
        Constructs a terrain object for a specified globe.
        Parameters:
        globe - the terrain's globe.
        targetResolution - the target terrain resolution, in meters, or null to use the globe's highest resolution.
        Throws:
        java.lang.IllegalArgumentException - if the globe is null.

      • HighResolutionTerrain

        public HighResolutionTerrain​(Globe globe,
                             Sector sector,
                             java.lang.Double targetResolution,
                             java.lang.Double verticalExaggeration)
        Constructs a terrain object for a specified sector of a specified globe.
        Parameters:
        globe - the terrain's globe.
        sector - the desired range for the terrain. Only locations within this sector may be used in operations. If null, the sector spans the entire globe.
        targetResolution - the target terrain resolution, in meters, or null to use the globe's highest resolution.
        verticalExaggeration - the vertical exaggeration to apply to terrain elevations. Null indicates no exaggeration.
        Throws:
        java.lang.IllegalArgumentException - if the globe is null.

    • Method Detail

      • getCacheUsage

        public double getCacheUsage()
        Indicates the proportion of the cache currently used.
        Returns:
        the fraction of the cache currently used: a number between 0 and 1.

      • getNumCacheEntries

        public int getNumCacheEntries()
        Returns the number of entries currently in the cache.
        Returns:
        the number of entries currently in the cache.s

      • getGlobe

        public Globe getGlobe()
        Returns the object's globe.
        Specified by:
        getGlobe in interface Terrain
        Returns:
        the globe specified to the constructor.

      • getSector

        public Sector getSector()
        Returns the object's sector.
        Returns:
        the object's sector, either the sector specified at construction or the default sector if no sector was specified at construction.

      • getTargetResolution

        public double getTargetResolution()

      • getVerticalExaggeration

        public double getVerticalExaggeration()
        Indicates the vertical exaggeration used when performing terrain operations.
        Specified by:
        getVerticalExaggeration in interface Terrain
        Returns:
        the vertical exaggeration. The default is 1: no exaggeration.

      • getTimeout

        public java.lang.Long getTimeout()
        Indicates the current timeout for operations requiring terrain data retrieval.
        Returns:
        the current timeout, in milliseconds. May be null.
        See Also:
        setTimeout(Long)

      • setTimeout

        public void setTimeout​(java.lang.Long timeout)
        Specifies the maximum amount of time allowed for retrieval of all terrain data necessary to satisfy an operation. Operations that retrieve data throw a WWTimeoutException if the specified timeout is exceeded.
        Parameters:
        timeout - the number of milliseconds to wait. May be null, to indicate that operations have unlimited amount of time to operate.

      • getDensity

        public int getDensity()

      • setDensity

        public void setDensity​(int density)
        Specifies the number of intervals within a single terrain tile. Density does not affect precision, it just determines how many sample points to include with each internal terrain tile. The precision -- the distance between each sample point -- is governed by the terrain tolerance specified in this object's constructor.
        Parameters:
        density - the number of intervals used to form a terrain tile.

      • getCacheCapacity

        public long getCacheCapacity()
        Indicates the current cache capacity.
        Returns:
        the current cache capacity, in bytes.

      • setCacheCapacity

        public void setCacheCapacity​(long size)
        Specifies the cache capacity.
        Parameters:
        size - the cache capacity, in bytes. Values less than 1 MB are clamped to 1 MB.

      • getSurfacePoint

        public Vec4 getSurfacePoint​(Position position)
        Computes the Cartesian, model-coordinate point of a position on the terrain.

        This operation fails with a WWTimeoutException if a timeout has been specified and it is exceeded during the operation.

        Specified by:
        getSurfacePoint in interface Terrain
        Parameters:
        position - the position.
        Returns:
        the Cartesian, model-coordinate point of the specified position, or null if the specified position does not exist within this instance's sector or if the operation is interrupted.

      • getSurfacePoint

        public Vec4 getSurfacePoint​(Angle latitude,
                            Angle longitude,
                            double metersOffset)
        Computes the Cartesian, model-coordinate point of a location on the terrain.

        This operation fails with a WWTimeoutException if a timeout has been specified and it is exceeded during the operation.

        Specified by:
        getSurfacePoint in interface Terrain
        Parameters:
        latitude - the location's latitude.
        longitude - the location's longitude.
        metersOffset - the location's distance above the terrain.
        Returns:
        the Cartesian, model-coordinate point of the specified location, or null if the specified location does not exist within this instance's sector or if the operation is interrupted.

      • getElevation

        public java.lang.Double getElevation​(LatLon location)
        Computes the elevation at a specified location.

        This operation fails with a WWTimeoutException if a timeout has been specified and it is exceeded during the operation.

        Specified by:
        getElevation in interface Terrain
        Parameters:
        location - the location at which to compute the elevation.
        Returns:
        the elevation at the location, or null if the elevation could not be determined.

      • intersect

        public Intersection[] intersect​(Position pA,
                                Position pB)
        Computes the intersections of a line with the terrain. The line is specified by two positions whose altitude field indicates the height above the terrain (not the altitude relative to sea level). All intersection points are returned.

        This operation fails with a WWTimeoutException if a timeout has been specified and it is exceeded during the operation.

        Specified by:
        intersect in interface Terrain
        Parameters:
        pA - the line's first position.
        pB - the line's second position.
        Returns:
        an array of Cartesian model-coordinate intersection points, or null if no intersections occur or the operation is interrupted.

      • intersect

        public Intersection[] intersect​(Position pA,
                                Position pB,
                                int altitudeMode)
        Computes the intersections of a line with the terrain. The line is specified by two positions whose altitude field is interpreted according to the specified altitude mode. All intersection points are returned.

        This operation fails with a WWTimeoutException if a timeout has been specified and it is exceeded during the operation.

        Specified by:
        intersect in interface Terrain
        Parameters:
        pA - the line's first position.
        pB - the line's second position.
        altitudeMode - the altitude mode indicating the reference for the altitudes in the specified positions.
        Returns:
        an array of Cartesian model-coordinate intersection points, or null if no intersections occur or the operation is interrupted.

      • intersect

        public void intersect​(java.util.List<Position> positions,
                      HighResolutionTerrain.IntersectionCallback callback)
               throws java.lang.InterruptedException
        Intersects a specified list of geographic two-position lines with the terrain.
        Parameters:
        positions - The positions to intersect, with the line segments formed by each pair of positions, e.g. the first line in formed by positions[0] and positions[1], the second by positions[2] and positions[3], etc.
        callback - An object to call in order to return the computed intersections.
        Throws:
        java.lang.InterruptedException - if the operation is interrupted.

      • cacheIntersectingTiles

        public void cacheIntersectingTiles​(Position pA,
                                   Position pB)
                            throws java.lang.InterruptedException
        Cause the tiles used by subsequent intersection calculations to be cached so that they are available immediately to those subsequent calculations.

        Pre-caching is unnecessary and is useful only when it can occur before the intersection calculations are needed. It will incur extra overhead otherwise. The normal intersection calculations cause the same caching.

        Parameters:
        pA - the line's first position.
        pB - the line's second position.
        Throws:
        java.lang.IllegalArgumentException - if either position is null.
        java.lang.InterruptedException - if the operation is interrupted. if the current timeout is exceeded while retrieving terrain data.

      • cacheIntersectingTiles

        public void cacheIntersectingTiles​(Sector sector)
                            throws java.lang.InterruptedException
        Cause the tiles used by subsequent intersection calculations to be cached so that they are available immediately to those subsequent calculations.

        Pre-caching is unnecessary and is useful only when it can occur before the intersection calculations are needed. It will incur extra overhead otherwise. The normal intersection calculations cause the same caching.

        Parameters:
        sector - the sector for which to cache elevation data.
        Throws:
        java.lang.IllegalArgumentException - if the specified sector is null.
        java.lang.InterruptedException - if the operation is interrupted. if the current timeout is exceeded while retrieving terrain data.

      • getIntersectionTiles

        public java.util.List<Sector> getIntersectionTiles​(Position pA,
                                                   Position pB)
                                            throws java.lang.InterruptedException
        Throws:
        java.lang.InterruptedException

      • computeDimensions

        protected void computeDimensions()
        Computes the row and column dimensions of the tile array.

      • getContainingTile

        protected HighResolutionTerrain.RectTile getContainingTile​(Angle latitude,
                                                           Angle longitude)
        Determines the tile that contains a specified location.
        Parameters:
        latitude - the location's latitude.
        longitude - the location's longitude.
        Returns:
        the tile containing the specified location.

      • createTile

        protected HighResolutionTerrain.RectTile createTile​(int row,
                                                    int col)
        Creates a tile for a specified row and column of the tile array.
        Parameters:
        row - the tile's 0-origin row index.
        col - the tile's 0-origin column index.
        Returns:
        the tile for the specified row and column, or null if the row or column are invalid.

      • createTile

        protected HighResolutionTerrain.RectTile createTile​(Sector tileSector)
        Creates the tile for a specified sector.
        Parameters:
        tileSector - the sector for which to create the tile.
        Returns:
        the tile for the sector, or null if the sector is outside this instance's sector.

      • computeRow

        protected int computeRow​(Sector range,
                         Angle latitude)
        Computes the row index corresponding to a specified latitude.
        Parameters:
        range - the reference sector, typically that of this terrain instance.
        latitude - the latitude in question.
        Returns:
        the row index for the sector.

      • computeColumn

        protected int computeColumn​(Sector range,
                            Angle longitude)
        Computes the column index corresponding to a specified latitude.
        Parameters:
        range - the reference sector, typically that of this terrain instance.
        longitude - the latitude in question.
        Returns:
        the column index for the sector.

      • makeLineFromPositions

        protected Line makeLineFromPositions​(Position pA,
                                     Position pB)
                              throws java.lang.InterruptedException
        Throws:
        java.lang.InterruptedException

      • doIntersect

        protected Intersection[] doIntersect​(Position pA,
                                     Position pB)
                              throws java.lang.InterruptedException
        Computes intersections of a line with the terrain.
        Parameters:
        pA - the line's first position.
        pB - the line's second position.
        Returns:
        an array of intersections, or null if no intersections occur.
        Throws:
        java.lang.InterruptedException - if the operation is interrupted.

      • getIntersectingTiles

        protected java.util.List<HighResolutionTerrain.RectTile> getIntersectingTiles​(Position pA,
                                                                              Position pB,
                                                                              Line line)
        Determines and creates the terrain tiles intersected by a specified line.
        Parameters:
        pA - the line's first position.
        pB - the line's second position.
        line - the line to intersect
        Returns:
        a list of tiles that likely intersect the line. Some returned tiles may not intersect the line but will only be near it.

      • doGetIntersectingTiles

        protected void doGetIntersectingTiles​(int r0,
                                      int c0,
                                      int r1,
                                      int c1,
                                      Line line,
                                      java.util.List<HighResolutionTerrain.RectTile> tiles)

      • makeVerts

        protected void makeVerts​(HighResolutionTerrain.RectTile tile)
                  throws java.lang.InterruptedException
        Computes a terrain tile's vertices of draws them from the cache.
        Parameters:
        tile - the tile to compute vertices for
        Throws:
        java.lang.InterruptedException - if the operation is interrupted.
        WWTimeoutException - if terrain data retrieval exceeds the current timeout.

      • buildVerts

        protected HighResolutionTerrain.RenderInfo buildVerts​(HighResolutionTerrain.RectTile tile)
                                               throws java.lang.InterruptedException
        Computes a terrain tile's vertices.
        Parameters:
        tile - the tile to compute vertices for
        Returns:
        the computed vertex information.
        Throws:
        java.lang.InterruptedException - if the operation is interrupted.
        WWTimeoutException - if terrain data retrieval exceeds the current timeout.

      • setUseCachedElevationsOnly

        public void setUseCachedElevationsOnly​(boolean tf)
        Indicates whether cached elevations are used exclusively. When this flag is true this high resolution terrain instance uses ElevationModel.getUnmappedLocalSourceElevation(Angle, Angle) to retrieve elevations. This assumes that the highest-resolution elevations for the elevation model are cached locally.
        Parameters:
        tf - true to force caching, otherwise false. The default is false.

      • isUseCachedElevationsOnly

        public boolean isUseCachedElevationsOnly()
        Indicates whether cached elevations are used exclusively. When this flag is true this high resolution terrain instance uses ElevationModel.getUnmappedLocalSourceElevation(Angle, Angle) to retrieve elevations. This assumes that the highest-resolution elevations for the elevation model are cached locally.
        Returns:
        true if cached elevations are forced, otherwise false.

      • getElevations

        protected void getElevations​(Sector sector,
                             java.util.List<LatLon> latlons,
                             double[] targetResolution,
                             double[] elevations)
                      throws java.lang.InterruptedException
        Throws:
        java.lang.InterruptedException

      • resolutionsMeetCriteria

        protected boolean resolutionsMeetCriteria​(double[] actualResolution,
                                          double[] targetResolution)

      • getCachedElevations

        protected void getCachedElevations​(java.util.List<LatLon> latlons,
                                   double[] elevations)

      • computeLocations

        protected java.util.ArrayList<LatLon> computeLocations​(HighResolutionTerrain.RectTile tile)
        Computes the tile's cell locations, determined by the tile's density and sector.
        Parameters:
        tile - the tile to compute locations for.
        Returns:
        the cell locations.

      • getSurfacePoint

        protected Vec4 getSurfacePoint​(HighResolutionTerrain.RectTile tile,
                               Angle latitude,
                               Angle longitude,
                               double metersOffset)
                        throws java.lang.InterruptedException
        Computes the Cartesian, model-coordinate point of a location within a terrain tile.

        This operation fails with a WWTimeoutException if a timeout has been specified and it is exceeded during the operation.

        Parameters:
        tile - the terrain tile.
        latitude - the location's latitude.
        longitude - the location's longitude.
        metersOffset - the location's distance above the terrain.
        Returns:
        the Cartesian, model-coordinate point of a the specified location, or null if the specified location does not exist within this instance's sector or if the operation is interrupted.
        Throws:
        java.lang.IllegalArgumentException - if the latitude or longitude are null.
        WWTimeoutException - if the current timeout is exceeded while retrieving terrain data.
        java.lang.InterruptedException - if the operation is interrupted.
        See Also:
        setTimeout(Long)

      • applyOffset

        protected Vec4 applyOffset​(Vec4 point,
                           double metersOffset)
        Applies a specified vertical offset to a surface point.
        Parameters:
        point - the surface point.
        metersOffset - the vertical offset to add to the point.
        Returns:
        a new point offset the specified amount from the input point.

      • getSurfacePoint

        protected Vec4 getSurfacePoint​(HighResolutionTerrain.RectTile tile,
                               Angle latitude,
                               Angle longitude)
                        throws java.lang.InterruptedException
        Computes the Cartesian, model-coordinate point of a location within a terrain tile.

        This operation fails with a WWTimeoutException if a timeout has been specified and it is exceeded during the operation.

        Parameters:
        tile - the terrain tile.
        latitude - the location's latitude.
        longitude - the location's longitude.
        Returns:
        the Cartesian, model-coordinate point of a the specified location, or null if the specified location does not exist within this instance's sector or if the operation is interrupted.
        Throws:
        java.lang.IllegalArgumentException - if the latitude or longitude are null.
        WWTimeoutException - if the current timeout is exceeded while retrieving terrain data.
        java.lang.InterruptedException - if the operation is interrupted.
        See Also:
        setTimeout(Long)

      • createPosition

        protected static double createPosition​(int start,
                                       double decimal,
                                       int density)

      • interpolate

        protected static Vec4 interpolate​(Vec4 bL,
                                  Vec4 bR,
                                  Vec4 tR,
                                  Vec4 tL,
                                  double xDec,
                                  double yDec)

      • intersect

        protected Intersection[] intersect​(HighResolutionTerrain.RectTile tile,
                                   Line line)
                            throws java.lang.InterruptedException
        Computes the intersections of a line with a tile.
        Parameters:
        tile - the tile.
        line - the line.
        Returns:
        an array of intersections, or null if no intersections occur.
        Throws:
        java.lang.InterruptedException - if the operation is interrupted.

      • intersect

        protected java.util.List<Vec4[]> intersect​(HighResolutionTerrain.RectTile tile,
                                           Vec4[] triangle)
                                    throws java.lang.InterruptedException
        Computes the intersection of a triangle with a terrain tile.
        Parameters:
        tile - the terrain tile
        triangle - the Cartesian coordinates of the triangle.
        Returns:
        a list of the intersection points at which the triangle intersects the tile, or null if there are no intersections. If there are intersections, each entry in the returned list contains a two-element array holding the Cartesian coordinates of the intersection point with one terrain triangle. In the cases of co-planar triangles, all three vertices of the terrain triangle are returned, in a three-element array.
        Throws:
        java.lang.InterruptedException - if the operation is interrupted before it completes.

      • intersectTriangle

        public void intersectTriangle​(Vec4[] triangleCoordinates,
                              Position[] trianglePositions,
                              java.util.List<Position[]> intersectPositionsOut)
                       throws java.lang.InterruptedException
        Intersects a specified triangle with the terrain.
        Parameters:
        triangleCoordinates - The Cartesian coordinates of the triangle.
        trianglePositions - The geographic coordinates of the triangle.
        intersectPositionsOut - A list in which to place the intersection positions. May not be null.
        Throws:
        java.lang.InterruptedException - if the operation is interrupted before it completes.

      • convertPointsToPositions

        protected void convertPointsToPositions​(java.util.List<Vec4[]> points,
                                        java.util.List<Position[]> positions)

      • getExtremeElevations

        public Position[] getExtremeElevations​(Sector sector)
                                throws java.lang.InterruptedException
        Determines the minimum and maximum elevations and their locations within a specified Sector.
        Parameters:
        sector - The sector in question.
        Returns:
        a two-element array containing the minimum and maximum elevations and their locations in the sector. The minimum as at index 0 in the array, the maximum is at index 1. If either cannot be determined, null is given in the respective array position.
        Throws:
        java.lang.InterruptedException - if the operation is interrupted before it completes.

      • getExtremeElevations

        public Position[] getExtremeElevations​(LatLon center,
                                       double width,
                                       double height)
                                throws java.lang.InterruptedException
        Determines the minimum and maximum elevations and their locations within a specified geographic quadrilateral.
        Parameters:
        center - The quadrilateral's center.
        width - The quadrilateral's longitudinal width, in meters.
        height - The quadrilateral's latitudinal height, in meters.
        Returns:
        a two-element array containing the minimum and maximum elevations and their locations in the quadrilateral. The minimum as at index 0 in the array, the maximum is at index 1. If either cannot be determined, null is given in the respective array position.
        Throws:
        java.lang.InterruptedException - if the operation is interrupted before it completes.