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 | Static Public Attributes
geotess::GeoTessUtils Class Reference

#include <GeoTessUtils.h>

List of all members.

Public Member Functions

 GeoTessUtils ()
virtual ~GeoTessUtils ()
virtual int class_size () const

Static Public Member Functions

static string class_name ()
static string getVersion ()
static void readString (string &s, ifstream &ifs)
static void writeString (ofstream &ofs, const string &s)
static double angle (const double *const v0, const double *const v1)
static double angleDegrees (const double *const v0, const double *const v1)
static double getDistance3D (const double *const v0, double r0, const double *const v1, double r1)
static double dot (const double *const v0, const double *const v1)
static double scalarTripleProduct (const double *const v0, const double *const v1, const double *const v2)
static double getEarthRadius (const double *const vector)
static double getGeoCentricLatitude (const double &lat)
static double getGeoGraphicLatitude (const double &lat)
static double getLat (const double *const vector)
static double getLon (const double *const vector)
static double getLatDegrees (const double *const vector)
static double getLonDegrees (const double *const vector)
static string getLatLonString (const double *const v)
static double * getVectorDegrees (const double &lat, const double &lon)
static double * getVector (const double &lat, const double &lon)
static double * getVector (const double &lat, const double &lon, double *v)
static double * getVectorDegrees (const double &lat, const double &lon, double *v)
static double azimuthDegrees (const double *const v1, const double *const v2, double errorValue)
static double azimuth (const double *const v1, const double *const v2, double errorValue)
static double normalize (double *const u)
static void cross (const double *const v1, const double *const v2, double *const rslt)
static double * crossNormal (const double *const u, const double *const v)
static double crossNormal (const double *const u, const double *const v, double *const w)
static double crossNorth (const double *const u, double *const w)
static bool vectorTripleProduct (const double *const v0, const double *const v1, const double *const v2, double *const rslt)
static bool vectorTripleProductNorthPole (const double *const u, double *const w)
static bool circumCenter (const double *const v0, const double *const v1, const double *const v2, double *const vs)
static double * circumCenter (const double *const v0, const double *const v1, const double *const v2)
static bool circumCenter (double const *const *const t, double *const vs)
static bool move (const double *const w, double distance, double azimuth, double *const u)
static void move (const double *const w, const double *const vtp, double a, double *const u)
static bool moveNorth (const double *const x, double distance, double *const z)
static void rotate (const double *const x, const double *const p, double a, double *const z)
static double ** getGreatCircle (const double *const v0, const double *const v1)
static void getGreatCircle (const double *const v0, const double *const v1, double **const gc)
static double ** getGreatCircle (const double *const v, double azimuth)
static void getGreatCircle (const double *const v, double azimuth, double **const gc)
static void getGreatCirclePoint (double const *const *const greatCircle, double distance, double *const v)
static double * getGreatCirclePoint (double const *const *const greatCircle, double distance)
static double getTriangleArea (const double *const v0, const double *const v1, const double *const v2)
static double * center (double const *const *const v, int n)
static void center (vector< double * > v, double *x)
static double length (const double *const u)
static bool isPole (const double *const u)
static bool parallel (const double *const u, const double *const v)
static void getTransform (const double *const u, const double *const v, double **const t)
static void transform (const double *x, double const *const *const transform, double *const g)

Static Public Attributes

static bool approximateLatitudes

Detailed Description

The Utils class provides basic static utility functions for GeoTess to manipulate geographic information.


Constructor & Destructor Documentation

geotess::GeoTessUtils::GeoTessUtils ( )
inline

Default constructor.

virtual geotess::GeoTessUtils::~GeoTessUtils ( )
inlinevirtual

Destructor.


Member Function Documentation

double geotess::GeoTessUtils::angle ( const double *const  v0,
const double *const  v1 
)
inlinestatic

Return the angular distance in radians between two unit vectors.

Return the angular distance in radians between two unit vectors.

Parameters:
v0a 3 component unit vector
v1a 3 component unit vector
Returns:
angular distance in radians.
double geotess::GeoTessUtils::angleDegrees ( const double *const  v0,
const double *const  v1 
)
inlinestatic

