agi.foundation.terrain

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

Class EllipsoidTerrainProvider

java.lang.Object

agi.foundation.terrain.TerrainProvider

agi.foundation.terrain.EllipsoidTerrainProvider

public class EllipsoidTerrainProvider
extends TerrainProvider

A very simple terrain provider that returns 0.0 whenever asked for a height. This class adapts an ellipsoid to act like a terrain provider.

Constructor Summary

Constructors

Constructor and Description
EllipsoidTerrainProvider() Initializes a new instance with the Shape (get / set) and FixedFrame (get / set) from the EarthCentralBody in the CentralBodiesFacet in the current CalculationContext.
EllipsoidTerrainProvider(Ellipsoid shape, ReferenceFrame shapeFixedFrame) Initializes a new instance with the specified shape and fixed frame.

Method Summary

Modifier and Type	Method and Description
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.
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, getMinimumSampleSpacing, 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

EllipsoidTerrainProvider

public EllipsoidTerrainProvider()

Initializes a new instance with the Shape (get / set) and FixedFrame (get / set) from the EarthCentralBody in the CentralBodiesFacet in the current CalculationContext.

EllipsoidTerrainProvider

public EllipsoidTerrainProvider(Ellipsoid shape,
                                ReferenceFrame shapeFixedFrame)

Initializes a new instance with the specified shape and fixed frame.

Parameters:

shape - The ellipsoid shape in which the longitude, latitude, and altitude are specified.

shapeFixedFrame - The reference frame fixed to the ellipsoid.

Method Detail

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.

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

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.