This class is responsible for loading, removing, and interpolating LibCorr3D model objects for travel time, slowness, and azimuth attributes. More...

#include <LibCorr3D.h>

Public Member Functions
	LibCorr3D (const string &newRootPath, const string &newRelGridPath, const string &oldRootPath, const string &oldRelGridPath)
	Standard constructor. More...

	LibCorr3D (const string &newRootPath, const string &oldRootPath)
	Standard constructor. More...

	LibCorr3D (const string &rootPath)
	Standard constructor. More...

virtual	~LibCorr3D ()
	Destructor. More...

int	getCurrentErrorCode () const
	Return current error code. More...

const string &	getCurrentErrorMessage () const
	Return the errorMessage generated by the most recent call to getModelResult(). More...

double	getCurrentInterpolationDepth ()
	Retrieve the depth of the current interpolation location in km . More...

double	getCurrentInterpolationLat ()
	Retrieve the latitude of the current interpolation location in degrees. More...

string	getCurrentInterpolationLocation ()
	Retrieve a string representation of the current interpolation location (lon, lat, depth, epochTime). More...

const double *	getCurrentInterpolationLocation () const
	Retrieve the current interpolation location as a unit vector. More...

double	getCurrentInterpolationLon ()
	Retrieve the longitude of the current interpolation location in degrees. More...

double	getCurrentInterpolationRadius ()
	Retrieve the radius of the current interpolation location in km . More...

double	getCurrentInterpolationTime ()
	Retrieve the epoch time of the current interpolation location in seconds since 1970. More...

const GeoTessInterpolatorType &	getGeographicInterpolatorType () const
	Returns the current geographic interpolator type. More...

LONG_INT	getMemory ()
	Return the amount of memory currently occupied by this LibCorr3D object, including all of the LibCorr3DModel objects currently in memory, and all the LibCorr3DGrid objects referenced by those models. More...

LibCorr3DModel *	getModel (int handle)

bool	getModelResult (int handle, double &modelValue, double &modelUncertainty)
	The access function used to retrieve the model attribute and associated uncertainty results at the current interpolation location for the model associated with the input handle h. More...

const string &	getOldRelGridPath () const
	Returns the path where all old LibCorr2D tessellation files are stored relative to the old root path (lc3dOldRootPath). More...

const string &	getOldRootPath () const
	Returns the old (LibCorr2D) path corrections root path to the caller. More...

const GeoTessInterpolatorType &	getRadialInterpolatorType () const
	Returns the current geographic interpolator type. More...

const string &	getRelGridPath () const
	Returns the path where all the grid files are stored (new GeoTess) relative to the input root path (lc3dGTRootPath). More...

const string &	getRootPath () const
	Returns the primary (new GeoTess) root path to the caller. More...

int	loadModel (const string &fname, const GeoTessOptimizationType &optimizationType=GeoTessOptimizationType::SPEED)
	Loads a new model from the specified file and returns an associated handle to the caller for later access. More...

int	loadModel (const string &fname, vector< int > &attributeFilter, const GeoTessOptimizationType &optimizationType=GeoTessOptimizationType::SPEED)
	Loads a new model from the specified file and returns an associated handle to the caller for later access. More...

void	removeModel (int handle)
	Removes the specified model from the list of supported models and deletes it from memory. More...

LibCorr3D *	setInterpolationLocation (double *unitVector, double radius=-1., double time=NA_VALUE)
	Sets the current interpolation location/time. More...

LibCorr3D *	setInterpolationLocation (double lon, double lat, double depth=0.0, double time=NA_VALUE)
	Sets the current interpolation location/time. More...

void	setInterpolator (GeoTessInterpolatorType const intrpGeographic, GeoTessInterpolatorType const intrpRadial)
	Sets the geographic and radial interpolators to the specified types. More...

Static Public Member Functions
static string	getVersion ()

Detailed Description

This class is responsible for loading, removing, and interpolating LibCorr3D model objects for travel time, slowness, and azimuth attributes.

