agi.foundation.terrain

(agi.foundation.terrainreaders-2024r3.jar)

Class NgaDigitalTerrainElevationData

java.lang.Object

agi.foundation.terrain.TerrainProvider

agi.foundation.terrain.NgaDigitalTerrainElevationData

public class NgaDigitalTerrainElevationData
extends TerrainProvider

A terrain provider for reading terrain from National Geospatial-Intelligence Agency (NGA) Digital Terrain Elevation Data (DTED) files.

Constructor Summary

Constructors

Constructor and Description
NgaDigitalTerrainElevationData(FileStreamFactory dmedFileStreamFactory) Initializes a new instance with the specified file stream factory for a DMED file.
NgaDigitalTerrainElevationData(FileStreamFactory dmedFileStreamFactory, TerrainCacheGroup cacheGroup) Initializes a new instance with the specified file stream factory for a DMED file.
NgaDigitalTerrainElevationData(String dmedFileName) Initializes a new instance using the specified DMED filename.
NgaDigitalTerrainElevationData(String dtedDirectory, int southLatitudeDegrees, int northLatitudeDegrees, int westLongitudeDegrees, int eastLongitudeDegrees) Initializes a new instance with the specified information.
NgaDigitalTerrainElevationData(String dtedDirectory, int southLatitudeDegrees, int northLatitudeDegrees, int westLongitudeDegrees, int eastLongitudeDegrees, TerrainCacheGroup cacheGroup) Initializes a new instance with the specified information.
NgaDigitalTerrainElevationData(String dmedFileName, TerrainCacheGroup cacheGroup) Initializes a new instance using the specified DMED filename.

Method Summary

Modifier and Type	Method and Description
TerrainCacheGroup	getCacheGroup() Gets the TerrainCacheGroup that contains this provider.
FirstPartialsOfHeight	getFirstPartials(double longitude, double latitude) Get the partial derivatives of height with respect to the specified longitude and latitude relative to the provider's Shape (get / set).
double	getHeight(double longitude, double latitude) Gets the interpolated height of the terrain at the specified longitude and latitude using the default interpolator for this terrain provider.
double	getHeightNativeUnits(double longitude, double latitude) Gets the interpolated height of the terrain at the specified longitude and latitude.
double	getMinimumSampleSpacing() Gets the smallest distance between the successive height samples of the terrain data, in radians.
SecondPartialsOfHeight	getSecondPartials(double longitude, double latitude) Get the second order (mixed) partial derivatives of height with respect to the specified longitude and latitude relative to the provider's Shape (get / set).
void	preloadExtent(CartographicExtent extent) Loads the terrain data in a given CartographicExtent into the terrain cache.
void	unloadExtent(CartographicExtent extent) Unloads the cached terrain data for a given CartographicExtent.

Methods inherited from class agi.foundation.terrain.TerrainProvider

getBoundingExtent, getBoundingExtentNativeUnits, getGradient, getHeightReference, getHeightRelativeToShape, getHessian, getLocalMinimumSampleSpacing, getNativeToMeters, getNormal, getRadiansToNative, getReferenceSurface, getShape, getShapeFixedFrame, inGlobalBounds, setBoundingExtent, setBoundingExtentNativeUnits, setHeightReference, setNativeToMeters, setRadiansToNative, setReferenceSurface, setShape, setShapeFixedFrame

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NgaDigitalTerrainElevationData

public NgaDigitalTerrainElevationData(@Nonnull
                                      String dmedFileName)

Initializes a new instance using the specified DMED filename.

Parameters:

dmedFileName - The full path and filename of the DMED file.

Throws:

IllegalStateException - Thrown when the Earth (get) instance in the current CalculationContext is not configured with a mean sea level (MSL).

InvalidDataException - Thrown when the DMED file does not have the expected format.

ArgumentNullException - Thrown when dmedFileName is null.

NgaDigitalTerrainElevationData

public NgaDigitalTerrainElevationData(@Nonnull
                                      String dmedFileName,
                                      @Nonnull
                                      TerrainCacheGroup cacheGroup)

Initializes a new instance using the specified DMED filename.

Parameters:

dmedFileName - The full path and filename of the DMED file.

cacheGroup - The cache group with which to associate this terrain provider.

Throws:

IllegalStateException - Thrown when the Earth (get) instance in the current CalculationContext is not configured with a mean sea level (MSL).

InvalidDataException - Thrown when the DMED file does not have the expected format.

ArgumentNullException - Thrown when dmedFileName or cacheGroup is null.

NgaDigitalTerrainElevationData

public NgaDigitalTerrainElevationData(@Nonnull
                                      FileStreamFactory dmedFileStreamFactory)

Initializes a new instance with the specified file stream factory for a DMED file.

Parameters:

