agi.foundation.terrain

(agi.foundation.models-2025r1.jar)

Class TerrainProvider

java.lang.Object

agi.foundation.terrain.TerrainProvider

Direct Known Subclasses:

CompositeTerrainProvider, EllipsoidTerrainProvider, NgaDigitalTerrainElevationData, QuantizedMeshTerrainProvider, RasterTerrainProvider

public abstract class TerrainProvider
extends Object

The base class for all terrain providers. Terrain providers describe the surface of a central body by providing heights relative to an idealized ellipsoidal shape or relative to another terrain provider.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	TerrainProvider() Initializes a new instance.

Method Summary

Modifier and Type	Method and Description
CartographicExtent	getBoundingExtent() Gets the smallest rectangular extent that bounds the terrain provided by this terrain provider.
CartographicExtent	getBoundingExtentNativeUnits() Gets the smallest rectangular extent that bounds the terrain provided by this terrain provider.
abstract 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).
Cartesian	getGradient(double longitude, double latitude) Get the interpolated gradient of height with respect to the terrain at the specified longitude and latitude relative to the provider's Shape (get / set).
abstract 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.
abstract double	getHeightNativeUnits(double longitude, double latitude) Gets the interpolated height of the terrain at the specified longitude and latitude.
HeightReference	getHeightReference() Gets an enumeration indicating whether the heights returned by the TerrainProvider.getHeight(double, double) method are relative to the Shape (get / set) or to the ReferenceSurface (get / set).
double	getHeightRelativeToShape(double longitude, double latitude) Gets the interpolated height of the terrain at the specified longitude and latitude relative to the provider's Shape (get / set).
Matrix3By3	getHessian(double longitude, double latitude) Get the interpolated hessian matrix based on the function of height with respect to the specified longitude and latitude relative to the provider's Shape (get / set).
double	getLocalMinimumSampleSpacing(double longitude, double latitude) Gets the smallest distance between the successive height samples of the terrain data, in radians, at the specified coordinates.
double	getMinimumSampleSpacing() Gets the smallest distance between the successive height samples of the terrain data, in radians.
double	getNativeToMeters() Gets the value to multiply a height in the native units of the terrain provider to convert it to meters.
UnitCartesian	getNormal(double longitude, double latitude) Get the normal vector to the terrain surface at the specified location.
double	getRadiansToNative() Gets the value to multiply an angle in radians by in order to convert it to the internal units of the terrain provider.
TerrainProvider	getReferenceSurface() Gets the reference surface.
abstract 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).
Ellipsoid	getShape() Gets the shape on which the longitude and latitude are defined.
ReferenceFrame	getShapeFixedFrame() Gets the reference frame fixed to the Shape (get / set) in which the longitude and latitude are defined.
protected boolean	inGlobalBounds(double longitude, double latitude) Returns true if the coordinates are in global bounds which is: [-π, π] for longitude and [-π/2, π/2] for latitude.
abstract void	preloadExtent(CartographicExtent extent) Loads the terrain data in a given CartographicExtent into the terrain cache.
protected void	setBoundingExtent(CartographicExtent value) Sets the smallest rectangular extent that bounds the terrain provided by this terrain provider.
protected void	setBoundingExtentNativeUnits(CartographicExtent value) Sets the smallest rectangular extent that bounds the terrain provided by this terrain provider.
protected void	setHeightReference(HeightReference value) Sets an enumeration indicating whether the heights returned by the TerrainProvider.getHeight(double, double) method are relative to the Shape (get / set) or to the ReferenceSurface (get / set).
protected void	setNativeToMeters(double value) Sets the value to multiply a height in the native units of the terrain provider to convert it to meters.
protected void	setRadiansToNative(double value) Sets the value to multiply an angle in radians by in order to convert it to the internal units of the terrain provider.
protected void	setReferenceSurface(TerrainProvider value) Sets the reference surface.
protected void	setShape(Ellipsoid value) Sets the shape on which the longitude and latitude are defined.
protected void	setShapeFixedFrame(ReferenceFrame value) Sets the reference frame fixed to the Shape (get / set) in which the longitude and latitude are defined.
abstract void	unloadExtent(CartographicExtent extent) Unloads the cached terrain data for a given CartographicExtent.

Methods inherited from class java.lang.Object

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

Constructor Detail

TerrainProvider

protected TerrainProvider()

Initializes a new instance.

Method Detail

getShape

public final Ellipsoid getShape()

Gets the shape on which the longitude and latitude are defined. If ReferenceSurface (get / set) is null, the heights returned by TerrainProvider.getHeight(double, double) are relative to this ellipsoid as well.

setShape

protected final void setShape(Ellipsoid value)

Sets the shape on which the longitude and latitude are defined. If ReferenceSurface (get / set) is null, the heights returned by TerrainProvider.getHeight(double, double) are relative to this ellipsoid as well.

getShapeFixedFrame

public final ReferenceFrame getShapeFixedFrame()

Gets the reference frame fixed to the Shape (get / set) in which the longitude and latitude are defined.

setShapeFixedFrame

protected final void setShapeFixedFrame(ReferenceFrame value)

Sets the reference frame fixed to the Shape (get / set) in which the longitude and latitude are defined.

getReferenceSurface

public final TerrainProvider getReferenceSurface()

Gets the reference surface. The TerrainProvider.getHeight(double, double) method returns heights relative to this reference surface. If this property is null, the heights are relative to the surface of the Shape (get / set) ellipsoid instead.

setReferenceSurface

