GeoTessCPP  2.0.0
Software to facilitate storage and retrieval of 3D information about the Earth.
 All Classes Namespaces Files Functions Variables Typedefs Friends Macros
Public Member Functions | Static Public Member Functions
geotess::GeoTessModel Class Reference

#include <GeoTessModel.h>

List of all members.

Public Member Functions

 GeoTessModel (const OptimizationType *optimization=&OptimizationType::SPEED)
 GeoTessModel (const string &inputFile, const string &relativeGridPath, const OptimizationType *optimization=&OptimizationType::SPEED)
 GeoTessModel (const string &modelInputFile, const OptimizationType *optimization=&OptimizationType::SPEED)
 GeoTessModel (vector< int > &attributeFilter, const OptimizationType *optimization=&OptimizationType::SPEED)
 GeoTessModel (const string &inputFile, const string &relativeGridPath, vector< int > &attributeFilter, const OptimizationType *optimization=&OptimizationType::SPEED)
 GeoTessModel (const string &modelInputFile, vector< int > &attributeFilter, const OptimizationType *optimization=&OptimizationType::SPEED)
 GeoTessModel (const string &gridFileName, GeoTessMetaData *metaData)
 GeoTessModel (GeoTessGrid *grid, GeoTessMetaData *metaData)
virtual ~GeoTessModel ()
GeoTessModelloadModel (const string &inputFile, const string &relGridFilePath="")
const GeoTessGridgetGrid () const
GeoTessGridgetGrid ()
GeoTessMetaDatagetMetaData ()
GeoTessPositiongetPosition ()
GeoTessPositiongetPosition (const InterpolatorType &horizontalType)
GeoTessPositiongetPosition (const InterpolatorType &horizontalType, const InterpolatorType &radialType)
int getNVertices () const
int getNLayers () const
int getNPoints ()
bool operator== (const GeoTessModel &other) const
bool operator!= (const GeoTessModel &other) const
PointMapgetPointMap ()
const set< int > & getConnectedVertices (int layerIndex)
void setActiveRegion ()
void setActiveRegion (const string &polygon)
void setActiveRegion (Polygon *polygon)
void getLayerCount (bool activeOnly, int *layerCount)
ProfilegetProfile (int vertex, int layer)
Profile ** getProfiles (int vertex)
Profile *** getProfiles () const
void setProfile (int vertex, int layer, Profile *profile)
template<typename T >
void setProfile (int vertex, int layer, vector< float > &radii, vector< vector< T > > &values)
template<typename T >
void setProfile (const int &vertex, const int &layer, float *radii, const int &nRadii, T **values, const int &nNodes, const int &nAttributes)
template<typename T >
void setProfile (const int &vertex, vector< T > &values)
template<typename T >
void setProfile (const int &vertex, T *values, const int &nAttributes)
void writeModel (const string &outputFile, const string &gridFileName)
string toString ()
void getLayerCount (vector< int > &layerCount, const bool &activeOnly)
void profileCount (vector< vector< int > > &count)
template<typename T >
void initializeData (const vector< string > &attributeNames, const vector< string > &attributeUnits, T fillValue)
template<typename T >
void initializeData (const string &attributeNames, const string &attributeUnits, T fillValue)
void getWeights (const vector< double * > &vectors, const vector< double > &radii, const InterpolatorType &horizontalType, const InterpolatorType &radialType, map< int, double > &weights)

Static Public Member Functions

static bool isGeoTessModel (const string &fileName)
static void clearReuseGrid ()
static int getReuseGridMapSize ()

Detailed Description

GeoTessModel manages the grid and data that comprise a 3D Earth model. The Earth is assumed to be composed of a number of layers each of which spans the entire geographic extent of the Earth. It is assumed that layer boundaries do not fold back on themselves, i.e., along any radial profile through the model, each layer boundary is intersected exactly one time. Layers may have zero thickness over some or all of their geographic extent. Earth properties stored in the model are assumed to be continuous within a layer, both geographically and radially, but may be discontinuous across layer boundaries.

A GeoTessModel is comprised of 3 major components:

