Package gov.nasa.worldwind.terrain

Class BasicElevationModel

    • Field Detail

      • levels

        protected final LevelSet levels

      • minElevation

        protected final double minElevation

      • maxElevation

        protected final double maxElevation

      • elevationDataType

        protected java.lang.String elevationDataType

      • elevationDataByteOrder

        protected java.lang.String elevationDataByteOrder

      • detailHint

        protected double detailHint

      • fileLock

        protected final java.lang.Object fileLock

      • extremesLevel

        protected int extremesLevel

      • extremesCachingEnabled

        protected boolean extremesCachingEnabled

      • extremesLookupCache

        protected MemoryCache extremesLookupCache

      • RESOURCE_ID_OGC_CAPABILITIES

        protected static final int RESOURCE_ID_OGC_CAPABILITIES
        See Also:
        Constant Field Values

    • Constructor Detail

      • BasicElevationModel

        public BasicElevationModel​(AVList params)

      • BasicElevationModel

        public BasicElevationModel​(org.w3c.dom.Document dom,
                           AVList params)

      • BasicElevationModel

        public BasicElevationModel​(org.w3c.dom.Element domElement,
                           AVList params)

      • BasicElevationModel

        public BasicElevationModel​(java.lang.String restorableStateInXml)

    • Method Detail

      • setValue

        public java.lang.Object setValue​(java.lang.String key,
                                 java.lang.Object value)
        Description copied from interface: AVList
        Adds a key/value pair to the list. Replaces an existing key/value pair if the list already contains the key.
        Specified by:
        setValue in interface AVList
        Overrides:
        setValue in class AVListImpl
        Parameters:
        key - the attribute name. May not be null.
        value - the attribute value. May be null, in which case any existing value for the key is removed from the collection.
        Returns:
        previous value associated with specified key, or null if there was no mapping for key. A null return can also indicate that the map previously associated null with the specified key, if the implementation supports null values.

      • getValue

        public java.lang.Object getValue​(java.lang.String key)
        Description copied from interface: AVList
        Returns the value for a specified key.
        Specified by:
        getValue in interface AVList
        Overrides:
        getValue in class AVListImpl
        Parameters:
        key - the attribute name. May not be null.
        Returns:
        the attribute value if one exists in the collection, otherwise null.

      • setFallbacks

        protected static void setFallbacks​(AVList params)

      • getMemoryCache

        protected MemoryCache getMemoryCache()

      • createMemoryCache

        protected MemoryCache createMemoryCache​(java.lang.String cacheName)

      • getLevels

        public LevelSet getLevels()

      • getExtremesLevel

        protected int getExtremesLevel()

      • setExpiryTime

        public void setExpiryTime​(long expiryTime)
        Specifies the time of the elevation models's most recent dataset update, beyond which cached data is invalid. If greater than zero, the model ignores and eliminates any in-memory or on-disk cached data older than the time specified, and requests new information from the data source. If zero, the default, the model applies any expiry times associated with its individual levels, but only for on-disk cached data. In-memory cached data is expired only when the expiry time is specified with this method and is greater than zero. This method also overwrites the expiry times of the model's individual levels if the value specified to the method is greater than zero.
        Specified by:
        setExpiryTime in interface ElevationModel
        Overrides:
        setExpiryTime in class AbstractElevationModel
        Parameters:
        expiryTime - the expiry time of any cached data, expressed as a number of milliseconds beyond the epoch. The default expiry time is zero.
        See Also:
        for a description of milliseconds beyond the epoch.

      • getMaxElevation

        public double getMaxElevation()
        Description copied from interface: ElevationModel
        Returns the maximum elevation contained in the elevation model. When the elevation model is associated with a globe, this value is the elevation of the highest point on the globe.
        Specified by:
        getMaxElevation in interface ElevationModel
        Returns:
        The maximum elevation of the elevation model.

      • getMinElevation

        public double getMinElevation()
        Description copied from interface: ElevationModel
        Returns the minimum elevation contained in the elevation model. When associated with a globe, this value is the elevation of the lowest point on the globe. It may be negative, indicating a value below mean surface level. (Sea level in the case of Earth.)
        Specified by:
        getMinElevation in interface ElevationModel
        Returns:
        The minimum elevation of the model.

      • getBestResolution

        public double getBestResolution​(Sector sector)
        Description copied from interface: ElevationModel
        Indicates the best resolution attainable for a specified sector.
        Specified by:
        getBestResolution in interface ElevationModel
        Parameters:
        sector - the sector in question. If null, the elevation model's best overall resolution is returned. This is the best attainable at some locations but not necessarily at all locations.
        Returns:
        the best resolution attainable for the specified sector, in radians, or Double.MAX_VALUE if the sector does not intersect the elevation model.

      • getDetailHint

        public double getDetailHint​(Sector sector)
        Description copied from interface: ElevationModel
        Returns the detail hint associated with the specified sector. If the elevation model does not have any detail hint for the sector, this method returns zero.
        Specified by:
        getDetailHint in interface ElevationModel
        Overrides:
        getDetailHint in class AbstractElevationModel
        Parameters:
        sector - the sector in question.
        Returns:
        The detail hint corresponding to the specified sector.

      • setDetailHint

        public void setDetailHint​(double hint)

      • getElevationDataType

        public java.lang.String getElevationDataType()

      • setElevationDataType

        public void setElevationDataType​(java.lang.String dataType)

      • getElevationDataByteOrder

        public java.lang.String getElevationDataByteOrder()

      • setByteOrder

        public void setByteOrder​(java.lang.String byteOrder)

      • intersects

        public int intersects​(Sector sector)
        Description copied from interface: ElevationModel
        Indicates whether the elevation model covers a specified sector either partially or fully.
        Specified by:
        intersects in interface ElevationModel
        Parameters:
        sector - the sector in question.
        Returns:
        0 if the elevation model fully contains the sector, 1 if the elevation model intersects the sector but does not fully contain it, or -1 if the sector does not intersect the elevation model.

      • contains

        public boolean contains​(Angle latitude,
                        Angle longitude)
        Description copied from interface: ElevationModel
        Indicates whether a specified location is within the elevation model's domain.
        Specified by:
        contains in interface ElevationModel
        Parameters:
        latitude - the latitude of the location in question.
        longitude - the longitude of the location in question.
        Returns:
        true if the location is within the elevation model's domain, otherwise false.

      • setExtremesCachingEnabled

        public void setExtremesCachingEnabled​(boolean enabled)
        Description copied from interface: ElevationModel
        Indicates whether extreme values of sectors should be cached as they're computed. Caching should be disabled if especially many sectors are to be used when querying extreme elevations of this elevation model, such as during terrain intersection calculations. The default is for caching to be enabled. During normal operation caching enhances performance, but during terrain intersection computation it can hamper performance.
        Specified by:
        setExtremesCachingEnabled in interface ElevationModel
        Parameters:
        enabled - true if extreme value caching should be performed.

      • requestTile

        protected void requestTile​(TileKey key)

      • isFileExpired

        protected boolean isFileExpired​(Tile tile,
                                java.net.URL fileURL,
                                FileStore fileStore)

      • loadElevations

        protected boolean loadElevations​(BasicElevationModel.ElevationTile tile,
                                 java.net.URL url)
                          throws java.lang.Exception
        Throws:
        java.lang.Exception

      • areElevationsInMemory

        protected boolean areElevationsInMemory​(TileKey key)

      • readElevations

        protected BufferWrapper readElevations​(java.net.URL url)
                                throws java.lang.Exception
        Throws:
        java.lang.Exception

      • makeBilElevations

        protected BufferWrapper makeBilElevations​(java.net.URL url)
                                   throws java.io.IOException
        Throws:
        java.io.IOException

      • makeTiffElevations

        protected BufferWrapper makeTiffElevations​(java.net.URL url)
                                    throws java.io.IOException,
                                           java.net.URISyntaxException
        Throws:
        java.io.IOException
        java.net.URISyntaxException

      • convertImageToElevations

        protected static java.nio.ByteBuffer convertImageToElevations​(java.nio.ByteBuffer buffer,
                                                              java.lang.String contentType)
                                                       throws java.io.IOException
        Throws:
        java.io.IOException

      • makeLocal

        public BulkRetrievalThread makeLocal​(Sector sector,
                                     double resolution,
                                     BulkRetrievalListener listener)
        Start a new BulkRetrievalThread that downloads all elevations for a given sector and resolution to the current WorldWind file cache, without downloading imagery already in the cache.

        This method creates and starts a thread to perform the download. A reference to the thread is returned. To create a downloader that has not been started, construct a BasicElevationModelBulkDownloader.

        Note that the target resolution must be provided in radians of latitude per texel, which is the resolution in meters divided by the globe radius.

        Specified by:
        makeLocal in interface BulkRetrievable
        Parameters:
        sector - the sector to download data for.
        resolution - the target resolution, provided in radians of latitude per texel.
        listener - an optional retrieval listener. May be null.
        Returns:
        the BulkRetrievalThread executing the retrieval or null if the specified sector does not intersect the elevation model bounding sector.
        Throws:
        java.lang.IllegalArgumentException - if the sector is null or the resolution is less than zero.
        See Also:
        BasicElevationModelBulkDownloader

      • makeLocal

        public BulkRetrievalThread makeLocal​(Sector sector,
                                     double resolution,
                                     FileStore fileStore,
                                     BulkRetrievalListener listener)
        Start a new BulkRetrievalThread that downloads all elevations for a given sector and resolution to a specified file store, without downloading imagery already in the file store.

        This method creates and starts a thread to perform the download. A reference to the thread is returned. To create a downloader that has not been started, construct a BasicElevationModelBulkDownloader.

        Note that the target resolution must be provided in radians of latitude per texel, which is the resolution in meters divided by the globe radius.

        Specified by:
        makeLocal in interface BulkRetrievable
        Parameters:
        sector - the sector to download data for.
        resolution - the target resolution, provided in radians of latitude per texel.
        fileStore - the file store in which to place the downloaded elevations. If null the current WorldWind file cache is used.
        listener - an optional retrieval listener. May be null.
        Returns:
        the BulkRetrievalThread executing the retrieval or null if the specified sector does not intersect the elevation model bounding sector.
        Throws:
        java.lang.IllegalArgumentException - if the sector is null or the resolution is less than zero.
        See Also:
        BasicElevationModelBulkDownloader

      • getEstimatedMissingDataSize

        public long getEstimatedMissingDataSize​(Sector sector,
                                        double resolution)
        Get the estimated size in bytes of the elevations not in the WorldWind file cache for the given sector and resolution.

        Note that the target resolution must be provided in radians of latitude per texel, which is the resolution in meters divided by the globe radius.

        Specified by:
        getEstimatedMissingDataSize in interface BulkRetrievable
        Parameters:
        sector - the sector to estimate.
        resolution - the target resolution, provided in radians of latitude per texel.
        Returns:
        the estimated size in bytes of the missing elevations.
        Throws:
        java.lang.IllegalArgumentException - if the sector is null or the resolution is less than zero.

      • getEstimatedMissingDataSize

        public long getEstimatedMissingDataSize​(Sector sector,
                                        double resolution,
                                        FileStore fileStore)
        Get the estimated size in bytes of the elevations not in a specified file store for the given sector and resolution.

        Note that the target resolution must be provided in radians of latitude per texel, which is the resolution in meters divided by the globe radius.

        Specified by:
        getEstimatedMissingDataSize in interface BulkRetrievable
        Parameters:
        sector - the sector to estimate.
        resolution - the target resolution, provided in radians of latitude per texel.
        fileStore - the file store to examine. If null the current WorldWind file cache is used.
        Returns:
        the estimated size in bytes of the missing elevations.
        Throws:
        java.lang.IllegalArgumentException - if the sector is null or the resolution is less than zero.

      • downloadElevations

        protected void downloadElevations​(Tile tile)

      • determineExtremes

        protected void determineExtremes​(double value,
                                 double[] extremes)

      • getUnmappedElevation

        public double getUnmappedElevation​(Angle latitude,
                                   Angle longitude)
        Description copied from interface: ElevationModel
        Returns the elevation at a specified location, but without replacing missing data with the elevation model's missing data replacement value. When a missing data signal is found, the signal value is returned, not the replacement value.
        Specified by:
        getUnmappedElevation in interface ElevationModel
        Parameters:
        latitude - the latitude of the location for which to return the elevation.
        longitude - the longitude of the location for which to return the elevation.
        Returns:
        the elevation at the specified location, or the elevation model's missing data signal. If no data is currently in memory for the location, and the location is within the elevation model's coverage area, the elevation model's minimum elevation at that location is returned.

      • getUnmappedLocalSourceElevation

        public double getUnmappedLocalSourceElevation​(Angle latitude,
                                              Angle longitude)
        Description copied from interface: ElevationModel
        Returns the elevation for this elevation model's highest level of detail if the source file for that level and the specified location exists in the local elevation cache on disk. This method is useful only when an elevation dataset has been pre-cached.
        Specified by:
        getUnmappedLocalSourceElevation in interface ElevationModel
        Overrides:
        getUnmappedLocalSourceElevation in class AbstractElevationModel
        Parameters:
        latitude - The latitude of the location whose elevation is desired.
        longitude - The longitude of the location whose elevation is desired.
        Returns:
        The elevation at the specified location, if that location is contained in this elevation model and the source file for the highest-resolution elevation at that location exists in the current disk cache. Otherwise this elevation model's missing data signal is returned (see ElevationModel.getMissingDataSignal()).

      • getElevations

        public double getElevations​(Sector sector,
                            java.util.List<? extends LatLon> latlons,
                            double targetResolution,
                            double[] buffer)
        Description copied from interface: ElevationModel
        Returns the elevations of a collection of locations. Replaces any elevation values corresponding to the missing data signal with the elevation model's missing data replacement value. If a location within the elevation model's coverage area cannot currently be determined, the elevation model's minimum extreme elevation for that location is returned in the output buffer. If a location is outside the elevation model's coverage area, the output buffer for that location is not modified; it retains the buffer's original value.
        Specified by:
        getElevations in interface ElevationModel
        Parameters:
        sector - the sector in question.
        latlons - the locations to return elevations for. If a location is null, the output buffer for that location is not modified.
        targetResolution - the desired horizontal resolution, in radians, of the raster or other elevation sample from which elevations are drawn. (To compute radians from a distance, divide the distance by the radius of the globe, ensuring that both the distance and the radius are in the same units.)
        buffer - an array in which to place the returned elevations. The array must be pre-allocated and contain at least as many elements as the list of locations.
        Returns:
        the resolution achieved, in radians, or Double.MAX_VALUE if individual elevations cannot be determined for all of the locations.
        See Also:
        ElevationModel.setMissingDataSignal(double)

      • getUnmappedElevations

        public double getUnmappedElevations​(Sector sector,
                                    java.util.List<? extends LatLon> latlons,
                                    double targetResolution,
                                    double[] buffer)
        Description copied from interface: ElevationModel
        Returns the elevations of a collection of locations. Does not replace any elevation values corresponding to the missing data signal with the elevation model's missing data replacement value. If a location within the elevation model's coverage area cannot currently be determined, the elevation model's minimum extreme elevation for that location is returned in the output buffer. If a location is outside the elevation model's coverage area, the output buffer for that location is not modified; it retains the buffer's original value.
        Specified by:
        getUnmappedElevations in interface ElevationModel
        Parameters:
        sector - the sector in question.
        latlons - the locations to return elevations for. If a location is null, the output buffer for that location is not modified.
        targetResolution - the desired horizontal resolution, in radians, of the raster or other elevation sample from which elevations are drawn. (To compute radians from a distance, divide the distance by the radius of the globe, ensuring that both the distance and the radius are in the same units.)
        buffer - an array in which to place the returned elevations. The array must be pre-allocated and contain at least as many elements as the list of locations.
        Returns:
        the resolution achieved, in radians, or Double.MAX_VALUE if individual elevations cannot be determined for all of the locations.
        See Also:
        ElevationModel.setMissingDataSignal(double)

      • getElevations

        protected double getElevations​(Sector sector,
                               java.util.List<? extends LatLon> latlons,
                               double targetResolution,
                               double[] buffer,
                               boolean mapMissingData)

      • getTargetLevel

        protected Level getTargetLevel​(Sector sector,
                               double targetSize)

      • getExtremeElevations

        public double[] getExtremeElevations​(Angle latitude,
                                     Angle longitude)
        Description copied from interface: ElevationModel
        Returns the minimum and maximum elevations at a specified location.
        Specified by:
        getExtremeElevations in interface ElevationModel
        Parameters:
        latitude - the latitude of the location in question.
        longitude - the longitude of the location in question.
        Returns:
        A two-element double array indicating, respectively, the minimum and maximum elevations at the specified location. These values are the global minimum and maximum if the local minimum and maximum values are currently unknown.

      • getExtremeElevations

        public double[] getExtremeElevations​(Sector sector)
        Description copied from interface: ElevationModel
        Returns the minimum and maximum elevations within a specified sector of the elevation model.
        Specified by:
        getExtremeElevations in interface ElevationModel
        Parameters:
        sector - the sector in question.
        Returns:
        A two-element double array indicating, respectively, the sector's minimum and maximum elevations. These elements are the global minimum and maximum if the local minimum and maximum values are currently unknown.

      • loadExtremeElevations

        public void loadExtremeElevations​(java.lang.String extremesFileName)

      • computeExtremeElevations

        protected double[] computeExtremeElevations​(Sector sector)

      • getExtremesLookupCache

        protected MemoryCache getExtremesLookupCache()
        Returns the memory cache used to cache extreme elevation computations, initializing the cache if it doesn't yet exist. This is an instance level cache: each instance of BasicElevationModel has its own instance of an extreme elevations lookup cache.
        Returns:
        the memory cache associated with the extreme elevations computations.

      • generateExtremeElevations

        public java.nio.ByteBuffer generateExtremeElevations​(int levelNumber)

      • retrieveResources

        protected java.lang.String retrieveResources()
        Retrieves any non-tile resources associated with this ElevationModel, either online or in the local filesystem, and initializes properties of this ElevationModel using those resources. This returns a key indicating the retrieval state: AVKey.RETRIEVAL_STATE_SUCCESSFUL indicates the retrieval succeeded, AVKey.RETRIEVAL_STATE_ERROR indicates the retrieval failed with errors, and null indicates the retrieval state is unknown. This method may invoke blocking I/O operations, and therefore should not be executed from the rendering thread.
        Returns:
        AVKey.RETRIEVAL_STATE_SUCCESSFUL if the retrieval succeeded, AVKey.RETRIEVAL_STATE_ERROR if the retrieval failed with errors, and null if the retrieval state is unknown.

      • initFromOGCCapabilitiesResource

        protected void initFromOGCCapabilitiesResource​(WMSCapabilities caps,
                                               AVList params)
        Initializes this ElevationModel's expiry time property from the specified WMS Capabilities document and parameter list describing the WMS layer names associated with this ElevationModel. This method is thread safe; it synchronizes changes to this ElevationModel by wrapping the appropriate method calls in SwingUtilities.invokeLater(Runnable).
        Parameters:
        caps - the WMS Capabilities document retrieved from this ElevationModel's WMS server.
        params - the parameter list describing the WMS layer names associated with this ElevationModel.
        Throws:
        java.lang.IllegalArgumentException - if either the Capabilities or the parameter list is null.

      • isRetrieveResources

        protected boolean isRetrieveResources()
        Returns a boolean value indicating if this ElevationModel should retrieve any non-tile resources, either online or in the local filesystem, and initialize itself using those resources.
        Returns:
        true if this ElevationModel should retrieve any non-tile resources, and false otherwise.

      • startResourceRetrieval

        protected void startResourceRetrieval()
        Starts retrieving non-tile resources associated with this model in a non-rendering thread.

      • createBasicElevationModelConfigDocument

        public static org.w3c.dom.Document createBasicElevationModelConfigDocument​(AVList params)
        Creates a configuration document for a BasicElevationModel described by the specified params. The returned document may be used as a construction parameter to BasicElevationModel.
        Parameters:
        params - parameters describing a BasicElevationModel.
        Returns:
        a configuration document for the BasicElevationModel.

      • writeConfigurationFile

        protected void writeConfigurationFile​(FileStore fileStore)

      • writeConfigurationParams

        protected void writeConfigurationParams​(AVList params,
                                        FileStore fileStore)

      • doWriteConfigurationParams

        protected void doWriteConfigurationParams​(FileStore fileStore,
                                          java.lang.String fileName,
                                          AVList params)

      • needsConfigurationFile

        protected boolean needsConfigurationFile​(FileStore fileStore,
                                         java.lang.String fileName,
                                         AVList params,
                                         boolean removeIfExpired)

      • getConfigurationParams

        protected AVList getConfigurationParams​(AVList params)

      • createConfigurationDocument

        protected org.w3c.dom.Document createConfigurationDocument​(AVList params)

      • getRestorableState

        public java.lang.String getRestorableState()
        Description copied from interface: Restorable
        Returns an XML document string describing the object's state. This state can be restored later by calling restoreState and passing the XML document.
        Specified by:
        getRestorableState in interface Restorable
        Overrides:
        getRestorableState in class AbstractElevationModel
        Returns:
        an XML document string describing the object's state.

      • restoreState

        public void restoreState​(java.lang.String stateInXml)
        Description copied from interface: Restorable
        Restores the object's state to what is described in the specified XML document string.
        Specified by:
        restoreState in interface Restorable
        Overrides:
        restoreState in class AbstractElevationModel
        Parameters:
        stateInXml - an XML document string describing an object's state.

      • restorableStateToParams

        protected static AVList restorableStateToParams​(java.lang.String stateInXml)

      • getLocalDataAvailability

        public double getLocalDataAvailability​(Sector requestedSector,
                                       java.lang.Double targetResolution)
        Description copied from interface: ElevationModel
        Returns the proportion of this elevation model's data that is local -- in the computer's data cache or installed data filestore -- for a specified sector and target resolution.
        Specified by:
        getLocalDataAvailability in interface ElevationModel
        Overrides:
        getLocalDataAvailability in class AbstractElevationModel
        Parameters:
        requestedSector - the sector of interest.
        targetResolution - the desired horizontal resolution, in radians, of the raster or other elevation sample from which elevations are drawn. (To compute radians from a distance, divide the distance by the radius of the globe, ensuring that both the distance and the radius are in the same units.) Specify null to use this elevation model's best resolution.
        Returns:
        the fraction of the data that is local. A value of 1.0 indicates that all the data is available.

      • isTileLocalOrAbsent

        protected boolean isTileLocalOrAbsent​(Tile tile)