geodesy.c File Reference


Detailed Description

GNSS core 'c' function library: geodesy related functions.

Author:
Glenn D. MacGougan (GDM)
Date:
2007-11-28
Since:
2005-08-14
"LICENSE INFORMATION"
Copyright (c) 2007, refer to 'author' doxygen tags
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided the following conditions are met:

THIS SOFTWARE IS PROVIDED BY THE CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Definition in file geodesy.c.

#include <math.h>
#include "geodesy.h"
#include "constants.h"

Go to the source code of this file.

Functions

BOOL GEODESY_GetReferenceEllipseParameters (const GEODESY_enumReferenceEllipse ellipse, double *a, double *b, double *f_inv, double *e2)
 This is a look up table function to get reference ellipse parameters.
BOOL GEODESY_ConvertGeodeticCurvilinearToEarthFixedCartesianCoordinates (const GEODESY_enumReferenceEllipse referenceEllipse, const double latitude, const double longitude, const double height, double *x, double *y, double *z)
 This function converts curvilinear geodetic coordinates from latitude, longitude, and ellipsoidal height to cartesian geodetic coordinates x, y, and z for the reference ellipse specified. (e.g. GEODESY_REFERENCE_ELLIPSE_WGS84).
BOOL GEODESY_ConvertEarthFixedCartesianToGeodeticCurvilinearCoordinates (const GEODESY_enumReferenceEllipse referenceEllipse, const double x, const double y, const double z, double *latitude, double *longitude, double *height)
 This function converts cartesian geodetic coordinates from x, y, and z to curvilinear geodetic coordinates latitude, longitude, and ellipsoidal height for the reference ellipse specified. An iterative approach is used. (e.g. GEODESY_REFERENCE_ELLIPSE_WGS84).
BOOL GEODESY_ComputeNorthingEastingVertical (const GEODESY_enumReferenceEllipse referenceEllipse, const double referenceLatitude, const double referenceLongitude, const double referenceHeight, const double latitude, const double longitude, const double height, double *northing, double *easting, double *vertical)
 Given a reference point (datum) for a local geodetic coordinate system compute northing easting and vertical of another point given its latitude, longitude, and height for the reference ellipse specified. (e.g. GEODESY_REFERENCE_ELLIPSE_WGS84).
BOOL GEODESY_ComputePositionDifference (const GEODESY_enumReferenceEllipse referenceEllipse, const double referenceLatitude, const double referenceLongitude, const double referenceHeight, const double latitude, const double longitude, const double height, double *difference_northing, double *difference_easting, double *difference_vertical)
 Compute the difference between two points in a local geodetic frame using one point as the reference. Can be used to compute position error with respect to a known reference but keep in mind a local geodetic frame is used.
BOOL GEODESY_ComputeMeridianRadiusOfCurvature (const GEODESY_enumReferenceEllipse referenceEllipse, const double latitude, double *M)
 Computes meridian radius of curvature for the reference ellipse specified. (e.g. GEODESY_REFERENCE_ELLIPSE_WGS84).
BOOL GEODESY_ComputePrimeVerticalRadiusOfCurvature (const GEODESY_enumReferenceEllipse referenceEllipse, const double latitude, double *N)
 Computes the prime vertical radius of curvature for the reference ellipse specified. (e.g. GEODESY_REFERENCE_ELLIPSE_WGS84).
BOOL GEODESY_ComputeMeridianArcBetweenTwoLatitudes (const GEODESY_enumReferenceEllipse referenceEllipse, const double referenceLatitude, const double latitude, double *arc)
 Compute the meridian arc between two latitudes for the reference ellipse specified. (e.g. GEODESY_REFERENCE_ELLIPSE_WGS84).
BOOL GEODESY_ComputeParallelArcBetweenTwoLongitudes (const GEODESY_enumReferenceEllipse referenceEllipse, const double referenceLatitude, const double referenceLongitude, const double longitude, double *arc)
 Compute the parallel arc between two longitudes for the reference ellipse specified. (e.g. GEODESY_REFERENCE_ELLIPSE_WGS84).