The term 'vertex' refers to a position in the 2D tessellation. They are 2D positions represented by unit vectors on a unit sphere. The term 'node' refers to a 1D position on a radial profile associated with a vertex and a layer in the model. Node indexes are unique only within a given profile (all profiles have a node with index 0 for example). The term 'point' refers to all the nodes in all the profiles of the model. There is only one 'point' in the model with index 0. PointMap is introduced to manage all these different indexes.

Author:
Sandy Ballard

Constructor & Destructor Documentation

geotess::GeoTessModel::GeoTessModel ( const OptimizationType optimization = &OptimizationType::SPEED)

Default constructor.

Parameters:
optimizationeither OptimizationType.SPEED or OptimizationType.MEMORY. The default is SPEED wherein the code will execute faster but require more memory to run.
geotess::GeoTessModel::GeoTessModel ( const string &  inputFile,
const string &  relativeGridPath,
const OptimizationType optimization = &OptimizationType::SPEED 
)

Construct a new GeoTessModel object and populate it with information from the specified file.

Parameters:
inputFilename of file containing the model.
relativeGridPaththe relative path from the directory where the model is stored to the directory where the grid is stored. Often, the model and grid are stored together in the same file in which case this parameter is ignored. Sometimes, however, the grid is stored in a separate file and only the name of the grid file (without path information) is stored in the model file. In this case, the code needs to know which directory to search for the grid file. The default is "" (empty string), which will cause the code to search for the grid file in the same directory in which the model file resides. Bottom line is that the default value is appropriate when the grid is stored in the same file as the model, or the model file is in the same directory as the model file.
optimizationeither OptimizationType.SPEED or OptimizationType.MEMORY. The default is SPEED wherein the code will execute faster but require more memory to run.
geotess::GeoTessModel::GeoTessModel ( const string &  modelInputFile,
const OptimizationType optimization = &OptimizationType::SPEED 
)

Construct a new GeoTessModel object and populate it with information from the specified file.

relativeGridPath is assumed to be "" (empty string), which is appropriate when the grid information is stored in the same file as the model or when the grid is stored in a separate file located in the same directory as the model file.

Parameters:
modelInputFilename of file containing the model.
optimizationeither OptimizationType.SPEED or OptimizationType.MEMORY. The default is SPEED wherein the code will execute faster but require more memory to run.
geotess::GeoTessModel::GeoTessModel ( vector< int > &  attributeFilter,
const OptimizationType optimization = &OptimizationType::SPEED 
)

Default constructor.

Parameters:
attributeFilterthe indexes of available attributes that should be loaded into memory.
optimizationeither OptimizationType.SPEED or OptimizationType.MEMORY. The default is SPEED wherein the code will execute faster but require more memory to run.
geotess::GeoTessModel::GeoTessModel ( const string &  inputFile,
const string &  relativeGridPath,
vector< int > &  attributeFilter,
const OptimizationType optimization = &OptimizationType::SPEED 
)

Construct a new GeoTessModel object and populate it with information from the specified file.

Parameters:
inputFilename of file containing the model.
relativeGridPaththe relative path from the directory where the model is stored to the directory where the grid is stored. Often, the model and grid are stored together in the same file in which case this parameter is ignored. Sometimes, however, the grid is stored in a separate file and only the name of the grid file (without path information) is stored in the model file. In this case, the code needs to know which directory to search for the grid file. The default is "" (empty string), which will cause the code to search for the grid file in the same directory in which the model file resides. Bottom line is that the default value is appropriate when the grid is stored in the same file as the model, or the model file is in the same directory as the model file.
attributeFilterthe indexes of available attributes that should be loaded into memory.
optimizationeither OptimizationType.SPEED or OptimizationType.MEMORY. The default is SPEED wherein the code will execute faster but require more memory to run.
geotess::GeoTessModel::GeoTessModel ( const string &  modelInputFile,
vector< int > &  attributeFilter,
const OptimizationType optimization = &OptimizationType::SPEED 
)

Construct a new GeoTessModel object and populate it with information from the specified file.

relativeGridPath is assumed to be "" (empty string), which is appropriate when the grid information is stored in the same file as the model or when the grid is stored in a separate file located in the same directory as the model file.