Return the angular distance in degrees between two unit vectors.

Parameters:
v0a 3 component unit vector
v1a 3 component unit vector
Returns:
angular distance in degrees.
static double geotess::GeoTessUtils::azimuth ( const double *const  v1,
const double *const  v2,
double  errorValue 
)
static
static double geotess::GeoTessUtils::azimuthDegrees ( const double *const  v1,
const double *const  v2,
double  errorValue 
)
static

Return azimuth from input vectors.

double * geotess::GeoTessUtils::center ( double const *const *const  v,
int  n 
)
inlinestatic

Return the normalized vector sum of the supplied unit vectors.

Parameters:
vone or more unit vectors
nsize of v
Returns:
the normalized vector sum of the supplied unit vectors.
void geotess::GeoTessUtils::center ( vector< double * >  v,
double *  x 
)
inlinestatic

Return the normalized vector sum of the supplied unit vectors.

Parameters:
vone or more unit vectors
xthe 3-element array of double in which to place the computed unit vector.
bool geotess::GeoTessUtils::circumCenter ( const double *const  v0,
const double *const  v1,
const double *const  v2,
double *const  vs 
)
inlinestatic

Calculated the triangle circumcenter.

Given three unit vectors, v0, v1 and v2, find the circumcenter, vs. The circumcenter is the unit vector of the center of a small circle that has all three unit vectors on its circumference.

Parameters:
v0
v1
v2
vs
Returns:
true if successful, false if the three input vectors do not define a triangle.
double * geotess::GeoTessUtils::circumCenter ( const double *const  v0,
const double *const  v1,
const double *const  v2 
)
inlinestatic

Given three unit vectors, v0, v1 and v2, find the circumcenter, vs. The circumcenter is the unit vector of the center of a small circle that has all three unit vectors on its circumference. Vectors must be specified in clockwise order.

Parameters:
v0
v1
v2
Returns:
the circumCenter (a unit vector).
bool geotess::GeoTessUtils::circumCenter ( double const *const *const  t,
double *const  vs 
)
inlinestatic

Given the three unit vectors, t[0], t[1] and t[2], find the circumcenter, vs. The circumcenter is the unit vector of the center of a small circle that has all three unit vectors on its circumference.

Parameters:
ta 3 x 3 array of doubles that contains the three unit vectors of a triangle.
vs
Returns:
true if successful, false if the three input vectors do not define a triangle.
static string geotess::GeoTessUtils::class_name ( )
inlinestatic

Returns the class name.

virtual int geotess::GeoTessUtils::class_size ( ) const
inlinevirtual

Returns the class size.

void geotess::GeoTessUtils::cross ( const double *const  v1,
const double *const  v2,
double *const  rslt 
)
inlinestatic

Vector cross product.

Cross product of two 3-component vectors. Result is not normalized.

Parameters:
v1vector<double> vector one.
v2vector<double> vector two.
rsltset to v1 cross v2 Result is not a unit vector.
double * geotess::GeoTessUtils::crossNormal ( const double *const  u,
const double *const  v 
)
inlinestatic

Vector cross product with a normalized result.

Normalized cross product of two 3-component unit vectors.

Parameters:
uvector one.
vvector two.
Returns:
Normalized cross product of u x v. Will be [0,0,0] if u and v are parallel.
double geotess::GeoTessUtils::crossNormal ( const double *const  u,
const double *const  v,
double *const  w 
)
inlinestatic

Normalized cross product of two 3-component unit vectors.

Parameters:
uvector one.
vvector two.
wset to u cross v, normalized to unit length. If u cross v has zero length, w will equal (0,0,0).
Returns:
the length of u cross v prior to normalization. Guaranteed >= 0.
double geotess::GeoTessUtils::crossNorth ( const double *const  u,
double *const  w 
)
inlinestatic

Normalized cross product of a 3-component unit vector with the north pole.

Normalized cross product of a 3-component unit vector with the north pole.