BOOL GEODESY_RotateVectorFromLocalGeodeticFrameToEarthFixedFrame (const double referenceLatitude, const double referenceLongitude, const double dN, const double dE, const double dUp, double *dX, double *dY, double *dZ)
 Rotates a vector from a Local Geodetic Frame (LG) to and Earth Centered Earth Fixed Frame (ECEF).
BOOL GEODESY_RotateVectorFromEarthFixedFrameToLocalGeodeticFrame (const double referenceLatitude, const double referenceLongitude, const double dX, const double dY, const double dZ, double *dN, double *dE, double *dUp)
 Rotates a vector from a Earth Centered Earth Fixed Frame (ECEF) to a Local Geodetic Frame (LG).
BOOL GEODESY_ComputeAzimuthAndElevationAnglesBetweenToPointsInTheEarthFixedFrame (const GEODESY_enumReferenceEllipse referenceEllipse, const double fromX, const double fromY, const double fromZ, const double toX, const double toY, const double toZ, double *elevation, double *azimuth)
 Computes the azimuth and elevation angles in the local geodetic (LG) frame between the 'from' point to the 'to' point given these point in the earth fixed frame. e.g. between a user gps location (from) and a satellite (to).


Function Documentation

BOOL GEODESY_ComputeAzimuthAndElevationAnglesBetweenToPointsInTheEarthFixedFrame ( const GEODESY_enumReferenceEllipse  referenceEllipse,
const double  fromX,
const double  fromY,
const double  fromZ,
const double  toX,
const double  toY,
const double  toZ,
double *  elevation,
double *  azimuth 
)

Computes the azimuth and elevation angles in the local geodetic (LG) frame between the 'from' point to the 'to' point given these point in the earth fixed frame. e.g. between a user gps location (from) and a satellite (to).

Author:
Glenn D. MacGougan (GDM)
Date:
2005-07-30
Since:
2005-07-30
Returns:
TRUE(1) if successful, FALSE(0) otherwise.
Parameters:
referenceEllipse  reference ellipse enumerated []
fromX  earth centered earth fixed vector from point X component [m]
fromY  earth centered earth fixed vector from point Y component [m]
fromZ  earth centered earth fixed vector from point Z component [m]
toX  earth centered earth fixed vector to point X component [m]
toY  earth centered earth fixed vector to point Y component [m]
toZ  earth centered earth fixed vector to point Z component [m]
elevation  elevation angle [rad]
azimuth  azimuth angle [rad]

Definition at line 735 of file geodesy.c.

BOOL GEODESY_ComputeMeridianArcBetweenTwoLatitudes ( const GEODESY_enumReferenceEllipse  referenceEllipse,
const double  referenceLatitude,
const double  latitude,
double *  arc 
)

Compute the meridian arc between two latitudes for the reference ellipse specified. (e.g. GEODESY_REFERENCE_ELLIPSE_WGS84).

Author:
Glenn D. MacGougan (GDM)
Date:
2005-07-30
Since:
2005-07-30
Returns:
TRUE(1) if successful, FALSE(0) otherwise.
REFERENCES
Parameters:
referenceEllipse  reference ellipse enumerated []
referenceLatitude  datum geodetic latitude [rad]
latitude  geodetic latitude [rad]
arc  computed meridian arc, North +ve, South -ve [m]

Definition at line 567 of file geodesy.c.

BOOL GEODESY_ComputeMeridianRadiusOfCurvature ( const GEODESY_enumReferenceEllipse  referenceEllipse,
const double  latitude,
double *  M 
)

Computes meridian radius of curvature for the reference ellipse specified. (e.g. GEODESY_REFERENCE_ELLIPSE_WGS84).

Author:
Glenn D. MacGougan (GDM)
Date:
2005-07-30
Since:
2005-07-30
Returns:
TRUE(1) if successful, FALSE(0) otherwise.
REFERENCES
Parameters:
referenceEllipse  reference ellipse enumerated []
latitude  geodetic latitude [rad]
M  computed meridian radius of curvature [m]

