The Essential GNSS Project: geodesy.c File Reference

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.

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

Schwartz, K. P. (1997). ENGO 421 Lecture Notes - Fundamentals of Geodesy. Chapter 3, pp. 33-66 & Appendix B, pp. 178-183. Geomatics Engineering, University of Calgary.

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

Schwartz, K. P. (1997). ENGO 421 Lecture Notes - Fundamentals of Geodesy. Chapter 3, pp. 33-66 & Appendix B, pp. 178-183. Geomatics Engineering, University of Calgary.

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

Schwartz, K. P. (1997). ENGO 421 Lecture Notes - Fundamentals of Geodesy. Chapter 3, pp. 33-66 & Appendix B, pp. 178-183. Geomatics Engineering, University of Calgary.

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

Schwartz, K. P. (1997). ENGO 421 Lecture Notes - Fundamentals of Geodesy. Chapter 3, pp. 33-66 & Appendix B, pp. 178-183. Geomatics Engineering, University of Calgary.

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

Schwartz, K. P. (1997). ENGO 421 Lecture Notes - Fundamentals of Geodesy. Chapter 3, pp. 33-66 & Appendix B, pp. 178-183. Geomatics Engineering, University of Calgary.
Iterative Method - Chapter 3, pp. 33-66. Closed Form - Appendix B, pp. 178-183.
Hsu, David Y. (1992). Closed Form Solution for Geodetic Coordinate Transformation. ION NTM 1992. pp. 397-400.
Misra, Pratap & Per Enge (2004). Global Positioning System Signals Measurements and Performance. Ganga-Jamuna Press. ISBN 0-9709544-0-9. PP. 115-116.

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

Schwartz, K. P. (1997). ENGO 421 Lecture Notes - Fundamentals of Geodesy. Chapter 3, pp. 33-66 & Appendix B, pp. 178-183. Geomatics Engineering, University of Calgary.

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

NovAtel OEM3 reference manual (www.novatel.com).

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 = (aa-bb)/(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

Schwartz, K. P. (1997). ENGO 421 Lecture Notes - Fundamentals of Geodesy. Chapter 3, pp. 33-66 & Appendix B, pp. 178-183. Geomatics Engineering, University of Calgary.

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

Schwartz, K. P. (1997). ENGO 421 Lecture Notes - Fundamentals of Geodesy. Chapter 3, pp. 33-66 & Appendix B, pp. 178-183. Geomatics Engineering, University of Calgary.

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.

geodesy.c File Reference

Detailed Description

Functions

Function Documentation