This object maintains a map of all loaded LibCorr3DModel objects and an accompanying array list of these objects stored by their associated handle. This provides a fast lookup facility during interpolation while the maps ensure that models are not loaded more than once. All models are loaded from a root path which is provided as an argument to the LibCorr3D constructor at instantiation.

Interpolation of any loaded model occurs by first setting the interpolation location which includes a latitude (degrees), longitude (degrees), depth (km), and time (epoch). The time is used to ensure that the loaded models station was active at the requested interpolation time. By calling the function with only the first three arguments (lon, lat, depth) a result is provided from the station regardless of the stations on/off status. Calling the function with only the first two arguments (lon, lat) returns a result at depth = 0.0 again ignoring the stations on/off status.

Once the interpolation location has been set the caller can request an interpolated result by calling the interpolation function with a handle of the model to be interpolated. The results (value and associated uncertainty) are returned as arguments in the function call. The type of attribute returned depends on the model type loaded and associated with the returned handle.

Interpolation of model values is accomplished separately in the geographic and radial dimensions and separate interpolation algorithms can be specified in these dimensions. In the geographic dimensions, linear interpolations results in bilateral interpolation being used inside the triangle where the interpolation position is located. With linear interpolation, model values will be continuous at triangle boundaries, but the derivatives of model values will not . If natural neighbor interpolation is specified for the geographic dimensions, then derivatives of interpolated model values will be continuous everywhere except at grid nodes. In the radial dimension, linear and cubic spline interpolation are supported. Interpolation algorithms use in the geographic and radial dimensions are independent of each other (you can mix-and-match low and high order interpolators). The interpolation algorithms used in the geographic and radial dimensions default to linear interpolation in both cases, but these can be changed by calling method setInterpolator().

Constructor & Destructor Documentation

◆ LibCorr3D() [1/3]

geotess::LibCorr3D::LibCorr3D ( const string & rootPath )

Standard constructor.

Parameters

rootPath Path to the directory that contains the LibCorr3D models, LibCorr2D models, LibCorr3D grids, and LibCorr2D grids.

◆ LibCorr3D() [2/3]

geotess::LibCorr3D::LibCorr3D	(	const string &	newRootPath,
		const string &	oldRootPath
	)

Standard constructor.

Parameters

newRootPath	Path to the directory that contains the new GeoTess LibCorr3D models and grids.
oldRootPath	Path to the directory that contains the old LibCorr2D models and tessellations.

◆ LibCorr3D() [3/3]

geotess::LibCorr3D::LibCorr3D	(	const string &	newRootPath,
		const string &	newRelGridPath,
		const string &	oldRootPath,
		const string &	oldRelGridPath
	)

Standard constructor.

Parameters

newRootPath	Path to the directory that contains the new GeoTess LibCorr3D models.
newRelGridPath	Relative path from newRootPath to the directory that contains the new GeoTess LibCorr3D grids.
oldRootPath	Path to the directory that contains the old LibCorr2D path correction models.
oldRelGridPath	Relative path from oldRootPath that contains the old LibCorr2D tessellation files.

◆ ~LibCorr3D()

virtual geotess::LibCorr3D::~LibCorr3D ( )

virtual

Destructor.

Member Function Documentation

◆ getCurrentErrorCode()

int geotess::LibCorr3D::getCurrentErrorCode ( ) const

inline

Return current error code.

If the call to getModelResults was successful, then the errorCode returned by getCurrentErrorCode() will be zero and the string returned by getCurrentErrorMessage() will be empty. Otherwise, the errorCode will a non-zero number and the errorMessage will return a description of what went wrong. The following errorCodes have the specified meanings.
0 : No error. Valid result returned.
-1 : The current interpolation position is outside the geographic range of the specified model.
-2 : The current interpolation time is outside the valid time range of the specified model (model on-off times). This only happens when the most recent call to setInterpolationLocation() specified an epoch time not equal to NA_VALUE.
-3 : The model associated with the specified handle is no longer in memory. It has been removed with a call to removeModel(handle).
-4 : Specified handle is out of range. < 0 or >= number of models that have been loaded (including models that have been removed).
>0 : This indicates a GeoTessException. The error message is also sent to standard error.
-99 : Some other unidentified exception.