Parameters:
uvector<double> vector one.
wset to u cross north, normalized to unit length. If u cross north has zero length, w will equal (0,0,0).
Returns:
the length of u cross north prior to normalization. Guaranteed >= 0.
double geotess::GeoTessUtils::dot ( const double *const  v0,
const double *const  v1 
)
inlinestatic

Dot product and scalar triple product.

Return the dot product of two vectors.

Parameters:
v0a 3 component vector
v1a 3 component vector
Returns:
dot product
double geotess::GeoTessUtils::getDistance3D ( const double *const  v0,
double  r0,
const double *const  v1,
double  r1 
)
inlinestatic

Returns the distance between point 0 (v0, r0) and 1 (v1, r1) assuming the vectors are unit vectors and the radii are in km then the result is in km.

Given two unit vectors and their radii, return the straight line separation between their tips. Assuming that the radii are in km, the result will also be in km.

Parameters:
v0Point 0 unit vector.
r0Point 0 length (km).
v1Point 1 unit vector.
r1Point 1 length (km).
Returns:
Distance between tip of v0*r0 and v1*r1, in km.
double geotess::GeoTessUtils::getEarthRadius ( const double *const  v)
inlinestatic

Returns the Earth radius at the input 3D vector position.

Retrieve the radius of the Earth in km at the position specified by an Earth-centered unit vector. Uses the WGS84 ellipsoid.

Parameters:
vEarth-centered unit vector
Returns:
radius of the Earth in km at specified position.
double geotess::GeoTessUtils::getGeoCentricLatitude ( const double &  lat)
inlinestatic

Return latitude and longitude from the input vectors.

Return geocentric latitude given a geographic latitude

Parameters:
latgeographic latitude in radians
Returns:
geocentric latitude in radians
double geotess::GeoTessUtils::getGeoGraphicLatitude ( const double &  lat)
inlinestatic

Return geographic latitude given a geocentric latitude

Parameters:
latgeocentric latitude in radians
Returns:
geographic latitude in radians
static double** geotess::GeoTessUtils::getGreatCircle ( const double *const  v0,
const double *const  v1 
)
static

A great circle is defined by two unit vectors that are 90 degrees apart. A great circle is stored in a double[2][3] array, which is the structure returned by this method. A great circle can be passed to the method getGreatCirclePoint() to retrieve a unit vector that is on the great circle and located some distance from the first point of the great circle.

This method returns a great circle that is computed from two unit vectors that are not necessarily 90 degrees apart.

Parameters:
v0the first point on the great circle
v1some other point that is also on the great circle but which is not necessarily 90 degrees away from v0.
Returns:
a 2 x 3 array specifying two unit vectors. The first one is a clone of unit vector v0 passed as first argument to this method. The second is located 90 degrees away from v0.
Exceptions:
GeoTessExceptionif v0 and v1 are parallel.
static void geotess::GeoTessUtils::getGreatCircle ( const double *const  v0,
const double *const  v1,
double **const  gc 
)
static

A great circle is defined by two unit vectors that are 90 degrees apart. A great circle is stored in a double[2][3] array, which is the structure returned by this method. A great circle can be passed to the method getGreatCirclePoint() to retrieve a unit vector that is on the great circle and located some distance from the first point of the great circle.

This method returns a great circle that is computed from two unit vectors that are not necessarily 90 degrees apart.

Parameters:
v0the first point on the great circle
v1some other point that is also on the great circle but which is not necessarily 90 degrees away from v0.
gca 2 x 3 array specifying two unit vectors. The first one is a clone of unit vector v0 passed as first argument to this method. The second is located 90 degrees away from v0.
Exceptions:
GeoTessExceptionif v0 and v1 are parallel.
static double** geotess::GeoTessUtils::getGreatCircle ( const double *const  v,
double  azimuth 
)
static

A great circle is defined by two unit vectors that are 90 degrees apart. A great circle is stored in a double[2][3] array, which is the structure returned by this method. A great circle can be passed to the method getGreatCirclePoint() to retrieve a unit vector that is on the great circle and located some distance from the first point of the great circle.

