Inheritance diagram for TSLTerrainDatabase:

Detailed Description

The TSLTerrainDatabase class provides functions to access the data stored within a terrain database.

This component provides the following capabilites:

File management of a single Terrain Database (open/close)
Setting the resolution of the terrain required
Querying points, lines and areas for terrain information

When initially opened, TSLTerrainDatabase will return terrain data from the first terrain layer in the database at the highest resolution. To optimise the performance of the database, the 'displayExtent' method should be called to indicate the required layer and resolution which is automatically determined using a combination of the display extent and window extent passed to the function.

Typical use of this class involves:

1) Open the terrain database using open() 2) Set the resolution required using displayExtent() 3) Query data from the database 4) Close the database when no more terrain information is required.

The parameters set by the displayExtent method may also be set via setCurrent Layer, and via the TSLTerrainDatabaseLayer object.

The terrain database is automatically closed on destruction of the TSLTerrain Database object.

Terrain Database Units

The units of the terrain database are the units of the output coordinate system when generated from Studio.

In the case of the Default Coordinate System the units will be the units of the input data. For DTED this is latitude/longitude.

Where an output coordinate system is defined then the units are usually meters.

The stored height value is the units used by the input data. This is usually meters.

Performance Considerations

When performing queries on terrain data the accuracy of the results is determined by the number or size of sample points specified. Depending on the number of sample points requested and the resolution of the terrain data this can cause low accuracy data to be returned when the number of sample points is too low, or performance degredation when too high. An application should take care to choose a sensible value based upon the required accuracy vs performance tradeoff.

Public Types
enum	TSLTerrainDatabaseTypeEnum { TSLTerrainDatabaseTypeStandard , TSLTerrainDatabaseTypeDTED }

Public Member Functions
	TSLTerrainDatabase ()

virtual	~TSLTerrainDatabase ()

void	cacheSize (unsigned int newSize)

unsigned int	cacheSize () const

virtual void	close ()

virtual TSLTerrainReturn	displayExtent (int wndWidth, int wndHeight, double x1, double y1, double x2, double y2)

TSLTerrainReturn	findLOSIntersection (double startLatitude, double startLongitude, double startAltitude, double suppressionAngle, double bearing, double sampleDistance, bool allowForCurvatureOfEarth, bool useHighestResolution, double maximumAltitude, TSLTerrainInterpolate interpolate, bool &intercepts, double &interceptLatitude, double &interceptLongitude, double &interceptAltitude, bool ignoreNull=false, bool local=false)

virtual int	getCurrentLayer () const

virtual TSLTerrainDatabaseLayer *	getLayerAt (int index) const

virtual bool	isOpen ()

TSLTerrainReturn	latLongToMU (double latitude, double longitude, double x, double y, bool local=false)

TSLTerrainReturn	MUToLatLong (double x, double y, double latitude, double longitude, bool local=false, bool boundCheck=true)

virtual int	numberOfLayers () const

virtual TSLTerrainReturn	open (const char filename, const TSLPathList pathList=0)

double	postDistance (double x1, double y1, double x2, double y2, bool highestRes)

virtual TSLTerrainReturn	query (double x, double y, TSLTerrainDataItem *dataItem, TSLTerrainData_LEVEL filter=TSLTerrainData_Min, bool highestRes=false, TSLTerrainInterpolate interpolate=TSLTerrainInterpolate_NONE)

virtual TSLTerrainReturn	queryArea (double x1, double y1, double x2, double y2, int numX, int numY, TSLTerrainDataItem *data, TSLTerrainData_LEVEL filter=TSLTerrainData_Min, bool highestRes=false, TSLTerrainInterpolate interpolate=TSLTerrainInterpolate_NONE)

virtual TSLTerrainReturn	queryAreaForViewshed (double x1, double y1, double x2, double y2, int numX, int numY, double nullDataValue, double *data, TSLTerrainData_LEVEL filter=TSLTerrainData_Min, bool highestRes=false, TSLTerrainInterpolate interpolate=TSLTerrainInterpolate_NONE)