Definition at line 509 of file geodesy.c.

BOOL GEODESY_ComputeNorthingEastingVertical ( const GEODESY_enumReferenceEllipse  referenceEllipse,
const double  referenceLatitude,
const double  referenceLongitude,
const double  referenceHeight,
const double  latitude,
const double  longitude,
const double  height,
double *  northing,
double *  easting,
double *  vertical 
)

Given a reference point (datum) for a local geodetic coordinate system compute northing easting and vertical of another point given its latitude, longitude, and height for the reference ellipse specified. (e.g. GEODESY_REFERENCE_ELLIPSE_WGS84).

Author:
Glenn D. MacGougan (GDM)
Date:
2005-07-30
Since:
2005-07-30
Returns:
TRUE(1) if successful, FALSE(0) otherwise.
REFERENCES
[1] Schwartz, K. P. (1997). ENGO 421 Lecture Notes - Fundamentals of Geodesy. Chapter 4, pp 79.
Parameters:
referenceEllipse  reference ellipse enumerated []
referenceLatitude  datum geodetic latitude [rad]
referenceLongitude  datum geodetic longitude [rad]
referenceHeight  datum geodetic height [m]
latitude  geodetic latitude [rad]
longitude  geodetic longitude [rad]
height  geodetic height [m]
northing  local geodetic northing [m]
easting  local geodetic easting [m]
vertical  local geodetic vertical [m]

Definition at line 393 of file geodesy.c.

BOOL GEODESY_ComputeParallelArcBetweenTwoLongitudes ( const GEODESY_enumReferenceEllipse  referenceEllipse,
const double  referenceLatitude,
const double  referenceLongitude,
const double  longitude,
double *  arc 
)

Compute the parallel arc between two longitudes for the reference ellipse specified. (e.g. GEODESY_REFERENCE_ELLIPSE_WGS84).

Author:
Glenn D. MacGougan (GDM)
Date:
2005-07-30
Since:
2005-07-30
Returns:
TRUE(1) if successful, FALSE(0) otherwise.
REFERENCES
Parameters:
referenceEllipse  reference ellipse enumerated []
referenceLatitude  reference geodetic latitude [rad]
referenceLongitude  reference geodetic longitude [rad]
longitude  geodetic longitude [rad]
arc  computed parallel arc, East +ve, West -ve [m]

Definition at line 621 of file geodesy.c.

BOOL GEODESY_ComputePositionDifference ( const GEODESY_enumReferenceEllipse  referenceEllipse,
const double  referenceLatitude,
const double  referenceLongitude,
const double  referenceHeight,
const double  latitude,
const double  longitude,
const double  height,
double *  difference_northing,
double *  difference_easting,
double *  difference_vertical 
)

Compute the difference between two points in a local geodetic frame using one point as the reference. Can be used to compute position error with respect to a known reference but keep in mind a local geodetic frame is used.

Author:
Glenn D. MacGougan (GDM)
Date:
2005-07-30
Since:
2005-07-30
Returns:
TRUE(1) if successful, FALSE(0) otherwise.
REFERENCES
See also:
GEODESY_ComputeNorthingEastingVertical
Parameters:
referenceEllipse  reference ellipse enumerated []
referenceLatitude  reference point geodetic latitude [rad]
referenceLongitude  reference point geodetic longitude [rad]
referenceHeight  reference point geodetic height [m]
latitude  geodetic latitude [rad]
longitude  geodetic longitude [rad]
height  geodetic height [m]
difference_northing  difference in northing [m] (+2 m, means 2 m North of the reference)
difference_easting  difference in easting [m] (+2 m, means 2 m East of the reference)
difference_vertical  difference in vertical [m] (+2 m, means 2 m above of the reference)

Definition at line 478 of file geodesy.c.

BOOL GEODESY_ComputePrimeVerticalRadiusOfCurvature ( const GEODESY_enumReferenceEllipse  referenceEllipse,
const double  latitude,
double *  N 
)

