agi.foundation.terrain

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

Class RasterTerrainProvider

java.lang.Object

agi.foundation.terrain.TerrainProvider

agi.foundation.terrain.RasterTerrainProvider

Direct Known Subclasses:

AGIProcessedDataTerrain, AGIWorldTerrain, EarthGravityModel96MeanSeaLevel, GeodasGriddedTerrain, GTOPO30Terrain, NgaDigitalTerrainElevationDataCell, UsgsDigitalElevationModel

public abstract class RasterTerrainProvider
extends TerrainProvider

The base class for raster-based terrain providers. Raster terrain is organized on a regularly spaced grid.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	RasterTerrainProvider() Initializes a new instance as a member of the default TerrainCacheGroup.
protected	RasterTerrainProvider(TerrainCacheGroup cacheGroup) Initializes a new instance.

Method Summary

Modifier and Type	Method and Description
RasterTerrainIndexExtent	cartographicExtentToIndexExtent(double westLongitude, double southLatitude, double eastLongitude, double northLatitude) Gets the post indices corresponding to a given cartographic extent.
RasterTerrainCache	getCache() Gets the cache for this terrain provider.
RasterTerrainInterpolator	getDefaultInterpolator() Gets the default interpolator to use to interpolate heights when a specific interpolator is not specified in the call to RasterTerrainProvider.getHeight(double,double) or RasterTerrainProvider.getHeightNativeUnits(double,double).
double	getDeltaLatitude() Gets the distance between each post in the latitude direction, in radians.
double	getDeltaLatitudeNativeUnits() Gets the distance between each post in the latitude direction, in the native units of the provider.
double	getDeltaLongitude() Gets the distance between each post in the longitude direction, in radians.
double	getDeltaLongitudeNativeUnits() Gets the distance between each post in the longitude direction, in the native units of the provider.
double	getEasternPostOffsetNativeUnits() Gets the longitude offset (from the east) of the eastern-most post in the terrain 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).
FirstPartialsOfHeight	getFirstPartials(double longitude, double latitude, RasterTerrainInterpolator interpolator) Get the interpolated 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	getHeight(double longitude, double latitude, RasterTerrainInterpolator interpolator) Gets the interpolated height of the terrain at the specified longitude and latitude using the specified TerrainInterpolator.
double	getHeightNativeUnits(double longitude, double latitude) Gets the interpolated height of the terrain at the specified longitude and latitude.
double	getHeightNativeUnits(double longitude, double latitude, RasterTerrainInterpolator interpolator) Gets the interpolated height of the terrain at the specified longitude and latitude.
double	getHeightRelativeToShape(double longitude, double latitude, RasterTerrainInterpolator interpolator) Gets the interpolated height of the terrain at the specified longitude and latitude relative to the provider's Shape (get / set).
int	getLatitudePosts() Gets the number of posts in the latitude direction.
int	getLongitudePosts() Gets the number of posts in the longitude direction.
double	getMinimumSampleSpacing() Gets the smallest distance between the successive height samples of the terrain data, in radians.
protected boolean	getNeedsSpecialCoordinateProcessing() Gets a value indicating whether or not special processing of longitude and latitude coordinates is required by this terrain provider.
double	getNorthernPostOffsetNativeUnits() Gets the latitude offset (from the north) of the northern-most post in the terrain provider.
abstract TerrainPosts	getPosts(RasterTerrainIndexExtent extent) Gets the posts over a specified area by reading them from the terrain data source.
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).
SecondPartialsOfHeight	getSecondPartials(double longitude, double latitude, RasterTerrainInterpolator interpolator) 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).
double	getSouthernPostOffsetNativeUnits() Gets the latitude offset (toward the north) of the southern-most post in the terrain provider.
double	getWesternPostOffsetNativeUnits() Gets the longitude offset (toward the east) of the western-most post in the terrain provider.
double	indexToLatitude(int index) Gets the latitude, in native units, of the post at a specified index.
double	indexToLongitude(int index) Gets the longitude, in native units, of the post at a specified index.
int	latitudeToIndex(double latitude) Gets the index of the post at or immediately to the south of the specified latitude.
int	longitudeToIndex(double longitude) Gets the index of the post at or immediately to the west of the specified longitude.
void	preloadExtent(CartographicExtent extent) Loads the terrain data in a given CartographicExtent into the terrain cache.
protected void	processCoordinates(double[] longitude, double[] latitude) Performs any additional processing of coordinate values prior to using them to load sets of posts or for interpolating heights.
void	setDefaultInterpolator(RasterTerrainInterpolator value) Sets the default interpolator to use to interpolate heights when a specific interpolator is not specified in the call to RasterTerrainProvider.getHeight(double,double) or RasterTerrainProvider.getHeightNativeUnits(double,double).
protected void	setDeltaLatitude(double value) Sets the distance between each post in the latitude direction, in radians.
protected void	setDeltaLatitudeNativeUnits(double value) Sets the distance between each post in the latitude direction, in the native units of the provider.
protected void	setDeltaLongitude(double value) Sets the distance between each post in the longitude direction, in radians.
protected void	setDeltaLongitudeNativeUnits(double value) Sets the distance between each post in the longitude direction, in the native units of the provider.
protected void	setEasternPostOffsetNativeUnits(double value) Sets the longitude offset (from the east) of the eastern-most post in the terrain provider.
protected void	setLatitudePosts(int value) Sets the number of posts in the latitude direction.
protected void	setLongitudePosts(int value) Sets the number of posts in the longitude direction.
protected void	setNeedsSpecialCoordinateProcessing(boolean value) Sets a value indicating whether or not special processing of longitude and latitude coordinates is required by this terrain provider.
protected void	setNorthernPostOffsetNativeUnits(double value) Sets the latitude offset (from the north) of the northern-most post in the terrain provider.
protected void	setSouthernPostOffsetNativeUnits(double value) Sets the latitude offset (toward the north) of the southern-most post in the terrain provider.
protected void	setWesternPostOffsetNativeUnits(double value) Sets the longitude offset (toward the east) of the western-most post in the terrain provider.
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