This method returns a great circle that is defined by an initial point and an azimuth.

Parameters:
va unit vector that will be the first point on the great circle.
azimutha direction, in radians, in which to move relative to v in order to define the great circle
Returns:
a 2 x 3 array specifying two unit vectors. The first one is a clone of unit vector v passed as an argument to this method. The second is located 90 degrees away from v in the direction specified by azimuth.
Exceptions:
GeoTessExceptionif v is located at north or south pole.
static void geotess::GeoTessUtils::getGreatCircle ( const double *const  v,
double  azimuth,
double **const  gc 
)
static

A great circle is defined by two unit vectors that are 90 degrees apart. A great circle is stored in a double[2][3] array, which is the structure returned by this method. A great circle can be passed to the method getGreatCirclePoint() to retrieve a unit vector that is on the great circle and located some distance from the first point of the great circle.

This method returns a great circle that is defined by an initial point and an azimuth.

Parameters:
va unit vector that will be the first point on the great circle.
azimutha direction, in radians, in which to move relative to v in order to define the great circle
gca 2 x 3 array specifying two unit vectors. The first one is a clone of unit vector v passed as an argument to this method. The second is located 90 degrees away from v in the direction specified by azimuth.
Exceptions:
GeoTessExceptionif v is located at north or south pole.
void geotess::GeoTessUtils::getGreatCirclePoint ( double const *const *const  greatCircle,
double  distance,
double *const  v 
)
inlinestatic

A great circle is defined by two unit vectors that are 90 degrees apart. A great circle is stored in a double[2][3] array and one can be obtained by calling one of the getGreatCircle() methods.

In this method, a great circle and a distance are specified and a point is returned which is on the great circle path and is the specified distance away from the first point of the great circle.

Parameters:
greatCirclea great circle structure
distancedistance in radians from first point of great circle
vunit vector of point which is on great circle and located specified distance away from first point of great circle.
double * geotess::GeoTessUtils::getGreatCirclePoint ( double const *const *const  greatCircle,
double  distance 
)
inlinestatic

A great circle is defined by two unit vectors that are 90 degrees apart. A great circle is stored in a double[2][3] array and one can be obtained by calling one of the getGreatCircle() methods.

In this method, a great circle and a distance are specified and a point is returned which is on the great circle path and is the specified distance away from the first point of the great circle.

Parameters:
greatCirclea great circle structure
distancedistance in radians from first point of great circle
Returns:
unit vector of point which is on great circle and located specified distance away from first point of great circle.
double geotess::GeoTessUtils::getLat ( const double *const  v)
inlinestatic

Convert a 3-component unit vector to geographic latitude, in radians.

Parameters:
v3-component unit vector
Returns:
geographic latitude in radians.
double geotess::GeoTessUtils::getLatDegrees ( const double *const  v)
inlinestatic

Convert a 3-component unit vector to geographic latitude, in degrees.

Parameters:
v3-component unit vector
Returns:
geographic latitude in degrees.
static string geotess::GeoTessUtils::getLatLonString ( const double *const  v)
static

Return latitude / longitude as a string.

double geotess::GeoTessUtils::getLon ( const double *const  v)
inlinestatic

Convert a 3-component unit vector to a longitude, in radians.

Parameters:
v3 component unit vector
Returns:
longitude in radians.
double geotess::GeoTessUtils::getLonDegrees ( const double *const  v)
inlinestatic

Convert a 3-component unit vector to a longitude, in degrees.

Parameters:
v3 component unit vector
Returns:
longitude in degrees.
static void geotess::GeoTessUtils::getTransform ( const double *const  u,
const double *const  v,
double **const  t 
)
static

Transform is a 3 x 3 matrix such that when a vector is multiplied by transform, the vector will be projected onto the plane of this GreatCircle. The z direction will point out of the plane of the great circle in the direction of the observer (lastPoint cross firstPoint; parallel to normal). The y direction will correspond to the mean of firstPoint and lastPoint. The x direction will correspond to y cross z, forming a right handed coordinate system.