Parameters:
modelInputFilename of file containing the model.
attributeFilterthe indexes of available attributes that should be loaded into memory.
optimizationeither OptimizationType.SPEED or OptimizationType.MEMORY. The default is SPEED wherein the code will execute faster but require more memory to run.
geotess::GeoTessModel::GeoTessModel ( const string &  gridFileName,
GeoTessMetaData metaData 
)

Parameterized constructor, specifying the grid and metadata for the model. The grid is constructed and the data structures are initialized based on information supplied in metadata. The data structures are not populated with any information however (all Profiles are null). The application should populate the new model's Profiles after this constructor completes.

Before calling this constructor, the supplied MetaData object must be populated with required information by calling the following MetaData methods:

  • setDescription()
  • setLayerNames()
  • setAttributes()
  • setDataType()
  • setLayerTessIds() (only required if grid has more than one multi-level tessellation)
  • setOptimization() (optional: defaults to SPEED)
Parameters:
gridFileNamename of file from which to load the grid.
metaDataMetaData the new GeoTessModel instantiates a reference to the supplied metaData. No copy is made.
Exceptions:
GeoTessExceptionif metadata is incomplete.
geotess::GeoTessModel::GeoTessModel ( GeoTessGrid grid,
GeoTessMetaData metaData 
)

Parameterized constructor, specifying the grid and metadata for the model. The grid is constructed and the data structures are initialized based on information supplied in metadata. The data structures are not populated with any information however (all Profiles are null). The application should populate the new model's Profiles after this constructor completes.

Before calling this constructor, the supplied MetaData object must be populated with required information by calling the following MetaData methods:

  • setDescription()
  • setLayerNames()
  • setAttributes()
  • setDataType()
  • setLayerTessIds() (only required if grid has more than one multi-level tessellation)
  • setOptimization() (optional: defaults to SPEED)
  • setSoftwareVersion()
  • setGenerationDate()
Parameters:
grida pointer to the GeoTessGrid that will support this GeoTessModel. GeoTessModel assumes ownership of the supplied grid object and will delete it when it is done with it.
metaDataMetaData the new GeoTessModel instantiates a reference to the supplied metaData. No copy is made.
Exceptions:
GeoTessExceptionif metadata is incomplete.
virtual geotess::GeoTessModel::~GeoTessModel ( )
virtual

Destructor.


Member Function Documentation

static void geotess::GeoTessModel::clearReuseGrid ( )
inlinestatic

GeoTessModel will attempt to reuse grids that it has already loaded into memory when a new model tries to reload the same grid. This method clears the map that supports this functionality.

const set<int>& geotess::GeoTessModel::getConnectedVertices ( int  layerIndex)
inline

Return a reference to the set<int> of the indexes of all the vertices that are connected together by triangles in the specified layer of the model.

Parameters:
layerIndex
Returns:
a reference to the set<int> of the indexes of all the vertices that are connected together by triangles in the specified layer of the model.
const GeoTessGrid& geotess::GeoTessModel::getGrid ( ) const
inline

Return a reference to the grid object.

GeoTessGrid& geotess::GeoTessModel::getGrid ( )
inline

Return a reference to the grid object.

void geotess::GeoTessModel::getLayerCount ( bool  activeOnly,
int *  layerCount 
)
inline

Retrieve the number of points in each layer of the model.

Parameters:
activeOnlyif true, counts only active nodes otherwise counts all nodes.
layerCountan int array with at least nLayers elements which will be populated with the number of nodes in each layer.
Returns:
the number of points in each layer of the model.
void geotess::GeoTessModel::getLayerCount ( vector< int > &  layerCount,
const bool &  activeOnly 
)
inline

Retrieve the number of points in each layer of the model.

Parameters:
activeOnlyif true, counts only active nodes otherwise counts all nodes.
layerCountthe number of points in each layer of the model.
GeoTessMetaData& geotess::GeoTessModel::getMetaData ( )
inline

Return a reference to the GeoTessMetaData object associated with this model. The metadata object stores information about the models such as a description of the model, the layer names, attribute names, attribute units, the data type, etc.

int geotess::GeoTessModel::getNLayers ( ) const

Return the number of layers that comprise the model.

Returns:
the number of layers that comprise the model.
int geotess::GeoTessModel::getNPoints ( )
inline

Retrieve the number of points in the model, including all nodes along all profiles at all grid vertices.

int geotess::GeoTessModel::getNVertices ( ) const