RasterTerrainProvider

protected RasterTerrainProvider()

Initializes a new instance as a member of the default TerrainCacheGroup.

RasterTerrainProvider

protected RasterTerrainProvider(@Nonnull
                                TerrainCacheGroup cacheGroup)

Initializes a new instance.

Parameters:

cacheGroup - The cache group of which this provider is a member.

Throws:

ArgumentNullException - Thrown when cacheGroup is null.

Method Detail

getCache

@Nonnull
public final RasterTerrainCache getCache()

Gets the cache for this terrain provider.

getDefaultInterpolator

public final RasterTerrainInterpolator getDefaultInterpolator()

Gets the default interpolator to use to interpolate heights when a specific interpolator is not specified in the call to RasterTerrainProvider.getHeight(double,double) or RasterTerrainProvider.getHeightNativeUnits(double,double).

setDefaultInterpolator

public final void setDefaultInterpolator(RasterTerrainInterpolator value)

Sets the default interpolator to use to interpolate heights when a specific interpolator is not specified in the call to RasterTerrainProvider.getHeight(double,double) or RasterTerrainProvider.getHeightNativeUnits(double,double).

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

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.

getHeight

public final double getHeight(double longitude,
                              double latitude,
                              RasterTerrainInterpolator interpolator)

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

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.

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.

interpolator - The RasterTerrainInterpolator to use to interpolate heights for points that do not fall precisely on a post.

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.

getHeightNativeUnits

public final double getHeightNativeUnits(double longitude,
                                         double latitude,
                                         RasterTerrainInterpolator interpolator)

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.

Parameters:

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

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

interpolator - The RasterTerrainInterpolator to use to interpolate heights for points that do not fall precisely on a post.

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.