protected final void setReferenceSurface(TerrainProvider value)

Sets the reference surface. The TerrainProvider.getHeight(double, double) method returns heights relative to this reference surface. If this property is null, the heights are relative to the surface of the Shape (get / set) ellipsoid instead.

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.

getHeightReference

@Nonnull
public final HeightReference getHeightReference()

Gets an enumeration indicating whether the heights returned by the TerrainProvider.getHeight(double, double) method are relative to the Shape (get / set) or to the ReferenceSurface (get / set).

setHeightReference

protected final void setHeightReference(@Nonnull
                                        HeightReference value)

Sets an enumeration indicating whether the heights returned by the TerrainProvider.getHeight(double, double) method are relative to the Shape (get / set) or to the ReferenceSurface (get / set).

getBoundingExtent

public final CartographicExtent getBoundingExtent()

Gets the smallest rectangular extent that bounds the terrain provided by this terrain provider. The returned extent's edges are expressed in radians.

setBoundingExtent

protected final void setBoundingExtent(CartographicExtent value)

Sets the smallest rectangular extent that bounds the terrain provided by this terrain provider. The returned extent's edges are expressed in radians.

getBoundingExtentNativeUnits

public final CartographicExtent getBoundingExtentNativeUnits()

Gets the smallest rectangular extent that bounds the terrain provided by this terrain provider. The returned extent's edges are expressed in the native units of the terrain provider.

setBoundingExtentNativeUnits

protected final void setBoundingExtentNativeUnits(CartographicExtent value)

Sets the smallest rectangular extent that bounds the terrain provided by this terrain provider. The returned extent's edges are expressed in the native units of the terrain provider.

getLocalMinimumSampleSpacing

public double getLocalMinimumSampleSpacing(double longitude,
                                           double latitude)

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

Parameters:

longitude - The longitude, in radians.

latitude - The latitude, in radians.

Returns:

The smallest distance between the successive height samples of the terrain data, in radians.

getHeight

public abstract 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.

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

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.

getHeightRelativeToShape

public final double getHeightRelativeToShape(double longitude,
                                             double latitude)

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.

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

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

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.

getGradient

@Nonnull
public final Cartesian getGradient(double longitude,
                                             double latitude)

Get the interpolated gradient of height with respect to the terrain at the specified longitude and latitude relative to the provider's Shape (get / set). This method produces a vector representing the gradient of height in the ShapeFixedFrame (get / set).

Note: The direction for the gradient is defined for use as the outward facing surface normal direction. To obtain the directional derivative for the height (rate of change of height with respect to time), take the negative gradient and dot it with a unit vector along the desired azimuth (change in height with respect to distance), times the speed along that direction in meters/second.

The gradient, as defined above, is parallel to the upward facing terrain surface normal, but its magnitude indicates the rate of change in the height at that location.

Parameters:

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

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

Returns:

The gradient vector in the ShapeFixedFrame (get / set) at the given location, in meters of height per meters of surface distance.

getHessian

@Nonnull
public final Matrix3By3 getHessian(double longitude,
                                             double latitude)

Get the interpolated hessian matrix based on the function of height with respect to the specified longitude and latitude relative to the provider's Shape (get / set). This method produces a matrix representing the mixed second order partial derivatives of height in the ShapeFixedFrame (get / set).

Note: The direction for the gradient and hessian is defined for use with the directional derivative on the surface. The gradient is defined to be orthogonal to the terrain surface with its surface projection in the direction of the greatest increase in the height. To obtain the second directional derivative for the height (acceleration of height along a particular azimuth), take the negative of the hessian then pre and post multiply it by the velocity vector along the desired azimuth. Then add the negative gradient dotted with the derivative of the velocity vector along the surface.

Parameters:

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

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

Returns:

The hessian matrix expressed in the ShapeFixedFrame (get / set) at the given location, in meters of height per meters of surface distance squared.

inGlobalBounds

protected final boolean inGlobalBounds(double longitude,
                                       double latitude)

Returns true if the coordinates are in global bounds which is: [-π, π] for longitude and [-π/2, π/2] for latitude.

Parameters:

longitude - The longitude to check.

latitude - The latitude to check.

Returns:

A boolean value indicating if the coordinates are in global bounds.

getNormal

@Nonnull
public final UnitCartesian getNormal(double longitude,
                                               double latitude)

Get the normal vector to the terrain surface at the specified location.

Parameters:

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

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

Returns:

The surface normal, if longitude and latitude are within BoundingExtent (get / set); otherwise Undefined (get).

getRadiansToNative

public final double getRadiansToNative()

Gets the value to multiply an angle in radians by in order to convert it to the internal units of the terrain provider.

setRadiansToNative

protected final void setRadiansToNative(double value)

Sets the value to multiply an angle in radians by in order to convert it to the internal units of the terrain provider.

getNativeToMeters

public final double getNativeToMeters()

Gets the value to multiply a height in the native units of the terrain provider to convert it to meters.

setNativeToMeters

protected final void setNativeToMeters(double value)

Sets the value to multiply a height in the native units of the terrain provider to convert it to meters.

preloadExtent

public abstract void preloadExtent(@Nonnull
                                   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 TerrainProvider.unloadExtent(agi.foundation.coordinates.CartographicExtent). This method is safe to call from any thread.

Parameters:

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

Throws:

ArgumentNullException - Thrown when extent is null.

unloadExtent

public abstract void unloadExtent(@Nonnull
                                  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.

Parameters:

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

Throws:

ArgumentNullException - Thrown when extent is null.