LibCorr3D 2.2
All Classes Namespaces Files Functions
Public Member Functions | Static Public Member Functions | List of all members
geotess::LibCorr3D Class Reference

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...
 
LibCorr3DModelgetModel (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...
 
LibCorr3DsetInterpolationLocation (double *unitVector, double radius=-1., double time=NA_VALUE)
 Sets the current interpolation location/time. More...
 
LibCorr3DsetInterpolationLocation (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
rootPathPath 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
newRootPathPath to the directory that contains the new GeoTess LibCorr3D models and grids.
oldRootPathPath 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
newRootPathPath to the directory that contains the new GeoTess LibCorr3D models.
newRelGridPathRelative path from newRootPath to the directory that contains the new GeoTess LibCorr3D grids.
oldRootPathPath to the directory that contains the old LibCorr2D path correction models.
oldRelGridPathRelative 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
handlethe 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
fnamethe 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.
optimizationTypeeither 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
fnamethe 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.
attributeFilterthe 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.
optimizationTypeeither 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
unitVector3-component unit vector reflecting current position. The input array is copied.
radiusdistance 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.
timeepoch 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
lonlongitude in degrees
latlatitude in degrees
depthdepth below surface of WGS84 ellipsoid, in km. Defaults to zero km.
timeepoch 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
intrpGeographicthe interpolator type to use for interpolation in the geographic dimensions. Must be either &InterpolatorType::LINEAR or &InterpolatorType::NATURAL_NEIGHBOR.
intrpRadialthe 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: