geodesy.h File Reference

#include <vgl/base.h>

Go to the source code of this file.

Classes
struct	vgl_ellipsoid
struct	vgl_geodetic

Macros
#define	VGL_PI   3.14159265358979323846
#define	VGL_DEGREES_TO_RADIANS(degrees)   ((degrees) * (VGL_PI / 180.0))
#define	VGL_RADIANS_TO_DEGREES(radians)   ((radians) * (180.0 / VGL_PI))
#define	VGL_WGS84_SEMI_MAJOR_AXIS   6378137.0
#define	VGL_WGS84_FLATTENING   (1.0 / 298.257223563)

Functions
vgl_result	vgl_ellipsoid_wgs84_get (vgl_ellipsoid *out_ellipsoid)
vgl_result	vgl_ellipsoid_geodetic_to_ecef (const vgl_ellipsoid *ellipsoid, const vgl_geodetic *geodetic, vgl_dvec3 *out_ecef)
vgl_result	vgl_ellipsoid_ecef_to_geodetic (const vgl_ellipsoid *ellipsoid, const vgl_dvec3 *ecef, vgl_geodetic *out_geodetic)
vgl_result	vgl_ellipsoid_enu_frame_get (const vgl_ellipsoid *ellipsoid, const vgl_geodetic *origin, vgl_dmat4 *out_enu_to_ecef, vgl_dmat4 *out_ecef_to_enu)
vgl_result	vgl_earth_rotation_angle_get (double julian_date, double *out_angle)
vgl_result	vgl_degrees_to_radians (double degrees, double *out_radians)
vgl_result	vgl_radians_to_degrees (double radians, double *out_degrees)

Macro Definition Documentation

VGL_PI

#define VGL_PI   3.14159265358979323846

VGL_DEGREES_TO_RADIANS

#define VGL_DEGREES_TO_RADIANS

(

degrees

)

((degrees) * (VGL_PI / 180.0))

Angle conversions for C and C++; vgl_degrees_to_radians and vgl_radians_to_degrees do the same for bindings that cannot use macros.

VGL_RADIANS_TO_DEGREES

#define VGL_RADIANS_TO_DEGREES

(

radians

)

((radians) * (180.0 / VGL_PI))

VGL_WGS84_SEMI_MAJOR_AXIS

#define VGL_WGS84_SEMI_MAJOR_AXIS   6378137.0

WGS84 defining parameters.

VGL_WGS84_FLATTENING

#define VGL_WGS84_FLATTENING   (1.0 / 298.257223563)

Function Documentation

vgl_ellipsoid_wgs84_get()

vgl_result vgl_ellipsoid_wgs84_get

(

vgl_ellipsoid *

out_ellipsoid

)

Gets the WGS84 ellipsoid.

Parameters

out_ellipsoid

Receives the ellipsoid.

Return values

VGL_RESULT_SUCCESS	The ellipsoid was written.
VGL_RESULT_INVALID_ARGUMENT	out_ellipsoid is null.

Thread safety

Free-threaded.

vgl_ellipsoid_geodetic_to_ecef()

vgl_result vgl_ellipsoid_geodetic_to_ecef	(	const vgl_ellipsoid *	ellipsoid,
		const vgl_geodetic *	geodetic,
		vgl_dvec3 *	out_ecef
	)

Converts a geodetic position to ECEF coordinates.

A latitude up to 1e-12 radians beyond a pole is accepted and treated as the pole, so that converted angles such as VGL_DEGREES_TO_RADIANS(90.0) are always valid.

Parameters

ellipsoid	The reference ellipsoid.
geodetic	The position to convert.
out_ecef	Receives the ECEF position in metres.

Return values

VGL_RESULT_SUCCESS	The position was written.
VGL_RESULT_INVALID_ARGUMENT	A pointer is null, the ellipsoid is invalid, a value is not finite, or the latitude is out of range.

Thread safety

Free-threaded.

vgl_ellipsoid_ecef_to_geodetic()

vgl_result vgl_ellipsoid_ecef_to_geodetic	(	const vgl_ellipsoid *	ellipsoid,
		const vgl_dvec3 *	ecef,
		vgl_geodetic *	out_geodetic
	)

Converts ECEF coordinates to a geodetic position.

The conversion is closed-form and accurate to a few nanometres for any position, including positions near the centre of the ellipsoid. On the polar axis the longitude is 0, and at the centre the result is the north pole at a height of minus the semi-minor axis.

Parameters

ellipsoid	The reference ellipsoid.
ecef	The ECEF position in metres.
out_geodetic	Receives the geodetic position.

Return values

VGL_RESULT_SUCCESS	The position was written.
VGL_RESULT_INVALID_ARGUMENT	A pointer is null, the ellipsoid is invalid, or a coordinate is not finite.

Thread safety

Free-threaded.

vgl_ellipsoid_enu_frame_get()

vgl_result vgl_ellipsoid_enu_frame_get	(	const vgl_ellipsoid *	ellipsoid,
		const vgl_geodetic *	origin,
		vgl_dmat4 *	out_enu_to_ecef,
		vgl_dmat4 *	out_ecef_to_enu
	)

Gets the local East-North-Up frame at a geodetic position.

In ENU coordinates, +X points east, +Y north and +Z up along the ellipsoid normal, with the origin at the given position. The matrices are rigid transforms in the layout of section 4.2 of docs/c-api.md: columns 0 to 2 of out_enu_to_ecef are the east, north and up axes in ECEF, and column 3 is the origin.

Parameters

ellipsoid	The reference ellipsoid.
origin	Origin of the frame.
out_enu_to_ecef	Optional. Receives the transform from ENU to ECEF coordinates.
out_ecef_to_enu	Optional. Receives the transform from ECEF to ENU coordinates.

Return values

VGL_RESULT_SUCCESS	The matrices were written.
VGL_RESULT_INVALID_ARGUMENT	ellipsoid or origin is null, both outputs are null, the ellipsoid is invalid, or origin is out of range.

Thread safety

Free-threaded.

vgl_earth_rotation_angle_get()

vgl_result vgl_earth_rotation_angle_get	(	double	julian_date,
		double *	out_angle
	)

Gets the Earth rotation angle at a time: the angle by which the Earth has turned from the celestial frame (the equator and equinox of J2000), so that a direction d in that frame is (d.x cos(a) + d.y sin(a), -d.x sin(a) + d.y cos(a), d.z) in ECEF. It is the IAU 2000 definition, which leaves out precession and nutation, a fraction of a degree over decades: enough to place stars behind the globe.

Parameters

julian_date	The time as a Julian date in UT1, which UTC is within a second of: 2451545.0 is 1 January 2000 at 12:00.
out_angle	Receives the angle in radians, in [0, 2 pi).

Return values

VGL_RESULT_SUCCESS	The angle was written.
VGL_RESULT_INVALID_ARGUMENT	out_angle is null, or julian_date is not finite.

Thread safety

Free-threaded.

vgl_degrees_to_radians()

vgl_result vgl_degrees_to_radians	(	double	degrees,
		double *	out_radians
	)

Converts an angle from degrees to radians, as VGL_DEGREES_TO_RADIANS does.

Parameters

degrees	The angle in degrees. Any value; NaN and infinities pass through.
out_radians	Receives the angle in radians.

Return values

VGL_RESULT_SUCCESS	The angle was written.
VGL_RESULT_INVALID_ARGUMENT	out_radians is null.

Thread safety

Free-threaded.

vgl_radians_to_degrees()

vgl_result vgl_radians_to_degrees	(	double	radians,
		double *	out_degrees
	)

Converts an angle from radians to degrees, as VGL_RADIANS_TO_DEGREES does.

Parameters

radians	The angle in radians. Any value; NaN and infinities pass through.
out_degrees	Receives the angle in degrees.

Return values

VGL_RESULT_SUCCESS	The angle was written.
VGL_RESULT_INVALID_ARGUMENT	out_degrees is null.

Thread safety

Free-threaded.