double	queryAverageElevation (double startLatitude, double startLongitude, double endLatitude, double endLongitude, double width, bool vincenty=false, bool straightLine=false, int numPoints=0, int numPointsWidth=0, bool highestRes=false, TSLTerrainInterpolate interpolate=TSLTerrainInterpolate_NONE, bool local=false)

virtual TSLCoordinateSystem *	queryCoordinateSystem ()

virtual TSLTerrainReturn	queryExtent (double &x1, double &y1, double &x2, double &y2)

virtual TSLTerrainReturn	queryLine (double x1, double y1, double x2, double y2, int numPoints, TSLTerrainDataItem *data, TSLTerrainData_LEVEL filter=TSLTerrainData_Min, bool highestRes=false, TSLTerrainInterpolate interpolate=TSLTerrainInterpolate_NONE, bool latLonCrossesDateline=false)

virtual bool	setCurrentLayer (int index)

virtual TSLTerrainDatabaseTypeEnum	type () const

Protected Attributes
TerrainDatabase *	m_terrainDB

Member Enumeration Documentation

◆ TSLTerrainDatabaseTypeEnum

enum TSLTerrainDatabase::TSLTerrainDatabaseTypeEnum

Enumerator
TSLTerrainDatabaseTypeStandard
TSLTerrainDatabaseTypeDTED

Constructor & Destructor Documentation

◆ TSLTerrainDatabase()

TSLTerrainDatabase::TSLTerrainDatabase ( )

Default constructor.

◆ ~TSLTerrainDatabase()

virtual TSLTerrainDatabase::~TSLTerrainDatabase ( )

virtual

Destructor.

Member Function Documentation

◆ cacheSize() [1/2]

unsigned int TSLTerrainDatabase::cacheSize ( ) const

Returns the current terrain grid cache size in bytes used by the terrain database.

◆ cacheSize() [2/2]

void TSLTerrainDatabase::cacheSize ( unsigned int newSize )

Sets the size of the cache to use for storing terrain grids. The default cache size is 64Mb.

Parameters

newSize The size to use for the grid cache in bytes

◆ close()

virtual void TSLTerrainDatabase::close ( )

virtual

Closes the terrain database if one has previously been opened.

◆ displayExtent()

virtual TSLTerrainReturn TSLTerrainDatabase::displayExtent	(	int	wndWidth,
		int	wndHeight,
		double	x1,
		double	y1,
		double	x2,
		double	y2 )

virtual

Defines the resolution of the required terrain data. This gives a hint to the Terrain SDK as to which terrain layer should be used and at which detail (pyramid) level.

When using the terrain SDK to retrieve terrain for display alongside a Map Link map, the parameters to this function should match the size of the window in pixels along with the currently displayed extent of the map. This means the retrieval of terrain data is optimised for the extent on display.

Parameters

wndWidth,wndHeight	Width and height of the screen in pixels the terrain data is to be used with. If not being used to display terrain on the screen, the width and height specifies the size of a grid defining the resolution of the data to be returned.
x1,y1,x2,y2	Bottom-left and top-right coordinate that define, in the units stored within the terrain database, the extent of the data that is to be used in the grid. Note that this does not clip the terrain data to the extent - any point within the database can still be queried, it only sets the "pyramid" level to use, i.e. the definition of the data.

Returns: TSLTerrain_OK if successful else an error code.

◆ findLOSIntersection()

TSLTerrainReturn TSLTerrainDatabase::findLOSIntersection	(	double	startLatitude,
		double	startLongitude,
		double	startAltitude,
		double	suppressionAngle,
		double	bearing,
		double	sampleDistance,
		bool	allowForCurvatureOfEarth,
		bool	useHighestResolution,
		double	maximumAltitude,
		TSLTerrainInterpolate	interpolate,
		bool &	intercepts,
		double &	interceptLatitude,
		double &	interceptLongitude,
		double &	interceptAltitude,
		bool	ignoreNull = false,
		bool	local = false )

The method calculates the Line Of Sight intersection with the terrain by stepping along the great circle line which starts at startLatitude and start Longitude in the direction of the bearing.

Assumptions:

When the default coordinate system is used it is assumed the units of the database is degrees.

When an output coordinate system is defined the units of the database is assumed to be in meters.

Parameters