dmedFileStreamFactory - The factory to use to create streams to read the DMED file.

Throws:

IllegalStateException - Thrown when the Earth (get) instance in the current CalculationContext is not configured with a mean sea level (MSL).

InvalidDataException - Thrown when the DMED file does not have the expected format, or the stream ends unexpectedly.

ArgumentNullException - Thrown when dmedFileStreamFactory is null.

NgaDigitalTerrainElevationData

public NgaDigitalTerrainElevationData(@Nonnull
                                      FileStreamFactory dmedFileStreamFactory,
                                      @Nonnull
                                      TerrainCacheGroup cacheGroup)

Initializes a new instance with the specified file stream factory for a DMED file.

Parameters:

dmedFileStreamFactory - The factory to use to create streams to read the DMED file.

cacheGroup - The cache group with which to associate this terrain provider.

Throws:

IllegalStateException - Thrown when the Earth (get) instance in the current CalculationContext is not configured with a mean sea level (MSL).

InvalidDataException - Thrown when the DMED file does not have the expected format, or the stream ends unexpectedly.

ArgumentNullException - Thrown when dmedFileStreamFactory or cacheGroup is null.

NgaDigitalTerrainElevationData

public NgaDigitalTerrainElevationData(@Nonnull
                                      String dtedDirectory,
                                      int southLatitudeDegrees,
                                      int northLatitudeDegrees,
                                      int westLongitudeDegrees,
                                      int eastLongitudeDegrees)

Initializes a new instance with the specified information. If a DMED file is available for this data set, the constructor taking that file should be used instead.

Parameters:

dtedDirectory - The directory containing DTED files, with the expected directory structure, specifically, subdirectories named HDDD, each containing cell files named HDD.dtN, where H is the hemisphere, DDD is longitude degrees, DD is latitude degrees, and N is 0, 1, or 2.

southLatitudeDegrees - The south latitude of the bounding rectangle for the data set, in degrees, with positive values representing latitudes in the northern hemisphere and negative values representing latitudes in the southern hemisphere.

northLatitudeDegrees - The north latitude of the bounding rectangle for the data set, in degrees, with positive values representing latitudes in the northern hemisphere and negative values representing latitudes in the southern hemisphere.

westLongitudeDegrees - The west longitude of the bounding rectangle for the data set, in degrees, with positive values representing longitudes in the eastern hemisphere and negative values representing longitudes in the western hemisphere.

eastLongitudeDegrees - The east longitude of the bounding rectangle for the data set, in degrees, with positive values representing longitudes in the eastern hemisphere and negative values representing longitudes in the western hemisphere.

Throws:

IllegalStateException - Thrown when the Earth (get) instance in the current CalculationContext is not configured with a mean sea level (MSL).

ArgumentNullException - Thrown when dtedDirectory is null.

NgaDigitalTerrainElevationData

public NgaDigitalTerrainElevationData(@Nonnull
                                      String dtedDirectory,
                                      int southLatitudeDegrees,
                                      int northLatitudeDegrees,
                                      int westLongitudeDegrees,
                                      int eastLongitudeDegrees,
                                      @Nonnull
                                      TerrainCacheGroup cacheGroup)

Initializes a new instance with the specified information. If a DMED file is available for this data set, the constructor taking that file should be used instead.

Parameters:

cacheGroup - The cache group with which to associate this terrain provider.

dtedDirectory - The directory containing DTED files, with the expected directory structure, specifically, subdirectories named HDDD, each containing cell files named HDD.dtN, where H is the hemisphere, DDD is longitude degrees, DD is latitude degrees, and N is 0, 1, or 2.

southLatitudeDegrees - The south latitude of the bounding rectangle for the data set, in degrees, with positive values representing latitudes in the northern hemisphere and negative values representing latitudes in the southern hemisphere.

northLatitudeDegrees - The north latitude of the bounding rectangle for the data set, in degrees, with positive values representing latitudes in the northern hemisphere and negative values representing latitudes in the southern hemisphere.

westLongitudeDegrees - The west longitude of the bounding rectangle for the data set, in degrees, with positive values representing longitudes in the eastern hemisphere and negative values representing longitudes in the western hemisphere.

eastLongitudeDegrees - The east longitude of the bounding rectangle for the data set, in degrees, with positive values representing longitudes in the eastern hemisphere and negative values representing longitudes in the western hemisphere.

Throws:

IllegalStateException - Thrown when the Earth (get) instance in the current CalculationContext is not configured with a mean sea level (MSL).

ArgumentNullException - Thrown when dtedDirectory or cacheGroup is null.

Method Detail

getCacheGroup

@Nonnull
public final TerrainCacheGroup getCacheGroup()

Gets the TerrainCacheGroup that contains this provider.

getHeight

public double getHeight(double longitude,
                        double latitude)

