agi.foundation.terrain

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

Class UsgsDigitalElevationModel

java.lang.Object

agi.foundation.terrain.TerrainProvider

agi.foundation.terrain.RasterTerrainProvider

agi.foundation.terrain.UsgsDigitalElevationModel

public class UsgsDigitalElevationModel
extends RasterTerrainProvider

A terrain provider for reading terrain from USGS Digital Elevation Model (DEM) files.

This TerrainProvider has a few limitations that prevent it from reading all USGS DEM files:

• Only the "geographic" ground-planimetric reference system is supported.
• Only the WGS84 horizontal datum is supported.
• Only the local mean sea level (MSL) vertical datum is supported. If the vertical datum is unspecified it is assumed to be MSL.

Attempting to load an unsupported DEM file will result in an InvalidDataException.

Constructor Summary

Constructors

Constructor and Description
UsgsDigitalElevationModel(StreamFactory streamFactory) Initializes a new instance with the specified stream factory.
UsgsDigitalElevationModel(StreamFactory streamFactory, TerrainCacheGroup cacheGroup) Initializes a new instance with the specified stream factory.
UsgsDigitalElevationModel(String fileName) Initializes a new instance using the specified DEM filename.
UsgsDigitalElevationModel(String fileName, TerrainCacheGroup cacheGroup) Initializes a new instance using the specified DEM filename.

Method Summary

Modifier and Type	Method and Description
TerrainPosts	getPosts(RasterTerrainIndexExtent extent) Gets the posts over a specified area by reading them from the terrain data source.

Methods inherited from class agi.foundation.terrain.RasterTerrainProvider

cartographicExtentToIndexExtent, getCache, getDefaultInterpolator, getDeltaLatitude, getDeltaLatitudeNativeUnits, getDeltaLongitude, getDeltaLongitudeNativeUnits, getEasternPostOffsetNativeUnits, getFirstPartials, getFirstPartials, getHeight, getHeight, getHeightNativeUnits, getHeightNativeUnits, getHeightRelativeToShape, getLatitudePosts, getLongitudePosts, getMinimumSampleSpacing, getNeedsSpecialCoordinateProcessing, getNorthernPostOffsetNativeUnits, getSecondPartials, getSecondPartials, getSouthernPostOffsetNativeUnits, getWesternPostOffsetNativeUnits, indexToLatitude, indexToLongitude, latitudeToIndex, longitudeToIndex, preloadExtent, processCoordinates, setDefaultInterpolator, setDeltaLatitude, setDeltaLatitudeNativeUnits, setDeltaLongitude, setDeltaLongitudeNativeUnits, setEasternPostOffsetNativeUnits, setLatitudePosts, setLongitudePosts, setNeedsSpecialCoordinateProcessing, setNorthernPostOffsetNativeUnits, setSouthernPostOffsetNativeUnits, setWesternPostOffsetNativeUnits, unloadExtent

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

UsgsDigitalElevationModel

public UsgsDigitalElevationModel(@Nonnull
                                 String fileName)

Initializes a new instance using the specified DEM filename.

Parameters:

fileName - The full path and filename of the DEM file.

Throws:

InvalidDataException -

Thrown when any of the following conditions are met:

• The DEM file specifies an unsupported ground planimetric reference system code.
• The vertical datum specified by the DEM file is unsupported.
• The horizontal datum specified by the DEM file is unsupported.
• The unit of measure for ground planimetric coordinates specified by the DEM file is unsupported.
• The coordinates of the bounding quadrangle in the DEM file do not define a rectangle.
• The number of profiles in the DEM file is different from the number of longitude posts expected based on the DEM extent and resolution.

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

ArgumentNullException - Thrown when fileName is null.

UsgsDigitalElevationModel

public UsgsDigitalElevationModel(@Nonnull
                                 String fileName,
                                 @Nonnull
                                 TerrainCacheGroup cacheGroup)

Initializes a new instance using the specified DEM filename.

Parameters:

fileName - The full path and filename of the DEM file.

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

Throws:

InvalidDataException -

Thrown when any of the following conditions are met:

• The DEM file specifies an unsupported ground planimetric reference system code.
• The vertical datum specified by the DEM file is unsupported.
• The horizontal datum specified by the DEM file is unsupported.
• The unit of measure for ground planimetric coordinates specified by the DEM file is unsupported.
• The coordinates of the bounding quadrangle in the DEM file do not define a rectangle.
• The number of profiles in the DEM file is different from the number of longitude posts expected based on the DEM extent and resolution.

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

ArgumentNullException - Thrown when fileName or cacheGroup is null.

UsgsDigitalElevationModel

public UsgsDigitalElevationModel(@Nonnull
                                 StreamFactory streamFactory)

Initializes a new instance with the specified stream factory.

The streams created by streamFactory must support seeking. This means that the streams must implement ISeekableStream or FileInputStream.

Parameters:

streamFactory - The factory to use to create streams to read the terrain data.

Throws:

InvalidDataException - Thrown when the InputStream from the streamFactory ended unexpectedly before the required terrain data could be read.

InvalidDataException -

Thrown when any of the following conditions are met:

• The DEM file specifies an unsupported ground planimetric reference system code.
• The vertical datum specified by the DEM file is unsupported.
• The horizontal datum specified by the DEM file is unsupported.
• The unit of measure for ground planimetric coordinates specified by the DEM file is unsupported.
• The coordinates of the bounding quadrangle in the DEM file do not define a rectangle.
• The number of profiles in the DEM file is different from the number of longitude posts expected based on the DEM extent and resolution.

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

ArgumentNullException - Thrown when streamFactory is null.

UsgsDigitalElevationModel

public UsgsDigitalElevationModel(@Nonnull
                                 StreamFactory streamFactory,
                                 @Nonnull
                                 TerrainCacheGroup cacheGroup)

Initializes a new instance with the specified stream factory.

The streams created by streamFactory must support seeking. This means that the streams must implement ISeekableStream or FileInputStream.

Parameters:

streamFactory - The factory to use to create streams to read the terrain data.

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

Throws:

InvalidDataException - Thrown when the InputStream from the streamFactory ended unexpectedly before the required terrain data could be read.

InvalidDataException -

Thrown when any of the following conditions are met:

• The DEM file specifies an unsupported ground planimetric reference system code.
• The vertical datum specified by the DEM file is unsupported.
• The horizontal datum specified by the DEM file is unsupported.
• The unit of measure for ground planimetric coordinates specified by the DEM file is unsupported.
• The coordinates of the bounding quadrangle in the DEM file do not define a rectangle.
• The number of profiles in the DEM file is different from the number of longitude posts expected based on the DEM extent and resolution.

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

ArgumentNullException - Thrown when streamFactory or cacheGroup is null.

Method Detail

getPosts

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

Specified by:

getPosts in class RasterTerrainProvider

Parameters:

extent - The extent of the posts to read.

Returns:

The requested posts.

Throws:

InvalidDataException - Thrown when terrain data source stream terminates unexpectedly before all of the required terrain data can be read.