◆ getCurrentErrorMessage()

const string & geotess::LibCorr3D::getCurrentErrorMessage ( ) const

inline

Return the errorMessage generated by the most recent call to getModelResult().

Result will be empty if no error was generated.

Returns: the errorMessage generated by the most recent call to getModelResult().

◆ getCurrentInterpolationDepth()

double geotess::LibCorr3D::getCurrentInterpolationDepth ( )

inline

Retrieve the depth of the current interpolation location in km .

Returns: the depth of the current interpolation location in km .

◆ getCurrentInterpolationLat()

double geotess::LibCorr3D::getCurrentInterpolationLat ( )

inline

Retrieve the latitude of the current interpolation location in degrees.

Returns: the latitude of the current interpolation location in degrees.

◆ getCurrentInterpolationLocation() [1/2]

string geotess::LibCorr3D::getCurrentInterpolationLocation ( )

inline

Retrieve a string representation of the current interpolation location (lon, lat, depth, epochTime).

Returns: a string representation of the current interpolation location (lon, lat, depth, epochTime).

◆ getCurrentInterpolationLocation() [2/2]

const double * geotess::LibCorr3D::getCurrentInterpolationLocation ( ) const

inline

Retrieve the current interpolation location as a unit vector.

Returns: the current interpolation location as a unit vector.

◆ getCurrentInterpolationLon()

double geotess::LibCorr3D::getCurrentInterpolationLon ( )

inline

Retrieve the longitude of the current interpolation location in degrees.

Returns: the longitude of the current interpolation location in degrees.

◆ getCurrentInterpolationRadius()

double geotess::LibCorr3D::getCurrentInterpolationRadius ( )

inline

Retrieve the radius of the current interpolation location in km .

Returns: the radius of the current interpolation location in km .

◆ getCurrentInterpolationTime()

double geotess::LibCorr3D::getCurrentInterpolationTime ( )

inline

Retrieve the epoch time of the current interpolation location in seconds since 1970.

Returns: the epoch time of the current interpolation location in seconds since 1970.

◆ getGeographicInterpolatorType()

const GeoTessInterpolatorType & geotess::LibCorr3D::getGeographicInterpolatorType ( ) const

inline

Returns the current geographic interpolator type.

Returns: either InterpolatorType::LINEAR or InterpolatorType::NATURAL_NEIGHBOR

◆ getMemory()

LONG_INT geotess::LibCorr3D::getMemory ( )

Return the amount of memory currently occupied by this LibCorr3D object, including all of the LibCorr3DModel objects currently in memory, and all the LibCorr3DGrid objects referenced by those models.

Returns: memory in bytes.

◆ getModel()

LibCorr3DModel * geotess::LibCorr3D::getModel ( int handle )

Returns: a pointer to a model object given the input handle.

◆ getModelResult()

bool geotess::LibCorr3D::getModelResult	(	int	handle,
		double &	modelValue,
		double &	modelUncertainty
	)

The access function used to retrieve the model attribute and associated uncertainty results at the current interpolation location for the model associated with the input handle h.

If the call to getModelResults is successful, then the call will return true, the errorCode returned by getCurrentErrorCode() will be zero and the string returned by getCurrentErrorMessage() will be empty. Otherwise, the call will return false, the errorCode will a non-zero number and the errorMessage will return a description of what went wrong. The following errorCodes have the specified meanings.
0 : No error. Valid result returned.
-1 : The current interpolation position is outside the geographic range of the specified model.
-2 : The current interpolation time is outside the valid time range of the specified model (model on-off times). This only happens when the most recent call to setInterpolationLocation() specified an epoch time not equal to NA_VALUE.
-3 : The model associated with the specified handle is no longer in memory. It has been removed with a call to removeModel(handle).
-4 : Specified handle is out of range. < 0 or >= number of models that have been loaded (including models that have been removed).
>0 : This indicates a GeoTessException. The error message is also sent to standard error.
-99 : Some other unidentified exception.

Parameters