Return number of vertices in the 2D geographic grid.

Returns:
number of vertices in the 2D geographic grid.
PointMap* geotess::GeoTessModel::getPointMap ( )
inline

Retrieve a pointer to the pointMap, which is an nPoints by 3 array of indexes. For each point in the 3D grid, pointMap stores 3 indexes: the vertex index, the layer index, and the node index.

The term 'vertex' refers to a position in the 2D tessellation. A vertex is a 2D point represented by unit vectors on a unit sphere. The term 'node' refers to a Data object on a radial profile associated with a vertex and a layer in the model. Node indexes are unique only within a given profile (all profiles have a node with index 0 for example). The term 'point' refers to all the nodes in all the profiles of the model. There is only one 'point' in the model with index 0. PointMap is introduced to help map back and forth between all these different indexes.

Users should not delete this pointer.

GeoTessPosition* geotess::GeoTessModel::getPosition ( )

Retrieve a pointer to a new GeoTessPosition object that knows how to interpolate information from the model. Linear interpolation will be performed in both the horizontal and radial dimensions

It is the caller's responsibility to delete this object when it is no longer needed.

Returns:
a GeoTessPosition object.
GeoTessPosition* geotess::GeoTessModel::getPosition ( const InterpolatorType horizontalType)

Retrieve a pointer to a new GeoTessPosition object that knows how to interpolate information from the model. If the horizontal InterpolatorType is LINEAR then the radial InterpolatorType will be LINEAR as well. If the horizontal InterpolatorType is NATUAL_NEIGHBOR then the radial InterpolatorType will be CUBIC_SPLINE.

It is the caller's responsibility to delete this object when it is no longer needed.

Parameters:
horizontalTypethe type of interpolation that is to be used for interpolation in the geographic dimensions; either InterpolatorType:LINEAR or InterpolatorType::NATURAL_NEIGHBOR
Returns:
a GeoTessPosition object.
GeoTessPosition* geotess::GeoTessModel::getPosition ( const InterpolatorType horizontalType,
const InterpolatorType radialType 
)

Retrieve a pointer to a new GeoTessPosition object that knows how to interpolate information from the model.

It is the caller's responsibility to delete this object when it is no longer needed.

Parameters:
horizontalTypethe type of interpolation that is to be used for interpolation in the geographic dimensions; either InterpolatorType:LINEAR or InterpolatorType::NATURAL_NEIGHBOR
radialTypethe type of interpolation that is to be used in the radia dimension; either InterpolatorType:LINEAR or InterpolatorType::CUBIC_SPLINE
Returns:
a GeoTessPosition object.
Profile* geotess::GeoTessModel::getProfile ( int  vertex,
int  layer 
)
inline

Get a reference to the Profile object for the specified vertex and layer.

Parameters:
vertexindex of a vertex in the 2D grid
layerindex of one of the layers that comprise the model
Returns:
a reference to a Profile object that contains the radii and Data values stored in profile[vertex][layer].
Profile** geotess::GeoTessModel::getProfiles ( int  vertex)
inline

Get a reference to the array of Profile objects for the specified vertex.

Parameters:
vertexindex of a vertex in the 2D grid
Returns:
a reference to an array of Profile objects that contains the radii and Data values for all the Profiles at the specified vertex.
Profile*** geotess::GeoTessModel::getProfiles ( ) const
inline

Get a reference to all Profile objects.

static int geotess::GeoTessModel::getReuseGridMapSize ( )
inlinestatic

GeoTessModel will attempt to reuse grids that it has already loaded into memory when a new model tries to reload the same grid. This method returns the size of the map that supports this functionality.

Returns:
size of reuseGridMap.
void geotess::GeoTessModel::getWeights ( const vector< double * > &  vectors,
const vector< double > &  radii,
const InterpolatorType horizontalType,
const InterpolatorType radialType,
map< int, double > &  weights 
)

Compute the weights on each model point that results from interpolating positions along the specified ray path. The following procedure is implemented:

  1. find the midpoint of each increment of the path (line segment between adjacent positions on the path).
  2. find the interpolation coefficients of all the model points that are 'touched' by the midpoint of the increment.
  3. find the length of the path increment in km.
  4. find the product of the length of the path increment times each interpolation coefficient and sum that value for each model point.