Gets the interpolated height of the terrain at the specified longitude and latitude using the default interpolator for this terrain provider.

If HeightReference (get / set) is HeightReference.REFERENCE_SURFACE, the returned height is relative to the surface specified by the ReferenceSurface (get / set) property. If HeightReference (get / set) is HeightReference.SHAPE, the returned height is relative to the ellipsoid specified by the Shape (get / set) property. This method may return Double.NaN if the requested longitude and latitude are outside the terrain region or if the terrain data indicates that the height is unknown.

It is safe to call this method from multiple threads simultaneously.

Specified by:

getHeight in class TerrainProvider

Parameters:

longitude - The longitude, in radians. Requesting a height for a longitude less than -π or greater than π will always return Double.NaN.

latitude - The latitude, in radians. Requesting a height for a latitude less than -π/2 or greater than π/2 will always return Double.NaN.

Returns:

The height, in meters, or Double.NaN if the height is not available at the requested longitude and latitude.

getHeightNativeUnits

public double getHeightNativeUnits(double longitude,
                                   double latitude)

Gets the interpolated height of the terrain at the specified longitude and latitude.

If HeightReference (get / set) is HeightReference.REFERENCE_SURFACE, the returned height is relative to the surface specified by the ReferenceSurface (get / set) property. If HeightReference (get / set) is HeightReference.SHAPE, the returned height is relative to the ellipsoid specified by the Shape (get / set) property. This method may return Double.NaN if the requested longitude and latitude are outside the terrain region or if the terrain data indicates that the height is unknown.

It is safe to call this method from multiple threads simultaneously.

Specified by:

getHeightNativeUnits in class TerrainProvider

Parameters:

longitude - The longitude, in the native units of the terrain provider.

latitude - The latitude, in the native units of the terrain provider.

Returns:

The height, in the native units of the terrain provider, or Double.NaN if the height is not available at the requested longitude and latitude.

getFirstPartials

@Nonnull
public FirstPartialsOfHeight getFirstPartials(double longitude,
                                                        double latitude)

Get the partial derivatives of height with respect to the specified longitude and latitude relative to the provider's Shape (get / set).

Specified by:

getFirstPartials in class TerrainProvider

Parameters:

longitude - The longitude, in radians. Requesting derivatives for a longitude less than -π or greater than π will always return Double.NaN.

latitude - The latitude, in radians. Requesting derivatives for a latitude less than -π/2 or greater than π/2 will always return Double.NaN.

Returns:

The FirstPartialsOfHeight with respect to longitude and latitude, in meters of height per radian.

getSecondPartials

@Nonnull
public SecondPartialsOfHeight getSecondPartials(double longitude,
                                                          double latitude)

Get the second order (mixed) partial derivatives of height with respect to the specified longitude and latitude relative to the provider's Shape (get / set).

Specified by:

getSecondPartials in class TerrainProvider

Parameters:

longitude - The longitude, in radians. Requesting derivatives for a longitude less than -π or greater than π will always return Double.NaN.

latitude - The latitude, in radians. Requesting derivatives for a latitude less than -π/2 or greater than π/2 will always return Double.NaN.

Returns:

The SecondPartialsOfHeight with respect to longitude and latitude, in meters of height per radian squared.

preloadExtent

public void preloadExtent(CartographicExtent extent)

Loads the terrain data in a given CartographicExtent into the terrain cache. This method does not return until the terrain data is fully loaded. All terrain data within the extent is loaded into memory, even if doing so would exceed the TerrainCacheGroup's MaximumSize (get / set). Furthermore, the loaded terrain data is locked in memory (meaning it will not be unloaded) until the user calls NgaDigitalTerrainElevationData.unloadExtent(agi.foundation.coordinates.CartographicExtent). This method is safe to call from any thread.

Specified by:

preloadExtent in class TerrainProvider

Parameters:

extent - The extent for which to load terrain data, in radians.

Throws:

ArgumentNullException - Thrown when extent is null.

unloadExtent

public void unloadExtent(CartographicExtent extent)

Unloads the cached terrain data for a given CartographicExtent. This method unloads all cached regions where any part of the region falls within the extent. It does not return until the regions have been unloaded. However, if a region within the extent is being used in another thread while this method is executing, the region may be reloaded immediately after this method unloads it. This method is safe to call from any thread.

Specified by:

unloadExtent in class TerrainProvider

Parameters:

extent - The CartographicExtent for which to unload terrain, in radians.

Throws:

ArgumentNullException - Thrown when extent is null.

getMinimumSampleSpacing

public double getMinimumSampleSpacing()

Gets the smallest distance between the successive height samples of the terrain data, in radians. If the return value is 0.0, then the minimum sample spacing is unknown.

Overrides:

getMinimumSampleSpacing in class TerrainProvider