Computes the prime vertical radius of curvature for the reference ellipse specified. (e.g. GEODESY_REFERENCE_ELLIPSE_WGS84).

Author:
Glenn D. MacGougan (GDM)
Date:
2005-07-30
Since:
2005-07-30
Returns:
TRUE(1) if successful, FALSE(0) otherwise.
REFERENCES
Parameters:
referenceEllipse  reference ellipse enumerated []
latitude  geodetic latitude [rad]
N  computed prime vertical radius of curvature [m]

Definition at line 540 of file geodesy.c.

BOOL GEODESY_ConvertEarthFixedCartesianToGeodeticCurvilinearCoordinates ( const GEODESY_enumReferenceEllipse  referenceEllipse,
const double  x,
const double  y,
const double  z,
double *  latitude,
double *  longitude,
double *  height 
)

This function converts cartesian geodetic coordinates from x, y, and z to curvilinear geodetic coordinates latitude, longitude, and ellipsoidal height for the reference ellipse specified. An iterative approach is used. (e.g. GEODESY_REFERENCE_ELLIPSE_WGS84).

Author:
Glenn D. MacGougan (GDM)
Date:
2005-07-30
Since:
2005-07-30
Returns:
TRUE(1) if successful, FALSE(0) otherwise.
Remarks:
(1) Hsu (1992) shows that the iterative form is slightly faster than the closed form for 3 iterations.
(2) Testing by GDM for WGS84, all points lat = -90:1:90 and lon = -180:1:180 were tested lat, lon, hgt first converted to x, y, z then converted back to lat ,lon, hgt and the number of iterations noted. No errors observed. 2-5 iterations are needed with a mean of 4.32 iterations.
REFERENCES
Parameters:
referenceEllipse  reference ellipse enumerated []

Definition at line 312 of file geodesy.c.

BOOL GEODESY_ConvertGeodeticCurvilinearToEarthFixedCartesianCoordinates ( const GEODESY_enumReferenceEllipse  referenceEllipse,
const double  latitude,
const double  longitude,
const double  height,
double *  x,
double *  y,
double *  z 
)

This function converts curvilinear geodetic coordinates from latitude, longitude, and ellipsoidal height to cartesian geodetic coordinates x, y, and z for the reference ellipse specified. (e.g. GEODESY_REFERENCE_ELLIPSE_WGS84).

Author:
Glenn D. MacGougan (GDM)
Date:
2005-07-30
Since:
2005-07-30
Returns:
TRUE(1) if successful, FALSE(0) otherwise.
Example
  double latitude=0;   //!< geodetic latitude                [rad]
  double longitude=0;  //!< geodetic longitude               [rad]
  double height=0;     //!< geodetic height                  [m]
  double x;            //!< earth fixed cartesian coordinate [m]
  double y;            //!< earth fixed cartesian coordinate [m]
  double z;            //!< earth fixed cartesian coordinate [m]

  result = GEODESY_ConvertGeodeticCurvilinearToEarthFixedCartesianCoordinates(
    GEODESY_REFERENCE_ELLIPSE_WGS84_A,
    latitude, 
    longitude,
    height,   
    &x,       
    &y,       
    &z        
    );
  printf( "ellipse   = %s\n", GEODESY_REFERENCE_ELLIPSE_STRING_DESCRIPTION[GEODESY_REFERENCE_ELLIPSE_WGS84_A] );
  printf( "latitude  = %.12lf\n", latitude );
  printf( "longitude = %.12lf\n", longitude );
  printf( "height    = %.4lf\n", height );
  printf( "x         = %.4lf\n", x );
  printf( "y         = %.4lf\n", y );
  printf( "z         = %.4lf\n\n", z );

REFERENCES

Parameters:
referenceEllipse  reference ellipse enumerated []
latitude  geodetic latitude [rad]
longitude  geodetic longitude [rad]
height  geodetic height [m]
x  earth fixed cartesian coordinate [m]
y  earth fixed cartesian coordinate [m]
z  earth fixed cartesian coordinate [m]