template<typename T >
void geotess::GeoTessModel::initializeData ( const vector< string > &  attributeNames,
const vector< string > &  attributeUnits,
fillValue 
)
inline

Reset all the Data objects in the model. The number of attributes in the new Data objects will equal the number of elements in the supplied lists of attributeNames and attributeUnits (which must be equal in length).

The DataType of the new Data objects will be the type of the supplied fillValue. Data values will be copied from the old to the new Data objects with casting to the type of the new data objects. It is the responsibility of the caller to ensure that casting of data values does not result in corruption of data values or the loss of important information.

If the number of attributes in the new Data objects is less than the number in the old Data objects, old data values are lost. If the number of attributes in the new Data objects is greater than the number in the old Data objects, new values are populated with fillValue.

This method can only modify the Data objects associated with existing Profiles. It does not instantiate Profiles, change the ProfileType of existing profiles, modify the number of nodes in existing Profiles, or modify the radii within a Profile. To do any of those things requires replacing the Profile.

Parameters:
attributeNamesnew names of the attributes. These names will replace the old names in the MetaData object.
attributeUnitsnew units of the attributes. These units will replace the old units in the MetaData object. The number of attributeNames and attributeUntis must be the same.
fillValuea value of type double, float, LONG_INT, int, short or byte. All data values in this models' Data objects will be of this type after this method executes. The supplied value is used to populate data values that are not copied from the old Data object.
Exceptions:
GeoTessExceptionif the model has not been populated with Profiles or if the number of attributeNames and attributeUnits is not the same.
template<typename T >
void geotess::GeoTessModel::initializeData ( const string &  attributeNames,
const string &  attributeUnits,
fillValue 
)
inline

Replace all the Data objects in the entire model. All current Data is lost. The new Data objects will be of the same type as fillValue. The length of the Data arrays will be equal to the number of attributeNames and units supplied.

AttributeNames and attributeUnits must contain the same number of entries.

Parameters:
attributeNamesa semi-colon delimeted list of attribute names.
attributeUnitsa semi-colon delimeted list of attribute units.
fillValuevalue to populate the model with
static bool geotess::GeoTessModel::isGeoTessModel ( const string &  fileName)
static

Test a file to see if it is a GeoTessModel file.

Parameters:
fileName
Returns:
true if inputFile is a GeoTessModel file.
GeoTessModel* geotess::GeoTessModel::loadModel ( const string &  inputFile,
const string &  relGridFilePath = "" 
)

Read model data and grid from a file.

Parameters:
inputFilethe path to the file that contains the model.
relGridFilePathif the grid is stored in a separate file then relGridFilePath is the relative path from the directory where the model located to the directory where the grid is located. The default value for relGridFilePath is "" which indicates that the grid file resides in the same directory as the model file.
Returns:
returns a pointer to this
bool geotess::GeoTessModel::operator!= ( const GeoTessModel other) const
inline

Return true if this and the input other model are not equal. i.e., their grids have different gridIDs, they have different number of layers, or any of their Profiles are not equal. For profiles to be equal, they must be of the same type and size, and all of their radii must be equal and all of their data must be equal.

Parameters:
otherthe other model to which this model is to be compared for equality.
Returns:
true if this and other are not equal.
bool geotess::GeoTessModel::operator== ( const GeoTessModel other) const

Return true if this and the input other model are equal. i.e., their grids have the same gridIDs, they have the same number of layers, and all their Profiles are equal. For profiles to be equal, they must be of the same type and size, and all of their radii must be equal and all of their data must be equal.

Parameters:
otherthe other model to which this model is to be compared for equality.
Returns:
true if this and other are equal.
void geotess::GeoTessModel::profileCount ( vector< vector< int > > &  count)
inline

Retrieve the number of Profiles of each ProfileType in each layer of the model. Also returns the total number of profiles of each type independent of layer.

Parameters:
countis a 2D vector of ints with dimensions (nLayers+1) x nProfileTypes.
void geotess::GeoTessModel::setActiveRegion ( )
inline

Set the active region such that it encompasses all the nodes in the model.

Returns:
a reference to the updated PointMap that has been configured to support the specified active region.
void geotess::GeoTessModel::setActiveRegion ( const string &  polygon)
inline

