SLBM  3.0
Regional Seismic Travel Time
Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Attributes | Static Protected Attributes | List of all members
slbm::Location Class Reference

The Location Class manages a single point in/on the Earth, which is described by the GRS80 ellipsoid. More...

#include <Location.h>

Inherited by slbm::GridProfile.

Public Member Functions

 Location ()
 
virtual ~Location ()
 
 Location (const Location &location)
 
 Location (const double &lat, const double &lon, const double &depth=0)
 
 Location (const double v[], const double &radius)
 
 Location (const Location &loc1, const Location &loc2)
 
Locationoperator= (const Location &other)
 
bool operator== (const Location &other) const
 
bool operator!= (const Location &other)
 
string toString () const
 
void setLocation (const double &lat, const double &lon, const double &depth)
 
void setLocation (const double *u, const double &r)
 
void setRadius (const double &r)
 
double getRadius () const
 
double getEarthRadius () const
 
double getDepth () const
 
void setDepth (const double &depth)
 
double distance (const Location &other) const
 
double distanceKm (Location &other) const
 
double distanceDegrees (const Location &other) const
 
double azimuth (const Location &other) const
 Find the azimuth from this Location to some other Location. Result will be between 0 and 2*PI radians. More...
 
double azimuthDegrees (const Location &other) const
 Find the azimuth from this Location to some other Location. Result will be between 0 and 360 degrees. More...
 
double azimuth (const Location &other, const double &errorValue) const
 Find the azimuth from this Location to some other Location. Result will be between 0 and 2*PI radians. If current position is the north or south pole, or if current position and other position are conincident, returns specified errorValue. More...
 
double azimuthDegrees (const Location &other, const double &errorValue) const
 Find the azimuth from this Location to some other Location. Result will be between 0 and 360 degrees. If current position is the north or south pole, or if current position and other position are conincident, returns specified errorValue. More...
 
double getLat () const
 Retrieve the geographic latitude of this Location, radians. More...
 
double getGeocentricLat () const
 Retrieve the geocentric latitude of this Location, radians. More...
 
double getGeocentricLatDegrees () const
 Retrieve the geocentric latitude of this Location, degrees. More...
 
double getLon () const
 Retrieve the longitude of this Location. Value will be between -PI and PI radians. More...
 
double getLatDegrees () const
 Retrieve the geographic latitude of this Location, degrees. More...
 
double getLonDegrees () const
 Retrieve the longitude of this Location. Value will be between -180 and 180 degrees. More...
 
const double * getUnitVector ()
 
void getUnitVector (double x[3])
 
void setUnitVector (double x[3])
 
void move (const double &azimuth, const double &distance, Location &loc) const
 Retrieve a Location that is a specified distance away from this Location, in a specified direction. More...
 
bool cross (const Location &x, Location &loc) const
 
void rotate (Location &pole, double angle, Location &loc) const
 
bool vectorTripleProduct (const Location &other, double vtp[]) const
 Compute the vector triple product (this x other) x this, normalized to unit length. Returns true if valid, false if triple product has zero length, which will happen when this and other are coincident or PI radians apart. More...
 
void move (const double vtp[], const double &a, Location &loc) const
 Move this Location object a specified angular distance (radians) in the direction specified by vtp. More...
 
void move_north (const double x[], const double &distance, double z[]) const
 
void move_north (const double &distance, Location &loc) const
 
void rotate (const double x[], const double p[], const double &a, double z[]) const
 
double scalarTripleProduct (const Location &loc1, const Location &loc2) const
 
double scalarTripleProduct (const double u[], const double w[]) const
 
double scalarTripleProduct (const double u[], const double v[], const double w[]) const
 
bool vectorTripleProduct (const double u[], const double v[], double vtp[]) const
 Compute the normalized vector triple product (u x v) x u and and store result in vtp. More...
 
bool vectorTripleProductNorthPole (const double u[], double w[]) const
 Compute the normalized vector triple product (u x northPole) x u and store result in w. Returns true if w has finite length, false if length(w) is zero. More...
 
void move (const double v[], const double vtp[], const double &a, double u[]) const
 Move unit vector v in direction of vtp by distance a and store result in u. vtp is assumed to be a unit vector normal to v. More...
 