double geotess::GeoTessUtils::getTriangleArea ( const double *const  v0,
const double *const  v1,
const double *const  v2 
)
inlinestatic

Get triangle area and centroid.

Parameters:
v0first corner of triangle
v1second corner of triangle
v2third corner of triangle
Returns:
the area of a triangle defined by three 3-component vectors
double * geotess::GeoTessUtils::getVector ( const double &  lat,
const double &  lon 
)
inlinestatic

Convert geographic lat, lon into a geocentric unit vector. The x-component points toward lat,lon = 0, 0. The y-component points toward lat,lon = 0, PI/2. The z-component points toward north pole.

Parameters:
latgeographic latitude in radians.
lonlongitude in radians.
Returns:
3 component unit vector.
double * geotess::GeoTessUtils::getVector ( const double &  lat,
const double &  lon,
double *  v 
)
inlinestatic

Convert geographic lat, lon into a geocentric unit vector. The x-component points toward lat,lon = 0, 0. The y-component points toward lat,lon = 0, PI/2 The z-component points toward north pole.

Parameters:
latgeographic latitude in radians.
lonlongitude in radians.
v3-component unit vector.
double * geotess::GeoTessUtils::getVectorDegrees ( const double &  lat,
const double &  lon 
)
inlinestatic

Convert geographic lat, lon into a geocentric unit vector.

Convert geographic lat, lon into a geocentric unit vector. The x-component points toward lat,lon = 0, 0. The y-component points toward lat,lon = 0, 90. The z-component points toward north pole.

Parameters:
latgeographic latitude in degrees.
lonlongitude in degrees.
Returns:
3 component unit vector.
double * geotess::GeoTessUtils::getVectorDegrees ( const double &  lat,
const double &  lon,
double *  v 
)
inlinestatic

Convert geographic lat, lon into a geocentric unit vector. The x-component points toward lat,lon = 0, 0. The y-component points toward lat,lon = 0, 90. The z-component points toward north pole.

Parameters:
latgeographic latitude in degrees.
lonlongitude in degrees.
v3 component unit vector.
static string geotess::GeoTessUtils::getVersion ( )
inlinestatic

The current GeoTess version.

bool geotess::GeoTessUtils::isPole ( const double *const  u)
inlinestatic

Returns true if unit vector u is very close to [0, 0, +/- 1]

Returns true if unit vector u is very close to [0, 0, +/- 1]

Parameters:
uunit vector
Returns:
true if unit vector u is very close to [0, 0, +/- 1]
double geotess::GeoTessUtils::length ( const double *const  u)
inlinestatic

Return edge length.

Find the length of a 3-element vector.

Parameters:
udouble[]
Returns:
the length of the vector. Guaranteed to be >= 0.
bool geotess::GeoTessUtils::move ( const double *const  w,
double  distance,
double  azimuth,
double *const  u 
)
inlinestatic

Move vector to a new position.

Move unit vector w specified distance in direction given by azimuth and return the result in u. If w is north or south pole, u will be equal to the same pole and method returns false.

Parameters:
wdouble[] unit vector of starting position
distancedistance to move in radians
azimuthdirection to move in radians
udouble[] unit vector of resulting position.
Returns:
true if successful, false if w is north or south pole
void geotess::GeoTessUtils::move ( const double *const  w,
const double *const  vtp,
double  a,
double *const  u 
)
inlinestatic

Move unit vector w in direction of vtp by distance a and store result in u. vtp is assumed to be a unit vector normal to w on input.

Parameters:
wdouble[]
vtpdouble[]
adouble
udouble[]
bool geotess::GeoTessUtils::moveNorth ( const double *const  x,
double  distance,
double *const  z 
)
inlinestatic

Return a unit vector that is distance radians due north of positon x. If x is the north or south pole, then z is set equal to x.

Parameters:
xthe position to be moved.
distancethe distance, in radians, that x is to be moved toward the north.
zthe 3-element unit vector representing the position after having moved distance north.
Returns:
true if operation successful, false if x is north or south pole.
double geotess::GeoTessUtils::normalize ( double *const  u)
inlinestatic