startLatitude	The starting latitude in degrees.
startLongitude	The starting longitude in degrees.
startAltitude	The starting altitude in meters.
suppressionAngle	The angle at which the intersection ray makes from horizontal line which is tangential with the Earth (ignoring effect of terrain) at the specified start position. The value is negative for looking down and positive for looking up. Valid values are between -90 and 90 degrees.
bearing	The bearing from north of the intersection ray (degrees). Valid values are between -180 and 180 degrees.
sampleDistance	The distance in meters at which to sample the terrain database. Intersections are performed along the line of sight based on this distance in order to determine the intersection point with the terrain. The intersection point returned will be the first sample point that is equal or below the height of the terrain, therefore using a smaller value here will increase the accuracy of the intersection at the cost of reducing the performance. A value should be chosen that balances speed and accuracy dependent on the use of this function inside the application.
allowForCurvatureOfEarth	Boolean flag: True then we take into account the curvature of the earth when calculating the height.
useHighestResolution	Boolean flag. True we use the highest available resolution terrain data.
maximumAltitude	The maximum altitude in meters. If the angle is shallow enough the intersection ray may not intersect with the Earth or Terrain. This limits the query.
interpolate	The interpolation mode to use when querying the terrain database. The value chosen will affect performance.
intercepts	Boolean return value indicating if we have an interception with the terrain.
interceptLatitude,interceptLongitude,interceptAltitude	Return values indicating where the interception occurred (in degrees and meters).
ignoreNull	Boolean flag. If false, the function returns immediately if a null data value is encountered and no intersection point will be returned. If true, null data areas will be ignored when determining the intersection point.
local	Indicates whether the lat/long co-ordinate is in WGS84 or the local datum.

Returns

The principal return values are

TSLTerrain_NoDataAtLocation A point we queried returned a NULL value.
TSLTerrain_OK Query was ok.
TSLTerrain_InvalidArgument An argument was invalid.
TSLTerrain_NullDataIgnoredInPath Returned if we find a Null data point which was ignored (see ignoreNull).

If ignoreNull is true then TSLTerrain_NoDataAtLocation can be returned to indicate that a point was queried which did not contain any data.

intercepts is set to true if we find an interception with the terrain. The values returned in interceptLatitude, interceptLongitude and interceptAltitude indicate the interception at this location when intercepts is true.

If intercepts is false then the interceptLatitude, interceptLongitude indicate the location we returned at. This is the last position tested.

◆ getCurrentLayer()

virtual int TSLTerrainDatabase::getCurrentLayer ( ) const

virtual

Returns the current layer used by the Terrain Database.

The current layer may be set automatically via displayExtent, or manually via setCurrentLayer.

◆ getLayerAt()

virtual TSLTerrainDatabaseLayer * TSLTerrainDatabase::getLayerAt ( int index ) const

virtual

Query the database layer object for the specified index.

This object may be used to retrieve information about individual layers, and to set layer-specific parameters.

This object should be deleted by the application.

◆ isOpen()

virtual bool TSLTerrainDatabase::isOpen ( )

virtual

Returns true if the database has been successfully opened.

◆ latLongToMU()

TSLTerrainReturn TSLTerrainDatabase::latLongToMU	(	double	latitude,
		double	longitude,
		double *	x,
		double *	y,
		bool	local = false )

Returns the MU position of a given latitude/longitude point. The conversion is performed using the coordinate system loaded from the current terrain database, configured by MapLink Studio.

Parameters

(latitude,longitude)	Geodetic position to convert to Map Units.
(x,y)	Pointers to doubles that will be filled with the Map Units for the required position on return.
local	Indicates whether the lat/long co-ordinate is in WGS84 or the local datum.

Returns: TSLTerrain_OK if successful else an error code.

◆ MUToLatLong()

TSLTerrainReturn TSLTerrainDatabase::MUToLatLong	(	double	x,
		double	y,
		double *	latitude,
		double *	longitude,
		bool	local = false,
		bool	boundCheck = true )

Returns the latitude/longitude position of a given Map Unit point. The conversion is performed using the coordinate system loaded from the current terrain database, configured by MapLink Studio.

Parameters