getHeightRelativeToShape

public final double getHeightRelativeToShape(double longitude,
                                             double latitude,
                                             RasterTerrainInterpolator interpolator)

Gets the interpolated height of the terrain at the specified longitude and latitude relative to the provider's Shape (get / set). This method takes into account the heights of any reference surfaces.

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.

interpolator - The RasterTerrainInterpolator to use to interpolate heights for points that do not fall precisely on a post.

Returns:

The height of terrain relative to Shape (get / set), in meters.

Throws:

IllegalStateException - Thrown when any reference surface does not have the same Shape (get / set) and ShapeFixedFrame (get / set) as this terrain provider.

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.

getFirstPartials

@Nonnull
public final FirstPartialsOfHeight getFirstPartials(double longitude,
                                                              double latitude,
                                                              RasterTerrainInterpolator interpolator)

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

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.

interpolator - The interpolator to use when computing the value of the partial derivatives inside the boundary.

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.

getSecondPartials

@Nonnull
public final SecondPartialsOfHeight getSecondPartials(double longitude,
                                                                double latitude,
                                                                RasterTerrainInterpolator interpolator)

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).

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.

interpolator - The interpolator to use when computing the value of the partial derivatives inside the boundary.

Returns:

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

getDeltaLongitude

public final double getDeltaLongitude()

Gets the distance between each post in the longitude direction, in radians.

setDeltaLongitude

protected final void setDeltaLongitude(double value)

Sets the distance between each post in the longitude direction, in radians.

getDeltaLongitudeNativeUnits

public final double getDeltaLongitudeNativeUnits()

Gets the distance between each post in the longitude direction, in the native units of the provider.

setDeltaLongitudeNativeUnits

protected final void setDeltaLongitudeNativeUnits(double value)

Sets the distance between each post in the longitude direction, in the native units of the provider.

getDeltaLatitude

public final double getDeltaLatitude()

Gets the distance between each post in the latitude direction, in radians.

setDeltaLatitude

protected final void setDeltaLatitude(double value)

Sets the distance between each post in the latitude direction, in radians.

getDeltaLatitudeNativeUnits

public final double getDeltaLatitudeNativeUnits()

Gets the distance between each post in the latitude direction, in the native units of the provider.

setDeltaLatitudeNativeUnits

protected final void setDeltaLatitudeNativeUnits(double value)

Sets the distance between each post in the latitude direction, in the native units of the provider.

getLongitudePosts

public final int getLongitudePosts()

Gets the number of posts in the longitude direction.

setLongitudePosts

protected final void setLongitudePosts(int value)

Sets the number of posts in the longitude direction.

getLatitudePosts

public final int getLatitudePosts()

Gets the number of posts in the latitude direction.

setLatitudePosts

protected final void setLatitudePosts(int value)

Sets the number of posts in the latitude direction.

getWesternPostOffsetNativeUnits

public final double getWesternPostOffsetNativeUnits()

Gets the longitude offset (toward the east) of the western-most post in the terrain provider.

setWesternPostOffsetNativeUnits

protected final void setWesternPostOffsetNativeUnits(double value)

Sets the longitude offset (toward the east) of the western-most post in the terrain provider.

getSouthernPostOffsetNativeUnits

public final double getSouthernPostOffsetNativeUnits()

Gets the latitude offset (toward the north) of the southern-most post in the terrain provider.

setSouthernPostOffsetNativeUnits

protected final void setSouthernPostOffsetNativeUnits(double value)

Sets the latitude offset (toward the north) of the southern-most post in the terrain provider.

getEasternPostOffsetNativeUnits

public final double getEasternPostOffsetNativeUnits()

Gets the longitude offset (from the east) of the eastern-most post in the terrain provider.

setEasternPostOffsetNativeUnits

protected final void setEasternPostOffsetNativeUnits(double value)

Sets the longitude offset (from the east) of the eastern-most post in the terrain provider.