double angle (const double u[], const double v[]) const
 
double dot (const Location &other) const
 
double dot (const double u[], const double v[]) const
 
double cross (const double u[], const double v[], double w[]) const
 
double crossNorth (const double u[], double w[]) const
 
double normalize (double v[]) const
 
double length (const double v[]) const
 

Static Public Member Functions

static int getClassCount ()
 

Static Public Attributes

static double EARTH_RADIUS
 

Protected Attributes

double v [3]
 
double radius
 

Static Protected Attributes

static int locationClassCount
 

Detailed Description

The Location Class manages a single point in/on the Earth, which is described by the GRS80 ellipsoid. See geovectors.pdf for a thorough mathematical description of Location.

There is a parameterized constructor that takes a geographic latitude, longitude and depth as parameters and converts them to internal representation. There are also many methods for computing the distance between 2 Location objects, the azimuth from one Location to another, the radius of the Earth at a given location, retreiving points along a great circle path between two Location objects, etc.

Constructor & Destructor Documentation

slbm::Location::Location ( )
virtual slbm::Location::~Location ( )
virtual
slbm::Location::Location ( const Location location)
slbm::Location::Location ( const double &  lat,
const double &  lon,
const double &  depth = 0 
)
slbm::Location::Location ( const double  v[],
const double &  radius 
)
slbm::Location::Location ( const Location loc1,
const Location loc2 
)

Parameterized constructor. Returns a new Location which is the mean of the two specified Locations.

Member Function Documentation

double slbm::Location::angle ( const double  u[],
const double  v[] 
) const
inline

Angular distance between two 3-component unit vectors, in radians. Vectors are assumed to be unit length on input.

Parameters
uunit vector one.
vunit vector two.
Returns
angular separation in radians.
double slbm::Location::azimuth ( const Location other) const
inline

Find the azimuth from this Location to some other Location. Result will be between 0 and 2*PI radians.

Parameters
otherthe other location to which the azimuth is requested.
Returns
the azimuth from this to other, in radians clockwise from north.
double slbm::Location::azimuth ( const Location other,
const double &  errorValue 
) const
inline

Find the azimuth from this Location to some other Location. Result will be between 0 and 2*PI radians. If current position is the north or south pole, or if current position and other position are conincident, returns specified errorValue.

Parameters
otherthe other location to which the azimuth is requested.
errorValuethe value to return when things go badly.
Returns
the azimuth from this to other, in radians clockwise from north. If current position is the north or south pole, or if current position and other position are conincident, returns specified errorValue.
double slbm::Location::azimuthDegrees ( const Location other) const
inline

Find the azimuth from this Location to some other Location. Result will be between 0 and 360 degrees.

Parameters
otherthe other location to which the azimuth is requested.
Returns
the azimuth from this to other, in degrees clockwise from north.
double slbm::Location::azimuthDegrees ( const Location other,
const double &  errorValue 
) const
inline

Find the azimuth from this Location to some other Location. Result will be between 0 and 360 degrees. If current position is the north or south pole, or if current position and other position are conincident, returns specified errorValue.

Parameters
otherthe other location to which the azimuth is requested.
errorValuethe value to return when things go badly.
Returns
the azimuth from this to other, in degrees clockwise from north. If current position is the north or south pole, or if current position and other position are conincident, returns specified errorValue.
bool slbm::Location::cross ( const Location x,
Location loc 
) const
inline

Retrieve a Location which is normal to the plane containing the great circle path from this Location to another Location. Considering the Locations to be unit vectors, loc will be set to this cross x. The radius of the resulting vector will be set to radius of this Location. If this Location and Location x are parallel, then the resulting Location will be invalid (vector will have zero length) and the radius will be -1 km.

Parameters
xthe other Location which, together with this Location, define the great circle path.
locthe Location normal to the plane containing the great circle path. Invalid if this and loc are parallel.
Returns
true if loc is valid, false if this and x are parallel.
double slbm::Location::cross ( const double  u[],
const double  v[],
double  w[] 
) const
inline

normalized cross product of two 3-component unit vectors.

Parameters
uvector<double> vector one.
vvector<double> vector 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 slbm::Location::crossNorth ( const double  u[],
double  w[] 
) const
inline

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 slbm::Location::distance ( const Location other) const
inline