(x,y)	Position in Map Units of the point to convert.
(latitude,longitude)	Pointers to doubles that will contain the converted geodetic position on return.
local	Indicates whether the lat/long co-ordinate is in WGS84 or the local datum.
boundCheck	When the initial coordinates are outside of the map extent, the lat/long returned could be invalid. When this flag is true, a check for invalid results is performed. This check will double the processing time required by the method, but return a validated status code. If the specified coordinate is guaranteed to be within the map extent, then this flag may be turned off.

Returns: TSLTerrain_OK if successful else an error code.

◆ numberOfLayers()

virtual int TSLTerrainDatabase::numberOfLayers ( ) const

virtual

Returns the number of layers in the Terrain Database.

◆ open()

virtual TSLTerrainReturn TSLTerrainDatabase::open	(	const char *	filename,
		const TSLPathList *	pathList = 0 )

virtual

Attempt to open a terrain library or header file. Automatically closes any previous terrain database.

Parameters

filename	Full path to a filename of the library or header file to open. When a pathlist is specified, the filename can contain just the filename without the path.
pathlist	Optional MapLink pathlist detailing directories where to find terrain database files

Returns: TSLTerrain_OK if successful, else an error code.

◆ postDistance()

double TSLTerrainDatabase::postDistance	(	double	x1,
		double	y1,
		double	x2,
		double	y2,
		bool	highestRes )

postDistance returns the distance between height values for the area defined. The distance returned is in units of the database.

Assumptions:

The difference between the bottom longitude and and should be no greater then 180 degrees. This is so that crossing the dateline can be detected.

Parameters

x1,y1,x2,y2	Bottom-left and top-right coordinate that define, in the units stored within the terrain database, the extent of the data that is to be queried to find the smallest post distance.
highestRes	If true use the highest resolution data.

Returns: the smallest post distance found. Zero will be returned if an error occurred.

◆ query()

virtual TSLTerrainReturn TSLTerrainDatabase::query	(	double	x,
		double	y,
		TSLTerrainDataItem *	dataItem,
		TSLTerrainData_LEVEL	filter = TSLTerrainData_Min,
		bool	highestRes = false,
		TSLTerrainInterpolate	interpolate = TSLTerrainInterpolate_NONE )

virtual

Returns terrain information about the given point.

Parameters

(x,y)	Coordinate to retrieve data for. The units are the Map Units as created in MapLink Studio.
dataItem	Pointer to TSLTerrainDataItem structure to contain information on the point on return.
filter	Specifies the level of information to request from the database.
highestRes	If set to true, returns the highest resolution (most accurate) return data for the point. If false, data using the resolution setup with displayExtent().
interpolate	Defines the type of interpolation to use when determining the result of the query. The default value is TSLNTerrainInterpolate_NONE, i.e. no interpolation is performed.

Returns: TSLTerrain_OK if successful else an error code.

◆ queryArea()

virtual TSLTerrainReturn TSLTerrainDatabase::queryArea	(	double	x1,
		double	y1,
		double	x2,
		double	y2,
		int	numX,
		int	numY,
		TSLTerrainDataItem *	data,
		TSLTerrainData_LEVEL	filter = TSLTerrainData_Min,
		bool	highestRes = false,
		TSLTerrainInterpolate	interpolate = TSLTerrainInterpolate_NONE )

virtual

Returns information of a specific area using the required spacing.

The area is defined by the bottom-left and top-right values passed into the function. Data for the bottom-left coordinate is included in the returned data. Data for the top-right coordinate is not included in the returned data.

The caller is responsible for allocating enough room for the returned data grid.

The grid is return on a row by row basis with the first row being the range of longitude from the bottom-left to the bottom-right.

Parameters

(x1,y1)	bottom-left corner of the area. The units are the Map Units as created in MapLink Studio.
(x2,y2)	top-right corner of the area. The units are the Map Units as created in MapLink Studio.
numX,numY	Number of samples to retrieve along the x and y axis - also
defines	how large the buffer "data" should be numX * numY.
data	Pointer to an array of TSLTerrainDataItem structures, the size of which is equal to numPoints, to contain information on the points along the line on return.
filter	Specifies the level of information to request from the database.
highestRes	If set to true, returns the highest resolution (most accurate) return data for the point. If false, data using the resolution setup with displayExtent().
interpolate	Defines the type of interpolation to use when determining the result of the query. The default value is TSLNTerrainInterpolate_NONE, i.e. no interpolation is performed.