getNorthernPostOffsetNativeUnits

public final double getNorthernPostOffsetNativeUnits()

Gets the latitude offset (from the north) of the northern-most post in the terrain provider.

setNorthernPostOffsetNativeUnits

protected final void setNorthernPostOffsetNativeUnits(double value)

Sets the latitude offset (from the north) of the northern-most post in the terrain provider.

getPosts

@Nonnull
public abstract TerrainPosts getPosts(@Nonnull
                                                RasterTerrainIndexExtent extent)

Gets the posts over a specified area by reading them from the terrain data source. This method is not expected to do any caching.

Parameters:

extent - The extent of the posts to read.

Returns:

The requested posts.

indexToLongitude

public final double indexToLongitude(int index)

Gets the longitude, in native units, of the post at a specified index.

Parameters:

index - The index.

Returns:

The longitude of the post at the index, in native units.

indexToLatitude

public final double indexToLatitude(int index)

Gets the latitude, in native units, of the post at a specified index.

Parameters:

index - The index.

Returns:

The latitude of the post at the index, in native units.

longitudeToIndex

public final int longitudeToIndex(double longitude)

Gets the index of the post at or immediately to the west of the specified longitude.

Parameters:

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

Returns:

The index of the post at or immediately to the west of the specified longitude.

latitudeToIndex

public final int latitudeToIndex(double latitude)

Gets the index of the post at or immediately to the south of the specified latitude.

Parameters:

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

Returns:

The index of the post at or immediately to the south of the specified latitude.

cartographicExtentToIndexExtent

@Nonnull
public final RasterTerrainIndexExtent cartographicExtentToIndexExtent(double westLongitude,
                                                                                double southLatitude,
                                                                                double eastLongitude,
                                                                                double northLatitude)

Gets the post indices corresponding to a given cartographic extent.

Parameters:

westLongitude - The western boundary of the extent, in the provider's native units.

southLatitude - The southern boundary of the extent, in the provider's native units.

eastLongitude - The eastern boundary of the extent, in the provider's native units.

northLatitude - The northern boundary of the extent, in the provider's native units.

Returns:

The indices of the posts that bound the requested extent. This method always returns an extent that includes at least two posts in each direction. If the two longitudes or two latitudes are identical, the indices of the posts to either side are returned. If the two longitudes and two latitudes are both identical and fall exactly on a post, the returned extent will include three posts in that direction. However, if the identical values that fall on a post happen to be on the edge of the entire terrain region, only two posts will be returned in that direction. If the coordinates indicate indices outside the extent of the terrain, the indices will be clamped to the terrain edges.

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 RasterTerrainProvider.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.

getNeedsSpecialCoordinateProcessing

protected final boolean getNeedsSpecialCoordinateProcessing()

Gets a value indicating whether or not special processing of longitude and latitude coordinates is required by this terrain provider. If this value is true, RasterTerrainProvider.getHeightNativeUnits(double,double,RasterTerrainInterpolator) will call RasterTerrainProvider.processCoordinates(double[], double[]) before using the coordinates to load sets of posts or interpolate heights.

setNeedsSpecialCoordinateProcessing

protected final void setNeedsSpecialCoordinateProcessing(boolean value)

Sets a value indicating whether or not special processing of longitude and latitude coordinates is required by this terrain provider. If this value is true, RasterTerrainProvider.getHeightNativeUnits(double,double,RasterTerrainInterpolator) will call RasterTerrainProvider.processCoordinates(double[], double[]) before using the coordinates to load sets of posts or interpolate heights.

processCoordinates

protected void processCoordinates(@Nonnull
                                  double[] longitude,
                                  @Nonnull
                                  double[] latitude)

Performs any additional processing of coordinate values prior to using them to load sets of posts or for interpolating heights. This method is only called if NeedsSpecialCoordinateProcessing (get / set) is true.

Parameters:

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

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