Returns the distance, in radians, from this Location to some other Location.

Parameters
otherthe other Location to which this Location is to be compared.
Returns
double separation of the locations in radians.
double slbm::Location::distanceDegrees ( const Location other) const
inline

Return the distance, in degrees, from this Location to some other Location.

Parameters
otherthe other Location to which this Location is to be compared.
Returns
double separation of the Locations in degrees.
double slbm::Location::distanceKm ( Location other) const
double slbm::Location::dot ( const Location other) const
inline

Dot product of the unit vector that backs this Location and the unit vector that backs Location other.

Parameters
otherthe other Location
Returns
dot product.
double slbm::Location::dot ( const double  u[],
const double  v[] 
) const
inline

Dot product of two 3-component unit vectors.

Parameters
uvector one.
vvector two.
Returns
dot product.
static int slbm::Location::getClassCount ( )
static
double slbm::Location::getDepth ( ) const
inline

Retrieve the depth of this Location.

Returns
the depth of this Location in km.
double slbm::Location::getEarthRadius ( ) const

Retrieve the radius of the Earth at the latitude of this Location.

Returns
the radius of the Earth in km.
double slbm::Location::getGeocentricLat ( ) const
inline

Retrieve the latitude of this Location.

Returns
geocentric latitude, in radians.
double slbm::Location::getGeocentricLatDegrees ( ) const
inline

Retrieve the latitude of this Location.

Returns
geocentric latitude, in degrees.
double slbm::Location::getLat ( ) const
inline

Retrieve the latitude of this Location.

Returns
geographic latitude, in radians.
double slbm::Location::getLatDegrees ( ) const
inline

Retrieve the latitude of this Location.

Returns
geographic latitude, in degrees.
double slbm::Location::getLon ( ) const
inline

Retrieve the longitude of this Location. Value will be between -PI and PI radians.

Returns
longitude, in radians.
double slbm::Location::getLonDegrees ( ) const
inline

Retrieve the longitude of this Location. Value will be between -180 and 180 degrees.

Returns
longitude, in degrees.
double slbm::Location::getRadius ( ) const
inline

Retrieve the radius of this Location object.

Returns
the radius in km.
const double* slbm::Location::getUnitVector ( )
inline
void slbm::Location::getUnitVector ( double  x[3])
inline
double slbm::Location::length ( const double  v[]) const
inline

Find the length of a 3-element vector.

Returns
the length of the vector. Guaranteed to be >= 0.
void slbm::Location::move ( const double &  azimuth,
const double &  distance,
Location loc 
) const
inline

Retrieve a Location that is a specified distance away from this Location, in a specified direction. The returned Location will have the same radius as this location.

Parameters
azimuththe azimuth from this Location to the desired Location, in radians, measured clockwise from north.
distancethe distance from this Location to the desired Location, in radians.
locthe Location that has been moved relative to this Location.
void slbm::Location::move ( const double  vtp[],
const double &  a,
Location loc 
) const
inline

Move this Location object a specified angular distance (radians) in the direction specified by vtp, which is assumed to be a unit vector normal to this Location object's unit vector. vtp values are typically obtained by calling Location::vectorTripleProduct().

Parameters
vtpa 3 component unit vector normal to this Location.
athe angular distance from this Location to the desired Location, in radians.
locthe Location object which has been relocated as requested.
void slbm::Location::move ( const double  v[],
const double  vtp[],
const double &  a,
double  u[] 
) const
inline

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

void slbm::Location::move_north ( const double  x[],
const double &  distance,
double  z[] 
) const
inline

Return a location on the earth that is distance radians due north of positon x. If x is already at the north or south pole, then it is returned unmodified.

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.
void slbm::Location::move_north ( const double &  distance,
Location loc 
) const
inline

Return a location on the earth that is distance radians due north of this Location. If this is already at the north or south pole, then it is returned unmodified.

Parameters
distancethe distance, in radians, that x is to be moved toward the north.
locthe Location after having moved distance north.
double slbm::Location::normalize ( double  v[]) const
inline

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

Parameters
vvector<double>
Returns
length of the vector prior to normalization ( >= 0.)
bool slbm::Location::operator!= ( const Location other)
inline