handle	the handle of the model to be interrogated.
modelValue	(output) the model value interpolated at the current position. Zero is returned if the current position is out-of-range or if an error occurred.
modelUncertainty	(output) the modelUncertainty interpolated at the current position. -1 is returned if the current position is out-of-range, model uncertainty is not supported, or if an error occurred.

Returns: true if modelValue was successfully determined.

◆ getOldRelGridPath()

const string & geotess::LibCorr3D::getOldRelGridPath ( ) const

inline

Returns the path where all old LibCorr2D tessellation files are stored relative to the old root path (lc3dOldRootPath).

This parameter defaults to empty ("") in which case the LibCorr2D tesselations are stored at the old root path location.

Returns: the path to where old LibCorr2D grid files are stored.

◆ getOldRootPath()

const string & geotess::LibCorr3D::getOldRootPath ( ) const

inline

Returns the old (LibCorr2D) path corrections root path to the caller.

The old root path defaults to the new root path but may be set differently to provide storage separation between the new GeoTess models and their older LibCorr2D counterparts.

Returns: the root path where old LibCorr2D models are stored.

◆ getRadialInterpolatorType()

const GeoTessInterpolatorType & geotess::LibCorr3D::getRadialInterpolatorType ( ) const

inline

Returns the current geographic interpolator type.

Returns: either InterpolatorType::LINEAR or InterpolatorType::CUBIC_SPLINE

◆ getRelGridPath()

const string & geotess::LibCorr3D::getRelGridPath ( ) const

inline

Returns the path where all the grid files are stored (new GeoTess) relative to the input root path (lc3dGTRootPath).

This parameter defaults to empty ("") in which case the LibCorr3D grids and models are stored at the root path location.

Returns: the path to where grid files are stored.

◆ getRootPath()

const string & geotess::LibCorr3D::getRootPath ( ) const

inline

Returns the primary (new GeoTess) root path to the caller.

The root path is the path to where all new GeoTess models and grids are stored and, if the old path defaults to this locations, where the old LibCorr2D path corrections and grids are stored.

Returns: the primary root path where new GeoTess-based models are stored.

◆ getVersion()

static string geotess::LibCorr3D::getVersion ( )

inlinestatic

Returns: the current LibCorr3D version.

◆ loadModel() [1/2]

int geotess::LibCorr3D::loadModel	(	const string &	fname,
		const GeoTessOptimizationType &	optimizationType = `GeoTessOptimizationType::SPEED`
	)

inline

Loads a new model from the specified file and returns an associated handle to the caller for later access.

If anything goes wrong caller can retrieve the error code and error message by calling getCurrentErrorCode() and getCurrentErrorMessage() respectively.

Parameters

fname	the name of the file containing the model. This name will be added to one of the rootPath names specified in the constructor in order generate the full path to the file.
optimizationType	either OptimizationType.SPEED or OptimizationType.MEMORY. The default is SPEED wherein the code will execute faster but require more memory.

Returns: handle that can be used to access the model after it is loaded. If anything goes wrong, -1 is returned and caller can retrieve the error code and error message by calling getCurrentErrorCode() and getCurrentErrorMessage() respectively

◆ loadModel() [2/2]

int geotess::LibCorr3D::loadModel	(	const string &	fname,
		vector< int > &	attributeFilter,
		const GeoTessOptimizationType &	optimizationType = `GeoTessOptimizationType::SPEED`
	)

Loads a new model from the specified file and returns an associated handle to the caller for later access.

If anything goes wrong caller can retrieve the error code and error message by calling getCurrentErrorCode() and getCurrentErrorMessage() respectively.

Parameters

fname	the name of the file containing the model. This name will be added to one of the rootPath names specified in the constructor in order generate the full path to the file.
attributeFilter	the indexes of the attributes in the model file that should be loaded into memory. Used to load into memory only a subset of all the attributes available in the model file. By default, all attributes are loaded. Applies only to new GeoTess-backed LibCorr3D models. Ignored when loading the old LibCorr2D models.
optimizationType	either OptimizationType.SPEED or OptimizationType.MEMORY. The default is SPEED wherein the code will execute faster but require more memory.