Definition at line 261 of file geodesy.c.

BOOL GEODESY_GetReferenceEllipseParameters ( const GEODESY_enumReferenceEllipse  ellipse,
double *  a,
double *  b,
double *  f_inv,
double *  e2 
)

This is a look up table function to get reference ellipse parameters.

Author:
Glenn D. MacGougan (GDM)
Date:
2005-07-30
Since:
2005-07-30
Returns:
TRUE(1) if successful, FALSE(0) otherwise.
Example
  double a;      //!< semi-major axis of the reference ellipse                     [m]
  double b;      //!< semi-minor axis of the reference ellipse (b = a - a*f_inv)   [m] 
  double f_inv;  //!< inverse of the flattening of the reference ellipse           []
  double e2;     //!< eccentricity of the reference ellipse (e2 = (a*a-b*b)/(a*a)) [] 
  BOOL result;
  result = GEODESY_GetReferenceEllipseParameters( GEODESY_REFERENCE_ELLIPSE_WGS84_A, &a, &b, &f_inv, &e2 );
  if( result == TRUE )
  {
    printf( "ellipse = %s\n", GEODESY_REFERENCE_ELLIPSE_STRING_DESCRIPTION[GEODESY_REFERENCE_ELLIPSE_WGS84_A] );
    printf( "a       = %20.3f\n", a );
    printf( "b       = %20.9f\n", b );
    printf( "f_inv   = %20.11f\n", f_inv );
    printf( "e2      = %.15f\n\n", e2 );
  }

REFERENCES

Parameters:
ellipse  reference ellipse enumerated []
a  semi-major axis of the reference ellipse [m]
b  semi-minor axis of the reference ellipse (b = a - a*f_inv) [m]
f_inv  inverse of the flattening of the reference ellipse []
e2  eccentricity of the reference ellipse (e2 = (a*a-b*b)/(a*a)) []

Definition at line 70 of file geodesy.c.

BOOL GEODESY_RotateVectorFromEarthFixedFrameToLocalGeodeticFrame ( const double  referenceLatitude,
const double  referenceLongitude,
const double  dX,
const double  dY,
const double  dZ,
double *  dN,
double *  dE,
double *  dUp 
)

Rotates a vector from a Earth Centered Earth Fixed Frame (ECEF) to a Local Geodetic Frame (LG).

Author:
Glenn D. MacGougan (GDM)
Date:
2005-07-30
Since:
2005-07-30
Returns:
TRUE(1) if successful, FALSE(0) otherwise.
REFERENCES
Parameters:
referenceLatitude  reference geodetic latitude [rad]
referenceLongitude  reference geodetic longitude [rad]
dX  earth centered earth fixed vector component [m]
dY  earth centered earth fixed vector component [m]
dZ  earth centered earth fixed vector component [m]
dN  local geodetic northing vector component [m]
dE  local geodetic easting vector component [m]
dUp  local geodetic vertical vector component [m]

Definition at line 695 of file geodesy.c.

BOOL GEODESY_RotateVectorFromLocalGeodeticFrameToEarthFixedFrame ( const double  referenceLatitude,
const double  referenceLongitude,
const double  dN,
const double  dE,
const double  dUp,
double *  dX,
double *  dY,
double *  dZ 
)

Rotates a vector from a Local Geodetic Frame (LG) to and Earth Centered Earth Fixed Frame (ECEF).

Author:
Glenn D. MacGougan (GDM)
Date:
2005-07-30
Since:
2005-07-30
Returns:
TRUE(1) if successful, FALSE(0) otherwise.
REFERENCES
Parameters:
referenceLatitude  reference geodetic latitude [rad]
referenceLongitude  reference geodetic longitude [rad]
dN  local geodetic northing vector component [m]
dE  local geodetic easting vector component [m]
dUp  local geodetic vertical vector component [m]
dX  earth centered earth fixed vector component [m]
dY  earth centered earth fixed vector component [m]
dZ  earth centered earth fixed vector component [m]

Definition at line 655 of file geodesy.c.