Equality operator. Returns false if other Location object has the exact same horizontal position and radius as this Location object.

Location& slbm::Location::operator= ( const Location other)
bool slbm::Location::operator== ( const Location other) const
void slbm::Location::rotate ( Location pole,
double  angle,
Location loc 
) const
inline

Rotate this Location around Location pole by angle a. When looking in direction of pole's unit vector, clockwise rotation is positive.

Parameters
polethe pole around which this Location is to be rotated.
anglethe angular distance by which this Location is to be rotated around pole, in radians.
locthe Location that results from rotating this Location around pole.
void slbm::Location::rotate ( const double  x[],
const double  p[],
const double &  a,
double  z[] 
) const
inline

rotate 3d vector x clockwise around 3d vector p, by angle a. x and p are assumed to be unit vectors on input.

Parameters
xvector to be rotated
ppole about which rotation is to occur.
adouble the amount of rotation, in radians.
zthe rotated vector, normalized to unit length.
double slbm::Location::scalarTripleProduct ( const Location loc1,
const Location loc2 
) const
inline

Return the scalar triple product of loc1, loc2 and this. In other words (loc1 cross loc2) dot this. Since these are all unit vectors, the the result is cos(phi) where phi is the angle between this Location and loc1 cross loc2.

double slbm::Location::scalarTripleProduct ( const double  u[],
const double  w[] 
) const
inline

Return the scalar triple product of u, w, and this Location objects unit vector. In other words (u cross w) dot v. If u and w are unit vectors, then the result is cos(phi) where phi is the angle between this Location and u cross w.

double slbm::Location::scalarTripleProduct ( const double  u[],
const double  v[],
const double  w[] 
) const
inline

Return the scalar triple product (u cross v) dot w. If all are unit vectors, then the result is cos(phi) where phi is the angle between w and u cross c.

void slbm::Location::setDepth ( const double &  depth)
inline

Set the depth of this Location.

Parameters
depththe desired depth in km.
void slbm::Location::setLocation ( const double &  lat,
const double &  lon,
const double &  depth 
)
inline

Set the location of this Location.

Parameters
latthe geographic latitude in radians.
lonthe geographic longitude in radians.
depththe depth in km.
void slbm::Location::setLocation ( const double *  u,
const double &  r 
)
inline

Set the location of this Location.

Parameters
uunit vector of new position.
rradius of new position in km.
void slbm::Location::setRadius ( const double &  r)
inline

Set the radius of this Location.

Parameters
rthe radius in km.
void slbm::Location::setUnitVector ( double  x[3])
inline
string slbm::Location::toString ( ) const
inline

Returns a convenient string representation of this Location.

bool slbm::Location::vectorTripleProduct ( const Location other,
double  vtp[] 
) const
inline

Compute the vector triple product (this x other) x this, normalized to unit length. Returns true if valid, false if triple product has zero length, which will happen when this and other are coincident or PI radians apart.

bool slbm::Location::vectorTripleProduct ( const double  u[],
const double  v[],
double  vtp[] 
) const
inline

Compute the normalized vector triple product (u x v) x u and and store result in vtp. Returns true if vtp has finite length, false if length(vtp) is zero.

bool slbm::Location::vectorTripleProductNorthPole ( const double  u[],
double  w[] 
) const
inline

Compute the normalized vector triple product (u x northPole) x u and store result in w. Returns true if w has finite length, false if length(w) is zero.

Member Data Documentation

double slbm::Location::EARTH_RADIUS
static

This variable is initialized to -1 in Location.cc, outside the class definition. There is a method SlbmInterface::fixEarthRadius(double) that will modify this value. If this value is less than zero, then Location::getEarthRadius() will return the radius of the earth that is a function of geocentric latitude (larger at the equator, smaller at the poles). If this value is > 0, then getEarthRadius() returns this value.

int slbm::Location::locationClassCount
staticprotected
double slbm::Location::radius
protected

The distance from the center of the earth to this location in km.

double slbm::Location::v[3]
protected

v is the geocentric unit vector that describes the position on the earth. The origin of the vector is at the center of the earth. The x-component points to lon,lat = 0,0. y-component points to lon,lat = PI/2,0 and the z-component points to lon,lat = 0,PI/2.


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