Set the active region to encompass only the nodes contained within the specified Polygon.

KML and KMZ formats are not supported by the C++ code. See GeoTessExplorer (Java) which can convert KML/KMZ files to ascii.

Parameters:
polygonthe name of a file containing a valid Polygon2D or Polygon3D object, in ascii format.
Returns:
a reference to the updated PointMap that has been configured to support the specified active region.
Exceptions:
PolygonException
void geotess::GeoTessModel::setActiveRegion ( Polygon polygon)
inline

Set the active region to encompass only the nodes contained within the specified Polygon object.

Parameters:
polygona Polygon object.
Returns:
a reference to the updated PointMap that has been configured to support the specified active region.
Exceptions:
PolygonException
void geotess::GeoTessModel::setProfile ( int  vertex,
int  layer,
Profile profile 
)

Replace the Profile object at the specified vertex and layer with a new one. Profile is checked to ensure that radii are monotonically increasing.

GeoTessModel assumes ownership of the Profile object and will delete it when it is no longer needed. Caller should not delete the Profile object.

Parameters:
vertexindex of a vertex in the 2D grid
layerindex of one of the layers that comprise the model
profilea pointer to a Profile object that contains the radii and Data values to be stored in profile[vertex][layer].
template<typename T >
void geotess::GeoTessModel::setProfile ( int  vertex,
int  layer,
vector< float > &  radii,
vector< vector< T > > &  values 
)
inline

Replace the Profile object at the specified vertex and layer with a new one. All radius and data values are copied out of the supplied vector<>s. GeoTessModel does not keep any references to the vectors<>

If vertex is not connected to other vertices by any triangles in the specified layer, than the values are ignored and a ProfileEmpty object is instantiated with just the first and last radii provided.

Parameters:
vertexindex of a vertex in the 2D grid
layerindex of one of the layers that comprise the model
radiithe radius values in km
valuesnNodes x nAttributes array of model values.
template<typename T >
void geotess::GeoTessModel::setProfile ( const int &  vertex,
const int &  layer,
float *  radii,
const int &  nRadii,
T **  values,
const int &  nNodes,
const int &  nAttributes 
)
inline

Replace the Profile object at the specified vertex and layer with a new one. All radius and data values are copied out of the supplied vector<>s. GeoTessModel does not keep any references to the vectors<> If vertex is not connected to other vertices by any triangles in the specified layer, than the values are ignored and a ProfileEmpty object is instantiated with just the first and last radii provided.

Parameters:
vertexindex of a vertex in the 2D grid
layerindex of one of the layers that comprise the model
radiithe radius values in km
nRadiithe number of radius values provided
valuesnNodes x nAttributes array of model values.
nNodes
nAttributes
template<typename T >
void geotess::GeoTessModel::setProfile ( const int &  vertex,
vector< T > &  values 
)
inline

Replace the Profile object at the specified vertex with a new one of type ProfileSurface, which supports 2D Earth models. All data values are copied out of the supplied vector<>. GeoTessModel does not keep any references to the vectors<>

Parameters:
vertexindex of a vertex in the 2D grid
valuesarray of model values with nAttribute elements.
template<typename T >
void geotess::GeoTessModel::setProfile ( const int &  vertex,
T *  values,
const int &  nAttributes 
)
inline

Replace the Profile object at the specified vertex with a new one of type ProfileSurface, which supports 2D Earth models. All data values are copied out of the supplied vector<>. GeoTessModel does not keep any references to the array

Parameters:
vertexindex of a vertex in the 2D grid
valuesarray of model values with nAttribute elements.
nAttributeslength of values array
string geotess::GeoTessModel::toString ( )

To string method.

void geotess::GeoTessModel::writeModel ( const string &  outputFile,
const string &  gridFileName 
)

Write the model to file. The data (radii and attribute values) are written to outputFile. If gridFileName is '*' then the grid information is written to the same file as the data. If gridFileName is something else, it should be the name of the file that contains the grid information. In the latter case, the gridFile referenced by gridFileName is not overwritten; all that happens is that the name of the grid file (with no path information) is stored in the data file.

Parameters:
outputFilename of the file to receive the model
gridFileNamename of file to receive the grid, or "*"

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