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 () |
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().
geotess::LibCorr3D::LibCorr3D | ( | const string & | rootPath | ) |
geotess::LibCorr3D::LibCorr3D | ( | const string & | newRootPath, |
const string & | oldRootPath | ||
) |
Standard constructor.
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. |
geotess::LibCorr3D::LibCorr3D | ( | const string & | newRootPath, |
const string & | newRelGridPath, | ||
const string & | oldRootPath, | ||
const string & | oldRelGridPath | ||
) |
Standard constructor.
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. |
|
virtual |
Destructor.
|
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.
|
inline |
Return the errorMessage generated by the most recent call to getModelResult().
Result will be empty if no error was generated.
|
inline |
Retrieve the depth of the current interpolation location in km .
|
inline |
Retrieve the latitude of the current interpolation location in degrees.
|
inline |
Retrieve a string representation of the current interpolation location (lon, lat, depth, epochTime).
|
inline |
Retrieve the current interpolation location as a unit vector.
|
inline |
Retrieve the longitude of the current interpolation location in degrees.
|
inline |
Retrieve the radius of the current interpolation location in km .
|
inline |
Retrieve the epoch time of the current interpolation location in seconds since 1970.
|
inline |
Returns the current geographic interpolator type.
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.
LibCorr3DModel * geotess::LibCorr3D::getModel | ( | int | handle | ) |
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.
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. |
|
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.
|
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.
|
inline |
Returns the current geographic interpolator type.
|
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.
|
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.
|
inlinestatic |
|
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.
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. |
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.
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. |
void geotess::LibCorr3D::removeModel | ( | int | handle | ) |
Removes the specified model from the list of supported models and deletes it from memory.
|
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).
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. |
|
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).
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. |
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.
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. |