Returns: TSLTerrain_OK if successful else an error code.

◆ queryAreaForViewshed()

virtual TSLTerrainReturn TSLTerrainDatabase::queryAreaForViewshed	(	double	x1,
		double	y1,
		double	x2,
		double	y2,
		int	numX,
		int	numY,
		double	nullDataValue,
		double *	data,
		TSLTerrainData_LEVEL	filter = TSLTerrainData_Min,
		bool	highestRes = false,
		TSLTerrainInterpolate	interpolate = TSLTerrainInterpolate_NONE )

virtual

Returns information of a specific area using the required spacing.

The area is defined by the bottom-left and top-right values passed into the function. Data for the bottom-left coordinate is included in the returned data. Data for the top-right coordinate is not included in the returned data.

The caller is responsible for allocating enough room for the returned data grid.

The grid is return on a row by row basis with the first row being the range of longitude from the bottom-left to the bottom-right.

Parameters

(x1,y1)	bottom-left corner of the area. The units are the Map Units as created in MapLink Studio.
(x2,y2)	top-right corner of the area. The units are the Map Units as created in MapLink Studio.
numX,numY	Number of samples to retrieve along the x and y axis - also
defines	how large the buffer "data" should be numX * numY.
nullDataValue	The value to use if null data is found when performing the query.
data	Pointer to an array of doubles, the size of which is equal to num Points, to contain information on the points along the line on return.
filter	Specifies the level of information to request from the database. Only TSLTerrainData_Min or TSLTerrainData_Nearest is supported.
highestRes	If set to true, returns the highest resolution (most accurate) return data for the point. If false, data using the resolution setup with displayExtent().
interpolate	Defines the type of interpolation to use when determining the result of the query. The default value is TSLNTerrainInterpolate_NONE, i.e. no interpolation is performed.

Returns: TSLTerrain_OK if successful else an error code.

◆ queryAverageElevation()

double TSLTerrainDatabase::queryAverageElevation	(	double	startLatitude,
		double	startLongitude,
		double	endLatitude,
		double	endLongitude,
		double	width,
		bool	vincenty = false,
		bool	straightLine = false,
		int	numPoints = 0,
		int	numPointsWidth = 0,
		bool	highestRes = false,
		TSLTerrainInterpolate	interpolate = TSLTerrainInterpolate_NONE,
		bool	local = false )

Finds the average elevation along a line of specified width.

The great circle path is quicker to compute then the geodesic (Vincenty) path. The geodesic path is more accurate.

A straight line is quicker then geodesic or great circle path.

Over a small distance there is unlikely to be any difference in the values returned.

Assumptions:

The difference between the longitudeStart and longitudeEnd should be no greater then 180 degrees. This is so that crossing the dateline can be detected.

A straight line query across the a pole may not work as expected.

The map units of the terrain database are assumed to be meters when the coordinate system of the database is not latitude and longitude.

Parameters

startLatitude,startLongitude	Start position in degrees.
endLatitude,endLongitude	End position in degrees.
width	Width of line in map units of the terrain database. If the width is zero then series of single points will be queried along the line.
vincenty	Boolean. True if geodesic (WGS84) formula is to be used or false for great circle (sphere).
straightLine	Boolean : True if we treat the line as a straight line. If this variable is true then the vincenty flag is ignored. If this flag is flase we treat the line in accordance with the vincenty flag.
numPoints	Number of samples down the line. The more samples the slower the query. If this is zero then the number of points queried will be based on the post distance.
numPointsWidth	Number of samples across the line (width). If this is zero then the number of samples will be 1 if the width is zero or if the post distance is less then or equal to the width.
highestRes	If set to true, returns the highest resolution (most accurate) return data for the point. If false, data using the resolution setup with displayExtent().
interpolate	The interpolation mode to use when querying the terrain database. The value chossen will affect performance.
local	Indicates whether the lat/long co-ordinate is in WGS84 or the local datum.

Returns: The average elevation. Zero is returned if an error occurred (check the Error stack).

If any errors occur they will be found on the TSLErrorStack.

◆ queryCoordinateSystem()

virtual TSLCoordinateSystem * TSLTerrainDatabase::queryCoordinateSystem ( )

virtual

Returns the coordinate system used by the currently loaded terrain database as configured by MapLink Studio.

Returns a pointer to the coordinate system. If no coordinate system has been defined for the terrain database then the function returns 0.

◆ queryExtent()

virtual TSLTerrainReturn TSLTerrainDatabase::queryExtent	(	double &	x1,
		double &	y1,
		double &	x2,
		double &	y2 )

virtual

Returns the data extent covered by the terrain database. The extent is in the same units as are used by the terrain database.

Parameters

(x1,y1)	Filled with position of bottom-left corner on return.
(x2,y2)	Filled with position of top-right corner on return.

Returns: TSLTerrain_OK if successful else an error code.

◆ queryLine()

virtual TSLTerrainReturn TSLTerrainDatabase::queryLine	(	double	x1,
		double	y1,
		double	x2,
		double	y2,
		int	numPoints,
		TSLTerrainDataItem *	data,
		TSLTerrainData_LEVEL	filter = TSLTerrainData_Min,
		bool	highestRes = false,
		TSLTerrainInterpolate	interpolate = TSLTerrainInterpolate_NONE,
		bool	latLonCrossesDateline = false )

virtual

Returns information at regular spaces between the two lat/long points.

The number of samples between the two points is determined by the numPoints argument. Space should be allocated by the caller for numPoints TSLTerrain DataItem structures in the data parameter.

Parameters

(x1,y1)	First coordinate, defining the start of the line. The units are the Map Units as created in MapLink Studio.
(x2,y2)	Second coordinate, defining the end of the line. The units are the Map Units as created in MapLink Studio.
numPoints	Number of samples to retrieve along the line - also defines how large the buffer "dataItem" should be.
dataItem	Pointer to an array of TSLTerrainDataItem structures, the size of which is equal to numPoints, to contain information on the points along the line on return.
filter	Specifies the level of information to request from the database.
highestRes	If set to true, returns the highest resolution (most accurate) return data for the point. If false, data using the resolution setup with displayExtent().
interpolate	Defines the type of interpolation to use when determining the result of the query. The default value is TSLNTerrainInterpolate_NONE, i.e. no interpolation is performed.
latLonCrossesDateline	Set to true if the map uses latitude and longitude as its map units and the specified coordinates cross the dateline boundary, otherwise set to false. Defaults to false.

Returns: TSLTerrain_OK if successful else an error code.

◆ setCurrentLayer()

virtual bool TSLTerrainDatabase::setCurrentLayer ( int index )

virtual

Set the current layer used by the Terrain Database.

This will override any layer set by a call to displayExtent, and further calls to displayExtent will override this value.

Parameters

index The index of the layer to use.

Returns: true if the current layer was set, false otherwise.

◆ type()

virtual TSLTerrainDatabaseTypeEnum TSLTerrainDatabase::type ( ) const

virtual

Returns the type of this terrain database.

Reimplemented in TSLDTEDTerrainDatabase.

Member Data Documentation

◆ m_terrainDB

TerrainDatabase* TSLTerrainDatabase::m_terrainDB

protected

Detailed Description

Public Types

Public Member Functions

Protected Attributes

Member Enumeration Documentation

◆ TSLTerrainDatabaseTypeEnum

Constructor & Destructor Documentation

◆ TSLTerrainDatabase()

◆ ~TSLTerrainDatabase()

Member Function Documentation

◆ cacheSize() [1/2]

◆ cacheSize() [2/2]

◆ close()

◆ displayExtent()

◆ findLOSIntersection()

◆ getCurrentLayer()

◆ getLayerAt()

◆ isOpen()

◆ latLongToMU()

◆ MUToLatLong()

◆ numberOfLayers()

◆ open()

◆ postDistance()

◆ query()

◆ queryArea()

◆ queryAreaForViewshed()

◆ queryAverageElevation()

◆ queryCoordinateSystem()

◆ queryExtent()

◆ queryLine()

◆ setCurrentLayer()

◆ type()

Member Data Documentation

◆ m_terrainDB