RSTT: slbm::Location Class Reference

RSTT 3.1.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>`

Inheritance diagram for slbm::Location:

## 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)
Location & | operator= (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.

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.

Definition at line 59 of file Location.h.

## Constructor & Destructor Documentation

## ◆ Location() [1/5]

slbm::Location::Location | ( |  | ) |

## ◆ ~Location()

virtual slbm::Location::~Location | ( |  | ) |
| virtual

## ◆ Location() [2/5]

slbm::Location::Location | ( | const Location & | location | ) |

## ◆ Location() [3/5]

slbm::Location::Location | ( | const double & | lat,
|  | const double & | lon,
|  | const double & | depth = `0`
| ) |  |

## ◆ Location() [4/5]

slbm::Location::Location | ( | const double | v[],
|  | const double & | radius
| ) |  |

## ◆ Location() [5/5]

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

## ◆ angle()

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

  u | unit vector one.
  v | unit vector two.

Returns
  angular separation in radians.

Definition at line 779 of file Location.h.

## ◆ azimuth() [1/2]

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.

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

Parameters

  other | the other location to which the azimuth is requested.

Returns
  the azimuth from this to other, in radians clockwise from north.

Definition at line 593 of file Location.h.

## ◆ azimuth() [2/2]

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.

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

  other | the other location to which the azimuth is requested.
  errorValue | the 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.

Definition at line 598 of file Location.h.

## ◆ azimuthDegrees() [1/2]

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.

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

Parameters

  other | the other location to which the azimuth is requested.

Returns
  the azimuth from this to other, in degrees clockwise from north.

Definition at line 624 of file Location.h.

## ◆ azimuthDegrees() [2/2]

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.

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

  other | the other location to which the azimuth is requested.
  errorValue | the 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.

Definition at line 629 of file Location.h.

## ◆ cross() [1/2]

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

normalized cross product of two 3-component unit vectors.

Parameters

  u | vector<double> vector one.
  v | vector<double> vector two.
  w | set 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.

Definition at line 809 of file Location.h.

## ◆ cross() [2/2]

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

  x | the other Location which, together with this Location, define the great circle path.
  loc | the 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.

Definition at line 798 of file Location.h.

## ◆ crossNorth()

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

  u | vector<double> vector one.
  w | set 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.

Definition at line 820 of file Location.h.

## ◆ distance()

double slbm::Location::distance | ( | const Location & | other | ) | const
| inline

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

Parameters

  other | the other Location to which this Location is to be compared.

Returns
  double separation of the locations in radians.

Definition at line 583 of file Location.h.

## ◆ distanceDegrees()

double slbm::Location::distanceDegrees | ( | const Location & | other | ) | const
| inline

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

Parameters

  other | the other Location to which this Location is to be compared.

Returns
  double separation of the Locations in degrees.

Definition at line 588 of file Location.h.

## ◆ distanceKm()

double slbm::Location::distanceKm | ( | Location & | other | ) | const

## ◆ dot() [1/2]

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

Dot product of two 3-component unit vectors.

Parameters

  u | vector one.
  v | vector two.

Returns
  dot product.

Definition at line 790 of file Location.h.

## ◆ dot() [2/2]

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

  other | the other Location

Returns
  dot product.

Definition at line 784 of file Location.h.

## ◆ getClassCount()

static int slbm::Location::getClassCount | ( |  | ) |
| static

## ◆ getDepth()

double slbm::Location::getDepth | ( |  | ) | const
| inline

Retrieve the depth of this Location.

Returns
  the depth of this Location in km.

Definition at line 573 of file Location.h.

## ◆ getEarthRadius()

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.

## ◆ getGeocentricLat()

double slbm::Location::getGeocentricLat | ( |  | ) | const
| inline

Retrieve the geocentric latitude of this Location, radians.

Retrieve the latitude of this Location.

Returns
  geocentric latitude, in radians.

Definition at line 250 of file Location.h.

## ◆ getGeocentricLatDegrees()

double slbm::Location::getGeocentricLatDegrees | ( |  | ) | const
| inline

Retrieve the geocentric latitude of this Location, degrees.

Retrieve the latitude of this Location.

Returns
  geocentric latitude, in degrees.

Definition at line 257 of file Location.h.

## ◆ getLat()

double slbm::Location::getLat | ( |  | ) | const
| inline

Retrieve the geographic latitude of this Location, radians.

Retrieve the latitude of this Location.

Returns
  geographic latitude, in radians.

Definition at line 542 of file Location.h.

## ◆ getLatDegrees()

double slbm::Location::getLatDegrees | ( |  | ) | const
| inline

Retrieve the geographic latitude of this Location, degrees.

Retrieve the latitude of this Location.

Returns
  geographic latitude, in degrees.

Definition at line 553 of file Location.h.

## ◆ getLon()

double slbm::Location::getLon | ( |  | ) | const
| inline

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

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

Returns
  longitude, in radians.

Definition at line 548 of file Location.h.

## ◆ getLonDegrees()

double slbm::Location::getLonDegrees | ( |  | ) | const
| inline

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

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

Returns
  longitude, in degrees.

Definition at line 558 of file Location.h.

## ◆ getRadius()

double slbm::Location::getRadius | ( |  | ) | const
| inline

Retrieve the radius of this Location object.

Returns
  the radius in km.

Definition at line 563 of file Location.h.

## ◆ getUnitVector() [1/2]

const double* slbm::Location::getUnitVector | ( |  | ) |
| inline

Definition at line 282 of file Location.h.

## ◆ getUnitVector() [2/2]

void slbm::Location::getUnitVector | ( | double | x[3] | ) |
| inline

Definition at line 284 of file Location.h.

## ◆ length()

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.

Definition at line 859 of file Location.h.

## ◆ move() [1/3]

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.

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

  azimuth | the azimuth from this Location to the desired Location, in radians, measured clockwise from north.
  distance | the distance from this Location to the desired Location, in radians.
  loc | the Location that has been moved relative to this Location.

Definition at line 638 of file Location.h.

## ◆ move() [2/3]

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.

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.

Definition at line 679 of file Location.h.

## ◆ move() [3/3]

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.

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

  vtp | a 3 component unit vector normal to this Location.
  a | the angular distance from this Location to the desired Location, in radians.
  loc | the Location object which has been relocated as requested.

Definition at line 670 of file Location.h.

## ◆ move_north() [1/2]

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

  distance | the distance, in radians, that x is to be moved toward the north.
  loc | the Location after having moved distance north.

Definition at line 660 of file Location.h.

## ◆ move_north() [2/2]

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

  x | the position to be moved.
  distance | the distance, in radians, that x is to be moved toward the north.
  z | the 3-element unit vector representing the position after having moved distance north.

Definition at line 651 of file Location.h.

## ◆ normalize()

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

  v | vector<double>

Returns
  length of the vector prior to normalization ( >= 0.)

Definition at line 842 of file Location.h.

## ◆ operator!=()

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.

Definition at line 113 of file Location.h.

## ◆ operator=()

Location& slbm::Location::operator= | ( | const Location & | other | ) |

## ◆ operator==()

bool slbm::Location::operator== | ( | const Location & | other | ) | const

## ◆ rotate() [1/2]

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

  x | vector to be rotated
  p | pole about which rotation is to occur.
  a | double the amount of rotation, in radians.
  z | the rotated vector, normalized to unit length.

Definition at line 754 of file Location.h.

## ◆ rotate() [2/2]

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

  pole | the pole around which this Location is to be rotated.
  angle | the angular distance by which this Location is to be rotated around pole, in radians.
  loc | the Location that results from rotating this Location around pole.

Definition at line 747 of file Location.h.

## ◆ scalarTripleProduct() [1/3]

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.

Definition at line 732 of file Location.h.

## ◆ scalarTripleProduct() [2/3]

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.

Definition at line 739 of file Location.h.

## ◆ scalarTripleProduct() [3/3]

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.

Definition at line 727 of file Location.h.

## ◆ setDepth()

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

Set the depth of this Location.

Parameters

  depth | the desired depth in km.

Definition at line 578 of file Location.h.

## ◆ setLocation() [1/2]

void slbm::Location::setLocation | ( | const double & | lat,
|  | const double & | lon,
|  | const double & | depth
| ) |  |
| inline

Set the location of this Location.

Parameters

  lat | the geographic latitude in radians.
  lon | the geographic longitude in radians.
  depth | the depth in km.

Definition at line 527 of file Location.h.

## ◆ setLocation() [2/2]

void slbm::Location::setLocation | ( | const double * | u,
|  | const double & | r
| ) |  |
| inline

Set the location of this Location.

Parameters

  u | unit vector of new position.
  r | radius of new position in km.

Definition at line 133 of file Location.h.

## ◆ setRadius()

void slbm::Location::setRadius | ( | const double & | r | ) |
| inline

Set the radius of this Location.

Parameters

  r | the radius in km.

Definition at line 568 of file Location.h.

## ◆ setUnitVector()

void slbm::Location::setUnitVector | ( | double | x[3] | ) |
| inline

Definition at line 286 of file Location.h.

## ◆ toString()

string slbm::Location::toString | ( |  | ) | const
| inline

Returns a convenient string representation of this Location.

Definition at line 866 of file Location.h.

## ◆ vectorTripleProduct() [1/2]

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.

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.

Definition at line 698 of file Location.h.

## ◆ vectorTripleProduct() [2/2]

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.

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.

Definition at line 691 of file Location.h.

## ◆ vectorTripleProductNorthPole()

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.

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.

Definition at line 718 of file Location.h.

## Member Data Documentation

## ◆ EARTH_RADIUS

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.

Definition at line 502 of file Location.h.

## ◆ locationClassCount

int slbm::Location::locationClassCount
| staticprotected

Definition at line 508 of file Location.h.

## ◆ radius

double slbm::Location::radius
| protected

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

Definition at line 521 of file Location.h.

## ◆ v

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.

Definition at line 516 of file Location.h.

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

- rstt/SLBM/include/Location.h