Returns: handle that can be used to access the model after it is loaded. If anything goes wrong, -1 is returned and caller can retrieve the error code and error message by calling getCurrentErrorCode() and getCurrentErrorMessage() respectively

◆ removeModel()

void geotess::LibCorr3D::removeModel ( int handle )

Removes the specified model from the list of supported models and deletes it from memory.

◆ setInterpolationLocation() [1/2]

LibCorr3D * geotess::LibCorr3D::setInterpolationLocation	(	double *	unitVector,
		double	radius = `-1.`,
		double	time = `NA_VALUE`
	)

inline

Sets the current interpolation location/time.

The radius defaults to the radius of the surface of the WGS84 ellipsoid (depth = 0) and the time defaults to NA_VALUE (implies time is not used to determine station status).

Parameters

unitVector	3-component unit vector reflecting current position. The input array is copied.
radius	distance from center of the Earth in km. Any value less than zero (default is -1.) will set the radius to surface of WGS84 ellipsoid which corresponds to depth=0.
time	epoch time (seconds since Jan 1, 1970). Defaults to NA_VALUE in which case time is not contrained to the valid on-off times of the model.

Returns: a pointer to this LibCorr3D object.

◆ setInterpolationLocation() [2/2]

LibCorr3D * geotess::LibCorr3D::setInterpolationLocation	(	double	lon,
		double	lat,
		double	depth = `0.0`,
		double	time = `NA_VALUE`
	)

inline

Sets the current interpolation location/time.

The depth defaults to 0 (surface of WGS84 ellipsoid) and the time defaults to NA_VALUE (implies time is not used to determine station status).

Parameters

lon	longitude in degrees
lat	latitude in degrees
depth	depth below surface of WGS84 ellipsoid, in km. Defaults to zero km.
time	epoch time (seconds since Jan 1, 1970). Defaults to NA_VALUE in which case time is not constrained to the valid on-off times of the model.

Returns: a pointer to this LibCorr3D object.

◆ setInterpolator()

void geotess::LibCorr3D::setInterpolator	(	GeoTessInterpolatorType const *	intrpGeographic,
		GeoTessInterpolatorType const *	intrpRadial
	)

Sets the geographic and radial interpolators to the specified types.

Calling this method after models have been loaded will cause all the GeoTessPosition objects currently initialized to be deleted and replaced with new ones that support the new InterpolatorTypes. All model values returned after this call will reflect the new InterpolatorTypes.

Parameters

intrpGeographic	the interpolator type to use for interpolation in the geographic dimensions. Must be either &InterpolatorType::LINEAR or &InterpolatorType::NATURAL_NEIGHBOR.
intrpRadial	the interpolator type to use for interpolation in the radial dimension. Must be either &InterpolatorType::LINEAR or &InterpolatorType::CUBIC_SPLINE.

The documentation for this class was generated from the following file:

include/LibCorr3D.h

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ LibCorr3D() [1/3]

◆ LibCorr3D() [2/3]

◆ LibCorr3D() [3/3]

◆ ~LibCorr3D()

Member Function Documentation

◆ getCurrentErrorCode()

◆ getCurrentErrorMessage()

◆ getCurrentInterpolationDepth()

◆ getCurrentInterpolationLat()

◆ getCurrentInterpolationLocation() [1/2]

◆ getCurrentInterpolationLocation() [2/2]

◆ getCurrentInterpolationLon()

◆ getCurrentInterpolationRadius()

◆ getCurrentInterpolationTime()

◆ getGeographicInterpolatorType()

◆ getMemory()

◆ getModel()

◆ getModelResult()

◆ getOldRelGridPath()

◆ getOldRootPath()

◆ getRadialInterpolatorType()

◆ getRelGridPath()

◆ getRootPath()

◆ getVersion()

◆ loadModel() [1/2]

◆ loadModel() [2/2]

◆ removeModel()

◆ setInterpolationLocation() [1/2]

◆ setInterpolationLocation() [2/2]

◆ setInterpolator()