Normalize input vector.

Normalize the input vector to unit length. Returns the length of the vector prior to normalization.

Parameters:
uvector<double>
Returns:
length of the vector prior to normalization ( >= 0.)
bool geotess::GeoTessUtils::parallel ( const double *const  u,
const double *const  v 
)
inlinestatic

Returns true if unit vector u and v are parallel or very close to it

Returns true if unit vector u and v are parallel or very close to it

Parameters:
ua unit vector
vanother unit vector
Returns:
1.-abs(dot(u,v)) < 2e-15
void geotess::GeoTessUtils::readString ( string &  s,
ifstream &  ifs 
)
inlinestatic

Read / write a binary string.

Read a string from the input file stream and set into s

static void geotess::GeoTessUtils::rotate ( const double *const  x,
const double *const  p,
double  a,
double *const  z 
)
static

Rotate vector.

double geotess::GeoTessUtils::scalarTripleProduct ( const double *const  v0,
const double *const  v1,
const double *const  v2 
)
inlinestatic

Calculate the scalar triple product of 3 3-component vectors: (v0 cross v1) dot v2

Parameters:
v0double[]
v1double[]
v2double[]
Returns:
scalar triple product (v0 cross v1) dot v2
void geotess::GeoTessUtils::transform ( const double *  x,
double const *const *const  transform,
double *const  g 
)
inlinestatic

Project vector x onto the plane of a great circle. Consider a great circle defined by two unti vectors, u and v. Find the transform of x by calling t = getTransform(u, v). Then call this method: transform(x, t, g), which will calculate unit vector g such that

  • g[2] is the z direction, i.e., the component of x that points out of the plane of the great circle, toward the observer (v cross u).
  • g[1] is the y direction, i.e., the mean of u and v, and
  • g[0] is the x direction, i.e, g[1] cross g2.

Project vector x onto the plane of a great circle. Consider a great circle defined by two unti vectors, u and v. Find the transform of x by calling t = getTransform(u, v). Then call this method: transform(x, t, g), which will calculate unit vector g such that

  • g[2] is the z direction, i.e., the component of x that points out of the plane of the great circle, toward the observer (v cross u).
  • g[1] is the y direction, i.e., the mean of u and v, and
  • g[0] is the x direction, i.e, g[1] cross g2.
Parameters:
xdouble[] the 3 element array containing the vector to be projected.
transformthe 3 x 3 transform matrix obtained by calling getTransform(u,v)
gdouble[] the projection of x onto plane of this GreatCircle
Exceptions:
GreatCircleException
bool geotess::GeoTessUtils::vectorTripleProduct ( const double *const  v0,
const double *const  v1,
const double *const  v2,
double *const  rslt 
)
inlinestatic

Vector triple product.

Compute the normalized vector triple product (v0 x v1) x v2 and store result in rslt. It is ok if rslt is a reference to one of the input vectors. Local variables are used to ensure memory is not corrupted.

Parameters:
v0double[]
v1double[]
v2double[]
rsltdouble[]
Returns:
true if rslt has finite length, false if length(rslt) is zero.
bool geotess::GeoTessUtils::vectorTripleProductNorthPole ( const double *const  u,
double *const  w 
)
inlinestatic

Vector triple product with the north pole.

Compute the normalized vector triple product (u x northPole) x u and store result in w. Returns false is u is north or south pole.

Parameters:
udouble[]
wdouble[]
Returns:
true if w has finite length, false if length(w) is zero.
void geotess::GeoTessUtils::writeString ( ofstream &  ofs,
const string &  s 
)
inlinestatic

Write the string s to the output file stream.


Member Data Documentation

bool geotess::GeoTessUtils::approximateLatitudes
static

If true, then an approximate algorithm will be used to convert back and forth between geocentric and geographic latitudes. The approximation incurs an error of about 0.1 meters in latitude calculations but is faster than the correct calculation.

Note that the existence of this static, mutable variable technically violates thread-safety of this class. But given the assumption that the approximation is just as good as the true conversions, this is not a significant violation.


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